Stream Profiles

Configure stream processing backends including FFmpeg, Streamlink, and VLC for transcoding and streaming

Stream profiles define how Dispatcharr processes and delivers IPTV streams. Configure different backends for transcoding, format conversion, or direct streaming.

Overview

Stream profiles control the execution of external programs that handle stream processing. Each profile defines:

• Command: The program to execute (e.g., ffmpeg, streamlink, vlc)
• Parameters: Command-line arguments with dynamic placeholders
• User Agent: Optional User-Agent override for HTTP requests

Dispatcharr includes two built-in protected profiles: Proxy and Redirect. These cannot be deleted or modified (except User-Agent settings).

Built-in Profiles

Proxy

Streams directly through Dispatcharr with buffering and failover support. No external processing.

Redirect

Returns HTTP redirect to original stream URL. Minimal processing overhead.

Creating a Stream Profile

1. Navigate to Stream Profiles

   Go to Settings > Stream Profiles

2. Add New Profile

   Click Add Stream Profile

3. Configure Command

   Enter the executable name and parameters

4. Test Profile

   Assign to a channel and verify streaming works correctly

Configuration Fields

name · string · required

Unique profile name for identification

command · string

Executable command to run. Examples:

• ffmpeg
• streamlink
• vlc
• /usr/local/bin/custom-script.sh

Leave blank for built-in Proxy/Redirect profiles.

parameters · text

Command-line parameters with placeholder support.

Available placeholders:

• {streamUrl} - Original stream URL
• {userAgent} - User-Agent string

Parameters are parsed using shell-style quoting (via shlex).

user_agent · reference

User-Agent to use for HTTP requests. Falls back to system default if not specified.

This is the only field that can be modified on protected profiles.

is_active · boolean · default: true

Enable or disable this profile. Inactive profiles cannot be assigned to streams.

locked · boolean · default: false

Protected profiles cannot be deleted or modified (except user_agent).

System profiles (Proxy, Redirect) are always locked.

Parameter Substitution

The build_command() method constructs the final command by replacing placeholders:

replacements = {
    "{streamUrl}": "http://provider.com/stream.m3u8",
    "{userAgent}": "Mozilla/5.0..."
}

Example transformation:

# Parameters template:
-i {streamUrl} -user_agent {userAgent} -c copy -f mpegts pipe:1

# Final command:
ffmpeg -i http://provider.com/stream.m3u8 -user_agent "Mozilla/5.0..." -c copy -f mpegts pipe:1

Profile Examples

FFmpeg Transcoding

Basic Stream Copy

{
  "name": "FFmpeg Direct Copy",
  "command": "ffmpeg",
  "parameters": "-i {streamUrl} -user_agent {userAgent} -c copy -f mpegts pipe:1",
  "is_active": true
}

Re-muxes stream without transcoding. Fast and low CPU usage.

H.264 Transcode

{
  "name": "FFmpeg H.264",
  "command": "ffmpeg",
  "parameters": "-i {streamUrl} -user_agent {userAgent} -c:v libx264 -preset veryfast -c:a aac -b:a 128k -f mpegts pipe:1",
  "is_active": true
}

Transcodes video to H.264 with AAC audio. Higher CPU usage.

Resolution Downscale

{
  "name": "FFmpeg 720p",
  "command": "ffmpeg",
  "parameters": "-i {streamUrl} -user_agent {userAgent} -vf scale=-2:720 -c:v libx264 -preset veryfast -c:a copy -f mpegts pipe:1",
  "is_active": true
}

Downscales video to 720p, copies audio stream.

Streamlink Integration

Streamlink Best Quality

{
  "name": "Streamlink Best",
  "command": "streamlink",
  "parameters": "--http-header 'User-Agent={userAgent}' --stdout {streamUrl} best",
  "is_active": true
}

Uses Streamlink to extract and stream best quality variant.

Streamlink with Retry

{
  "name": "Streamlink Resilient",
  "command": "streamlink",
  "parameters": "--http-header 'User-Agent={userAgent}' --retry-streams 3 --retry-max 10 --stdout {streamUrl} best",
  "is_active": true
}

Adds retry logic for unstable streams.

VLC Backend

VLC Streaming

