Stream Transcoding

Dispatcharr supports real-time stream transcoding using FFmpeg, Streamlink, VLC, and custom backends. Stream profiles let you configure different transcoding options for bandwidth control, format conversion, and client compatibility.

Stream Profiles

Stream profiles define how Dispatcharr processes streams before delivering them to clients. Each channel can be assigned a profile.

Built-in Profiles

Dispatcharr includes these locked (read-only) profiles:

FFmpeg Transcode

Command: ffmpegParameters:

-headers "User-Agent: {userAgent}" -i {streamUrl} 
-c:v libx264 -preset veryfast -b:v 3000k 
-c:a aac -b:a 128k 
-f mpegts pipe:1

Use case: Transcode to H.264 with controlled bitrate for bandwidth management.

FFmpeg Copy (Direct Stream)

Command: ffmpegParameters:

-headers "User-Agent: {userAgent}" -i {streamUrl} 
-c copy -f mpegts pipe:1

Use case: Direct copy without transcoding (lowest CPU, no quality loss).

Streamlink

Command: streamlinkParameters:

{streamUrl} --http-header User-Agent={userAgent} best --stdout

Use case: Handle streams from YouTube, Twitch, and other platforms that require protocol handling.

VLC

Command: vlcParameters:

{streamUrl} --sout '#std{access=file,mux=ts,dst=-}' --http-user-agent={userAgent}

Use case: Alternative streaming backend with broad codec support.

Proxy (No Processing)

Command: proxyParameters: (none)Use case: Direct proxy with no transcoding or processing.

Redirect

Command: redirectParameters: (none)Use case: HTTP 302 redirect to original stream URL.

Creating Custom Profiles

Navigate to Stream Profiles

Go to Settings → Stream Profiles in the Dispatcharr UI.

Create new profile

Click New Profile and configure:

Name: Descriptive name (e.g., “Low Bandwidth”)
Command: Select built-in tool or choose Custom
Parameters: Command-line arguments with placeholders
User Agent: Optional custom user agent
Active: Enable the profile

Assign to channels

Edit channels and select your new profile from the Stream Profile dropdown.

Parameter Placeholders

Use these placeholders in profile parameters:

Placeholder	Description	Example
`{streamUrl}`	Original stream URL	`http://provider.com/live/stream`
`{userAgent}`	User agent from profile settings	`Mozilla/5.0 ...`

FFmpeg Transcoding Options

Quality Tiers

Create profiles for different quality levels:

High Quality (1080p)

-headers "User-Agent: {userAgent}" -i {streamUrl}
-c:v libx264 -preset medium -b:v 6000k -maxrate 6500k -bufsize 12000k
-vf scale=1920:1080
-c:a aac -b:a 192k -ar 48000
-f mpegts pipe:1

Video: H.264, 6 Mbps, 1080p
Audio: AAC, 192 kbps
Target: High-speed connections, large screens

Medium Quality (720p)

-headers "User-Agent: {userAgent}" -i {streamUrl}
-c:v libx264 -preset veryfast -b:v 3000k -maxrate 3500k -bufsize 6000k
-vf scale=1280:720
-c:a aac -b:a 128k -ar 48000
-f mpegts pipe:1

Video: H.264, 3 Mbps, 720p
Audio: AAC, 128 kbps
Target: Standard connections, tablets

Low Bandwidth (480p)

-headers "User-Agent: {userAgent}" -i {streamUrl}
-c:v libx264 -preset ultrafast -b:v 1000k -maxrate 1200k -bufsize 2000k
-vf scale=854:480
-c:a aac -b:a 64k -ar 44100
-f mpegts pipe:1

Video: H.264, 1 Mbps, 480p
Audio: AAC, 64 kbps
Target: Mobile networks, low-bandwidth connections

Mobile Optimized (360p)

-headers "User-Agent: {userAgent}" -i {streamUrl}
-c:v libx264 -preset ultrafast -b:v 500k -maxrate 600k -bufsize 1000k
-vf scale=640:360
-c:a aac -b:a 48k -ar 44100
-f mpegts pipe:1

Video: H.264, 500 kbps, 360p
Audio: AAC, 48 kbps
Target: Smartphones, very low bandwidth

Hardware Acceleration

Leverage GPU encoding for better performance:

Intel QuickSync (VA-API)

-hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi
-i {streamUrl}
-vf 'scale_vaapi=1280:720'
-c:v h264_vaapi -b:v 3000k
-c:a aac -b:a 128k
-f mpegts pipe:1

Docker setup:

devices:
  - /dev/dri:/dev/dri
group_add:
  - video

NVIDIA NVENC

-hwaccel cuda -hwaccel_output_format cuda
-i {streamUrl}
-vf 'scale_cuda=1280:720'
-c:v h264_nvenc -preset fast -b:v 3000k
-c:a aac -b:a 128k
-f mpegts pipe:1

Docker setup:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

AMD AMF (VA-API)

-hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi
-i {streamUrl}
-vf 'scale_vaapi=1280:720'
-c:v h264_amf -b:v 3000k
-c:a aac -b:a 128k
-f mpegts pipe:1

Audio Processing

Audio Normalization

-i {streamUrl}
-c:v copy
-af loudnorm=I=-16:TP=-1.5:LRA=11
-c:a aac -b:a 128k
-f mpegts pipe:1

Normalizes audio levels to prevent sudden volume changes.

Stereo Downmix

-i {streamUrl}
-c:v copy
-ac 2 -c:a aac -b:a 128k
-f mpegts pipe:1

Converts surround sound to stereo.

Audio-Only Stream

-i {streamUrl}
-vn
-c:a libmp3lame -b:a 192k
-f mp3 pipe:1

