requirements

Requirements.md

@@ -0,0 +1,211 @@
+# 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