From 065cc2407c6a125c8e10fb7ad6769578300435d1 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 9 Dec 2025 16:36:04 +1100 Subject: [PATCH] Initial commit: Add comprehensive README --- README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..efbff8e --- /dev/null +++ b/README.md @@ -0,0 +1,192 @@ +# Moonlight Drive-In Theater System + +A sophisticated NFC-based video player system designed for an immersive drive-in theater experience. Features seamless dual-player video transitions, web-based remote control, and advanced automation capabilities. + +## 🎬 Features + +- **NFC-Based Control**: Physical NFC tags trigger movie playback +- **Seamless Video Transitions**: Dual MPV player architecture for smooth playback +- **Web Interface**: Modern, responsive dashboard for remote control +- **Folder Sequences**: Support for multi-video sequences with automatic progression +- **Anti-Repeat Logic**: Smart trailer rotation to prevent repetitive playback +- **Unattend Mode**: Automatic cycling through content (3 trailers + 1 movie pattern) +- **Global NFC Capture**: Works even when video is fullscreen +- **Multi-Device Support**: Control from desktop, mobile, or tablet + +## 🚀 Quick Start + +### Prerequisites + +```bash +pip install -r web_requirements.txt +``` + +### Basic Setup + +1. **Place your videos**: + - Trailers → `videos/trailers/` + - Single movies → `videos/specific/` + - Folder sequences → `videos/groupvideos/[folder_name]/` + +2. **Configure NFC mappings**: + - Single videos: Edit `videos/key_mapping.txt` + - Folder sequences: Edit `videos/folder_mapping.txt` + +3. **Run the player**: + ```bash + # MPV-only mode + python movie.bat + + # With web interface + python start_web_player.bat + ``` + +4. **Access web interface**: + - Local: `http://localhost:8547` + - Network: `http://[your-ip]:8547` + +## 📁 Project Structure + +``` +moonlight-drive-in/ +├── main.py # VLC-based main (legacy) +├── mpv_seamless_player.py # Core MPV video player +├── config.py # Configuration management +├── debug_console.py # Desktop debug interface +├── enhanced_debug_console.py # Enhanced debug with web support +├── web_interface.py # Flask web dashboard +├── web_mpv_main.py # Web-enabled entry point +├── *.bat # Windows launcher scripts +├── dashboard.html # Web dashboard interface +├── validate_videos.py # Validation tool +└── videos/ + ├── trailers/ # Trailer video files + ├── specific/ # Single movie files + ├── groupvideos/ # Folder sequence videos + ├── key_mapping.txt # NFC to single video mappings + ├── folder_mapping.txt # NFC to folder mappings + └── folder_state.json # Playback position tracking +``` + +## 🎮 Usage + +### NFC Mapping Format + +**Single Videos** (`key_mapping.txt`): +``` +12345678,avengers +87654321,spider-man +``` + +**Folder Sequences** (`folder_mapping.txt`): +``` +11111111,LOTR +22222222,Avengers +33333333,Jurassic +``` + +### Web Interface + +Access the web dashboard for: +- 📊 Real-time statistics +- 🎮 Video controls (skip, mute, fullscreen) +- 🎬 Manual video selection +- 📁 Folder management +- ⚙️ System configuration + +### Debug Console + +The desktop debug console provides: +- Real-time log viewing +- Manual NFC input testing +- System statistics +- Quick controls +- Folder sequence reset + +## 🛠️ Advanced Features + +### Folder Sequences + +Create multi-video sequences that play in order: + +1. Create folder: `videos/groupvideos/MySequence/` +2. Add numbered videos: `01_intro.mp4`, `02_main.mp4`, `03_outro.mp4` +3. Map NFC tag in `folder_mapping.txt`: `12345678,MySequence` +4. Each scan plays the next video in sequence + +### Anti-Repeat Algorithm + +- Tracks last 36 trailers played +- Ensures variety in trailer rotation +- Automatically clears history when pool runs low + +### Network Client Support + +Send NFC commands over network (port 1360): +```python +import socket +sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) +sock.connect(('localhost', 1360)) +sock.send(b'12345678') +``` + +## 🔧 Configuration + +Edit `config.py` to customize: +- Video directories +- NFC settings +- Playback parameters +- Display preferences +- Logging levels + +## 🐛 Troubleshooting + +### Validate Your Setup + +```bash +python validate.bat +``` + +This checks: +- Directory structure +- Video file locations +- NFC mapping validity +- Missing files + +### Common Issues + +**No trailers playing**: Ensure trailer files are in `videos/trailers/` + +**NFC not working**: Check global input capture status in debug console + +**Web interface not accessible**: Verify firewall allows port 8547 + +**Folder sequences not advancing**: Check `folder_state.json` or reset via debug console + +## 📊 System Requirements + +- **OS**: Windows (primary), Linux (experimental) +- **Python**: 3.8+ +- **MPV**: Required for video playback +- **NFC Reader**: ACS ACR122 or compatible +- **Network**: For web interface access + +## 🔮 Planned Features + +- LEGO Dimensions Portal integration (7-zone NFC reading) +- Bluetooth LED controller integration +- Expanded capacity beyond 64 movies +- Additional automation patterns +- Enhanced gallery interfaces + +## 📝 License + +This is a personal project for the Moonlight Drive-In theater system. + +## 🙏 Credits + +Created by Jess for an immersive drive-in theater experience. + +--- + +**Note**: This system is designed for a specific drive-in theater setup. Adapt paths and configurations for your environment.