moonlight-drive-in/README.md

# 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.