Channels and sources

What a channel is

One source plus one destination. The source is a URL Castmux pulls from; the destination is an IPv4 address and port it pushes MPEG-TS to. Everything else on the channel — engine, resolution profile, on-demand behaviour, expected bitrate — modifies how that one pipe is run, not what it carries.

Channels are independent. Each one is supervised on its own, restarted on its own, and measured on its own, so a dead origin on one channel does not disturb the others.

Source types

Three input protocols are supported today: HLS, SRT and RTMP. Everything else in the table below is planned rather than present.

Source	Status	Notes
HLS	Supported	Master playlist or a single media playlist. See resolution profiles for how a rung is chosen.
SRT	Supported	Caller mode, configured entirely from the URL. Latency is derived automatically.
RTMP	Supported	Remux engine only. Typically a local encoder pushing into the appliance's network.
UDP / RTP multicast input	Roadmap	Re-receiving an existing multicast feed. roadmap
HTTP MPEG-TS	Roadmap	A plain transport stream over HTTP, without a playlist. roadmap
RTSP cameras	Roadmap	For lobby, chapel and CCTV feeds. roadmap
DVB-S/C/T tuner input	Roadmap	Taking services off air rather than off IP. roadmap

HLS sources

Give the channel a master playlist URL. Castmux reads the ladder it advertises and selects one variant to hand to the engine, according to the channel’s resolution profile. With no profile set — the default, and what every pre-existing channel has — the master playlist is passed through unchanged and the origin’s ordering decides.

The starting position at the live edge is configurable. Starting further back in the playlist buys resilience against an origin that publishes segments irregularly, at the cost of a longer delay behind live and a slower first picture after a channel change.

fMP4/CMAF origins need the remux engine

The pass-through engine’s HLS reader handles MPEG-TS segments only. If the origin publishes fragmented MP4 (CMAF) segments, that channel must use the remux engine. This is a property of the reader, not a setting — no combination of options makes the pass-through engine parse fMP4. See Streaming engines.

SRT sources

SRT channels run in caller mode: Castmux connects out to the origin. The whole configuration lives in the URL, and the following query parameters are translated to the engine:

streamid, passphrase, transtype, latency, rcvlatency, peerlatency, rcvbuf, sndbuf, maxbw, pbkeylen, payloadsize, tlpktdrop, linger.

srt://origin.example.net:9000?streamid=play/news&passphrase=••••••••&transtype=live

Automatic latency

Castmux measures the round-trip time to the origin host and sets the SRT latency budget to four times the measured RTT, with a floor of 200 ms and a ceiling of 4000 ms. Any latency value present in the URL is replaced.

This exists because the usual default of 120 ms is wrong on any link with real jitter, and because the resulting failure is one nobody attributes to latency. An undersized budget does not break the channel; it produces intermittent artefacting — a few seconds of blocking every so often, at no predictable interval, on a channel whose dashboard is entirely green. Sites chase the encoder, the switch and the television for weeks before anyone suspects a transport setting that was copied from another installation with a shorter path.

The multiplier is the conventional SRT recommendation: a receiver must be able to wait out a retransmission, which costs a full round trip, with room for a second attempt. The floor stops a very short link from getting a budget too small to absorb any loss at all; the ceiling stops one bad measurement from adding seconds of delay to a channel.

If you would rather pin the value yourself, turn the behaviour off with overwrite_srt_latency: false in the global configuration, and the latency in the URL is left alone.

Listener and rendezvous modes

Both are reachable today by passing engine parameters in the URL, but they are not modelled in the interface: there is no field that says “listen on this port”, and nothing validates what you type. First-class support for listener and rendezvous channels is roadmap.

RTMP sources

RTMP is supported on the remux engine, and is normally used for a local encoder on the same network as the appliance rather than for a feed arriving over the internet.

RTMP does not work on the pass-through engine

This is not a tuning problem or a missing option. If you set an RTMP channel to the pass-through engine it will not run. Leave such channels on the remux engine, or set the engine override on the channel if your global default is pass-through.

The destination

One IPv4 address and one port. The address may be a multicast group, which is the normal case for television distribution, or a unicast address for a single receiver or a test.

