rpi-tulivision/Requirements.md

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