rpi-tulivision/README.md

# Raspberry Pi Video Player Auto-Start System

A comprehensive video player system for Raspberry Pi that automatically starts on boot and provides TV-like channel navigation with IR remote control support.

## Features

- **Auto-Start on Boot**: Automatically starts when Raspberry Pi boots
- **VLC Integration**: Uses VLC media player for robust video playback
- **IR Remote Control**: Full IR remote support with multiple protocol decoding (NEC, RC5)
- **TV Channel System**: Number key mapping to videos (0-9, multi-digit support)
- **Configuration Management**: Comprehensive configuration system with validation
- **Systemd Service**: Reliable service management with auto-restart
- **Logging**: Detailed logging with rotation
- **Easy Setup**: Interactive setup wizard and installation scripts

## Hardware Requirements

### Required
- Raspberry Pi (any model with sufficient processing power)
- 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
- Case with cooling for extended operation

## Software Requirements

- **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

## Installation

### Quick Installation

1. **Clone the repository**:
   ```bash
   git clone https://github.com/your-repo/ulivision-tv.git
   cd ulivision-tv
   ```

2. **Run the installation script**:
   ```bash
   sudo chmod +x install.sh
   sudo ./install.sh
   ```

3. **Run the setup wizard**:
   ```bash
   sudo python3 setup.py
   ```

4. **Start the service**:
   ```bash
   video-player-start
   ```

### Manual Installation

1. **Install system dependencies**:
   ```bash
   sudo apt-get update
   sudo apt-get install -y python3 python3-pip vlc python3-rpi.gpio
   ```

2. **Install Python dependencies**:
   ```bash
   pip3 install -r requirements.txt
   ```

3. **Copy files to system directories**:
   ```bash
   sudo mkdir -p /opt/video_player /etc/video_player
   sudo cp *.py /opt/video_player/
   sudo cp video-player.service /etc/systemd/system/
   ```

