streamflow/docs/HARDWARE_ACCELERATION.md

# Hardware Acceleration Guide

## Overview
StreamFlow IPTV supports hardware-accelerated video encoding and decoding for smooth playback with minimal CPU usage. This feature utilizes Intel Quick Sync, NVIDIA NVENC, or VAAPI for optimal performance.

## Supported Technologies

### Intel Quick Sync (QSV)
- **Best for**: Intel CPUs (6th gen and newer recommended)
- **Performance**: Excellent balance of quality and speed
- **Power efficiency**: Very good
- **Setup**: Automatic with `/dev/dri/renderD128` device

### NVIDIA NVENC
- **Best for**: Systems with NVIDIA GPUs (GTX 10-series and newer)
- **Performance**: Highest quality at high bitrates
- **Power efficiency**: Good
- **Setup**: Requires nvidia-docker and CUDA

### VAAPI (Video Acceleration API)
- **Best for**: AMD/Intel integrated graphics
- **Performance**: Good for live streaming
- **Power efficiency**: Excellent
- **Setup**: Similar to Quick Sync

## Docker Setup

### Intel Quick Sync / VAAPI (Default)

The default `docker-compose.yml` already includes Intel Quick Sync support:

```yaml
services:
  streamflow:
    devices:
      - /dev/dri:/dev/dri  # Intel Quick Sync / VAAPI
```

**Verification**:
```bash
# Check if device exists
ls -la /dev/dri/

# Should show renderD128 and card0
# crw-rw----+ 1 root video 226,   0 Dec 10 10:00 card0
# crw-rw----+ 1 root render 226, 128 Dec 10 10:00 renderD128
```

**Permissions**:
Ensure the container user has access to the render group:
```bash
# Add appuser to render group (inside container)
sudo usermod -a -G render appuser
```

### NVIDIA GPU Setup

For NVIDIA GPUs, uncomment these lines in `docker-compose.yml`:

```yaml
services:
  streamflow:
    # Uncomment for NVIDIA GPU:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu, video]
```

**Prerequisites**:
1. Install NVIDIA drivers on host
2. Install nvidia-docker:
   ```bash
   # Ubuntu/Debian
   distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
   curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
   curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
     sudo tee /etc/apt/sources.list.d/nvidia-docker.list
   
   sudo apt-get update
   sudo apt-get install -y nvidia-docker2
   sudo systemctl restart docker
   ```

3. Verify:
   ```bash
   docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
   ```

## Application Configuration

### Settings Page

Navigate to **Settings → Streaming & Hardware Acceleration**:

1. **Hardware Acceleration**:
   - `Auto (Recommended)`: Automatically selects best available method
   - `Intel Quick Sync`: Force Intel QSV
   - `VAAPI`: Force VAAPI
   - `NVIDIA NVENC`: Force NVIDIA (requires GPU setup)
   - `Software Only`: Disable hardware acceleration

2. **Hardware Device**:
   - Default: `/dev/dri/renderD128`
   - Change if using multiple GPUs (e.g., `/dev/dri/renderD129`)

3. **Encoder Preset**:
   - `Ultra Fast`: Lowest quality, highest speed
   - `Very Fast`: Recommended balance
   - `Medium`: Better quality, more CPU
   - `Slow`: Best quality for recording

4. **Buffer Size**:
   - `512 KB`: Low latency (live events)
   - `2 MB`: Recommended for most use cases
   - `8 MB`: Smooth playback (high bitrate streams)

5. **Max Bitrate**:
   - `2 Mbps`: Mobile/low bandwidth
   - `8 Mbps`: Recommended (Full HD)
   - `20 Mbps`: High quality (4K content)

## API Endpoints

### Get Hardware Capabilities
```bash
GET /api/stream/capabilities

Response:
{
  "quicksync": true,
  "nvenc": false,
  "vaapi": true,
  "videotoolbox": false
}
```

### Stream with Hardware Acceleration
```bash
GET /api/stream/proxy/:channelId
Authorization: Bearer <token>

# Streams channel with user's configured hardware acceleration
```

### Get Stream Settings
```bash
GET /api/settings/stream_settings
Authorization: Bearer <token>

Response:
{
  "value": {
    "hwaccel": "auto",
    "hwaccel_device": "/dev/dri/renderD128",
    "codec": "h264",
    "preset": "veryfast",
    "buffer_size": "2M",
    "max_bitrate": "8M"
  }
}
```

