Channel Management

Manage and organize live TV channels with advanced features including multi-stream support, EPG integration, and automatic failover

Dispatcharr provides powerful channel management capabilities for organizing and streaming live TV content from multiple sources.

Overview

Channels in Dispatcharr are virtual channel assignments that can pull streams from one or multiple M3U sources. Each channel has:

• Channel Number: Unique identifier for the channel (supports decimals like 2.1)
• Name & Logo: Display information for the channel
• Multiple Streams: Assign multiple streams with automatic failover
• EPG Integration: Link channels to Electronic Program Guide data
• Stream Profiles: Control transcoding and streaming behavior
• Access Control: User-level restrictions and adult content filtering

Channel Structure

Channels are organized into a flexible hierarchy:

Channels

Virtual channel assignments with unique channel numbers

Channel Groups

Organize channels into categories (Sports, News, Movies, etc.)

Streams

Actual stream sources from M3U accounts

Channel Profiles

Control which channels are enabled for specific users

Creating Channels

1. Navigate to Channels

   Go to the Channels page in the Dispatcharr interface

2. Add New Channel

   Click the “Add Channel” button and provide:

   • Channel number (auto-assigned if not specified)
   • Channel name
   • Optional logo URL
   • Channel group assignment
3. Assign Streams

   Add one or more streams from your M3U accounts:

   • Streams are tried in order
   • Automatic failover if primary stream fails
   • Each stream can have its own profile
4. Configure EPG

   Link the channel to EPG data:

   • Auto-match using TVG ID
   • Manual EPG data assignment
   • Configure Schedules Direct integration

Stream Assignment & Failover

Multiple Stream Sources

Channels support multiple streams with automatic failover:

# From channels/models.py
class Channel:
    streams = ManyToManyField(Stream, through="ChannelStream")
    
class ChannelStream:
    order = PositiveIntegerField(default=0)  # Priority order

How it works:

1. Primary Stream: First stream in the order is tried
2. Failover: If unavailable, next stream is attempted
3. Profile Selection: Each M3U account can have multiple profiles with connection limits
4. Redis Tracking: Active streams tracked in Redis for connection management

Streams are selected based on order and profile availability. If all profiles for a stream are at maximum connections, the next stream in order is tried.

Connection Management

Dispatcharr intelligently manages stream connections:

Profile Connection Limits

Each M3U profile has a max_streams setting:

• 0: Unlimited connections
• N: Maximum N concurrent connections

When a profile reaches its limit, Dispatcharr automatically tries:

1. Other profiles on the same M3U account
2. Next stream source in the channel’s stream list

Stream Selection Algorithm

For each stream in channel.streams (ordered):
  Get M3U account
  If account is inactive: skip
  
  Get profiles (default profile first)
  For each active profile:
    Check connection count
    If available slots:
      Assign stream
      Increment connection counter
      Return stream + profile
  
If no available streams:
  Return error with specific reason

Channel Groups

Organize channels into logical categories:

• Auto-Sync: Automatically create/delete channels from M3U groups
• M3U Mapping: Link M3U account groups to channel groups
• Custom Organization: Override automatic grouping

Auto Channel Sync

When enabled, auto channel sync will automatically create and delete channels to match the streams in the linked M3U group. This is useful for providers that frequently update their channel lineup.

# From channels/models.py
class ChannelGroupM3UAccount:
    auto_channel_sync = BooleanField(default=False)
    auto_sync_channel_start = FloatField()  # Starting channel number
    last_seen = DateTimeField()  # Stale detection
    is_stale = BooleanField()  # Mark for cleanup

EPG Integration

Link channels to Electronic Program Guide data:

Manual EPG Assignment

class Channel:
    epg_data = ForeignKey(EPGData)  # Direct EPG link
    tvg_id = CharField()  # TVG identifier
    tvc_guide_stationid = CharField()  # Schedules Direct ID

Auto-Matching

Dispatcharr can automatically match channels to EPG sources:

1. By TVG ID: Matches tvg_id field
2. By Name: Fuzzy matching on channel name
3. Priority: EPG sources have priority levels for conflict resolution

Run EPG matching from the Channels page or configure automatic matching when importing EPG data.

Stream Profiles

Control how channels are streamed to clients:

Profile Assignment

Profiles can be assigned at multiple levels:

1. Channel Level: channel.stream_profile - Overrides default
2. Stream Level: stream.stream_profile - Per-stream configuration
3. Default Profile: System-wide default from CoreSettings

Profile Features

Proxy

Pass-through streaming with minimal processing

Redirect

Direct client to original stream URL

Transcoding

FFmpeg transcoding with custom parameters

Custom Backends

Use Streamlink, VLC, or custom scripts

Advanced Features

Adult Content Filtering

class Channel:
    is_adult = BooleanField(default=False)

Channels marked as adult can be:

• Hidden from specific users
• Filtered in playlist exports
• Restricted by network access rules

Custom Properties

Store arbitrary metadata:

class Stream:
    custom_properties = JSONField(default=dict)

Use cases:

• Provider-specific metadata
• Custom integration data
• Plugin extensions

Recording & DVR

Schedule recordings for channels:

One-Time Recordings

class Recording:
    channel = ForeignKey(Channel)
    start_time = DateTimeField()
    end_time = DateTimeField()
    task_id = CharField()  # Celery task ID

Recurring Rules

class RecurringRecordingRule:
    channel = ForeignKey(Channel)
    days_of_week = JSONField()  # [0-6]
    start_time = TimeField()
    end_time = TimeField()
    enabled = BooleanField()
    start_date = DateField()  # Optional date range
    end_date = DateField()

Real-World Use Cases

Consolidate Multiple Providers

Channel: CNN (2.0)
├── Stream 1: Provider A → Profile A (2 connections max)
├── Stream 2: Provider B → Profile B (5 connections max)
└── Stream 3: Backup Provider → Profile C (unlimited)

When viewer connects:
1. Try Provider A/Profile A → Success if < 2 connections
2. Else try Provider B/Profile B → Success if < 5 connections  
3. Else try Backup Provider → Always succeeds

Geographic Redundancy

Channel: BBC One (100.0)
├── UK Provider (Primary)
├── EU Provider (Backup)
└── Global CDN (Fallback)

Auto-failover ensures uninterrupted streaming

Custom Channel Ordering

Channel numbers support decimals:
- 2.0: Main NBC feed
- 2.1: NBC East Coast
- 2.2: NBC West Coast
- 2.5: NBC 4K

API Operations

Channels can be managed via REST API:

List Channels

GET /api/channels/

Filter by group, search, ordering

Create Channel

POST /api/channels/

Auto-assigns next available channel number

Update Channel

PATCH /api/channels/{id}/

Modify channel properties

Delete Channel

DELETE /api/channels/{id}/

Removes channel and stream assignments

Bulk Operations

• Match EPG: Auto-match channels to EPG data
• Assign Streams: Bulk assign streams to channels
• Update Properties: Batch update channel metadata
• Export: Generate M3U or XMLTV exports

All channel operations support real-time WebSocket updates to keep the UI in sync.