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:

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

Verification:

# 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:

# 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:

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:

   # 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:

   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

GET /api/stream/capabilities

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

Stream with Hardware Acceleration

GET /api/stream/proxy/:channelId
Authorization: Bearer <token>

# Streams channel with user's configured hardware acceleration

Get Stream Settings

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

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:

   ls -la /dev/dri/
   

2. Check container has access:

   docker exec streamflow-app ls -la /dev/dri/
   

3. Restart container:

   docker compose restart
   

Permission Denied on /dev/dri

Symptoms: FFmpeg error "Cannot open device"

Solutions:

1. Check host permissions:

   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:

   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:

   # 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:

   docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
   

2. Uncomment GPU lines in docker-compose.yml

3. Restart docker service:

   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:

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 - Initial setup instructions
• ARCHITECTURE.md - System architecture
• docker-compose.yml - Docker configuration