### Update Stream Settings
```bash
PUT /api/settings/stream_settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "value": {
    "hwaccel": "quicksync",
    "preset": "medium",
    "buffer_size": "4M"
  }
}
```

## Troubleshooting

### No Hardware Acceleration Available

**Symptoms**: All hardware options show "Not Available"

**Solutions**:
1. Verify device exists:
   ```bash
   ls -la /dev/dri/
   ```

2. Check container has access:
   ```bash
   docker exec streamflow-app ls -la /dev/dri/
   ```

3. Restart container:
   ```bash
   docker compose restart
   ```

### Permission Denied on /dev/dri

**Symptoms**: FFmpeg error "Cannot open device"

**Solutions**:
1. Check host permissions:
   ```bash
   sudo chmod 666 /dev/dri/renderD128
   # Or add user to render group
   sudo usermod -a -G render $USER
   ```

2. Ensure docker-compose has device mapping:
   ```yaml
   devices:
     - /dev/dri:/dev/dri
   ```

### Low Quality Despite Hardware Acceleration

**Symptoms**: Pixelation, artifacts

**Solutions**:
1. Increase bitrate in Settings → Max Bitrate
2. Change preset to `medium` or `slow`
3. Increase buffer size to `4M` or `8M`
4. Check source stream quality

### High CPU Usage with Hardware Acceleration Enabled

**Symptoms**: CPU usage not reduced

**Solutions**:
1. Verify hardware acceleration is actually being used:
   ```bash
   # Check FFmpeg logs
   docker logs streamflow-app | grep -i "qsv\|vaapi\|nvenc"
   ```

2. Try different hwaccel method:
   - Quick Sync might not be available on older CPUs
   - Try VAAPI as alternative

3. Check if transcoding is needed:
   - If source and output codecs match, use copy mode
   - Hardware acceleration only helps with transcoding

### NVIDIA GPU Not Detected

**Symptoms**: NVENC shows "Not Available"

**Solutions**:
1. Verify nvidia-docker is installed:
   ```bash
   docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
   ```

2. Uncomment GPU lines in docker-compose.yml

3. Restart docker service:
   ```bash
   sudo systemctl restart docker
   docker compose up -d
   ```

## Performance Comparison

### CPU Usage (1080p60 stream)

| Method | CPU Usage | Quality | Latency |
|--------|-----------|---------|---------|
| Software (x264) | 80-100% | Excellent | Medium |
| Quick Sync | 5-15% | Very Good | Low |
| NVENC | 3-10% | Excellent | Very Low |
| VAAPI | 8-20% | Good | Low |

### Recommendations by Use Case

**Live TV Streaming**:
- Hardware: Auto or Quick Sync
- Preset: veryfast
- Buffer: 2M
- Bitrate: 8M

**Recording**:
- Hardware: None or NVENC
- Preset: slow
- Buffer: 8M
- Bitrate: 20M

**Mobile Viewing**:
- Hardware: Auto
- Preset: faster
- Buffer: 512K
- Bitrate: 2M

**4K Content**:
- Hardware: NVENC (if available)
- Preset: medium
- Buffer: 8M
- Bitrate: 20M

## Best Practices

1. **Start with Auto**: Let the system detect the best method
2. **Monitor Performance**: Check CPU usage and stream quality
3. **Adjust Gradually**: Change one setting at a time
4. **Test Different Sources**: Some streams work better with certain settings
5. **Update Drivers**: Keep GPU drivers current for best compatibility

## Technical Details

### FFmpeg Command Example

With Quick Sync enabled:
```bash
ffmpeg -hwaccel qsv \
       -hwaccel_device /dev/dri/renderD128 \
       -hwaccel_output_format qsv \
       -re -i <stream_url> \
       -c:v copy \
       -c:a copy \
       -f mpegts pipe:1
```

### Codec Support

| Method | H.264 | H.265/HEVC | VP9 | AV1 |
|--------|-------|------------|-----|-----|
| Quick Sync | ✓ | ✓ (7th gen+) | ✗ | ✗ |
| NVENC | ✓ | ✓ (Pascal+) | ✗ | ✓ (Ada+) |
| VAAPI | ✓ | ✓ | ✓ | ✓ (new) |

## Related Documentation
- [SETUP.md](SETUP.md) - Initial setup instructions
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
- [docker-compose.yml](../docker-compose.yml) - Docker configuration