commit fdb7ef65f24eed7e606c105eb0f94da3ee71bc0e Author: Oier Bravo Urtasun Date: Thu Sep 25 11:08:57 2025 +0200 requirements diff --git a/Requirements.md b/Requirements.md new file mode 100644 index 0000000..efeeb3f --- /dev/null +++ b/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