Initial commit: StreamFlow IPTV platform
This commit is contained in:
aiulian25
commit
73a8ae9ffd
1240 changed files with 278451 additions and 0 deletions
340
docs/HARDWARE_ACCELERATION.md
Normal file
340
docs/HARDWARE_ACCELERATION.md
Normal file
|
|
@ -0,0 +1,340 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue