The web interface
Signing in
Section titled “Signing in”The interface listens on port 8080 by default. Credentials come from the environment variables CASTMUX_WEB_USERNAME and CASTMUX_WEB_PASSWORD set when the container is started; there is no separate user store and no first-run account wizard.
A successful sign-in sets a session cookie that lasts seven days. Seven days is chosen so that an operator who checks the headend weekly is not re-authenticating at every visit, while a laptop left in a cupboard eventually stops being a way in.
One account, today
Section titled “One account, today”There is a single administrator account. Everyone who signs in has full control: they can edit channels, change engine defaults and reboot the appliance.
This is not good enough for a site where reception staff and the installer both need access, and it is worth saying plainly rather than dressing up. Reception needs to see whether a channel is on air and perhaps restart it; they do not need the ability to change the egress interface. A shared password means either the installer’s credentials circulate among staff, or staff have no access at all and every trivial question becomes a call-out.
Multiple users with distinct roles are on the roadmap. Until then, the realistic mitigation is network-level: restrict which addresses can reach port 8080.
Layout
Section titled “Layout”The top navigation carries the four working areas and two controls:
| Item | What it is |
|---|---|
| UDP channels | The main page. One card per multicast channel. |
| HDMI channel | Configuration for the local HDMI output, if the appliance has one. |
| DVB-C | Multiplex configuration and modulator status. |
| Settings | Appliance-wide defaults and site identification. |
| Theme toggle | Light or dark. Stored in the browser, not on the appliance. |
| Sign out | Clears the session cookie. |
The footer
Section titled “The footer”The footer is present on every page and shows the appliance’s own condition: version, CPU load, memory use, CPU temperature and per-interface network bitrate. It refreshes every fifteen seconds.
Two of these are more useful than they first appear. CPU temperature matters because the reference hardware is fanless and lives in a cupboard, and a blocked vent shows up here weeks before it shows up as instability. Per-interface bitrate is the quickest way to confirm that traffic is leaving the interface you think it is: if the television-facing NIC shows nothing while the management NIC shows several megabits, the multicast route is pointing at the wrong place — see Installation → multicast routing.
The channels page
Section titled “The channels page”One card per channel. The card is designed so that the question “is this channel on air?” is answerable without opening anything.
The active switch
Section titled “The active switch”Enables or disables the channel. A disabled channel is not started under any circumstances, regardless of viewers or the always-on setting. This is the switch to use when taking a channel out of service; deleting it loses the configuration.
Badges
Section titled “Badges”always-on / on-demand
Whether the channel runs continuously or only while somebody is watching. An on-demand channel showing no activity and no viewers is behaving correctly, not failing — a distinction worth remembering before raising a fault.
viewer count
How many clients have joined this channel’s multicast group, derived from observed IGMP membership rather than guessed. Hover to see the individual client addresses, which is how you confirm that the television in room 214 is the one actually watching.
engine
Which engine this channel is using. Worth checking before reading the metric tiles, because the two engines do not populate the same tiles.
resolution profile
The requested quality rung and, in brackets, what the origin actually had. See below.
The amber resolution badge
Section titled “The amber resolution badge”A resolution profile asks for a rung of the source’s quality ladder — 4K, Full HD, HD, SD or mobile. Origins publish whatever ladders they like, so the requested rung frequently does not exist. Castmux selects the closest available height rather than refusing to start, because a channel streaming 480p when you asked for 576p is better than a channel that will not start because nobody serves exactly 576p.
When the match is inexact the badge shows both values — 4K (1080p) means 4K was requested and 1080p is what the origin offered — and it is coloured amber.
Resolution profiles covers the selection rules, including why a ladder with separately delivered audio is refused outright.
The licence banner
Section titled “The licence banner”Above the cards, a banner shows the appliance’s licence state. Its colour says what matters, whether channels are on air:
| Colour | Meaning |
|---|---|
| Green | Licensed. The plan and channel limit are shown. |
| Amber | Streaming, but something needs attention: the licence server cannot be reached and the appliance is running on its cached licence, or channels the licence server supplied were refused. The reason is given. |
| Blue | Waiting: the appliance is enrolling, or waiting to be approved. Nothing streams yet. |
| Red | Streaming is blocked, with the reason and who to contact. |
The device code is shown on the right. It is what support asks for, and what identifies this appliance when it is approved. While the licence is not active, a Retry button checks in immediately. The appliance also retries by itself every five minutes while blocked, so the button is for when you have just fixed the cause. The page reloads a few seconds later, because a check-in can add, remove or change licence-supplied channels.
When nothing is streaming, this banner is the first place to look. The web interface is deliberately available even when the licence server cannot be reached, precisely so this banner can say why. See Internet access.
Metric tiles
Section titled “Metric tiles”| Tile | What it is | Source |
|---|---|---|
| Bitrate | The rate the engine reports for the stream it is handling. | Reported by the engine |
| Speed | Whether the channel is keeping up with real time. Anything meaningfully below 1× is falling behind. | Reported by the engine |
| Uptime | How long this channel has been running since it last started. A short uptime on a channel nobody has touched is the signature of a restart loop. | Castmux |
| UDP bitrate | What is genuinely leaving the network interface for this group. | Measured off the wire |
| Source ping | Round-trip time to the origin. A useful early warning: source ping degrading before a channel becomes unstable points at the network, not at Castmux. | Castmux |
The distinction in the last column is the important one. Engine-reported figures describe what a process believes it is doing; UDP bitrate describes what happened. When they disagree, UDP bitrate is right. It is also the only tile that is populated identically on both engines — the pass-through engine never decodes video, so it has no frame rate or speed to report, and those tiles will be empty on a perfectly healthy pass-through channel.
The tiles are a live snapshot. For history, use the card’s Stats button: it graphs the last 30 minutes of the stream actually leaving the appliance, with the errors broken out — continuity and transport errors, PCR accuracy, and bitrate with its spread. That is the view that says whether a picture that “breaks up sometimes” is being damaged before it reaches the appliance or after.
Card actions
Section titled “Card actions”Five buttons: Preview, Logs, Stats, Edit and Delete. Stats opens graphs of the channel’s transport-stream quality — bitrate, PCR accuracy and transport errors over the last half hour — described in Transport-stream quality. Delete asks for confirmation and removes the channel from the configuration; there is no undo beyond restoring a backup of the config directory. On a channel supplied by the licence server, Edit and Delete are disabled, because the next licence check-in would undo them — see Channels supplied by the licence.
A channel mapped to a programme guide also shows what is on now and what is on next.
Adding and editing a channel
Section titled “Adding and editing a channel”The same dialog serves both. Fields:
Name
Used in the interface and in logs, and on the pass-through engine it becomes the service name carried in the transport stream, so it is what a television may display.
Source type
HLS, SRT, RTMP or MPEG-TS (over UDP multicast or HTTP). See Source types.
Source URL
Where the channel is pulled from. For HLS this is normally the master playlist.
Destination address
The multicast group. Use the administratively scoped range, 239.0.0.0/8.
Destination port
The UDP port. Each channel needs its own group-and-port combination.
Engine
Pass-through or remux, overriding the appliance default for this channel.
Resolution profile
Which rung of the HLS ladder to select, or empty to accept whatever the origin lists first. Empty is the default and is what every pre-existing channel has.
Force always-on
Run the channel continuously instead of only while it has viewers.
Changes take effect on the channel’s next start, so editing a running channel restarts it.
Preview
Section titled “Preview”Preview plays the channel in the browser. It does so by re-reading the channel’s own multicast output rather than by opening a second connection to the origin, which means what you see is what the televisions are receiving, including any fault introduced between the engine and the wire. A preview that is broken in the same way as a television is genuinely informative; a preview that pulled from the source separately would not be.
Each channel keeps its own circular buffer of log lines — 1000 entries or 24 hours, whichever is reached first. The Logs button on the card opens it.
Per-channel rather than one combined stream, because the question being asked is almost always about one channel, and on a twenty-channel appliance a combined log buries the six relevant lines under several thousand irrelevant ones. The buffer is in memory and does not survive a restart, so capture anything you need before restarting the container.
The DVB-C page
Section titled “The DVB-C page”Where IP channels are assembled into a multiplex on a real RF carrier: modulator status, multiplex composition and carrier parameters. Present whether or not a modulator is fitted. Full detail is in DVB-C multiplexing.
The EPG page
Section titled “The EPG page”Where programme guide sources are added and channels are matched to their guide entries: each source’s last fetch and its result, a Sync now button, and a mapping field per channel that suggests guide identifiers as you type. See Programme guide (EPG).
The HDMI page
Section titled “The HDMI page”Configuration for the appliance’s local HDMI output — a single channel rendered to a directly attached display, typically for a foyer or waiting room screen. See HDMI output.
Settings
Section titled “Settings”Appliance-wide values, in four cards.
Global Settings
Location and Re-Seller. Location is more than a label: it names the site in exported metrics, it is reported to the licence server as the site name, and it is the DVB-C network name that televisions show during a scan unless a network name is set below. Re-Seller names the installer or partner responsible for the site, and also labels exported metrics.
UDP Settings
The Streaming Engine used by channels that do not choose their own, and the UDP Device: the source address outbound multicast is sent from. It does not decide which interface the packets leave by — the kernel routing table does that; see Installation → multicast routing. Under Advanced overrides are the dummy listeners and the automatic SRT latency and UDP packet size, described in the Configuration reference.
DVB-C Network
Settings for the cable network as a whole rather than one frequency: network name and ID, QAM and symbol rate, the character set for programme guide text, and placeholder slots. See DVB-C multiplexing.
License
Read-only licence details: the device code, plan, customer, number of licensed channels, when the subscription ends, when the appliance registered, its last check-in, when the licence next renews, and the licence id. Recheck licence & channels checks in immediately. Unlike the banner’s Retry button, it is always available, because it is also how you pull a line-up change from the licence server without waiting for the next check-in.
Not every save is harmless to what is on air:
- Global Settings apply without interrupting anything.
- UDP Settings change how every engine is started, so saving them restarts every active channel. A change to the UDP Device also rebuilds every DVB-C multiplex.
- DVB-C Network values are built into the modulator setup and the multiplexes’ signalling, so saving them rebuilds every multiplex. Every carrier drops for the duration, and televisions on the cable lose the whole line-up for a few seconds.
Save the last two at a quiet moment.
The on-demand and IGMP settings are not on this page. They are set in the configuration file — see On-demand streaming and the Configuration reference.
What is deliberately not here
Section titled “What is deliberately not here”Raw engine parameter strings are not exposed in the interface. They exist, and they can be set in /config/config.yaml — see the Configuration reference — but they are not editable from a browser.
The reason is blast radius. A malformed parameter string does not break one channel, it breaks the engine invocation for every channel using it, and it does so at the moment the next channel starts rather than at the moment the mistake was made. Putting that behind a text box on a settings page, where a plausible-looking edit takes an entire site off air at three in the afternoon, is not a good trade for the small number of installations that need it. Editing the file instead is a deliberate speed bump: it requires shell access, it produces something you can diff, and it is not something anyone does by accident.
System actions
Section titled “System actions”Restart all streams
Stops and restarts every channel without restarting the appliance. Channels come back staggered, roughly three seconds apart, so on a large installation this takes a minute or so to complete. The stagger is not cosmetic: starting everything at once saturates the source uplink and makes every channel fail together.
Reboot
Restarts the appliance. Worth reaching for less often than instinct suggests — a reboot cannot fix a multicast route pointing at the wrong interface, and it will not fix a source that has stopped serving. If a reboot appears to fix a problem that then returns, the reboot was not the fix.