On-demand streaming

Why it matters

Memory is the binding constraint on these appliances, not CPU. Every running channel holds a decoder or a demultiplexer, buffers and a socket, and that cost is paid whether or not a television is listening. In a hotel with a hundred rooms and forty channels, the number of distinct channels being watched at three in the morning is usually two or three.

Running only what is watched converts idle channels back into headroom. It also cuts the load on the uplink, because a channel that is not running is not pulling segments from the origin.

How viewers are detected

When a television tunes to a multicast channel it announces itself with an IGMP membership report, and when it tunes away it sends a leave. Those messages are the only reliable evidence that somebody is watching, because nothing downstream of the appliance reports back in any other way. Castmux therefore watches IGMP traffic on the interface facing the televisions.

It does this with packet capture, in promiscuous mode, using libpcap. That choice is not arbitrary and it is worth understanding, because the obvious alternative — a raw IPPROTO_IGMP socket — does not work at all.

Why a raw IGMP socket cannot see other hosts

Membership traffic is not addressed to this machine. It is addressed to multicast groups that this machine has, in general, not joined:

Message	Destination	Consequence
IGMPv3 report	224.0.0.22	The all-routers-v3 group. A headend is not a router and has no reason to have joined it.
IGMPv2 leave	224.0.0.2	The all-routers group. Same problem.
IGMPv2 report	the group being joined	Addressed to, for example, 239.10.0.1 — a group the sender is joining and the appliance is only ever sending to.

Linux discards multicast destined for a group the host has not joined inside the input routing path, before delivery to any socket. A raw socket is a delivery endpoint; the packet is gone long before it gets there. No socket option changes this. The socket opens cleanly, reads block forever, and the resulting bug reads as “nobody is ever watching” rather than as an error.

All-multicast mode is not the fix either

Enabling all-multicast on the interface stops the network card filtering unjoined groups in hardware, so the frames reach the kernel. They are still dropped by the kernel’s own membership check a moment later. It relaxes the card’s filter and leaves the one that matters in place, which makes it a convincing-looking dead end.

Packet capture sits below that check, at the point where frames arrive, so it sees the traffic regardless of what the host has joined. This is why Castmux needs the capability to capture raw packets and why the container is run with host networking — see Installation.

What is tracked, and what is ignored

Only the destination groups configured on your channels are tracked. A building’s network carries a great deal of unrelated multicast — mDNS service discovery, SSDP from printers and smart televisions, routing protocol chatter — and none of it counts as a viewer. Membership for a group Castmux does not serve is discarded.

Castmux also distinguishes its own traffic from a viewer’s. Sending to a group is not watching it; a channel does not keep itself alive.

Active querying

A client sends an unsolicited report when it joins, and then says nothing until something asks it to. On a properly routed network the IGMP querier — normally the router — asks periodically, and any listener can reconstruct the membership table from the answers.

The segments these appliances live on usually have no querier. There is no router on the television VLAN, the switches are doing snooping at best, and nothing sends general queries. In that state a listener only ever hears about a join at the moment it happens. Restart Castmux, or install it into a building where televisions are already tuned, and it knows about nobody: every existing viewer is invisible until they change channel.

Castmux therefore sends its own IGMP general queries, by default every 30 seconds, and builds the membership table from the replies. This is what makes viewer state survive a restart and what makes the viewer count correct within one query interval of starting up rather than eventually.

Turn active querying off if your network already queries

IGMP defines a querier election, and a device that sends general queries takes part in it. On a dedicated television segment with no other querier that is exactly what you want. On a shared LAN where a router or a snooping switch is already the querier, adding a second one means the two elect between themselves, and the winner’s timers govern the segment. If your switches already query, disable active querying and let them. Castmux will still see every join and leave; it simply will not prompt for them.

Timers

Three timers govern the behaviour. The defaults suit a set-top-box estate on a quiet segment; the reason to change one is a specific observed symptom, not tidiness.

Timer	Default	What it controls
Grace	90 s	How long a known viewer may stay silent before it is treated as gone. It must comfortably exceed the query interval, so that a single lost query or a single lost reply does not evict a television that is still watching. Raise it if you see viewers flicker in and out on a lossy segment.
Linger	30 s	How long a channel keeps running after its last viewer leaves. Channel-hopping is the normal case: a guest steps through six channels in twenty seconds and comes back. Linger makes the return instant instead of paying a fresh cold start each time.
Query interval	30 s	How often Castmux sends a general query when active querying is enabled. Shorter means faster recovery of the membership table and more traffic; longer means the opposite. Change grace with it, not independently.

What linger is protecting you from

A cold start is the interval between the join arriving and the first packet leaving for the television. Measured on the appliance, it is about 1.9 seconds on the pass-through engine and about 4.4 seconds on the remux engine. See Streaming engines for why they differ.

Neither figure is objectionable once. Paid six times in twenty seconds by somebody stepping through the line-up, it is the difference between a television that feels like a television and one that feels broken. That is the whole argument for the linger timer, and it is why the default is not zero.

Fail open

If packet capture cannot start — the capability is missing, the interface is wrong, the library is unavailable — Castmux keeps streaming every channel rather than concluding that nobody is watching.

The principle

On the streaming path, a broken watcher must degrade to always-on, never to a black screen. A failure in an optimisation should cost memory, not television. Every component that can decide to stop a stream is built this way.

The behaviour is configurable, because there are estates where an operator would genuinely rather a channel stopped than ran unsupervised. The default is to fail open and it should stay that way unless you have a concrete reason otherwise.

When detection is impaired, Castmux marks itself degraded and says so in the interface. This matters more than it sounds: without it, “0 viewers” is ambiguous between “nobody is watching” and “I cannot tell”, and an operator will read the first meaning every time. A degraded indicator turns a silent wrong answer into a visible unknown.

Per-channel override

force-always-on makes a single channel run continuously, whatever the viewer count says. Reach for it when the consumer of the stream is not something that can join a group:

• A channel feeding a DVB-C multiplex. The multiplexer consumes the stream continuously and does not issue membership reports on its behalf. An on-demand channel in a multiplex is a gap in the carrier. See DVB-C multiplexing.
• A lobby or signage screen behind a device that does not do IGMP properly, or that must never show a start-up delay.
• While commissioning. During installation you want the stream on the wire so you can measure it, before viewer detection is a variable in the diagnosis. Turn it back off when you are done.

A forced channel is shown as forced in the interface, so it is clear that its running state is an instruction rather than a measurement.

Preview counts as a viewer

Opening the preview in the web interface registers as a viewer for that channel, so an on-demand channel starts when you preview it and stays up while the preview is open. Without this, previewing an idle channel would show nothing and previewing a live one would keep it alive by accident — both confusing. Closing the preview lets the normal linger timer run.

When to turn it off

On-demand is not free complexity, and there are two cases where it buys nothing:

• A small always-on line-up on a box with spare memory. If eight channels fit comfortably and all eight are watched most of the day, on-demand adds a start-up delay on the first tune of the morning and saves nothing you needed. Run them always-on.
• A segment where you cannot capture traffic. If the appliance cannot see the televisions’ IGMP — because it is not on their layer 2 segment, or because the deployment forbids promiscuous capture — viewer detection has nothing to work with. It will fail open and stream everything anyway, but you should turn it off explicitly rather than leave a permanently degraded indicator, which trains operators to ignore warnings.

Everywhere else, the memory it returns is the reason the channel count on these appliances is what it is.