{
  "name": "VLC Transcode",
  "command": "vlc",
  "parameters": "{streamUrl} --http-user-agent {userAgent} --sout '#standard{access=file,mux=ts,dst=-}' vlc://quit",
  "is_active": true
}

Uses VLC for stream processing and output.

Custom Scripts

Custom Processing Script

{
  "name": "Custom Handler",
  "command": "/usr/local/bin/stream-processor.sh",
  "parameters": "{streamUrl} {userAgent}",
  "is_active": true
}

Executes custom script with stream URL and User-Agent as arguments.

Profile Assignment

Stream profiles can be assigned at multiple levels:

1. System Default

   Set in Settings > Stream Settings > Default Stream Profile

   Accessible via CoreSettings.get_default_stream_profile_id()

2. M3U Account Level

   Assign profile to entire M3U source:

   m3u_account.stream_profile = profile
   

   All streams from this source inherit the profile.

3. Individual Stream

   Override on specific streams for granular control.

Profile precedence: Stream-level > M3U Account-level > System Default

Protected Profiles

System profiles with locked=True have restrictions:

if instance.locked:
    allowed_fields = {"user_agent_id"}  # Only this field can change
    
    for field in modified_fields:
        if field not in allowed_fields:
            raise ValidationError(
                f"Cannot modify {field} on a protected profile."
            )

Attempting to modify name, command, or parameters on locked profiles will raise a validation error.

Special Profile Detection

# Check if profile is built-in Proxy
if profile.is_proxy():
    return []  # No command execution needed

# Check if profile is built-in Redirect  
if profile.is_redirect():
    return redirect_response

These methods check both locked status and profile name:

def is_proxy(self):
    if self.locked and self.name == PROXY_PROFILE_NAME:
        return True
    return False

Command Building Process

1. Check for Proxy Profile

   If is_proxy() returns True, return empty command list

2. Define Replacements

   Create dictionary with {streamUrl} and {userAgent} values

3. Parse Parameters

   Use shlex.split() to handle quoted strings properly:

   shlex_split(self.parameters)
   
4. Apply Replacements

   Iterate through parsed parts and replace placeholders:

   cmd = [self.command] + [
       self._replace_in_part(part, replacements)
       for part in shlex_split(self.parameters)
   ]
   

User-Agent Handling

Profiles can reference a User-Agent model:

user_agent.name · string · required

Friendly name for the User-Agent

user_agent.user_agent · string · required

Complete User-Agent string:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

user_agent.description · string

Optional description of browser/device type

user_agent.is_active · boolean · default: true

Whether this User-Agent is currently allowed

If no profile User-Agent is set, falls back to:

user_agent_obj = UserAgent.objects.get(
    id=CoreSettings.get_default_user_agent_id()
)

Best Practices

Profile Naming

Use descriptive names that indicate:

• Backend: “FFmpeg”, “Streamlink”, “VLC”
• Purpose: “Transcode”, “Copy”, “Downscale”
• Quality: “720p”, “Best”, “Low Bandwidth”

Example: FFmpeg H.264 720p Transcode

Parameter Quoting

Use proper quoting for parameters with spaces:

# Correct:
--http-header 'User-Agent={userAgent}'

# Wrong:
--http-header User-Agent={userAgent}

The system uses shlex.split() which handles quoted strings correctly.

Testing Profiles

1. Create profile with minimal parameters first
2. Test with a single stream
3. Monitor CPU/memory usage
4. Verify output format compatibility
5. Add advanced parameters incrementally

Performance Considerations

• Stream copy (-c copy): Minimal CPU, fast
• Transcoding (-c:v libx264): High CPU, slower
• Hardware acceleration: Use GPU encoders when available
• Preset selection: Balance speed vs quality (veryfast, fast, medium)

Troubleshooting

Command Not Found

Ensure the executable is:

• Installed on the system
• In the system PATH
• Executable by the Dispatcharr user

Use full path if needed: /usr/bin/ffmpeg

Stream Buffering Issues

Add buffer-related parameters:

# FFmpeg buffering
-fflags +genpts -probesize 32 -analyzeduration 0

# Streamlink buffering
--ringbuffer-size 16M

Protected Profile Errors

If you see “Cannot modify X on a protected profile”:

• Only User-Agent can be changed on locked profiles
• Create a new profile instead of modifying system profiles
• Don’t attempt to delete Proxy or Redirect profiles