# Raspberry Pi Video Player Auto-Start Script Requirements

## Project Overview
A Raspberry Pi script that automatically starts on boot and handles video playing using VLC media player on Raspbian desktop.

## System Requirements

### Hardware
- Raspberry Pi (any model with sufficient processing power for video playback)
- MicroSD card (minimum 16GB, Class 10 recommended)
- Power supply (official Raspberry Pi power adapter recommended)
- HDMI cable for display output
- **IR Receiver Module**: Compatible with Raspberry Pi GPIO (e.g., TSOP4838, TSOP38238)
- **IR Remote Control**: Any standard IR remote (TV, DVD player, etc.)
- Optional: External storage for video files

### Software
- **Operating System**: Raspbian Desktop (latest version)
- **Python**: Python 3.x (usually pre-installed on Raspbian)
- **VLC Media Player**: Latest version compatible with Raspbian
- **System Dependencies**: Standard Linux utilities for service management

## Functional Requirements

### Core Features
1. **Auto-Start on Boot**
   - Script must start automatically when Raspberry Pi boots
   - Should work with both GUI and headless boot scenarios
   - Must handle system startup delays gracefully

2. **Video Playback Management**
   - Launch VLC media player programmatically
   - Support for common video formats (MP4, AVI, MKV, MOV, etc.)
   - Handle video file discovery and selection
   - Manage playback controls (play, pause, stop, next, previous)

3. **IR Remote Control**
   - Receive and decode IR signals from remote control
   - Map IR codes to video playback commands
   - Support configurable IR code mapping through configuration file
   - Handle multiple remote control types and protocols
   - Real-time IR signal processing with GPIO
   - **TV Channel Simulation**: Map number keys (0-9) to specific videos
   - **Channel Management**: Direct video access via remote number keys

4. **File Management**
   - Monitor a specific folder for video files
   - Handle file path resolution and validation for the designated video folder
   - Support for common video file extensions in the target folder
   - Optional: Support for network storage (SMB, NFS) if the folder is on network storage

5. **TV Channel System**
   - **Channel Assignment**: Automatically assign videos to channel numbers
   - **Channel Discovery**: Scan video folder and create channel list
   - **Channel Navigation**: Direct channel access via number keys
   - **Channel Display**: Show current channel number and video name
   - **Channel Management**: Add, remove, or reorder channels
   - **Default Channel**: Set a default channel to start on boot

### Configuration Requirements
1. **Configurable Settings**
   - **Video source directory path**: Single designated folder containing all video files
   - Playback mode (single file, playlist, loop, random)
   - VLC player options and preferences
   - Display settings (fullscreen, windowed)
   - Audio output configuration
   - **Channel System Settings**:
     - Default channel number on startup
     - Channel assignment method (alphabetical, manual, custom order)
     - Channel display timeout duration
     - Multi-digit channel input timeout

2. **IR Remote Configuration**
   - **IR Code Mapping File**: JSON/YAML configuration file mapping IR codes to commands
   - GPIO pin configuration for IR receiver
   - IR protocol settings (NEC, RC5, RC6, etc.)
   - Command mapping for standard controls:
     - Play/Pause
     - Stop
     - Next/Previous video
     - Volume up/down
     - Seek forward/backward
     - Fullscreen toggle
   - **Channel Mapping Configuration**:
     - Number keys (0-9) mapped to specific video files
     - Channel list configuration file (channels.json/yaml)
     - Support for multi-digit channel numbers (e.g., 10, 11, 12...)
     - Channel naming and organization
     - Channel metadata (name, description, category)
     - Channel priority and ordering

3. **Logging and Monitoring**
   - Log script execution and errors
   - Monitor VLC process status
   - Handle VLC crashes and restart scenarios
   - System resource monitoring (optional)
   - Channel switching logs and statistics
   - IR remote usage tracking

## Technical Requirements

### Dependencies
- **python-vlc**: Python bindings for VLC media player
- **python-dotenv**: Environment variable management
- **psutil**: System and process utilities
- **pathlib**: Modern path handling
- **logging**: Built-in Python logging module
- **subprocess**: Process management
- **time**: Timing and delays
- **os**: Operating system interface
- **RPi.GPIO**: Raspberry Pi GPIO control library
- **lirc**: Linux Infrared Remote Control (optional, for advanced IR handling)
- **pigpio**: Alternative GPIO library with IR support
- **json/yaml**: Configuration file parsing
- **threading**: Multi-threaded IR signal processing and channel management
- **queue**: Thread-safe communication between IR handler and video player

### System Integration
- **systemd service**: For reliable auto-start functionality
- **Desktop autostart**: Alternative method using .desktop files
- **User permissions**: Proper file access permissions
- **Environment variables**: Configuration management
- **GPIO permissions**: Access to GPIO pins for IR receiver
- **IR signal processing**: Real-time IR code detection and decoding
- **Channel management system**: Video-to-channel mapping and navigation
- **Multi-digit input handling**: Channel number input with timeout

## Non-Functional Requirements

### Performance
- Script should start within 30 seconds of system boot
- Minimal system resource usage when idle
- Efficient video file scanning of the designated folder
- Responsive playback control
- IR signal response time under 100ms
- Low-latency GPIO interrupt handling
- Channel switching response time under 200ms
- Multi-digit channel input processing under 50ms per digit

### Reliability
- Handle VLC crashes gracefully
- Recover from temporary file system issues
- Robust error handling and logging
- Prevent multiple script instances
- Handle IR signal interference and noise
- Graceful degradation when IR receiver fails
- Handle invalid channel numbers gracefully
- Recover from channel mapping file corruption

### Usability
- Simple configuration through text files
- Clear logging for troubleshooting
- Easy installation and setup process
- Support for remote management (optional)
- Easy IR code learning and mapping process
- Intuitive remote control operation
- TV-like channel navigation experience
- Clear channel number display and feedback

## Security Considerations
- Secure file access permissions
- Input validation for file paths
- Protection against malicious video files
- Safe handling of user-provided configuration

## Future Enhancements (Optional)
- Web interface for remote control
- Support for streaming protocols
- Integration with media servers
- Scheduled playback
- Multi-monitor support
- Audio-only mode support
- Multiple IR remote support with device switching
- IR code learning mode for unknown remotes
- Custom IR command sequences (macros)
- IR remote power management (wake/sleep)
- **Advanced Channel Features**:
  - Channel favorites and bookmarks
  - Channel categories and filtering
  - Channel guide/EPG-like interface
  - Parental controls for specific channels
  - Channel recording and scheduling

## Installation Requirements
- Automated installation script
- Dependency management
- Configuration file templates
- Documentation for setup and usage
- Uninstallation procedure
- GPIO pin configuration guide
- IR receiver hardware setup instructions
- IR code mapping configuration examples
- Channel mapping setup and configuration guide
- Sample channel configuration files

## Testing Requirements
- Test on different Raspberry Pi models
- Verify compatibility with various video formats
- Test auto-start functionality
- Validate error handling scenarios
- Performance testing with large video files
- IR remote control testing with various remote types
- GPIO interrupt handling validation
- IR signal decoding accuracy testing
- Configuration file parsing validation
- **Channel System Testing**:
  - Channel number input and validation
  - Multi-digit channel number handling
  - Channel switching performance
  - Channel mapping file integrity
  - Channel display and feedback testing