User Guide

Channels

From the channels page you can create and manage all added channels, streams, and external links

Channels

• Search channel names by clicking in the "Name" column header
• Search by channel group by clicking in the "Group" column header
• Edit a channel by clicking the corresponding "Edit Channel" icon under the "Actions" column
  • Channel Name - Edit the name for your Channel
  • Channel Group - Edit the group for your channel. If you want to create and add to a new group, click the icon
  • Stream Profile - Click here if you want to use something other than the default stream profile for this channel
  • Logo - Choose a logo or upload a new one
  • Channel # - Edit the channel number. Currently only integers are accepted
  • TVG-ID - Edit the TVG-ID field for your channel. Auto-match tries to match episode guide to this field
  • Gracenote StationID - Edit the Gracenote ID for your channel. These are typically 5 or 6 digit numbers that Gracenote (a common EPG provider) can use to identify TV channels.
  • EPG - Click in the box to manually choose an EPG entry, or click "Use Dummy" to assign a dummy EPG entry
• Delete a channel by clicking the corresponding "Delete channel" icon under the "Actions" column
• Preview (play) a channel by clicking the corresponding "Preview channel" icon under the "Actions" column
• Toggle the channel check boxes to use the bulk editing buttons above the grid on the selected channels, or to add streams to channels
  • " Remove" to bulk remove channels
  • " Assign" to assign channel numbers

  Warning

  Currently channel number will start with 1 and auto-increment by 1 for each selected channel. This feature is still under development

  • " Auto-Match" to auto match channels to EPG
  • Click the "Add to channel" icon under the Streams Actions column to add that stream to the selected channels

Streams

• Search stream names by clicking in the "Name" column header
• Search by M3U group by clicking in the "Group" column header
• Search by M3U name by clicking the "M3U" column header
• Create a new channel by clicking the corresponding "Create New Channel" icon under the "Actions" column
• Add a stream to an existing channel by clicking the corresponding "Add to Channel" button under the "Actions" column
• Preview (play) a stream by clicking the corresponding icon under the "Actions" column, then press "Preview Stream"
• Toggle the stream check boxes to use the bulk editing buttons above the grid on the selected streams
  • " Add streams to channel" to add the checked streams to the checked channel(s)
  • " Remove" to bulk remove streams
  • " Create Channels" to create a new channel for each selected stream

  Note

  For every selected stream, a corresponding new channel will be created. For example, if 3 streams are selected, 3 new channels will be created.

• " Create Stream" to create a new stream not associated with any of your uploaded M3Us

Links

The "Links" section has buttons to see and copy the external links needed by a client

• HDHR - Use this link for clients that use HD Homerun format
• M3U - Use this link for clients that use M3U format
  • Advanced options
    1. Bypass logo caching by adding the following to your URL ?cachedlogos=false (Default true)
    2. Set what is used for the TVG-ID field (Options: channel_number (default), tvg_id, gracenote) ?tvg_id_source=gracenote
    3. URLs output in the M3U will be the direct URL from the first stream in the channel list ?direct=true (Default false)
    4. Combine multiple options ?cachedlogos=false&tvg_id_source=gracenote
• EPG - Use this link to provide your client with episode guide data that matches your channels
  • Advanced options
    1. Bypass logo caching by adding the following to your URL (useful for Plex) ?cachedlogos=false
    2. Use Gracenote ID's for TVG-ID's by adding the following to your URL (useful for Emby) ?tvg_id_source=gracenote
    3. Number of days to output the epg for ?days=4 (Default 0 = all)
    4. Combine multiple options ?cachedlogos=false&tvg_id_source=gracenote&days=7

---

M3U & EPG Manager

From this page you can add and maintain your M3U accounts and EPGs

M3U accounts

• " Add" - Click this button to add new M3U accounts
  • Name - A name for your M3U account
  • URL - The M3U URL (not required if uploading an M3U file)
  • Account Type - Standard for direct M3U URLs, Xtream Codes for panel-based services
  • Upload files - If uploading a local M3U file (not required if M3U URL is used)
  • Max Streams - Set a number for the max number of concurrent streams allowed for your account. For unlimited, set to 0
  • User-Agent - If you want to set a specific user-agent for this account
  • Refresh Interval (hours) - How often (in number of hours) to refresh the M3U URL
  • Stale Stream Retention (days) - Streams not seen for this many days will be removed
  • Is Active - Toggle whether this account is active or not

  Note

  M3Us can be automatically added into dispatcharr by adding M3U file(s) into the /data/m3us folder

