Castmux documentation

If you read one page, read two

Quick start gets a channel on air in about ten minutes. Troubleshooting covers the four faults that account for most support calls, three of which are network problems that look like software problems.

What Castmux does

A headend is the point where content becomes television. Castmux is a small one. It runs as a single process on a fanless appliance and performs four jobs:

Stage	What happens	Read more
Receive	Pull each channel from an HLS, SRT or RTMP origin, or take a plain MPEG-TS stream over UDP multicast or HTTP. On an HLS ladder, choose a quality rung deliberately instead of accepting whatever the origin lists first.	Channels and sources
Prepare	Produce a well-formed transport stream. Either pass the original PIDs, audio tracks and language descriptors through untouched, or remux where a downstream device demands it.	Streaming engines
Deliver	Send MPEG-TS to a multicast group for set-top boxes and smart TVs, and/or assemble several channels into a DVB-C multiplex on a real RF carrier.	UDP · DVB-C
Supervise	Watch each channel, measure what actually leaves the network port, restart what is genuinely broken, and refuse to restart what a restart cannot fix.	Monitoring

What Castmux does not do

Worth establishing before you invest an afternoon. None of the following are oversights; each is a decision with a reason, and each is stated so you can rule the product out early rather than at commissioning.

• It does not transcode. Video and audio are passed through, never re-encoded. This is why 25 channels fit on a 2 GB appliance and why picture quality is exactly what your provider sent. If you need one 4K feed turned into five bitrates, you need a different class of machine.
• It cannot recover what the source does not carry. If the origin sends one audio track, no engine setting produces a second one.
• It does not descramble. There is no DVB-CI or CAM support. Sources must arrive in the clear.
• It has no conditional access system. Full DVB Simulcrypt with an ECMG is out of scope. BISS scrambling is on the roadmap.
• It is not a CDN. The scale target is one building, not one region.

Where to start

🚀 Quick start Install, log in, add one channel, confirm packets are actually on the wire. About ten minutes. 📐 Requirements Measured figures for memory, CPU and network per channel — and the capacity cliff you must not walk off. 📦 Installation Container deployment, the capabilities it needs and why, multicast routing, and the watchdog. 📡 DVB-C multiplexing Turn a set of IP channels into a real cable carrier on the coax already in the walls. 👥 On-demand streaming How Castmux detects real viewers and runs only the channels somebody is watching. 🩺 Troubleshooting Green dashboard, blank televisions. Pixelation. Restart loops. Channels that will not start.

Conventions in this manual

Features that are shipping today carry no marker. Features that are committed but not yet released are marked roadmap and appear on the roadmap page with a target release. Nothing in this manual describes behaviour that does not exist — if a page says Castmux does something, it does it now.

Command examples assume a Linux host with a container runtime. Where a value must be replaced, it appears in angle brackets, like <your-config-dir>.

A note on multicast

Most difficulties with this product are not with this product. Multicast fails in ways that are invisible from inside a streaming process: sending to an unroutable group succeeds, so every counter reads healthy while nothing arrives. Castmux checks for this from outside and reports it, but if you are new to multicast, read Troubleshooting → multicast routing before you install rather than after.