Extracts audio only (for radio channels).

Advanced Configurations

H.265/HEVC Encoding

Better compression than H.264, but requires client support:

-headers "User-Agent: {userAgent}" -i {streamUrl}
-c:v libx265 -preset medium -crf 28 -x265-params log-level=error
-c:a aac -b:a 128k
-f mpegts pipe:1

H.265 requires more CPU for software encoding. Use hardware acceleration when possible.

Deinterlacing

For interlaced sources (1080i, 720i):

-i {streamUrl}
-vf yadif=0:-1:0
-c:v libx264 -preset veryfast -b:v 3000k
-c:a aac -b:a 128k
-f mpegts pipe:1

Subtitle Burn-In

Burn subtitles into video stream:

-i {streamUrl}
-vf subtitles=subtitles.srt
-c:v libx264 -preset veryfast -b:v 3000k
-c:a copy
-f mpegts pipe:1

Multi-Audio Track Selection

Select specific audio track:

-i {streamUrl}
-map 0:v:0 -map 0:a:1
-c:v copy -c:a aac -b:a 128k
-f mpegts pipe:1

Streamlink Profiles

Streamlink excels at handling platform-specific streams:

YouTube Live

{streamUrl} --http-header User-Agent={userAgent} 
--stream-sorting-excludes >=1080p 
best --stdout

Twitch with OAuth

{streamUrl} 
--twitch-api-header="Authorization=OAuth token123" 
best --stdout

Use shlex.split() parsing for parameters with quotes. Dispatcharr handles this automatically.

Custom Plugin

{streamUrl} 
--plugin-dirs /data/streamlink-plugins 
best --stdout

Performance Tuning

CPU Priority

Set process priority for streaming:

docker-compose.yml

environment:
  - UWSGI_NICE_LEVEL=-5  # Higher priority for streaming
cap_add:
  - SYS_NICE

FFmpeg Presets

Balance quality vs. CPU usage:

Preset	CPU Usage	Latency	Quality
`ultrafast`	Very Low	Lowest	Lower
`veryfast`	Low	Low	Good
`fast`	Medium	Medium	Better
`medium`	High	Higher	Best

Use ultrafast or veryfast for live streams to minimize latency.

Buffer Sizes

Optimize buffering for network conditions:

-bufsize 6000k  # 2x video bitrate
-maxrate 3500k  # Slightly higher than target bitrate

Default Stream Profile

Set the default profile for new channels:

Go to Settings → Core Settings
Find Default Stream Profile
Select your preferred profile

Channels without an explicit profile use this default.

Multi-Profile Strategy

Create multiple profiles for different use cases:

Profile Name	Use Case	Settings
Direct	LAN, high bandwidth	FFmpeg copy
Standard	WAN, mixed clients	720p, 3 Mbps
Mobile	Smartphones, 4G/5G	480p, 1 Mbps
Satellite	High latency links	Lower buffer, faster preset
Audio Only	Radio channels	Audio extraction

Troubleshooting

Stream buffering constantly

Reduce bitrate in profile parameters
Use faster preset (veryfast, ultrafast)
Enable hardware acceleration
Check CPU usage during streaming

Video quality poor

Increase bitrate (-b:v 5000k)
Use slower preset (fast, medium)
Check source stream quality
Verify resolution scaling is correct

Hardware acceleration not working

Verify GPU devices are mounted in Docker
Check FFmpeg supports your GPU (ffmpeg -hwaccels)
Review Docker logs for hardware errors
Ensure correct group permissions (video, render)

Audio sync issues

Add -async 1 to FFmpeg parameters
Use -vsync 1 for variable frame rate sources
Check source stream for timestamp issues

Reference Implementation

See the stream profile source code:

Model: core/models.py:41
Stream Handler: core/views.py:139
Profile Settings: core/models.py:205

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

Stream Profiles

Built-in Profiles

Creating Custom Profiles

Parameter Placeholders

FFmpeg Transcoding Options

Quality Tiers

Hardware Acceleration

Audio Processing

Advanced Configurations

H.265/HEVC Encoding

Deinterlacing

Subtitle Burn-In

Multi-Audio Track Selection

Streamlink Profiles

YouTube Live

Twitch with OAuth

Custom Plugin

Performance Tuning

CPU Priority

FFmpeg Presets

Buffer Sizes

Default Stream Profile

Multi-Profile Strategy

Troubleshooting

Reference Implementation

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

​Stream Profiles

​Built-in Profiles

​Creating Custom Profiles

​Parameter Placeholders

​FFmpeg Transcoding Options

​Quality Tiers

​Hardware Acceleration

​Audio Processing

​Advanced Configurations

​H.265/HEVC Encoding

​Deinterlacing

​Subtitle Burn-In

​Multi-Audio Track Selection

​Streamlink Profiles

​YouTube Live

​Twitch with OAuth

​Custom Plugin

​Performance Tuning

​CPU Priority

​FFmpeg Presets

​Buffer Sizes

​Default Stream Profile

​Multi-Profile Strategy

​Troubleshooting

​Reference Implementation

Stream Profiles

Built-in Profiles

Creating Custom Profiles

Parameter Placeholders

FFmpeg Transcoding Options

Quality Tiers

Hardware Acceleration

Audio Processing

Advanced Configurations

H.265/HEVC Encoding

Deinterlacing

Subtitle Burn-In

Multi-Audio Track Selection

Streamlink Profiles

YouTube Live

Twitch with OAuth

Custom Plugin

Performance Tuning

CPU Priority

FFmpeg Presets

Buffer Sizes

Default Stream Profile

Multi-Profile Strategy

Troubleshooting

Reference Implementation