• You can click column headers to change the sort order of existing M3U accounts

• Actions column

  • edit icon to edit the associated M3U account

    • "Groups" button - Allows you to filter streams from the M3U based on the listed groups
    • "Profiles" button - Allows you to add a second set of credentials for the same provider.

    Example

    Let's say you have 3 accounts you want to add to dispatcharr. 2 from Provider-A and 1 from Provider-B. Rather than adding three separate M3U accounts, you could add Provider-A once and set up a profile to use the username and password from each Provider-A account under the same M3U account.
    1. Set up Provider-A as an M3U account in the M3U & EPG manager.
    2. Click the corresponding yellow edit icon under the Actions column.
    3. Click the "Profiles" button.
    4. Click the "New" button.
    5. Copy the text under "Search" at the bottom of the dialog box, and paste into the "Search" box.
    6. Paste the same text into the "Replace" box. Within the text, you should see something like "username=XXXXXXX&password=YYYYYYY".
    7. Replace the XXXXXXX and YYYYYYY with the username and password with the credentials from your second Provider-A account.

  • delete icon to remove the associated M3U account

  • refresh icon to manually refresh/update the associated M3U account

EPGs

• " Add EPG" - Click this button to add a new EPG
  • Name - A name for your EPG
  • URL - The URL for your EPG
  • API Key - API key associated with your EPG, if required
  • Source Type - Choose XMLTV or Schedules Direct depending on your EPG provider format
  • Refresh Interval (hours) - How often (in number of hours) to refresh the EPG

  Note

  EPGs can be automatically added into dispatcharr by adding EPG file(s) into the /data/epgs folder

• You can click column headers to change the sort order of existing EPGs
• Actions column
  • edit icon to edit the associated EPG
  • delete icon to remove the associated EPG
  • refresh icon to manually refresh/update the associated EPG

---

TV Guide

• The TV Guide page will by default display channels for which there is EPG data loaded.
• You can search by channel name and/or filter by channel groups and profiles.
• Click a channel logo to preview the channel.
• Click guide entries to expand guide data, preview the channel, or set to record.

Note

You can record by channel and time from the DVR page

---

DVR

• The DVR page allows you to manage your current and future recordings and set new recordings based on channel and time.

---

Stats

• The Stats page shows info on all active streams
  • Channel name
  • Stream profile
  • Stream uptime
  • Stream speed (current and average)
  • Stream total data served
  • Number of watchers
  • IP addresses and associated User-Agents
• You can force stop any current streams by clicking the "Stop Channel" button

---

Settings

Stream Settings

• Default User-Agent - Set the default User-Agent
• Default Stream Profile - Set the default Stream Profile
• Preferred Region - Set your preferred region
• Auto Import Mapped Files - Toggle on/off auto-importing of M3U files or EPG xml data from /data/epgs and/or /data/m3us
• M3U Hash Key - Set how to hash your M3U. This affects the Stale stream cleanup.

User-Agents

• In the context of IPTV, a user agent is a string of text that identifies the client application (e.g., a player like Kodi or VLC) to the IPTV server. It's included in the HTTP headers of requests sent by the client to the server, informing the server about the type of device and software used to access the IPTV stream.
• Default Dispatcharr User-Agents are available for VLC, Chrome, and TiviMate
• Add your own User-Agent by clicking the " Add User-Agent" button on the Settings page
  • Name - a name for your user-agent
  • User-Agent - The text to include for your user-agent string
  • Description - (Optional) a description of the user-agent for your own use

Stream Profiles

• There are 4 default stream profiles with the ability to create your own custom ones
  • ffmpeg - Dispatcharr will proxy streams via ffmpeg. No transcoding takes place with the default ffmpeg stream profile, it will just remux streams. Uses more system resources than proxy
  • Proxy - Proxies the original streams, allowing you to use Dispatcharr features (redundant streams per channel), and adds a slight buffer to help with stream stability. Uses fewer system resources than ffmpeg
  • Redirect - Redirects the original M3U stream URL to your client. There is no proxying with this profile
  • streamlink - For custom streams based on the services supported by streamlink
• Custom Stream Profiles - create your own custom stream profile by clicking the "Add Stream Profile" button on the Settings page
  • Name - a name for your stream profile
  • Command - ffmpeg or streamlink
  • Parameters - Set your custom ffmpeg or streamlink parameters
  • User-Agent - Set the default user-agent for this stream profile

