Playout troubleshooting¶
Start with the observable symptom and check the chain in order: saved schedule → actual video frame → EPG → viewer access. An API response or a correct programme guide alone does not prove what is on air.
You need operator access to the playout and its stream, plus a subscriber account for the final check. See Check the stream for the HLS link procedure.
You can inspect the playout state through the management API. Set the installation address, operator account, and stream name; send the password only over HTTPS:
BASE='https://catena.example.com'
API_USER='operator'
read -rsp 'Operator password: ' API_PASSWORD; echo
STREAM='playout_<id>'
curl -fsS -u "$API_USER:$API_PASSWORD" \
"$BASE/central/api-v4/streams/stats/$STREAM" |
jq '.input.playout'
Check health and problems in the response, then open the relevant section below.
Air and schedule¶
Filler is on air¶
- Symptom: a slot filler, the general filler, or color bars play instead of a film or live source.
- Possible causes: no slot covers the current time, the VOD asset ended before the slot ended, or the content is unavailable.
- Check: open Playout and compare Now and next with the grid. If there is no current slot, check the boundaries of neighboring slots. If a slot exists, check its duration and asset availability. The state request above helps distinguish an asset error from a schedule gap.
- Action: for a gap, add or move a slot and click the general Save as described in Build a VOD schedule. If the VOD asset ended naturally, leave filler until the next slot or change the slot duration and content. For an asset error, go to Content and sources.
- Result check: if you added or corrected a slot, Now shows it, HLS or WebTV shows its frame, and EPG shows its programme. If you intentionally leave filler after natural VOD EOF, verify that it plays until the next slot boundary and that the next slot's content starts afterward. For a repaired source,
healthmust return toon_airandproblemsmust clear.
The wrong slot is on air or a saved edit is missing¶
- Symptom: the player shows the previous programme or a different slot from the one you just edited.
- Possible causes: you edited a future slot, the edit is only a draft, the slot time is wrong, or an open WebTV page retains the previous EPG.
- Check: compare Now and next with the grid and check the slot start and duration. After saving the slot window, verify that the general Save above the grid completed without an error. Compare fresh EPG on the channel card with the actual HLS frame.
- Action: click the general Save. For a future slot, wait until its start; for an incorrect time, fix the boundaries and save again. Reload the open WebTV page after an EPG edit. You do not need to restart the stream to apply the schedule.
- Result check: Now, fresh EPG, and the video frame refer to the same slot. A future-slot edit appears in its programme but does not change the current broadcast before its scheduled start.
The general filler does not save¶
- Symptom: after selecting Channel filler, the general Save returns HTTP 422 with “missing field
fps”. - Possible cause: in the verified version, the editor sends an incomplete output config when the general filler changes. Saving the schedule and slot filler is a separate working path.
- Check: reopen the playout and verify that the previous general filler is unchanged. Do not repeat the same editor request.
- Action: save the complete existing
configwith onlyfillerchanged through the management API by following Set the general filler through the API. This procedure preservesfps, size, audio, and the other parameters and usesIf-Matchto prevent overwriting another operator's edit. - Result check: the API response contains the new
fillerand the previous output parameters. Check the selected filler over HLS at the next schedule gap; do not delete the current slot just to test it.
Content and sources¶
A VOD file is unavailable¶
- Symptom: a VOD slot appears in Now, but filler is on air; the stream state can be
degradedwith an asset error. - Possible causes: the file or storage is unavailable, the asset placement is not ready, or Catena has not read the video information yet.
- Check: open the asset in VOD → Catalog. Check the available status, video and audio tracks under Media info, a ready placement, and available storage under Copies. Run the stream state request from the beginning of this page.
- Action: restore the file or storage and wait for the placement to become ready. Delete the failed slot and click the general Save, then recreate it with the previous content, start, duration, and metadata and save again so that the playout reopens the asset. See Edit the current broadcast for the deletion and recreation sequence. For unavailable storage, use Streamer diagnostics and VOD placement; do not recreate the playout. If the asset cannot be restored now, replace the slot content with another available VOD asset and click the general Save.
- Result check: the asset is available,
healthreturns toon_air, the asset error disappears fromproblems, and fresh HLS or WebTV shows the slot content instead of filler.
A live source does not play¶
- Symptom: a live slot is saved and visible in Now, but filler is on air. EPG can show the correct live programme at the same time.
- Possible causes: the live source itself is unavailable, or the verified-version limitation applies: a working source can fail to reach playout air even without an asset error.
- Check: play the source live stream independently of the playout and inspect its inputs with Source diagnostics. Then compare the actual playout HLS frame and
problems. Do not treat EPG as proof of live air. - Action: if the source is unavailable, restore its input and wait until the live stream plays independently. Delete the failed live slot and click the general Save, then recreate it with the previous parameters and save the schedule again. If the source plays independently but the playout remains on filler, replace the live slot with an available VOD asset and click the general Save as described in Add a live source. No other live-air recovery is verified in this version.
- Result check: the player shows the actual frame, not only an EPG event. After switching to VOD, check the new slot content and updated programme.
Programme guide¶
EPG is empty¶
- Symptom: the channel card, WebTV, or XMLTV has no current and next programmes.
- Possible causes: the selected interval has no slot, the event was deleted with its slot, the channel points to another stream, or the subscriber cannot access the channel.
- Check: compare the interval with the saved schedule. Check the programme and Stream field on the channel card, then Available channels on the subscriber card. Gaps between slots create no events, and the next save removes events that ended more than a day ago.
- Action: add or restore the slot and click the general Save. If the channel points to the wrong stream, fix the link by following Create the channel. If only the subscriber's guide is empty, restore the channel → package → subscription chain in The channel is not visible to the viewer. Reload WebTV.
- Result check: the channel card shows a programme with the intended title and time; after reloading WebTV or making a new XMLTV request, the same data appears there.
EPG is stale or contains incorrect data¶
- Symptom: a title, description, time, or programme order does not match your latest edit.
- Possible causes: the edit is only a draft, the slot contains incorrect saved fields, or an open WebTV page shows a previously loaded guide.
- Check: open the slot and compare its saved fields. Check fresh EPG on the channel card or with a new XMLTV request: if the data is already correct there, only the open WebTV page is stale.
- Action: if the fresh channel card or XMLTV already shows the correct data, only reload WebTV; no further edit or schedule save is needed. If the saved fields are wrong or the edit is still a draft, correct the slot fields, save the window, and click the general Save by following Update the guide after an edit. Refresh the console page for the channel card.
- Result check: the fresh channel card, WebTV, and XMLTV show the corrected title, boundaries, and description. Season, Episode, and the poster are not passed to EPG; include the episode number in the title if viewers need it.
EPG is correct but filler is on air¶
- Symptom: the current WebTV programme matches the schedule while the video frame shows filler.
- Possible cause: EPG reflects the operator's saved intent, not the actual frame. An unavailable VOD or live source and the live-air limitation do not necessarily change the event.
- Check: open the direct HLS link and inspect the stream
healthandproblems. Then check the current slot asset and independent live-source playback. - Action: follow A VOD file is unavailable or A live source does not play. If the live source works independently but the playout remains on filler, use the verified switch to VOD.
- Result check: a fresh player shows the current slot content. If you selected VOD instead of live, EPG also matches the new slot after saving and reloading WebTV.
Viewer access¶
Direct HLS works but the channel is not visible to the viewer¶
- Symptom: the operator can watch the direct stream link, while WebTV reports No channels available or omits the required channel.
- Possible cause: direct HLS checks the stream, not publication. The channel is not linked to this stream, does not belong to a package, or its package is not in the subscriber's subscriptions.
- Check: in Channels, verify the exact
playout_<id>stream name; in Packages, check the package contents; on the subscriber card, check Subscriptions and the resulting Available channels block. - Action: restore the three links by following Publish the channel: channel → stream, channel → package, subscriber → package subscription. Reload WebTV after changing them.
- Result check: the channel appears in Available channels and WebTV, and the viewer sees its frame and current programme. The subscription determines available channels; working direct HLS does not replace it.
The channel is visible but does not play¶
- Symptom: the channel appears in the list, but the player reports an error or does not start playback.
- Possible causes: no stream is assigned to the channel, another stream is assigned, or playback fails in the WebTV session even though the assigned stream works.
- Check: read the player message and check the channel's Stream field. This channel has no broadcast configured means that no stream is assigned. Compare an assigned stream's exact name with the required playout's
playout_<id>. If the correct stream is already assigned, do not save or reassign it. Compare direct HLS from that stream first. - Action: if the stream is missing or wrong, assign the correct one by following Create the channel and save the channel. If direct HLS fails with the correct stream already assigned, go to Direct HLS does not play either. If direct HLS plays, reload WebTV or open a fresh WebTV session in a private browser window and sign in again. If the player remains silent without an error, continue with Direct HLS plays, but WebTV stays silent without an error. For an explicit message about screen limits or device sign-in, use A viewer reports that nothing plays.
- Result check: a fresh WebTV session shows the channel's frame with sound and the current programme. If WebTV remains silent, keep the already-working direct-HLS result for escalation; it does not identify a root cause in the player.
Direct HLS plays, but WebTV stays silent without an error¶
- Symptom: the correct stream is assigned and direct HLS plays, but a fresh WebTV session shows no video and no player error.
- Possible cause: the evidence limits the failure to viewer playback in this WebTV session, but does not identify its root cause. Do not infer a playout, transcoder, network, or browser defect from this symptom alone.
- Check: note whether reloading WebTV and opening a fresh session changed the result. On a desktop browser, open developer tools before reloading. Save Console errors and warnings plus Network failed requests and HTTP statuses for the page, HLS manifests, and media segments. Do not change code, browser flags, or the stream. On a device without these tools, record that limitation instead of attaching a debugger.
- Action: stop changing the playout, transcoder, and channel assignment solely for this symptom. Escalate to the service administrator or support with the packet below; redact passwords, cookies, access tokens, and secret query parameters.
-
Escalation packet:
-
The exact WebTV page and URL, without credentials or tokens.
- The browser name and version, plus the device and operating system.
- The fresh-session result, including whether the channel list and programme guide loaded.
- The Console and Network evidence, or a note that the device cannot collect it.
-
The already-working direct HLS fact, including the stream name and the programme that played.
-
Result check: if WebTV starts, verify picture, sound, and the current programme. If it remains silent, the packet records the fresh-session result and the working direct-HLS comparison without inventing a diagnosis.
Direct HLS does not play either¶
- Symptom: the playout stream plays neither in WebTV nor through its direct link; the master manifest can contain only a header without quality variants.
- Possible cause: the playout outputs raw YUV video and PCM audio, and no transcoder is configured for an ordinary HLS player.
- Check: open the master manifest and check for quality variants. On the stream page, open Transcoder and inspect Preview: input → output. If a warning reports a transcoder error, use the dedicated diagnostics.
- Action: configure the Standard ladder 1080/720/360 + AAC preset as described in Choose the viewer output and save the transcoder.
- Result check: the master manifest contains quality variants, a variant manifest contains media segments, and the player shows the current slot with sound. Then check the subscriber's channel access separately.
What's next¶
- Change the source format — a safe restart and checks when Media info or the frame size does not change after a format edit, or a green frame appears.
- Delete a playout — consequences of irreversible deletion and restoring publication on another stream.
- Broadcast schedule — the save and warning verification sequence.
- Playout programme guide — EPG checks on the channel card, in WebTV, and in XMLTV.
- Channel from VOD — the complete subscriber playback check.