4. **Enable and start the service**:
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable video-player
   sudo systemctl start video-player
   ```

## Configuration

### Main Configuration

The main configuration is stored in `/etc/video_player/config.json`:

```json
{
  "video_folder": "/home/pi/Videos",
  "default_channel": 1,
  "auto_play": true,
  "fullscreen": true,
  "ir_pin": 18,
  "ir_protocols": ["NEC", "RC5"],
  "vlc_options": [
    "--fullscreen",
    "--no-video-title-show",
    "--no-audio-display"
  ],
  "log_level": "INFO"
}
```

### Channel Configuration

Channels are configured in `/etc/video_player/channels.json`:

```json
{
  "1": {
    "number": 1,
    "name": "Sample Video 1",
    "path": "/home/pi/Videos/sample1.mp4",
    "description": "First sample video",
    "category": "general",
    "enabled": true,
    "priority": 0
  }
}
```

### IR Remote Mapping

IR codes are mapped in `/etc/video_player/ir_mapping.json`:

```json
{
  "NEC_00FF_807F": {
    "ir_code": "NEC_00FF_807F",
    "command": "channel_0",
    "description": "Channel 0",
    "repeatable": true
  }
}
```

## Usage

### Basic Operation

1. **Add video files** to the configured video folder (default: `/home/pi/Videos`)
2. **Configure channels** using the setup wizard or manually edit the channels.json file
3. **Map IR remote codes** using the IR learning mode or manually edit the mapping file
4. **Start the service** and use your IR remote to control playback

### IR Remote Commands

- **Number keys (0-9)**: Direct channel access
- **Multi-digit channels**: Enter channel number (e.g., 12, 25)
- **Play/Pause**: Toggle playback
- **Stop**: Stop current video
- **Next/Previous**: Navigate between channels
- **Volume Up/Down**: Control audio volume
- **Power**: Exit application

### Management Commands

- `video-player-start`: Start the service
- `video-player-stop`: Stop the service
- `video-player-restart`: Restart the service
- `video-player-status`: Check service status
- `video-player-logs`: View live logs

## IR Remote Setup

### Learning IR Codes

1. **Start IR learning mode**:
   ```bash
   sudo /opt/video_player/venv/bin/python /opt/video_player/ir_remote.py
   ```

2. **Press buttons** on your remote control
3. **Enter commands** when prompted (e.g., "channel_1", "play_pause")
4. **Save mappings** to the configuration file

### Manual IR Code Mapping

Edit `/etc/video_player/ir_mapping.json` to manually map IR codes:

```json
{
  "NEC_00FF_807F": {
    "ir_code": "NEC_00FF_807F",
    "command": "channel_0",
    "description": "Channel 0",
    "repeatable": true
  }
}
```

## Hardware Setup

### IR Receiver Connection

1. **Connect IR receiver** to Raspberry Pi GPIO:
   - VCC → 3.3V (Pin 1)
   - GND → Ground (Pin 6)
   - OUT → GPIO 18 (Pin 12) - or configure different pin

2. **Test IR receiver**:
   ```bash
   sudo python3 -c "import RPi.GPIO as GPIO; GPIO.setmode(GPIO.BCM); GPIO.setup(18, GPIO.IN); print('GPIO 18 ready')"
   ```

### GPIO Pin Configuration

The IR receiver GPIO pin can be configured in the main configuration file:

```json
{
  "ir_pin": 18
}
```

## Troubleshooting

### Common Issues

1. **Service won't start**:
   - Check logs: `video-player-logs`
   - Verify configuration: `sudo python3 setup.py`
   - Check file permissions

2. **IR remote not working**:
   - Verify GPIO pin configuration
   - Check IR receiver connections
   - Test with IR learning mode
   - Verify IR code mappings

3. **Videos not playing**:
   - Check video file formats (supported: MP4, AVI, MKV, MOV, WMV, FLV, WebM, M4V)
   - Verify file paths in channels.json
   - Check VLC installation: `vlc --version`

4. **No audio**:
   - Check audio device configuration
   - Verify volume settings
   - Test audio: `speaker-test -t wav -c 2`

### Log Files

- **Service logs**: `journalctl -u video-player -f`
- **Application logs**: `/var/log/video_player.log`
- **System logs**: `/var/log/syslog`

### Debug Mode

Enable debug logging by setting log level to DEBUG in the configuration:

```json
{
  "log_level": "DEBUG"
}
```

## Development

### Project Structure

```
ulivision-tv/
├── video_player.py          # Main video player application
├── ir_remote.py            # IR remote control system
├── config_manager.py       # Configuration management
├── setup.py               # Interactive setup wizard
├── install.sh             # Installation script
├── uninstall.sh           # Uninstallation script
├── video-player.service   # Systemd service file
├── requirements.txt       # Python dependencies
└── README.md             # This file
```

### Adding New Features

1. **Fork the repository**
2. **Create a feature branch**
3. **Implement your changes**
4. **Add tests** (if applicable)
5. **Submit a pull request**

### Testing

Run the test suite:

```bash
python3 -m pytest tests/
```

## Uninstallation

To completely remove the video player system:

```bash
sudo ./uninstall.sh
```

This will remove:
- Application files
- Configuration files
- Service configuration
- Management scripts
- Desktop shortcuts
- Log files

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

For support and questions:

- **Issues**: Create an issue on GitHub
- **Documentation**: Check the wiki
- **Community**: Join our Discord server

## Changelog

### Version 1.0.0
- Initial release
- VLC integration
- IR remote control
- TV channel system
- Systemd service
- Configuration management
- Setup wizard

## Acknowledgments

- VLC Media Player team for the excellent media player
- Raspberry Pi Foundation for the amazing hardware
- Python community for the great libraries
- Contributors and testers

---

**Note**: This system is designed for educational and personal use. Ensure you have proper licensing for any video content you play.