From d64e271633ef08ad54569c62ad86ac83bcad10c3 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 9 Dec 2025 16:39:27 +1100 Subject: [PATCH] Add comprehensive setup guide --- SETUP.md | 332 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 SETUP.md diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..2088096 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,332 @@ +# Moonlight Drive-In Setup Guide + +Complete setup instructions for the Moonlight Drive-In theater system. + +## 📋 Prerequisites + +### System Requirements +- **Operating System**: Windows 10/11 (primary), Linux (experimental) +- **Python**: Version 3.8 or higher +- **MPV**: Media player library +- **NFC Reader**: ACS ACR122 or compatible USB reader + +### Hardware Setup +1. Connect NFC reader to USB port +2. Connect display/projector +3. Ensure stable network connection (for web interface) + +## 🔧 Installation + +### Step 1: Install Python Dependencies + +```bash +# Install all required packages +pip install -r web_requirements.txt + +# Or install individually +pip install python-mpv flask flask-socketio pynput psutil +``` + +### Step 2: Install MPV Player + +**Windows:** +1. Download MPV from https://mpv.io/installation/ +2. Extract to `C:\DriveIn\mpv\` or update PATH in batch files +3. Ensure `mpv.exe` is in system PATH + +**Linux:** +```bash +sudo apt install mpv python3-mpv +``` + +### Step 3: Configure Directories + +The system will auto-create required directories on first run: +``` +videos/ + ├── trailers/ # Trailer video files + ├── specific/ # Single movie files + └── groupvideos/ # Folder sequences +``` + +## 🎬 Video Setup + +### Adding Trailers + +1. Place trailer videos in `videos/trailers/` +2. Supported formats: .mp4, .avi, .mov, .mkv, .wmv, .flv, .webm, .m4v +3. Trailers play randomly between movies + +### Adding Single Movies + +1. Place movie files in `videos/specific/` +2. Note the filename (without extension) +3. Map to NFC tags in `videos/key_mapping.txt` + +Example: +``` +videos/specific/avengers-endgame.mp4 +``` + +Mapping in `videos/key_mapping.txt`: +``` +12345678,avengers-endgame +``` + +### Creating Folder Sequences + +For multi-part movies or series: + +1. Create a folder in `videos/groupvideos/` +``` +videos/groupvideos/LOTR/ +``` + +2. Add numbered videos: +``` +videos/groupvideos/LOTR/01_fellowship.mp4 +videos/groupvideos/LOTR/02_towers.mp4 +videos/groupvideos/LOTR/03_return.mp4 +``` + +3. Map to NFC in `videos/folder_mapping.txt`: +``` +11111111,LOTR +``` + +4. Each NFC scan plays the next video in sequence! + +## 🏷️ NFC Configuration + +### Reading NFC IDs + +Use the debug console's "NFC Test" field to read your tags: +1. Start the player +2. Click in the "NFC Test" field +3. Scan your NFC tag +4. The ID will appear in the field +5. Copy this ID for your mapping files + +### Mapping Files + +**videos/key_mapping.txt** - Single videos: +``` +# Format: NFC_ID, Movie_Name +12345678,avengers +87654321,spider-man +``` + +**videos/folder_mapping.txt** - Folder sequences: +``` +# Format: NFC_ID, Folder_Name +11111111,LOTR +22222222,Avengers +``` + +### Validation + +Run the validation script to check your setup: +```bash +python validate.bat +``` + +This checks: +- All video files exist +- Mapping files are valid +- NFC IDs are properly configured +- Reports missing files + +## 🚀 Running the System + +### Basic Mode (MPV Only) + +```bash +# Windows +movie.bat + +# Or directly +python mpv_main_fixed.py +``` + +### Web Interface Mode + +```bash +# Windows +start_web_player.bat + +# Or directly +python web_mpv_main.py +``` + +Access web interface at: +- Local: http://localhost:8547 +- Network: http://[your-ip]:8547 + +### Features Available + +**Debug Console:** +- Real-time log viewing +- Manual NFC testing +- Quick controls +- Statistics display +- Folder sequence reset + +**Web Interface:** +- Multi-page dashboard +- Statistics page +- Control page +- Video selection +- System management + +## 🎮 Usage + +### Playing Videos + +1. **NFC Scan**: Simply scan an NFC tag to play mapped video +2. **Manual Selection**: Use web interface to select videos +3. **Trailers**: Play automatically between movies + +### Folder Sequences + +1. Scan NFC tag to play first video in sequence +2. Video plays to completion +3. Returns to trailer mode +4. Next scan plays second video +5. Continues through sequence, then loops + +### Controls + +**Keyboard (when focused):** +- Numbers + Enter: Manual NFC input + +**Web Interface:** +- Skip Video +- Toggle Fullscreen +- Mute/Unmute +- Manual video selection + +**Debug Console:** +- Skip Video button +- Toggle Fullscreen +- Mute/Unmute +- Reset Folder Sequences + +## 🔧 Troubleshooting + +### NFC Reader Not Working + +1. Check USB connection +2. Verify driver installation +3. Test with NFC Test field in debug console +4. Check global input capture status + +### Videos Won't Play + +1. Run validation script +2. Check video format is supported +3. Verify file paths in mapping files +4. Check MPV is installed and in PATH + +### Web Interface Not Accessible + +1. Check firewall allows port 8547 +2. Verify Flask and Flask-SocketIO installed +3. Check IP address is correct for network access +4. Try http://localhost:8547 first + +### Folder Sequences Not Advancing + +1. Check folder_state.json in videos folder +2. Use "Reset Folder Sequences" in debug console +3. Verify folder structure is correct +4. Check videos are named in correct order + +## 📊 Advanced Configuration + +### Changing Web Port + +Edit `web_mpv_main.py`: +```python +web_port = 8547 # Change to your preferred port +``` + +Or pass as command line argument: +```bash +python web_mpv_main.py 9000 +``` + +### Custom Video Directories + +Edit paths in `config.py`: +```python +VIDEOS_DIR = BASE_DIR / "videos" +TRAILERS_DIR = VIDEOS_DIR / "trailers" +``` + +### Anti-Repeat Settings + +Edit `mpv_seamless_player.py`: +```python +self.max_recent_trailers = 36 # Don't repeat within last N plays +``` + +### Logging Level + +Edit `config.py`: +```python +LOG_LEVEL = logging.DEBUG # Change to INFO, WARNING, or ERROR +``` + +## 🔄 Maintenance + +### Reloading Mappings + +Without restart: +1. Edit mapping files +2. Use web interface → System → Reload Mappings +3. Or press "Reload Mappings" in debug console + +### Clearing Folder State + +To restart all sequences from beginning: +1. Debug Console → "Reset Folder Sequences" button +2. Or delete `videos/folder_state.json` + +### Log Files + +Logs stored in `logs/` directory: +- Named by timestamp +- Rotated automatically +- Contains detailed debugging info + +## 📝 Best Practices + +1. **File Naming**: Use numbers for ordering (01_, 02_, etc.) +2. **Video Formats**: Prefer .mp4 for compatibility +3. **Backup Mappings**: Keep copies of mapping files +4. **Test First**: Use validation script before deployment +5. **Network**: Use static IP for consistent web access + +## 🆘 Support + +Check the logs in `logs/` directory for detailed error messages. + +Run diagnostics: +```bash +python folder_diagnostic.py # Check folder structure +python validate_videos.py # Validate complete setup +``` + +## 🎯 Quick Start Checklist + +- [ ] Python 3.8+ installed +- [ ] MPV player installed +- [ ] Required packages installed (`pip install -r web_requirements.txt`) +- [ ] Videos placed in appropriate directories +- [ ] NFC tags mapped in configuration files +- [ ] Validation script run successfully +- [ ] Test with manual NFC input +- [ ] Web interface accessible +- [ ] NFC reader connected and working + +You're ready to go! 🎬