For multicast, use the administratively scoped range 239.0.0.0/8. It is reserved for exactly this purpose — private, organisation-local use — so nothing you choose inside it can collide with a well-known assignment.

Never use 224.0.0.0/24 for content

That range is reserved for link-local control protocols: routing adjacency, IGMP itself, and neighbour discovery all live there. Packets addressed to it are sent with a TTL of one and are processed by every device on the segment. Putting a television channel there floods control-plane traffic across your switches and will disrupt the network long before anyone notices the picture is missing.

One destination per channel today. Sending the same channel to several groups — for example one multicast group and one unicast probe — requires a second channel with the same source URL. Multiple destinations per channel is roadmap.

Per-channel settings

active

Whether the channel is under supervision at all. An inactive channel keeps its configuration but is never started and produces no metrics.

force_always_on

Keep the channel running whether or not anybody is watching. The default is off, which means on-demand: the channel runs only while a viewer is detected on its group. Set this for channels that must never take the cold-start delay on a channel change. See On-demand streaming.

engine

Override the global engine choice for this channel. Empty means inherit. See Streaming engines.

resolution_profile

Which rung of an HLS ladder to take. Empty means take the master playlist unchanged. Ignored for SRT and RTMP, which carry no ladder. See Resolution profiles.

min_output_kbps

The output bitrate below which this channel is treated as not producing anything, and therefore as needing a restart.

Radio channels need the bitrate floor lowered

The global default for the minimum expected output bitrate assumes video. An audio-only service is legitimately far below it — 128 kbps is an ordinary radio bitrate — so with the global floor in place it is declared silent on every check and restarted forever while working perfectly. Set min_output_kbps on that channel to a value comfortably under its real rate.

Naming a channel

The channel name is not only a label in the interface. It becomes the DVB service name carried in the SDT, which is what a television displays in its channel list, and it is the label attached to every metric the channel produces.

That second consequence is the one that catches people out: renaming a channel renames its metric series. Historical data does not follow the rename, so a dashboard or alert keyed on the old name goes quiet, and a graph of the channel appears to start from nothing. Decide on names before you build dashboards, and treat a rename as an operation with a downstream cost rather than a cosmetic edit.

Channel identity

Channels are identified by an integer id. That id appears in the configuration file, in the HTTP API, and anywhere a channel is referenced from outside.

Ids are currently reused after a delete. If you delete channel 7 and then add a new channel, the new one can be given id 7. It is a different channel in every respect an operator cares about — different name, different source, different destination — but everything keyed on the id sees continuity where there is none.

The practical consequences are worth knowing before you rely on ids:

• Anything storing per-channel state against the id — an external scheduler, a saved API call, a bookmark in the interface — can end up pointed at the wrong channel after a delete-and-add cycle.
• Browsers restore form control state on a soft reload independently of what the server rendered, so a newly created channel can briefly display a setting inherited from the deleted channel that held its id. What the badge beside the control says is the truth.
• On DVB-C, service identity is derived from position in a multiplex rather than from the channel id, so reordering or removing a channel moves the services around it.

Stable, non-reused identifiers and pinned service identity are roadmap. Until then, the safe rule is: an id identifies a slot, and a name identifies a channel.

Worked example

Two channels in config.yaml — one HLS with a resolution profile, one SRT with a lowered bitrate floor because it is a radio service:

streams:
  - id: 1
    name: BBC One
    description: Reception and lounge
    active: true
    source:
      type: hls
      url: https://origin.example.net/bbcone/master.m3u8
    destination:
      address: 239.1.1.10
      port: 5000
    # Televisions here are 720p panels; the origin lists 1080p first.
    resolution_profile: hd
    force_always_on: true

  - id: 2
    name: Classic FM
    description: Audio only
    active: true
    source:
      type: srt
      url: srt://origin.example.net:9000?streamid=play/classicfm&transtype=live
    destination:
      address: 239.1.1.11
      port: 5000
    # Radio: well under the video-oriented global floor, so lower it or the
    # channel is treated as silent and restarted forever.
    min_output_kbps: 64
    force_always_on: true

No latency is given on the SRT URL because Castmux derives it from the measured round trip. No engine is given on either channel, so both inherit the global default.