---

Advanced

Hardware Acceleration

• Dispatcharr does not currently support hardware acceleration directly, but you can use hardware acceleration with custom ffmpeg stream profiles.
• This will require mapping your hardware to the container and setting up a custom ffmpeg stream profile.

Mapping Hardware

NVIDIAIntelNVIDIA (Unraid)Intel (Unraid)

• Install the NVIDIA Container toolkit
• Add a deploy section to your docker-compose.yml

Example

services:
  dispatcharr:
    # build:
    #   context: .
    #   dockerfile: Dockerfile
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr
    ports:
      - 9191:9191
    volumes:
      - dispatcharr_data:/data
    environment:
      - DISPATCHARR_ENV=aio
      - REDIS_HOST=localhost
      - CELERY_BROKER_URL=redis://localhost:6379/0
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
volumes:
  dispatcharr_data:

• Add a devices section to your docker-compose.yml

Example

services:
  dispatcharr:
    # build:
    #   context: .
    #   dockerfile: Dockerfile
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr
    ports:
      - 9191:9191
    volumes:
      - dispatcharr_data:/data
    environment:
      - DISPATCHARR_ENV=aio
      - REDIS_HOST=localhost
      - CELERY_BROKER_URL=redis://localhost:6379/0
    devices:
      - /dev/dri:/dev/dri

volumes:
  dispatcharr_data:

• Install the NVIDIA Driver Package plugin from community apps if not already installed
• Edit the Dispatcharr docker container in Unraid
  • Toggle Advanced View On
  • Go to Extra Parameters
    • Add --runtime=nvidia
  • Scroll down and click "Add another Path, Port, Variable, Label or Device"
    • Config Type: Variable
    • Name: NVIDIA_VISIBLE_DEVICES
    • Key: NVIDIA_VISIBLE_DEVICES
    • Value: all
  • Click Save
  • Again click "Add another Path, Port, Variable, Label or Device"
    • Config Type: Variable
    • Name: NVIDIA_DRIVER_CAPABILITIES
    • Key: NVIDIA_DRIVER_CAPABILITIES
    • Value: all
  • Click Save

• Edit the Dispatcharr docker container in Unraid
• Scroll down and click "Add another Path, Port, Variable, Label or Device"
  • Config Type: Device
  • Name: /dev/dri
  • Key: /dev/dri
  • Description: Intel GPU
• Click Save

Custom Stream Profiles

• Open Dispatcharr

• Navigate to Settings > Add Stream Profile

  • Name it anything you like
  • Command ffmpeg
  • Parameters will vary based on your hardware type and streaming needs
    • See ffmpeg docs for more
  • Visit our discord for more user-submitted ffmpeg parameters
  NVIDIAIntel VAAPIIntel QSV

  Example

  • Parameters: -user_agent {userAgent} -hwaccel cuda -i {streamUrl} -c:v h264_nvenc -c:a copy -f mpegts pipe:1

  Example

  • Parameters: -user_agent {userAgent} -hwaccel vaapi -hwaccel_output_format vaapi -hwaccel_device /dev/dri/renderD128 -i {streamUrl} -c:a aac -c:v h264_vaapi -f mpegts pipe:1

  Example

  • Parameters: -hwaccel qsv -user_agent {userAgent} -i {streamUrl} -c:v h264_qsv -c:a aac -f mpegts pipe:1

Nginx reverse proxy

HTTPS config example (streams only)

# Dispatcharr HTTPS DynuDNS
server {
    listen 443 ssl;
    server_name dispatcharr.yourdomain.com;  #Adjust for your domain

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location /proxy/ts/stream/ {
        allow all;  # Allow everyone else
        proxy_pass http://ubuntuserver:9191;  # Adjust for your server name or IP
        proxy_set_header Host $host:443;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # CORS settings
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Origin, Content-Type, Accept';
    }

    location / {
        allow 10.0.0.0/22;  # Allow the entire network, adjust for your network
        allow 10.1.0.0/24;  # Allow Wireguard, adjust for your network
        deny all;  # Deny everyone else
        proxy_pass http://ubuntuserver:9191;  # Adjust for your server name or IP
        # WebSocket headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host:443;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # CORS settings
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Origin, Content-Type, Accept';
    }
}