🎬 PlayoutGo Operations Manual v3.64.0

A Go multichannel broadcast playout platform. Demuxes MP4 (H.264/AAC), muxes live MPEG-TS, and streams via SRT, HLS and an optional RTMP push — with no FFmpeg or GStreamer on the on-air path. It builds into one self-contained binary. ffmpeg/ffprobe, when installed, power the extras: the gap slate, thumbnails, demo watermarking, local encodes, the CBR test and audio-language detection. Every feature, with the version that introduced it, is in the feature reference; what is still to come is in the roadmap.

Overview

PlayoutGo is a multi-tenant broadcast playout server designed to run 24/7 live channels from a library of uploaded MP4 files. Each channel has an independent playlist, schedule, and output pipeline. The system outputs to:

• HLS — native HTTP Live Streaming, served at /hls/{slug}/index.m3u8, viewable in any browser or media player.
• SRT — Secure Reliable Transport for low-latency contribution to broadcast encoders, Nimble Streamer, Flussonic, Wowza, etc.
• Both — simultaneous HLS monitoring preview and SRT contribution output.
• RTMP push — rtmp_push_url sends the same frames to YouTube, Facebook or Twitch (Pushing to YouTube).
• SDI — a Blackmagic DeckLink card in the server plays the channel out of an SDI port (SDI output, 3.62.0).
• UDP / RTP — the transport stream to a multicast group or a unicast address, for head-ends, IRDs and multiplexers (UDP / RTP output, 3.63.0).

And one input: every channel has a live RTMP publishing point (rtmp_port, default 1935) that an operator can cut to and back from (Live insertion).

HLS is always active when a channel is running, even in SRT-only mode. This lets operators monitor playout in a browser without interrupting the SRT feed.

Feature Reference 3.60.0

Everything PlayoutGo does, by area, with the version that introduced it and where it is described. A later version in a description is when that part changed. What is still to come is in the roadmap; each version's details are in the changelog.

Channels & outputs

Rundown & scheduling

Traffic

Live insertion & ad breaks

Audio, captions, DVB & constant rate

Graphics & branding

Encoding

Delivery & feeds

Media & storage

Accounts & security

Operations

Interface

Roadmap — What Is Left 3.60.0

The features not built are listed below, checked against the code in 3.60.0; 3.60.0 built three of them (conform on ingest, loudness, two-factor sign-in), and 3.63.0 two more (UDP/RTP output, alert webhooks). 3.55.0 closed the last documented limits. 3.56.0 was a hardening round: every parser fuzzed and features aired together, and what that found fixed (changelog, fuzzing and combinations). 3.57.0 is the production release: a deploy bundle with an installer that upgrades and rolls back, a hardened unit, a configuration check, process metrics, and an hour-long soak (deployment). 3.58.0 made the as-run log survive a crash, shipped alert rules, set up built-in HTTPS from the installer — and made upgrades on such hosts work at all — and added clock-change and weekday options to traffic for 3ABN to choose between. 3.59.0 ran the installer on a real systemd and built-in TLS against a real ACME server, and fixed what that found. What is left needs something only an operator can supply — hardware, an account, a node release, a partner's answer.

Needs something from the operator

• A multicast network and a head-end, IRD or multiplexer for the UDP/RTP output (3.63.0): it is verified on the loopback interface and to a unicast receiver; IGMP/PIM routing and real receiving equipment are untested here.
• The composite node drawing overlays and logo_url on its built-in frame (3.53.0 sends both; see the node contract). Until the node does, traffic graphics reach air only on channels whose graphics are a page.
• NVENC on real hardware: the local-GPU path, GPU decoding (NVDEC, scale_cuda) included, is tested with stand-in tools and the software encoder.
• NVENC filler data on the production ffmpeg build (the test ffmpeg has no such option).
• On-air graphics on a real GPU composite node, and gpuff's mp4mux output.
• A real YouTube OAuth client (tested against a stand-in Google).
• 3ABN's answers: acceptance of generated logs and airing numbers; the undocumented fields; weekend and other-channel dayparts; the DST convention; the hour-spot scheme; episode rules per series; which RUSS items are fillers.
• A real A/53 caption master to verify end to end, including the CLOSED-CAPTIONS declaration on Apple players.
• A key-management service of yours behind secrets_key_command (tested with a stand-in command), and a TPM-sealed systemd credential (an encrypted credential under the host key is tested on a real systemd, 3.59.0; no TPM here).
• Firefox and WebKit runs of the browser proofs, and Safari and tvOS for the audio menu (only Chromium is installed here).
• A certificate from Let’s Encrypt itself: no public DNS name reaches the build host. Issuance, the cache and renewal-free restarts are tested against Pebble, Let’s Encrypt’s own ACME test server, on the real ports 443 and 80 (3.59.0); the first start on a host whose DNS points at it is the last step.
• The first install on a production host, and moving plt.bozztv.com’s hand-made setup over. The installer is tested on a real systemd (version 255, as PID 1 of its own namespaces, 3.59.0) — install, confinement, notify and watchdog, restart, upgrade, rollback, boot — but with the distribution’s other services not running.

Features not built 3.60.0

What commercial playout commonly has and PlayoutGo does not, checked against the code. None is scheduled; each is a round of its own.

• Subtitles: no SRT, WebVTT or SCC sidecar import, no WebVTT rendition in HLS, no DVB subtitles or teletext. A/53 captions in the video are carried.
• Live inputs: RTMP only — no SRT, UDP/multicast or HLS-pull ingest, and no scheduled live event (a take at a set time).
• Outputs: UDP/RTP multicast is built (3.63.0, UDP / RTP output) but has no FEC (SMPTE 2022-1), 2022-7 or SAP; no DASH, CMAF or LL-HLS; no HEVC, MPEG-2 or AC-3/E-AC-3 output.
• Protection: no HLS encryption or DRM — AES-128, SAMPLE-AES, Widevine or FairPlay (CPIX, or a key server such as wvgate).
• Catch-up and compliance: no timeshift or DVR window, and no air-check recording of the output.
• Ad signalling: SCTE-35 splice_insert only — no time_signal with segmentation descriptors, no SSAI/VAST hand-off, no SCTE-104.
• Redundancy: no main/backup pair with sync and automatic switch-over; one SQLite database, its snapshots on the host only.
• Alerting from the server itself: webhooks are built (3.63.0, alert webhooks); no e-mail of its own — a relay or Alertmanager with the shipped Prometheus rules sends it.
• EAS/CAP emergency alert insertion.
• Monitoring: no multiviewer with audio and loudness meters on air (files are measured; output is not).
• Accounts: no SSO (OIDC, SAML); no operator or read-only role inside an account (admin and user only); two-factor cannot yet be required of administrators.

Known limits, documented, not scheduled

None open. The four listed in 3.54.0 were closed in 3.55.0. One of them was stated wrongly: gap filler and the slate always reached every audio rendition (they air as samples, like an item); only dead air — a gap with neither filler nor a slate possible — named the variant's segment.

Architecture

One Go module (module playout, Go 1.23+), every non-test file in package main at the repository root — there is no src/ directory. Grouped by what the files do:

Data flow

When a channel starts: the PlayoutEngine reads MP4 samples via mp4reader.go (the encoded rendition when the channel has one, otherwise the original), paces them to wall-clock time, and feeds the HLS segmenter (browser playback), the SRT output (downstream ingest, muxed to MPEG-TS on the way out, with service tables and splice information added there) and the RTMP push, when one is set. Audio is routed per language (audio languages). A gap is covered by gap filler, then by a generated black-and-silence slate. SRT reconnection happens in a background goroutine so a dropped SRT client never interrupts HLS output. A live RTMP feed, once taken, replaces the file samples on every output until it is returned or stops.

Quick Start

# from the repository root (Go 1.23+)
CGO_ENABLED=0 go build -o playout .
./playout

UI Tour & In-App Help v1.5

The entire documentation you are reading lives inside the application: open the 📚 Help tab in the top navigation — it opens with a one-click launcher bar for the tutorials, recipes, comparison, FAQ, glossary and testing guide. Every page also has a small ? button next to its title that jumps straight to the relevant manual section — Channels → channel management, Rundown → the scheduling manual, Media → upload & probing, and so on. The ↗ button in the header opens this manual in its own browser tab if you prefer a second window while operating.

A new account with no channels is offered a guided tour once (🧭) — a spotlight walkthrough of the pages; the 🧭 Guide tab starts it again at any time.

Five-minute tour for a new operator

1. 📺 Channels — create a channel, choose output (HLS, SRT, or both), press ▶ to start, ⏹ to stop. The card shows live status, the copy-ready player URLs, and shortcuts to the rundown and stats.
2. 🎞 Media — drag-drop MP4s (H.264 + AAC). Files probe automatically: watch processing → ready and the real resolution/fps/duration appear. A file marked error is not playable — re-encode it.
3. 📋 Rundown — the heart of the system: order content, pin air times with 🔒 anchors, watch gaps/overruns, and read the NOW line. Full manual in the Rundown section.
4. ▶ HLS Player — quick in-browser preview of any HLS URL (served through the built-in CORS proxy).
5. 📡 EPG — copy XMLTV and M3U links for Plex/Jellyfin/IPTV apps. The links carry a feed token, not your login token: it opens only /epg/ and /m3u, never expires, and stops working when you change your password.
6. 📊 Stats — live throughput, viewer counts, play history, and the channel error log.
7. 🛡 Admin (admins only) — user and system management; see the Admin Guide.

Configuration (config.json)

Config is loaded from config.json in the working directory (under systemd, WorkingDirectory=). If missing, it is created with defaults — including a random admin_password and jwt_secret — at mode 0600, because it holds secrets. A misspelled key is named in the log at startup, and a malformed file stops startup with the line and column. config.sample.json lists every key with its default. Relative paths resolve against the working directory (under systemd, WorkingDirectory=), so use absolute paths in production.

{
  "port": 8700,
  "admin_email": "admin@playout.local",
  "admin_password": "(random, generated on first run)",
  "jwt_secret": "(random, generated on first run)",
  "database_path": "playout.db",
  "uploads_dir": "uploads",
  "hls_dir": "/dev/shm/playout_hls",
  "advertised_base_url": "http://10.0.0.5:8700"
}

Tutorial 1 · Your First Channel 10 min

Goal: take a fresh install to a channel playing in a browser. No prior playout experience assumed.

1. Log in with the admin credentials from config.json (default admin@playout.local). Change the password from the 🔑 button in the header.
2. Upload media. Go to 🎞 Media and drag in two or three MP4s. They must be H.264 video + AAC audio (video-only is fine — PlayoutGo adds a silent track automatically). Watch the status go processing → ready; the real resolution, fps and duration appear when probing finishes.
   If a file lands on error, it isn't H.264/AAC or the container is damaged. Re-encode:
   ffmpeg -i input.mkv -c:v libx264 -preset veryfast -g 48 -c:a aac -ac 2 -ar 48000 output.mp4
3. Create a channel. 📺 Channels → + New Channel. Name it demo, set Output mode to HLS (simplest — plays in any browser), leave the rest at defaults. Save.
4. Fill the rundown. Open 📋 Rundown, pick demo in the channel selector, and click files in the right-hand Add Files panel to append them.
5. Start it. Back on Channels, press ▶ Start. Within ~10 seconds the card shows ● LIVE.
6. Watch it. Click the ▶ button on the card (opens the built-in player), or copy the HLS URL into VLC or Safari.

What just happened: the engine opened your first file, remuxed it to MPEG-TS in real time, and wrote 4-second keyframe-aligned segments to /dev/shm/playout_hls/demo-1/, updating index.m3u8 as it went. When the file ended it moved to the next item with a discontinuity marker and continuous timestamps — no re-encoding anywhere, which is why one modest server can run many channels.

Tutorial 2 · Build a Broadcast Day 15 min

Goal: understand anchors, flow, gaps and overruns — the heart of the Rundown.

Step 1 — flow everything from a start time

Add six items. In Schedule day from pick today at 18:00 and press ⏩ Set & flow. Item 1 becomes 🔒 anchored at 18:00; everything else shows a grey computed time that simply follows the previous item's end. Drag any row — every grey time recalculates instantly, the anchor never moves.

Step 2 — pin a hard start

Say item 4 is a news bulletin that must hit 19:00 exactly. Click its 🔓 to anchor it, then edit the yellow time to 19:00. Now one of two things appears:

• ⚠ GAP — 00:14:00 — your first three items end at 18:46, so 14 minutes are unaccounted for. Options: add content, move the anchor earlier, or assign a gap filler to replace the built-in black slate with your own clips.
• ⛔ OVERLAP (red row) — content before an anchor runs past its air time, so the anchored item starts late by that amount. PlayoutGo never truncates a file: the item already playing always runs to completion. The delay does not accumulate — the next anchor is an absolute wall-clock time, so if there is slack before it the engine waits there and the schedule self-corrects. Shown as a full-width row, like a gap, because a late programme is at least as serious as dead air.
• +00:07 over (red, on the anchor) — your content runs past 19:00. The bulletin will start late. Options: remove or shorten an item, or move the anchor.

This is the entire job of a traffic scheduler: make the gaps and overruns visible before air, not while viewers are watching.

Step 3 — repeat a block

Tick the checkboxes for items 1–3 (shift-click selects a range), then press ⧉ Duplicate in the blue bulk bar. Floating copies land at the end and immediately flow after the last item.

Step 4 — safety net

Press ↩ Undo. Every schedule and order change is snapshotted (10 levels). Try to drag or delete the row marked ▶ playing — you'll be asked to confirm, because that item is on air right now.

Step 5 — survive a restart

Stop and start the channel mid-programme. It resumes inside the correct item at the correct offset: the engine walks anchors, chains floating durations after them, and compares against the wall clock. A 25-minute-old anchor followed by two 10-minute items resumes 5 minutes into the third.

Tutorial 3 · A 24/7 FAST Channel 20 min

Goal: a channel that runs unattended forever, in the shape a FAST/OTT operator actually needs.

1. Create the channel with Output mode = Both (HLS for viewers, SRT for a downstream CDN or transcoder) and Loop playlist ticked.
2. Load a deep rundown — several hours of content. With looping on, when the last item finishes the whole playlist resets to pending and starts again.
3. Assign a gap filler (channel settings → Gap filler content): a 10–30 s branded slate. Anything that would have been dead air becomes on-brand.
4. Decide on anchors. For pure looping, use no anchors — content just cycles. For appointment programming, anchor only the few must-hit slots and let the rest flow.
   Anchors and looping interact: an anchor is a one-shot wall-clock event. When a looping playlist resets, anchors already in the past fire immediately in flow order rather than waiting for tomorrow. For a repeating daily grid, re-anchor per day (or leave the day unanchored and let it cycle).
5. Publish. From 📡 EPG copy the M3U link into your IPTV app (it carries your feed token, which does not expire), and the XMLTV URL into Plex/Jellyfin/Emby for a programme guide.
6. Monitor. 📊 Stats shows live throughput and the error log. Install from the deploy bundle (sudo ./install.sh, see Deployment) so the server runs under systemd, restarts on reboot and is restarted if it ever wedges.

Tutorial 4 · Multi-Tenant Setup 10 min

Goal: give several people (clients, colleagues, departments) their own isolated channels on one server.

1. As admin, open 🛡 Admin and create a user with an email, a password of at least 8 characters, and role user.
2. They log in and see only their own channels, media, rundowns, EPG feeds and stats. Admins see everything.
3. Isolation is enforced server-side, not merely hidden in the UI: a user cannot read another tenant's files, add another tenant's media to their playlist, or point their gap filler at it — all return 403/400. (Both playlist and filler paths were hardened in v1.7.0; see the changelog.)
4. Give each tenant a distinct SRT port, or share a port and give each channel a distinct stream ID — the listener routes by exact stream-ID match.
5. Each tenant's /m3u?token=FEED_TOKEN and /epg/my?token=FEED_TOKEN (from their EPG tab, or GET /api/epg/feed-token) return only their channels, so the links are safe to hand out individually. A password change revokes them.

Tutorial 5 · Diagnose a Dead Stream 10 min

Goal: a repeatable path from "nothing is playing" to a root cause. Work top to bottom — each step rules out a layer.

Layer 1 — is the engine running?

› Channels tab: does the card show ● LIVE?
› Server log: look for "Playing: filename"
✗ Status "error"      → open Stats and read the channel error log
✗ Nothing playing     → the rundown may be empty, or every item failed to parse

Layer 2 — is content being produced?

› ls -la /dev/shm/playout_hls/<slug>-<id>/
✓ .ts files with timestamps advancing every few seconds = engine is fine
✗ No files / stale files = the engine is stuck; check the log

Layer 3 — is it valid?

› curl -s http://SERVER:8700/hls/<slug>-<id>/index.m3u8
✓ #EXTM3U with #EXTINF lines and segment names
› Download one segment and probe it:
  curl -s .../seg00000042.ts -o /tmp/s.ts
  ffprobe -v error -show_entries stream=codec_name,channels,sample_rate -of csv=p=0 /tmp/s.ts
✓ h264 + aac,48000,2
✗ "aac, 0 channels"  → source has no audio and silent-track synthesis failed (pre-v1.4 bug)
  ffmpeg -v error -i /tmp/s.ts -f null -
✓ silent output = decodes cleanly
✗ "non-existing PPS" = segment starts mid-GOP (pre-v1.6 bug)

Layer 4 — the player

› Works in VLC but not Safari?  Safari is far stricter: it needs every segment to start
  on a keyframe and a consistent audio layout. Test in a private window (Safari caches
  HLS aggressively) or with a cache-buster: index.m3u8?v=2
› Works in the browser but not VLC over SRT? SRT is single-consumer — disconnect the
  other client first, and use the exact URL form below.

Layer 5 — SRT specifics

› ffprobe -i "srt://SERVER:9000?mode=caller&transtype=live&streamid=YOUR_ID&latency=200000"
✗ ERROR:PEER          → stream ID doesn't match. It must equal the channel's Stream ID
                         exactly. The URL parameter is streamid= (NOT srt_streamid=),
                         and latency is in MICROseconds (200 ms = 200000).
✗ Connection refused  → the channel isn't started, or output mode excludes SRT
✗ Bad secret          → passphrase mismatch (10–79 chars)

Recipes & Examples

Encode source files for reliable playout

# Standard 1080p conform — closed GOP every 2 s, AAC stereo 48 kHz
ffmpeg -i input.mov -c:v libx264 -preset medium -crf 20 -g 48 -keyint_min 48 \
       -sc_threshold 0 -pix_fmt yuv420p -c:a aac -b:a 128k -ac 2 -ar 48000 \
       -movflags +faststart output.mp4

-g 48 with -sc_threshold 0 gives predictable 2-second keyframes, which lets the segmenter cut cleanly at its 4-second target.

Make a branded slate for gap filler

# 15-second slate from a still image, silent stereo audio track
ffmpeg -loop 1 -i slate.png -f lavfi -i anullsrc=r=48000:cl=stereo -t 15 \
       -c:v libx264 -g 48 -pix_fmt yuv420p -c:a aac -ac 2 -shortest slate.mp4

Restream a channel to YouTube/Facebook

# Built in: paste the service's address and key into the channel's
# "Push to a streaming service" field — no relay is needed:
rtmp://a.rtmp.youtube.com/live2/YOUR-KEY

See Pushing to YouTube, or connect a YouTube account and let PlayoutGo create the broadcast.

Pull a channel into another server over SRT

ffmpeg -i "srt://SERVER:9000?mode=caller&transtype=live&streamid=ch1&latency=200000" \
       -c copy -f mpegts "srt://DEST:9000?mode=caller&streamid=relay1"

Schedule a day from a script

TOKEN=$(curl -s -X POST http://SERVER:8700/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"..."}' | jq -r .token)

# anchor item 101 at 18:00 UTC, let the rest flow
curl -s -X POST http://SERVER:8700/api/playlist/1/schedule_bulk \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"items":[{"id":101,"scheduled_at":"2026-08-01T18:00:00Z"},
                {"id":102,"scheduled_at":""},
                {"id":103,"scheduled_at":""}]}'

Back up and restore

# Everything lives in the database plus the uploads tree
tar czf playout-backup-$(date +%F).tar.gz playout.db uploads/
# HLS segments are ephemeral — never need backing up

How PlayoutGo Compares

An honest positioning guide, so you can tell whether this is the right tool for a given job.

Choose PlayoutGo when

• You want many unattended file-based channels per server, without paying to re-encode content that is already H.264/AAC.
• You need a genuine schedule (hard starts, gap/overrun visibility, mid-item restart resume) rather than a shuffle loop.
• You want a single self-contained binary (static with CGO_ENABLED=0; ffmpeg optional, for the extras) and your content on your own disks.
• You're feeding a downstream CDN/transcoder over SRT, or serving HLS directly.

Choose something else when

• You need live camera/studio switching or rich layered CG → OBS, vMix, CasparCG. (PlayoutGo does have an L-shape frame with headline, ticker and logo, composited by a node — L-shape graphics — and burned-in QR codes.)
• You need DRM, live transcoding or SDI output → a platform downstream (PlayoutGo serves HLS ABR from a ladder encoded ahead of time; SRT and RTMP carry one rendition).
• You need ad sales, traffic/billing integration or contractual support → a commercial playout suite.
• You need frame-accurate SDI compliance for a licensed broadcaster → dedicated broadcast hardware.

Frequently Asked Questions

Does PlayoutGo re-encode my files?

Not on air: playout remuxes H.264/AAC into MPEG-TS in real time. Files are encoded only if you choose Single bitrate or ABR for a channel — ahead of time, on an encode node or this server's GPUs — and a demo account's uploads are always transcoded. CPU use per channel is small, which is why a modest server runs many channels — but it also means all files should already be H.264/AAC, and mixed resolutions/frame rates are passed through as-is with discontinuity markers rather than conformed.

How many channels can one server run?

Because playout does no encoding, the practical limits are disk I/O and network throughput rather than CPU. Measure on your own hardware with your own bitrates before committing to a number — the honest answer is that it depends on your content and storage far more than on PlayoutGo.

Why does my SRT client get rejected?

Almost always the stream ID. It must match the channel's Stream ID exactly; the URL parameter is streamid= (not srt_streamid=) and latency is in microseconds. Also remember SRT here is single-consumer: one client at a time per channel.

Why does VLC play my stream but Safari won't?

Safari enforces the HLS spec strictly: every segment must start on a keyframe and the audio layout must stay consistent. VLC tolerates violations of both. If Safari refuses a stream that VLC plays, probe an individual segment (Tutorial 5, Layer 3) — and remember to test in a private window, because Safari caches playlists aggressively.

What happens if the server restarts mid-programme?

On start the engine recomputes the on-air position from your anchors plus the durations of floating items, and seeks into the correct item at the correct offset. A channel with a schedule rejoins where it should be, not at the top of the playlist.

Can I use video files with no audio?

Yes. Video-only files automatically get a synthesized silent 48 kHz stereo AAC track, so a mixed playlist presents one stable audio layout — required for Safari and tvOS.

Where are the HLS segments stored, and do I need to back them up?

In hls_dir (default /dev/shm/playout_hls, a tmpfs). They're ephemeral and regenerate on start — back up only playout.db and uploads/.

Is it safe to expose this to the internet?

Serve it over HTTPS — the built-in Let's Encrypt support (HTTPS) or a TLS reverse proxy — sign in with the generated admin password and change it, and keep the JWT secret out of version control. API access is token-authenticated and per-user isolated; the HLS endpoints are intentionally public so players can reach them.

Can two channels share one SRT port?

Yes — they share a listener and are routed by stream ID, provided their passphrase, latency, buffer and max-bandwidth settings match. Mismatched settings on the same port are rejected with a clear error.

Glossary

Channels

A Channel represents one live broadcast stream. Each channel has:

• An independent playlist (ordered queue of media files)
• Optional scheduled_at times on individual playlist items
• An output mode: hls, srt, or both
• SRT connection parameters (used when output mode includes SRT)
• A loop_playlist flag — when true the playlist auto-resets when all items are played

Channel statuses

HLS URL format

Each channel gets a directory named {slugified-name}-{id}. For example, channel GB1 with ID 3 → /hls/gb1-3/index.m3u8. Legacy ch{id} format is also recognised for backward compatibility.

Media Files

The engine airs MP4 with H.264 video and AAC audio. Since 3.60.0 uploads, watch folders and re-imports also take MOV, MXF, MPEG-TS (.ts, .m2ts, .mts), MKV and WebM, and anything that is not H.264/AAC in MP4 is conformed first.

• Video: H.264 8-bit 4:2:0 airs as it is; HEVC, ProRes, MPEG-2, VP9, AV1 and 10-bit or 4:2:2 H.264 are re-encoded to H.264.
• Audio: AAC airs as it is; AC-3, E-AC-3, MP3, MPEG audio, PCM and the rest are converted to AAC — before 3.60.0 such a track aired as silence.

Conform on ingest 3.60.0

Before a new file’s first probe, ffprobe reads its streams. A file that cannot air as it is shows conforming while ffmpeg converts it, one file at a time and at a lower priority than the channels on air:

• another container is re-wrapped to MP4, and the file renamed .mp4;
• video other than 8-bit 4:2:0 H.264 is re-encoded with x264 (conform_x264_preset, CRF 18, a keyframe every two seconds), its A/53 captions carried into the new stream; H.264 that can air is copied untouched;
• each audio track that is not AAC is converted to AAC at 48 kHz (192 kb/s stereo, 384 kb/s surround, at most 5.1); every track is kept, with its language;
• with a loudness target, a track outside it is normalised (the video copied).

The result is read back and checked before it replaces the original, atomically; the library card says what was done (⚙ Conformed: audio 1 AC-3 → AAC), as does the file’s conform_note. A file is conformed once: probing it again does not convert it again. A file that is on air (or being encoded) is never replaced: it is marked with the reason, and ⚙ Conform converts it once it is off air — the same button converts a file already in the library, for example after setting a loudness target. Subtitle and data streams are not carried, nor SCTE-35 in a transport-stream upload. Without ffprobe on the server files are judged by the probe alone, as before 3.60.0; without ffmpeg a file that needs converting is refused with the reason.

Loudness 3.60.0

Every file’s audio tracks are measured in the background (ITU-R BS.1770 as ffmpeg’s loudnorm measures it): integrated loudness in LUFS, true peak in dBTP and loudness range in LU. Files already in the library are measured after the upgrade, one at a time. The library card shows the first track’s figure (🔉 −23.8 LUFS; yellow when a target is set and a track is outside it), the tooltip every track; 🔉 Measure measures again, and GET /api/media/loudness.csv is the whole library, one row per track.

With loudness_target_lufs set — −24 for ATSC A/85, the CALM Act’s reference, or −23 for EBU R128 — a new file whose track is further than loudness_tolerance_lu (2) from the target, or over loudness_true_peak_dbtp (−2), is normalised at ingest with loudnorm’s second pass: a linear gain where the ceiling allows, so the programme’s dynamics are kept. Files already in the library are not changed until ⚙ Conform is pressed. Live inserts and the slate are not measured or normalised.

After upload, the server probes the file asynchronously and stores: duration, width, height, FPS, bitrate, video/audio codec, whether closed captions are present, and whether SCTE-35 markers exist.

The Rundown — Playlist & Scheduling v1.4

As of v1.4.0 the separate Playlist and Schedule tabs are merged into a single Rundown — one ordered list per channel showing what plays and when, side by side with the media library for quick adds. This section is the operator manual for it.

Core concept: anchors and floating items

Every rundown item is in one of two states, toggled with the padlock in the ⏱ column:

• 🔒 Anchored — the item has an exact air time (scheduled_at is set). The engine covers the wait — gap filler if the channel has some, otherwise the built-in black-and-silence slate — until that wall-clock moment and starts precisely on it. Anchored times display in bold yellow and are edited inline.
• 🔓 Floating — no stored time. The item airs immediately after the previous one ends; its computed start is shown in grey. Reordering, adding, or removing items reflows all floating times instantly. Anchors never move.

This mirrors a broadcast traffic log: a few hard starts ("news at 18:00"), with everything between flowing by duration. Items placed before the first anchor have no defined air time and simply play in loop order.

Gap and overrun detection

• ⚠ unknown duration — a file whose length was never recorded is treated as zero-length, so every Start and Ends value after it, and any gap or overrun warning, becomes unreliable. The rundown flags these items and shows a banner; recover the metadata with Admin → Re-probe Broken Files.
• ⚠ GAP (amber row) — content before an anchor ends early. If the channel has a gap filler configured, the row names the clip that will loop there; otherwise it warns of dead air. Fix by assigning a filler, adding content, or moving the anchor earlier.
• +MM:SS over (red badge on an anchor) — content before the anchor runs past its start time. The engine will begin the anchored item late. Fix by removing/trimming content or moving the anchor later.

Orientation aids

• NOW line — a red rule at the current wall-clock position with a live countdown to the next item; the view auto-scrolls to it when the rundown loads.
• Day separators — automatic date headers when the schedule crosses midnight.
• Footer totals — item count, total content duration, anchor count, and the covered time span.
• Timezone label — the header shows which timezone all displayed times use: the channel's timezone (its timezone setting, an IANA name such as America/New_York), falling back to the browser's. Stored values are UTC RFC-3339.

Operator tutorial: building a broadcast day

1. Open Rundown, select the channel.
2. Add content from the right-hand panel (search, click to append).
3. Drag rows to order the day. All times reflow as you drag.
4. Set the day start: pick a time in Schedule day from and press ⏩ Set & flow. This anchors item 1 and lets everything else float.
5. Pin the hard starts: click 🔓 on any item that must air at an exact time, then adjust its yellow time inline. Watch for GAP/over indicators and correct them.
6. Start the channel. On restart or crash the engine recomputes the correct item and offset inside it from the anchors + flow, so the channel rejoins the schedule mid-item.

Multi-select, bulk edits, undo

• Checkbox column with shift-click ranges; a bulk bar appears with Move Top / Move Bottom / ⧉ Duplicate / Clear times / Remove. Duplicate appends floating copies of the selection at the end — the quick way to repeat a block later in the day.
• ↩ Undo (up to 10 levels) reverts schedule and order mutations — cascades, clears, reorders, bulk moves. The stack resets when you switch channels.
• All bulk schedule writes go through one atomic API call — a failure changes nothing (no half-written rundowns).

On-air safety

Removing, moving, or re-scheduling the item that is currently playing prompts for confirmation. The playing row is highlighted green with a ▶ marker. The change runs inside that question: if the server refuses it, the refusal is shown in the dialog, which stays open to retry or cancel, and undo records only a change the server made (3.52.0 — the change used to be sent after the dialog closed, so a refusal for the one item where it matters most was a toast). Removing a selection that includes the on-air item asks once, naming it.

More rundown tools

• Keyboard reorder (3.47.0): ↑ and ↓ on each row move an item one place, with the same on-air question and undo as dragging; focus stays on the moved row.
• Channel timezone (1.57.0): each channel may set an IANA zone (timezone, e.g. Europe/London); the rundown, the Day and Week grids, repeated days and imports all use it.
• Fill the rest of today (2.70.0): spreads random items from your library across what is left of the day as minute anchors, and reports how many hours it covered (POST /api/channels/{id}/schedule/fill-day).
• Shuffle on every loop (2.95.0): shuffle_on_loop re-orders a looping rundown each time it starts over.
• Media-delete protection (1.73.0): deleting a file that is on air or scheduled is refused, naming the channel; DELETE /api/files/{id}?force=1 deletes it anyway.

Schedule engine semantics

The engine walks the rundown in position order. If the next pending item is anchored in the future, it covers the wait with gap filler, then the built-in slate — it never skips ahead. A background scheduler checks every 10 seconds and auto-starts stopped channels when an anchored item comes up within 15 seconds.

Flow-aware restart (v1.4): on start/restart the engine computes the on-air position from anchors and the durations of floating items chained after them, then seeks into the correct item at the correct offset. Example: an anchor 25 minutes ago followed by two floating 10-minute items resumes 5 minutes into the third item.

Gap Filler — Covering Dead Air v1.27

A linear channel must always be transmitting something. When your rundown does not reach the next anchored item, PlayoutGo covers the hole with content you choose instead of the built-in black slate.

What happens during a gap, precisely

• The stream never stops. Even with no filler configured, the engine plays a generated black-and-silence slate (10 s of 1280×720 H.264 with 48 kHz stereo AAC, made once with ffmpeg) on every output: HLS, SRT, the RTMP push and every ABR rung. Segments decode, SRT clients stay connected and the channel stays running. Viewers see black with silence, not a dropped stream. Null packets are used only when no slate can be generated (no ffmpeg on the server) — and for an empty rundown.
• With a filler configured, the engine fits your clips into the hole and plays them, covering whatever is left over with the slate.
• The anchor still starts on its exact second. Filler is only ever scheduled when a whole clip fits before the deadline, with a 300 ms safety margin, so covering a gap can never delay the programme that follows.
• Without ffmpeg there is no slate, and the gap is dead air: program tables, a running clock and padding. On SRT since 3.56.0 they are the programme’s own tables — the same map PID, stream PIDs and clock PID — so a receiver that tunes in during the gap decodes the programme that follows. Until then dead air used another layout under the same table version; a receiver that joined in the gap kept the wrong map and decoded nothing, for as long as it stayed connected. An avail still open when its item ended returns on time inside the gap.
• A live take during any gap goes to air at once (3.56.0, live insertion).

Bin-packing: why a pool beats a single clip

Configure several clips and PlayoutGo fits the best combination into each gap rather than looping one slate. The difference is large:

The algorithm is greedy longest-fit: it repeatedly takes the longest clip that still fits in the time remaining. It is fast, predictable, and easy to read back from the log — which matters more for an operator than squeezing out a final second.

It also avoids playing the same clip twice in a row whenever an alternative fits. If only one clip fits the remaining time, it repeats rather than leaving black — repetition beats dead air.

Verified in production conditions: a 29 second gap with a pool of 8 s, 4 s and 2 s clips was covered as 8+8+4+4+2+2 = 28 s with 1 s of slate, and the anchored item still started on its exact second.

Configuring it

1. Upload your filler clips like any other media (short promos, idents, sponsor tags, a branded slate).
2. Open the channel's settings and select them under Gap filler content — ⌘-click or Ctrl-click for several.
3. Save. The change takes effect at the next gap; no channel restart needed.

Choosing good filler

• Mix the lengths. A pool of 2:00 / 1:00 / 0:30 / 0:10 packs almost any hole exactly. Four clips of 2:00 pack no better than one.
• Include something short (10–20 s). The remainder covered by the slate is always shorter than your shortest clip, so a short clip keeps it short. (The log calls that remainder "null-padded"; it airs as the slate.)
• Match your channel's format — same resolution and frame rate as your programming, with real audio (silent is fine, but the track must exist; PlayoutGo adds a silent one automatically if it doesn't).
• Keep it evergreen. Filler plays at unpredictable times, so avoid anything with a date or "coming up next" reference.

How this compares with professional playout systems

An honest positioning of what PlayoutGo does and does not do here:

Troubleshooting

Gap shows "dead air" in the Rundown
  → no filler configured for that channel; select clips in channel settings

Filler configured but black still airs
  → the gap is shorter than your shortest clip (check the log line, which
    reports exactly what was played and how much was padded)
  → or every clip is unusable: the channel error log names them

Log line to look for:
  [channel] Filler: covering 29s with promo8.mp4 ×2 + ident4.mp4 ×2 + tag2.mp4 ×2 (1s null-padded)

Generating & Importing Schedules v1.19

Two ways to fill a rundown without clicking each file: generate one randomly from your library, or import a schedule produced by another system.

🎲 Generate — randomised rundown

In the Rundown toolbar press 🎲 Generate and give either a count ("20") or a duration ("3h", "90m"). PlayoutGo fills the rundown from the channel owner's media library.

• Only ready files are used. Anything still probing, or marked error, is skipped — scheduling those produces dead air at transmission time. The result tells you how many were skipped and why.
• No back-to-back repeats. When more items are requested than you have files, the library is reshuffled for each pass rather than repeating one fixed order, and the seam between passes is checked so the same file never plays twice in a row.
• Duration fill adds items until the requested length is reached, so the last item may overshoot slightly — the result reports the true total.
• Reproducible when you supply a seed via the API: the same seed and library always produce the same order, which is useful for testing.

The dialog exposes every option below: fill by count or by hours, replace or append, the no-repeat guarantee, and a seed. The same options are available through the API:

POST /api/playlist/{channelID}/generate
{
  "count": 20,              // or "duration_minutes": 180
  "replace": true,          // false appends to the existing rundown
  "no_repeat": true,        // never place the same file twice in a row
  "seed": 12345             // optional: reproducible ordering
}

⬆ Import — CSV or XML

Press ⬆ Import and choose a file. The format is detected from the content, and you are asked whether to replace the rundown or append to it. Entries whose media cannot be found are reported individually rather than failing the whole import.

Matching: a schedule entry is matched against your uploaded filenames — exact first, then case-insensitively, then ignoring the extension, then as a substring. So news.mp4, News.MP4 and news all find the same asset.

Air times are optional. An entry with a start time becomes an 🔒 anchored item; entries without one simply flow after the previous item (see the Rundown manual).

CSV

A header row is recommended. The media column may be named file, filename, media, asset, title, clip, name, material or content; the time column start, start_time, start_datetime, air_time, scheduled_at, time or on_air. Case, spaces, hyphens and underscores are ignored.

file,start
news.mp4,2026-08-01T18:00:00Z
promo.mp4,
weather.mp4,2026-08-01T18:30:00Z

Without a header, the first column is the media reference and an optional second column the start time. Blank lines and lines beginning with # are ignored.

Accepted time formats: RFC-3339 (2026-08-01T18:00:00Z), 2026-08-01 18:00:00, 2026-08-01 18:00, 2026-08-01, DD/MM/YYYY HH:MM:SS, and a bare 18:00 meaning today at that time.

XML — three dialects accepted

The importer detects the dialect from the document's contents rather than its namespace, so exports that omit or alter namespaces still import.

1 · PlayoutGo native — the simplest option if you are generating the file yourself:

<?xml version="1.0"?>
<playlist>
  <item file="news.mp4" start="2026-08-01T18:00:00Z"/>
  <item file="promo.mp4"/>
</playlist>

<entry>, <event> and <clip> are accepted as synonyms for <item>, and the media reference may be an attribute (file, filename, src, media, asset, name, title) or a child element of the same name.

2 · SMPTE ST 2021 (BXF) — the broadcast industry standard for schedule interchange, used by traffic and automation systems such as WideOrbit, Imagine, Pebble and Amagi. PlayoutGo reads a subset: each <ScheduledEvent> contributes one rundown item, using the first available of EventTitle, AssetName, MaterialName, Name, Title, MaterialId or EventId as the media reference, and StartDateTime, StartTime or SmpteDateTime as the air time.

<BxfMessage xmlns="http://smpte-ra.org/schemas/2021/2008/BXF">
  <BxfData><Schedule>
    <ScheduledEvent>
      <EventData>
        <EventTitle>news</EventTitle>
        <StartDateTime>2026-08-01T18:00:00Z</StartDateTime>
      </EventData>
    </ScheduledEvent>
  </Schedule></BxfData>
</BxfMessage>

3 · XMLTV — the widely used open EPG format. Each <programme> becomes an item, using <title> as the media reference and the start attribute (20260801180000 +0000) as the air time. Handy because PlayoutGo already publishes XMLTV, so a guide can round-trip.

<tv>
  <programme start="20260801180000 +0000" channel="c1">
    <title>news</title>
  </programme>
</tv>

API

# multipart upload (as the interface does)
curl -X POST "http://SERVER:8700/api/playlist/3/import?replace=true" \
  -H "Authorization: Bearer $TOKEN" -F "file=@schedule.csv"

# or post the document directly
curl -X POST "http://SERVER:8700/api/playlist/3/import" \
  -H "Authorization: Bearer $TOKEN" --data-binary @schedule.xml

The response reports the detected format, how many entries were parsed, added, anchored and skipped, plus a warnings list naming each unmatched entry and its line number.

Restart & Resilience v1.9

A 24/7 channel must survive a reboot, a crash or an upgrade without an operator pressing anything. PlayoutGo separates two ideas to make that work:

• Status — what a channel is doing right now (running, stopped, error).
• Desired state — what you asked for. ▶ Start marks the channel as should be running; ⏹ Stop clears it.

Shutdown stops the engines but deliberately preserves the desired state, so the next start brings back every channel you left on air. Channels queued for resume show an ⟳ auto-resume badge in the Channels list.

Where does it resume from?

• With a schedule — the engine walks your anchors, chains floating-item durations after them, compares against the wall clock, and seeks mid-file into the item that should be airing now. A channel anchored 25 minutes ago with three 10-minute items resumes 5 minutes into the third item.
• Without a schedule — playback continues from the next pending item.
• Empty rundown — the channel is left stopped with a note in its error log rather than spinning.

Resume is driven by the schedule rather than saved playback state, so it behaves correctly whether the process was stopped cleanly, killed, or the machine rebooted.

Automatic at the OS level

Run under systemd with Restart=always (see the 24/7 tutorial). Combined with channel resume, a reboot restores the entire playout unattended.

Measuring Channel Density v1.28

"How many channels will this box run?" has no useful generic answer — it depends on your bitrates, resolutions and storage far more than on PlayoutGo. The capacity panel gives a projection; benchmark.sh (shipped with the source) gives a measurement.

./benchmark.sh --password 'your-admin-password' \
               --file representative-clip.mp4 \
               --max 40 --step 4 --settle 60

It starts channels in steps, lets each step settle, then records CPU, load per core, I/O wait, memory, disk utilisation and egress — and, critically, whether every channel is still producing healthy HLS. Results go to benchmark-<timestamp>.csv; the benchmark channels are deleted automatically when it finishes or is interrupted.

Why it stops on output health, not a resource threshold

A host can look comfortable on CPU while segments start arriving late. The run therefore stops when any channel's HLS goes unhealthy, and reports the previous step as your practical density. Resource verdicts (LOAD_SATURATED, IO_BOUND) are recorded alongside so you can see which resource gave out first.

Reading the results

• The last row with verdict ok and zero unhealthy channels is your measured density for that content.
• IO_BOUND in the verdict means storage, not CPU, is your ceiling — move media to SSD/NVMe before buying cores.
• Run it with representative content. A 640×360 test pattern will give a flattering and useless number; benchmark with the bitrate and resolution you actually air.
• Benchmark on an otherwise quiet host. If the machine is already loaded by other work, you are measuring that, not PlayoutGo.

As-Run Logs v1.10

The as-run log is the record of what actually aired, as opposed to what was scheduled. Broadcasters need it for advertiser reconciliation, licensing reports, affiliate compliance and post-incident review. PlayoutGo writes one record per item automatically — there is nothing to enable.

Reading the log

Open the 🧾 As-Run tab. Filter by channel and date range (quick buttons for 1, 7 and 30 days), and the header summarises total items, total airtime in hours, bytes delivered, and how many entries had errors.

Exporting

⬇ Export CSV downloads exactly the rows currently filtered, with columns channel, file, started_at, ended_at, duration_sec, bytes_sent, errors, status, last_error. Timestamps are UTC RFC-3339 so spreadsheets and billing systems parse them unambiguously. The download is fetched with your auth header rather than a URL token, so your credentials never reach server access logs.

API

GET /api/asrun?channel_id=&from=&to=&format=csv|json&limit=
  from / to   RFC3339 or YYYY-MM-DD (a bare date for 'to' means end of that day)
  default     the last 24 hours
  format=csv  returns a downloadable CSV instead of JSON

# last week for one channel, as CSV
curl -H "Authorization: Bearer $TOKEN" \
  "http://SERVER:8700/api/asrun?channel_id=3&from=2026-07-20&to=2026-07-27&format=csv" \
  -o asrun.csv

Output Modes

Live Insertion — Cutting to an RTMP Feed 3.2.0

Every channel has its own publishing point. A contribution encoder (OBS, vMix, a hardware encoder, ffmpeg) publishes RTMP to it; the operator sees the feed arrive in the channel dialog and cuts the channel to it with ▶ Take live, then back with ⏎ Return to playout. Nothing is transcoded: the feed's own picture and bitrate go to air, on HLS, SRT and the RTMP push.

The publish URL and the stream key

• The URL is rtmp://HOST[:PORT]/live/<key>. HOST comes from advertised_base_url — without it the dialog shows 127.0.0.1, which only works for an encoder on this machine. PORT is rtmp_port (0 means 1935, which is left out of the URL).
• rtmp_port: -1 turns the publishing point off. The dialog then shows no URL and says "RTMP publishing is turned off on this server (rtmp_port is -1 in config.json)"; a port that could not be opened, or a listener that closed, is reported the same way. A failed accept no longer ends the listener: it retries with a back-off (3.52.0).
• New channels get a random key, live_ plus 48 hex characters (192 bits). A channel created before 3.48.0 may still accept the guessable ch<id>; the dialog warns, and the server lists such channels at startup. New key issues a fresh one (refused while the feed is on air); update the encoder afterwards. Keys are stored encrypted (secrets at rest); a key this server's keyring cannot decrypt accepts nothing and the dialog says so.
• A wrong key is refused at publish with "no channel is configured with this stream key".

What is accepted

• RTMP publish, simple handshake, version 3. Video must be H.264 (FLV codec 7) — anything else is reported as "the publisher is not sending H.264". Audio must be AAC; other audio is ignored. No HEVC or enhanced RTMP.
• The AAC is wrapped in ADTS on the way in, so every output decodes it (before 3.52.0 the raw frames reached air undecodable — silence). SPS/PPS are put in front of every keyframe.
• Long publishes stay in sync past 4 h 39 min, where RTMP timestamps need the extended field, including on continuation chunks (3.52.0).
• One encoder per key. A second publisher is refused with "another encoder is already publishing with this stream key" while the first sent anything in the last 3 s. If the first has gone quiet (an encoder reconnecting after a network blip), the newcomer replaces it and the stale connection is closed. Only the owning connection's media and disconnect count (3.52.0 — before, two encoders on one key were mixed into one feed).

Ready, take and return

The dialog polls GET /api/channels/{id}/live every two seconds while it is open, and stops when it closes. The feed is ready once it is connected, has sent its parameter sets and a keyframe, and has delivered a frame in the last 3 s; otherwise why says what is missing (audio is not required).

• Take (POST …/live/take) is refused with 409 unless the feed is ready and the channel is on air. The cut happens on the feed's first keyframe: between items, or mid-item on a video keyframe of a file item — a single-rendition item or, since 3.54.0, an ABR item, whose every rung then carries the feed. During a gap — gap filler, the slate or dead air while the channel waits for its next scheduled item — the cut is immediate (3.56.0; until then it waited for the whole gap, however long). When the feed ends the channel goes back to its wait, and the scheduled item still airs at its time. An avail that is open when the feed is taken is closed at once with its return marker. The interrupted item is recorded as completed and the schedule resumes after it.
• A take left on when a channel stops — stopped by an operator, or restarted for a settings change, while live was on air — is resumed at the next start only while its feed is still sending (a frame within 3 s); otherwise it is dropped and the channel starts on its schedule (3.57.0). Before, it was resumed regardless: with the publisher gone, the channel aired nothing for five seconds — only padding on a constant-rate channel — and logged a live as-run row and a live.lost entry for an event that had ended.
• While live airs, the feed's timeline continues the channel's, so there is no timestamp jump; the feed's single AAC track feeds every language slot.
• Return (POST …/live/return) hands back to the schedule within 100 ms.
• Feed lost. If nothing arrives for 5 s the channel returns to its schedule by itself and writes the audit entry live.lost (3.52.0 — before, the channel sat on dead air until someone pressed Return).
• As-run. A live insert is a row of its own, labelled LIVE — RTMP from <address>, with status live and, when the feed was lost, the reason (3.52.0).

GET  /api/channels/{id}/live          → {publish_url, key, key_predictable, key_locked, connected, remote,
                                         width, height, has_audio, mbps, frames, keyframes,
                                         last_frame_ago_s, on_air, ready, why, listener_off}
POST /api/channels/{id}/live/take     → 409 "the live feed is not ready to take — …" | "the channel is not on air"
POST /api/channels/{id}/live/return
POST /api/channels/{id}/live/rekey    → 409 while on air

ABR channels (3.54.0): a take during an ABR item cuts in on its next keyframe, and the feed reaches every variant playlist, so a player on any rung sees it. Until 3.54.0 the take waited for the ABR item to end and the feed reached HLS through the main playlist only.

Scheduled Ad Breaks & SCTE-35 1.54.0

An item can carry ad breaks — points in it where an avail begins, and for how long. When one is reached the channel signals it: a SCTE-35 splice_insert on the SRT transport stream for a downstream splicer, and cue tags in the HLS playlist for server-side ad insertion. Break now signals one immediately.

Setting breaks

• In the Rundown, 📢 on a row opens the break editor (mm:ss). A pattern — every N minutes, D seconds long, first at M — fills an item, and apply to every item lays the same structure across the rundown. Applying an empty list to every item removes every break; that asks first, and runs inside the question so a refusal is shown there (3.52.0).
• The API: POST /api/playlist/item/{id}/breaks with {"ad_breaks":[{"at_ms":600000,"duration_ms":120000}]}. An empty list clears the item. At most 64 breaks; at_ms ≥ 0 and before the item's (trimmed) end; duration_ms 1 ms–30 minutes. The answer says what will actually be signalled: {ad_breaks, requested, effective, item_duration_ms}. A break that starts inside the previous one is dropped and counted.
• at_ms is measured from where the item starts as aired — after a trim-in point.
• A resumed item (a restart mid-item) skips breaks before the resume point, and the rest fire at the right moment from there (3.52.0 — before, elapsed time restarted at zero, so a past break fired again).

On the SRT transport stream

• The program map declares the splice stream once a channel has breaks or a Break now: stream type 0x86 with a cue_identifier_descriptor (0x8A, cue stream type 0), and the programme carries the CUEI registration descriptor SCTE 35 §8.1 requires (3.52.0 — without it ffprobe and many splicers read the PID as unknown data).
• The PID is above every elementary stream: 0x111 with one audio track, 0x112 with two languages, and so on.
• The cue-out is an immediate splice_insert with out_of_network_indicator=1 and a break_duration (auto_return=1). The matching return (out_of_network_indicator=0) goes out when the avail ends, on whatever is airing then — the same item, the next one, or a live feed (3.52.0 — an avail that outlasted its item never got its return). Each section has its own continuity counter (3.52.0 — every splice packet used to carry counter 0, so a receiver discarded the return as a duplicate). splice_event_id starts at the engine's start time and counts up.
• No section goes out before a program map declaring its PID has reached the receiver; a new receiver starts that check again. With no SRT receiver connected, breaks are signalled on time anyway — in both mode HLS viewers no longer wait for an SRT receiver to get their cues (3.52.0).

In HLS

• #EXT-X-CUE-OUT:<seconds> and #EXT-X-DATERANGE:ID=…,START-DATE=…,PLANNED-DURATION=…,SCTE35-OUT=0x… on the segment where the avail begins, carrying that avail's own section; #EXT-X-CUE-OUT-CONT:<elapsed>/<planned> while it runs; #EXT-X-CUE-IN when it ends.
• Every media segment carries #EXT-X-PROGRAM-DATE-TIME, which RFC 8216 requires alongside DATERANGE (3.52.0).
• HLS segments carry no in-band SCTE-35; the cue tags are the HLS signal.

An avail inside an avail 3.53.0

Break now during a scheduled break (or a scheduled break due while Break now's avail is open) does not nest: the open avail returns first — its return goes out on that frame — and the new one starts, so every cue-out has a return of its own. In HLS both land on the same segment, #EXT-X-CUE-IN written before the new #EXT-X-CUE-OUT. Until 3.53.0 the new avail overwrote the open one's end: the first cue-out never got its return and a splicer saw one avail of the wrong length.

ABR items (3.54.0): an ABR item's scheduled breaks, and Break now during one, go out like a single-rendition item's — on SRT, and as cue tags in every rung's playlist on the same segment, so an SSAI system reads the same avail whichever rung a player is on. Break now during gap filler, the slate or a live feed still waits for the next item, and says so (queued).

Audio Languages 3.32.0

A file with several audio tracks — English, Spanish, French — airs all of them, each as its own stream labelled with its language. There is no channel setting for this: the channel's set of languages is worked out from its rundown when it starts.

The channel's languages

• The probe records each file's tracks (audio_tracks: language, codec, channels, sample rate); und counts as untagged. The Media library shows a badge for multi-track files.
• At the first file it plays, the channel fixes its set: the first item's first-track language is the main slot, then every new language found on the other tracks of the rundown, in rundown order. The set stays for the whole run, so a programme without Spanish does not make the Spanish stream disappear. Rundown edits take effect at the next start.

Routing each item into the slots 3.52.0

1. Each slot takes the item's track tagged with its language.
2. The main slot falls back to the item's first track.
3. Untagged tracks fill the remaining slots in order.
4. A slot still empty carries a copy of the main slot, so a declared stream never goes silent.

Before 3.52.0 tracks were routed by position, so a file whose tracks were in a different order from the first item's aired French on the Spanish stream. A track in a language the channel does not carry is not aired (the log says which). Live feeds and the slate have one track, which feeds every slot.

On the outputs

• SRT: one AAC stream per slot (main on PID 0x101, then 0x102…), each with an ISO 639 language descriptor in the program map.
• HLS (3.54.0): index.m3u8 is a master playlist with an EXT-X-MEDIA audio rendition per language — the main one muxed in the variant, each other one an audio-only playlist audioN.m3u8 — so a player offers an audio menu. Every variant segment still carries every slot. See the master playlist.
• RTMP push: the main language only — RTMP carries one audio track.
• Encodes keep every track (3.52.0): local encodes and demo watermarking map all audio (-map 0:a?), where they used to keep only the first. Local encodes re-encode audio to AAC stereo; a remote node decides for itself.

ABR rungs (3.54.0) carry every language too, each rung's tracks routed by language like an item's; a rung encoded with the first track only feeds every slot from it. Until 3.54.0 the rungs carried the main language only, and the media playlist carried EXT-X-MEDIA lines, which RFC 8216 allows only in a master playlist — players that follow it showed no audio menu.

A receiver that connected early (3.53.0): one that connected during a start-up slate got a stream built before the first item fixed the languages — one audio stream — and the other languages were dropped for it until it reconnected. The transport stream is now rebuilt when the language set no longer matches it, with a new program-map version, so the receiver re-reads the map and gets every stream without reconnecting.

Closed Captions 2.44.0

• CEA-608/708 captions carried in the video as A/53 SEI pass through untouched: playout copies every NAL unit, so captions in a file — or in a live feed — reach HLS and SRT. The probe sets has_captions and the Media library shows a CC badge; it is informational and changes nothing.
• Every encode on this server carries them forward explicitly (-a53cc 1): local GPU and CPU encodes, and demo watermarking (3.52.0 added it there). For a remote node, carrying them is up to the node.
• PlayoutGo does not author captions. Since 3.54.0 the HLS master declares them when any item in the rundown has has_captions: #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS,GROUP-ID="cc",NAME="CC1",INSTREAM-ID="CC1" and CLOSED-CAPTIONS="cc" on every variant, an ABR channel's rungs included. Apple players show a captions menu only for a declared track. Like the languages, this is fixed when the channel starts.

DVB Service Information 2.5.0

A channel feeding a DVB modulator, multiplexer or IRD can carry the tables a DVB receiver reads to name the service and set its clock. They go on the SRT output only (HLS has no use for them). Choose Constant bitrate with DVB service tables in the channel dialog's broadcast setting, or send a dvb object on channel create or update; "dvb": null turns them off, and leaving it out of an update keeps the current settings. Changing it on a running channel restarts the channel (3.52.0).

What goes out

• The PAT's transport_stream_id and the programme number in the PAT and PMT are the service's own numbers (3.52.0 — they used to say programme 1 in transport stream 0, so a receiver could not join the SDT's name to the programme it was watching).
• The clock: the programme's video packets carry the PCR, on the PID the PMT names; while no programme flows (a gap, a receiver waiting for its first keyframe) PCR-only packets on that PID keep it running every 30 ms, continuing its continuity counter (3.52.0 — they used to go on the audio PID).
• The tables go out on their schedule while the programme airs (3.52.0 — they used to be sent only in gaps and while a receiver waited for a keyframe, so after its first second a receiver saw no SDT at all).
• No EIT (programme guide) — the guide is XMLTV (XMLTV).

QR Codes on the Picture 2.8.0

A channel can carry a QR code — a link to a donation page, an app, a programme website — burned into its picture at encode time. Set QR code on screen and its corner in the channel dialog, which shows a scannable preview, then press Re-encode this channel.

• qr_url: empty, or an http:///https:// address of at most 666 bytes (QR version 20 at error correction M). It is checked when the channel is saved and refused with qr_url: … (3.52.0 — it used to be checked only when an encode rendered it, so a bad address saved fine and every encode went out without a code).
• qr_corner: top-left, top-right, bottom-left or bottom-right (default; also tl, tr, bl, br, any case), stored in full. Anything else is refused with qr_corner must be … (3.53.0 — it used to be stored and silently meant bottom-right; a corner stored that way before keeps meaning bottom-right when the channel is saved for another reason). Inset 3% of the picture height from both edges.
• Size: 11% of each rendition's picture height — about 119 px on 1080p, 79 px on 720p — raised so the shortest rung still gets at least 64 px, capped at 25%. A channel whose tallest rendition is under 480 lines gets no code (it would not scan); the log says so.
• Only encoded output carries it. A channel playing original files has nowhere to burn it in, so Re-encode refuses (choose single bitrate or ABR first). Live feeds, the slate and filler that is not in the rundown carry none.
• Re-encode (POST /api/channels/{id}/reencode) queues each ready file in the rundown once, however often it is scheduled. A file already waiting in the queue for this channel is not queued again — it reads the channel's current code when it starts (3.52.0 — pressing Re-encode twice queued everything twice). A file encoding right now is queued again, because that run started with the old code. The answer gives queued, skipped, already_queued and an ETA.
• Saving a new address changes nothing on air by itself; each item shows the new code the next time it starts after its re-encode finished.

Graphics & Branding — What Goes on the Picture

• The built-in frame is drawn by the node from two colours — bg_color (default #101820) and accent_color (default #2ea0ff) — sent as bar_background and bar_accent (3.52.0: they were never sent before). Headline and ticker edits reach air live, without rebuilding the session.
• A page (html up to 64 KB, or a url) is rendered by a node with headless Chromium and re-captured every snapshot_sec — default 300, at least 30 (3.52.0: the default sent was 5 seconds). Graphics and logo URLs must resolve to public addresses, or to hosts in graphics_allowed_hosts.
• The channel card shows ▣ L-SHAPE while viewers get the composited picture, FALLBACK — clean output when the node is not delivering, resuming at boundary when it has recovered, and composited when the channel is stopped (3.52.0: a stopped channel was shown as FALLBACK, and the chips did not update until something else on the card changed).

• Traffic graphics on the built-in frame (3.53.0): the node is sent the cues on air as overlays — code, image URL, corner, width and margin, the same objects cues.json gives a page — in the session spec, and again through /v1/composite/{id}/update whenever the set changes (checked twice a second; an empty list clears them). Every text update carries them too. Until 3.53.0 they never reached air on the built-in frame.
• The logo (3.53.0): logo_url when set, otherwise the logo uploaded for the channel, served at /graphics/{id}/logo with a version that changes with the file. Uploading a new logo rebuilds a running session with it. Until 3.53.0 the upload was never used by the L-shape.

L-Shape Graphics v2.50

A channel in composited graphics mode gets the classic FAST-channel L-shape: the programme in the top-left 75% of a 1080p frame, a sidebar and bottom bar carrying headline, a smoothly scrolling ticker, colours and logo. The work happens on a composite-capable gpunode (-role composite or both, gpunode ≥ 1.34): the node pulls this origin’s clean HLS, renders the frame, re-emits HLS — and this origin keeps serving viewers, fronting the node’s output while it is healthy and its own clean output when it is not. Delivery accounting, DRM and CDN configuration are untouched, because the origin never moves.

Graphics sources

The built-in frame (headline/ticker/colours/logo in the channel dialog) is drawn entirely by ffmpeg on the node — no browser anywhere, works on every node, and the ticker scrolls smoothly because the encoder renders it. Pasted HTML and an external URL switch the node to headless Chromium: the page is screenshotted at 1920×1080 (leave the top-left 1440×810 transparent — the programme goes there), external URLs are re-snapshotted on an interval (min 30 s, default 5 min) with hold-last-good-frame — a failed snapshot keeps the previous image, because a broken graphics vendor must never take the programme down. Content changes apply while on air; the compositor restarts with the new frame and the clean fallback covers the seconds of gap.

The fallback (and the patience)

The origin health-checks the node’s playlist every few seconds; a playlist that stops changing is as dead as a 404. When it goes stale, viewers get the clean programme immediately — mid-item, because the alternative is dead air — and the switch is loud: a red FALLBACK chip on the channel card, an audit entry, and playoutgo_channel_graphics_ok at 0. When the node recovers, composited output returns quietly, at the next item boundary — graphics never pop back mid-programme. The amber resuming at boundary chip shows the wait. At start there is nothing on air to protect: the session's first healthy check serves composited output at once (3.53.0 — it used to wait for the first item boundary, so a channel opening on a two-hour film had no graphics for two hours).

Tiered Media Storage & Failover v2.49

Original media can live on up to three tiers: the primary (the uploads directory), an optional local mirror on another disk or partition, and an optional S3 bucket (AWS, MinIO, Wasabi — anything speaking the S3 API; a minimal SigV4 client is built in, no SDK). Configure in config.json:

"mirror_dir": "/data1/playout-media",
"s3": {"endpoint": "https://s3.us-east-1.amazonaws.com", "region": "us-east-1",
       "bucket": "tulix-playout", "prefix": "media", "access_key": "…", "secret_key": "…"}

With neither configured, nothing changes — single-directory installations behave exactly as before.

Replication

Every ingested original (browser upload or watch folder) is copied to the other tiers immediately, and a reconciler sweep runs every five minutes with one direction-free rule: every configured tier ends up holding every file at the right size, copied from wherever a good copy lives. That single rule is initial seeding, ongoing mirroring, healing a damaged replica, and post-outage resync — four behaviours that would each have bugs if they were four mechanisms. Truth is size: cheap enough to check every file every sweep, and it catches the failures disks actually have (missing, truncated, half-copied). If bit-rot is your concern, put the mirror on ZFS. Replicas are copied via a temporary name and rename, so an interrupted copy can never be mistaken for a finished one. Deleting a file deletes it from every tier — a mirror still holding a deleted file would resurrect it at the next sweep.

Failover

A health monitor write-probes the primary and mirror every five seconds — a stat is not enough, because a dead NFS mount stats fine and a read-only remount stats fine; writing a byte tests what ingest and playback actually need. Two consecutive failures declare a tier down (one slow probe during a backup does not fail anything over); two consecutive successes bring it back. While the primary is down: reads resolve per-file down the chain — primary, mirror, the restore cache, then a synchronous S3 download — so playback continues without any global switch; ingest writes to the first healthy local tier, so uploads keep working through the outage. The failover is announced everywhere an operator looks: a red badge in the top bar, the storage card in Admin, an audit entry, and the log.

Failback — automatic, with resync

When the primary passes probes again, an audit entry records the return, a sweep is kicked immediately, and everything that landed on the mirror during the outage flows back to the primary — then ingest routes to it again. Failback is not an operation anyone performs; it is a state the reconciler converges on. The ⟳ Sweep now button in Admin exists for the day a new disk is plugged in and five minutes feels long.

Disk Quotas & Account Lifecycle v2.48

Three controls cover an account’s life on the platform: a disk quota while it is active, suspension while a dispute is open, and deletion when it is over. Together they answer the question a multi-tenant playout host eventually asks: whose bytes are these, and who said they could be here?

Disk quotas

The quota covers original files — the bytes a user chooses to store. Renditions the system encodes do not count: their size is a property of the encode profile, not of anything the user did. Zero means unlimited, and is the default. Set it per account in the Users panel (✏ Edit → disk quota in GB) or via PUT /api/admin/users/{id} with disk_quota_bytes.

Enforcement happens at every path that adds bytes, before a byte is written: the browser upload is refused with HTTP 507 and a message carrying the numbers (file size, space used, the ceiling); the watch folder leaves the file in place unimported — and picks it up on a later poll if space is freed or the quota raised, logging its refusal at most every ten minutes. The re-import scan is not gated: it adopts files already on disk, so refusing it would not save a byte, only hide existing bytes from the accounting the quota reads. Users see their own usage as a bar above the upload area (GET /api/media/usage), so a refusal is never the first they hear of the ceiling. Deleting files frees allowance immediately — the accounting is the library’s own file_size, corrected by every probe, so it tracks the disk without walking it.

Suspension

Suspension (⏸ in the Users panel, or POST /api/admin/users/{id}/suspend) stops the account’s channels immediately, refuses every start while it lasts, and — since v2.48 — closes the upload gate too: browser uploads answer 403 with the suspension reason, and the watch folder stops importing. Nothing is deleted; the usual reason is a billing dispute, and a customer who then pays should not have lost their library over it. Restoring lifts everything at once.

Deletion

Deleting an account (DELETE /api/admin/users/{id}) is the full teardown, in order: every running channel is stopped; the account’s file paths are collected before the database cascade (afterwards there would be no way to find them); the rows go; then the files go — uploads and encoded renditions. The response reports freed_bytes, and anything that could not be removed is named in not_removed rather than silently left to fill the disk. There is no undo; the confirmation says so.

Demo Accounts v2.47

A demo account exists to be tried, not to run a channel for free. The deal is stated in one sentence on the sign-up form: everything a demo account uploads is converted to at most 720p with a “Playout from TULIX.COM” watermark burned into the bottom-right corner before it can air. Everything else — channels, scheduling, EPG, the full interface — works exactly as it does for a paying account, which is the point: the demo shows the product, and the watermark shows whose.

How enforcement works

Enforcement happens at the probe gate — the one step every file passes on its way to becoming playable, whether it arrived through the browser uploader, the watch folder, or the re-import scan. A file belonging to a demo account is never “ready” clean:

uploading → processing → watermarking → ready   (demo account)
uploading → processing → ready                  (normal account)

While a file shows watermarking it cannot be added to a rundown or played. When the transcode finishes, the watermarked file replaces the original atomically — the clean copy is not kept — and the re-probe marks it ready with its new dimensions. If the transcode fails, the file is marked error rather than being allowed to air clean; the failure is in the log with ffmpeg’s own words.

What the watermark looks like

One filter, defined in one place, so it cannot drift: video scaled to at most 720 lines (a smaller source is watermarked at its own size — upscaling would spend bits making it worse), then bold text at h/30 (≈24 px on a 720 line) in white at 92% over a soft dark pill (35% black, 10 px padding) with a one-pixel shadow, anchored bottom-right with a 24/20 px margin, clear of TV overscan. The pill is what makes it read on any content — white text alone disappears on clouds, black on shadows.

scale=-2:'min(720,ih)',format=yuv420p,
drawtext=fontfile=…DejaVuSans-Bold.ttf:text='Playout from TULIX.COM':
  fontsize=h/30:fontcolor=white@0.92:box=1:boxcolor=black@0.35:boxborderw=10:
  shadowcolor=black@0.6:shadowx=1:shadowy=1:x=w-tw-24:y=h-th-20

Where the transcode runs — and why

Demo transcodes run locally on the playout host, on the CPU (libx264, veryfast, CRF 21, audio copied — re-encoded to AAC only if the copy is refused), bounded to two at a time. This is deliberate: demo traffic must never occupy a GPU encode slot that paying work is queued for, and a demo account must work on a system with no encode nodes configured at all. A demo upload therefore takes a little longer to become ready than a paying upload does. That is the correct trade.

Lifting demo status

An administrator lifts it from the Users panel (✦ Lift demo) or the API. Lifting affects future uploads only: files already watermarked keep the watermark, because it is burned into the content — there is no clean copy to go back to. Re-uploading the originals is the path to clean copies. The same endpoint can also apply demo status to an existing account, which watermarks what it uploads from then on and leaves its existing library untouched. Both directions are audited.

Authentication

API calls need an account token (a JWT, 72 hours) in the Authorization header. The exceptions are /api/auth/login, /api/auth/register, /api/auth/reset, /api/youtube/callback and the App API (/api/app/*, application key). The feeds /epg, /epg/my and /m3u take a feed token; /epg/{id}, /hls/, /hls-clean/ and /graphics/ are public; /metrics is IP-allowlisted. Obtain an account token via login.

POST /api/auth/login
{"email": "admin@playout.local", "password": "<admin_password from config.json>"}

→ {"token": "eyJ...", "user": {...}}

Pass the token in the Authorization header:

Authorization: Bearer eyJ...

The three tokens

Public Endpoints (no token)

These are served without authentication, deliberately, because the systems that fetch them cannot hold a credential: /hls/ and /hls-clean/ (players and compositing nodes), /epg/{id} (one channel's XMLTV, for media servers), /graphics/{id}.html and /graphics/{id}/cues.json (compositors), /docs, /about, /viewer, /guide/push, /guide/deploy, /healthz and /api/youtube/callback. The ones with something to say are below.

Connecting a YouTube Account

An operator can connect their YouTube account once and never copy a stream key again. PlayoutGo creates the broadcast and reads the ingest address itself.

Setting it up, once, per deployment

1. In the Google Cloud console: a project, the YouTube Data API v3 enabled, and an OAuth client of type Web application.
2. Add the redirect URI the status endpoint reports — it is <advertised_base_url>/api/youtube/callback. Google rejects anything not listed there, so it must match exactly.
3. Put the client id and secret in config.json as google_client_id and google_client_secret.

curl -s -X POST $BASE/api/channels/7/youtube -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{"title":"Tulix Live","privacy":"unlisted"}'
→ {"broadcast_id":"…","stream_id":"…","privacy":"unlisted",
   "watch_url":"https://youtu.be/…","push_target":"rtmp://a.rtmp.youtube.com/live2/ab…op",
   "message":"The broadcast is ready. Start the channel and it will go live automatically."}

How the token is held

The refresh token is encrypted with AES-256-GCM under the server’s keyring (secrets_key_file, see Secrets at rest), which is not in the database — so a copy of the database alone yields nothing. The short-lived access token is held in memory and refreshed a minute before it expires, because a token that lapses between the check and the call fails a live operation for no reason. Neither token is ever returned by any endpoint or written to a log.

Pushing a Channel to YouTube

A channel can publish itself to any service that gives you an RTMP address and a stream key — YouTube, Facebook, Twitch. It sends the same frames as SRT — the original, the single rendition, or an ABR channel's tallest rung (until 3.52.0 a fully encoded ABR item sent the push nothing) — so there is only ever one quality to reason about. Only the main audio language is pushed.

Setting it up

1. In the channel dialog, paste the address and key into Push to a streaming service: rtmp://a.rtmp.youtube.com/live2/xxxx-xxxx-xxxx-xxxx. It is checked as you type — an address with no key is the commonest mistake and is caught before saving.
2. Press “Use YouTube’s recommended quality” to set the ladder from their own live guidance: 1080p at 4500 kbps, 720p at 2500, 480p at 1000, AAC 128, and a two-second GOP. Getting one rung wrong means the stream is accepted and then transcoded badly, which looks like a fault in the picture rather than a setting.
3. Start the channel. The push connects, and retries by itself with a widening delay if the service drops it.

curl -s $BASE/api/channels/7/push -H "Authorization: Bearer $TOK"
→ {"enabled":true,"target":"rtmp://a.rtmp.youtube.com/live2/ab…op",
   "connected":true,"seconds_up":412,"video_frames":10300,"audio_frames":17800,
   "dropped":0,"mbps":4.6,"retries":0}

One soundtrack. RTMP carries a single audio stream, so a channel with several languages pushes the main one and counts the rest — alt_audio_dropped in the push status, with a line saying why. Sending them all would put four soundtracks into one stream, which decodes as noise.

What to expect. The push never slows the channel: if the service cannot keep up, frames are dropped and counted rather than queued — a live push that buffers falls further behind every second and never recovers. Frames sent before the connection is established are dropped too, which is why a small dropped count at start-up is normal. Stopping the channel closes the connection, so the service stops showing a stream with nothing behind it.

SDI Output (DeckLink) 3.62.0

A channel can play out of an SDI port on a Blackmagic DeckLink card in this server — to a router, a transmitter, a master-control switcher or a monitor — alongside SRT, HLS and the RTMP push. The output takes the same frames as everything else: they are muxed into a transport stream and piped to ffmpeg, which decodes them, scales and pads them to the SDI format (aspect kept, black bars), sets its frame rate and field order, converts to 4:2:2 8-bit (uyvy422), embeds the audio as 48 kHz 16-bit PCM, and writes to the card with ffmpeg’s decklink output device. The card’s clock paces the port.

What the server needs

• A DeckLink card and Blackmagic’s Desktop Video driver.
• ffmpeg built with --enable-decklink against Blackmagic’s Desktop Video SDK. Distribution packages are not built that way. GET /api/sdi/devices says whether this server’s ffmpeg can drive a card, and why not when it cannot.

Setting it up

1. As an administrator, open the channel dialog: SDI output (Blackmagic DeckLink). The DeckLink output box suggests the cards ffmpeg sees (as ffmpeg -sinks decklink names them: DeckLink Duo (1)).
2. Choose the video format: 1080i59.94 (North America), 1080i50, 1080p29.97, 1080p30, 1080p25, 1080p59.94 and 1080p50 (3G-SDI), 720p59.94, 720p50, 525i59.94 (SD NTSC, 720×486, bottom field first), 625i50 (SD PAL). Interlaced HD is top field first.
3. Choose the embedded audio: 2, 8 or 16 channels. The channel’s main audio is on channels 1 and 2; the others are silent.
4. Set SDI On and press Apply SDI settings. It takes effect at once: on air, the port starts (or restarts with the new settings); off air, it starts with the channel.

curl -s -X PUT $BASE/api/channels/7/sdi -H "Authorization: Bearer $TOK" \
  -d '{"enabled":true,"device":"DeckLink Duo (1)","format":"1080i59.94","audio_channels":8}'

What to expect. The output never slows the channel: if ffmpeg falls behind, frames are dropped and counted, as the RTMP push does. It starts on a keyframe. If ffmpeg exits — no card, the card busy, the driver missing — the status gives ffmpeg’s own message, and it is started again after 1, 2, 4 … up to 30 seconds. Stopping the channel stops the port. A channel’s second and further languages are not embedded (counted as alt_audio_dropped). Captions are not carried in the SDI ancillary data.

UDP / RTP Output 3.63.0

A channel can send its transport stream over UDP — to a multicast group (239.1.1.1:5000) or a unicast address — the way cable head-ends, IRDs, multiplexers and IPTV networks take it. It is the same stream the SRT output carries: one muxer feeds every transport output, so the DVB service tables, SCTE-35 splices and constant-rate padding reach the multicast as they reach SRT. It runs whenever the channel is on air, whatever its output mode.

Setting it up

1. As an administrator, open the channel dialog: UDP / RTP output.
2. Destination: IP:port — an IP literal, not a name, so a feed never moves because a DNS answer did (239.1.1.1:5000, [ff3e::1234]:5000, 10.0.0.5:1234).
3. Encapsulation: UDP, seven 188-byte packets to a datagram (1316 bytes); or RTP, the same with a 12-byte RFC 3551 header — payload type 33 (MP2T), a sequence number, a 90 kHz timestamp and one SSRC per run. A datagram is always seven packets while the stream flows; packets that have waited a quarter of a second for the rest — a channel with no constant rate gone still — are sent short, and counted (short_datagrams).
4. Interface: the network interface multicast leaves by (eth1); blank lets the routing table choose. TTL: multicast hops, 1–255 (default 16). DSCP: the IP header’s traffic class, 0–63 (34 is AF41, 46 is EF).
5. Pacing: -1 spreads the datagrams evenly at the channel’s constant bitrate (the default, and what equipment with small input buffers needs); a number paces at that many kb/s; 0 sends each frame’s packets at once. Paced, a queue holds two seconds; a stream faster than the pacing rate drops datagrams and counts them.
6. Set it On and press Apply UDP settings. On air, it starts at once.

curl -s -X PUT $BASE/api/channels/7/udp -H "Authorization: Bearer $TOK" \
  -d '{"enabled":true,"address":"239.1.1.1:5000","interface":"eth1","ttl":8,"dscp":34,"rtp":true,"pace_kbps":-1}'

With SRT as well. When the UDP output runs, an SRT receiver connecting no longer restarts the stream: the multicast carries on with no continuity break, and the SRT receiver is given only padding and service information until the next keyframe, then the current PAT and program map, then the stream. Without a UDP output, SRT works as it always did.

Watching it. playoutgo_channel_udp_bytes_total, playoutgo_channel_udp_datagrams_total, playoutgo_channel_udp_dropped_total and playoutgo_channel_udp_send_errors_total in /metrics; the bundle’s alert rules fire on refused and dropped datagrams; a refused output is an output.down webhook event. Datagrams the network accepts can still be lost beyond the server: multicast routing (IGMP, PIM) is the network’s.

Alert Webhooks 3.63.0

The server tells your systems when something goes wrong on air, instead of waiting to be scraped. Each event is an HTTP POST of JSON to every webhook that wants it, signed with that webhook’s secret, queued in the database and retried, so an endpoint that is down for a while gets what it missed. Administrators set them up under Admin ▸ Alert Webhooks; at most 20.

Events

A down/up pair is sent once each way: a channel that keeps failing is one channel.down, then one channel.up when it is back. A webhook can take every event or a list, and every channel or a list.

What is sent

POST /your/endpoint
Content-Type: application/json
X-PlayoutGo-Event: output.down
X-PlayoutGo-Delivery: 42
X-PlayoutGo-Timestamp: 1792008000
X-PlayoutGo-Signature: sha256=6f1c…

{"id":"evt_9b2e…","event":"output.down","at":"2026-10-14T21:20:00Z","server":"https://plt.example.com",
 "version":"3.64.0","channel":{"id":7,"name":"ENG"},"summary":"udp output down",
 "detail":"datagrams to 239.1.1.1:5000 are refused: network is unreachable","extra":{"output":"udp"}}

Checking the signature. Compute HMAC-SHA256 of <X-PlayoutGo-Timestamp>.<body> with the webhook’s secret and compare it, in constant time, with the hex after sha256=; refuse a timestamp more than a few minutes old. The secret (whsec_…) is shown once, when the webhook is added or given a new one, and stored sealed.

Delivery

• A 2xx answer is delivered. Anything else, or no answer within 15 seconds, is retried after 10 s, 30 s, 2 min, 10 min and 30 min; after that the delivery is marked failed. Each webhook keeps its deliveries, with the last code and error, for seven days.
• Redirects are not followed. The URL must be http or https, with no user name or password in it. Link-local addresses (cloud metadata at 169.254.169.254 among them), multicast and the unspecified address are refused — when the webhook is saved, and again when each connection is made, after DNS. Private and loopback addresses are allowed: a relay or Alertmanager usually lives there.
• The audit trail names the URL without its query, where a relay’s token often sits.

Watching a Running Server

curl -s http://playout:8937/healthz
→ {"status":"ok","version":"3.38.0","uptime_seconds":412}

Deliberately shallow. It confirms the database is reachable and nothing more. A check that queries hard becomes the thing that finishes off a server already under strain, and one that reports on every channel would fail the whole instance because a single channel is stopped — which is a normal condition, not an unhealthy one. Use /metrics to alarm on channels.

"metrics_allow_from": ["10.0.0.0/8", "127.0.0.1"]

The pair worth alarming on is playoutgo_channel_up and playoutgo_channel_delivering. A channel can be up and not delivering — marked on air while writing no segments — and that gap is the failure an operator most wants to hear about, because nothing else reports it.

The process itself 3.57.0

playoutgo_process_goroutines, playoutgo_process_heap_bytes, playoutgo_process_resident_bytes, playoutgo_process_open_fds, playoutgo_process_threads and playoutgo_process_uptime_seconds. Alert on resident memory approaching the memory limit, open files approaching the unit’s LimitNOFILE, and an uptime that resets (a restart). Over an hour with five channels on air they held flat: 41 goroutines throughout, 18–24 open files, 9 threads, 24–30 MB resident (26.6 MB on average) — 3.57.0; from 3.58.0 each channel adds one goroutine, the as-run heartbeat, so 46 with five, flat over the 3.58.0 soak.

Bytes (3.57.0): playoutgo_channel_bytes_sent_total is the transport stream alone (SRT), as its description says, and playoutgo_channel_hls_bytes_total is the HLS variant’s segments. Until 3.57.0 the first was the engine’s total, HLS included: a constant-rate channel read about 15% above its configured rate, and an HLS-only channel appeared to send on a transport output it does not have.

Alert rules 3.58.0

The deploy bundle holds playoutgo-alerts.yml, Prometheus rules for the alerts above: the server down; a channel on air and not delivering; a restart; resident memory above 80% of the default memory limit; open files above 80% of LimitNOFILE; the disk under 10% and 3%; encoding nodes down and the queue stalled; a constant-rate channel more than 2% off its rate; late or backwards DVB clock references; graphics falling back. Copy it to the Prometheus host and list it under rule_files; scrape the server as job playoutgo. A test checks that every metric the rules name is one /metrics exports, and, where promtool is installed, runs promtool check rules and the rule tests in deploy/playoutgo-alerts.test.yml, which feed each alert the series it should fire on. Adjust the memory and file thresholds if you change GOMEMLIMIT or LimitNOFILE.

Capacity, Measured

Eight channels on air at once, each looping a 1280×720 25 fps file to HLS: 197 MB resident and 10.3% of one core, with all eight writing fresh segments. That is roughly 17 MB and 1.3% of a core per channel over about 40 MB of baseline.

Read those as a floor rather than a promise. The measurement looped one small file on every channel, so the page cache is working less hard than it would with a hundred distinct programmes, and there is no encoding in the figure — that is what the nodes are for. Graphics compositing, CBR pacing and an RTMP push each add work this did not include. What it does establish is that the per-channel cost is small and flat: eight channels behaved no differently from one, and memory grew linearly rather than in steps.

Playout is I/O and clock bound, not processor bound — it remuxes rather than transcodes, so the disk feeding the files is the thing to size. Each channel also holds its own segment directory, continuously written; a hundred channels at a six-segment window of 1080p is real disk.

And it plays

A standard HLS client consumed 40 seconds of a live channel over HTTP, across a rundown of two different files so it had to cross an item boundary mid-stream: 998 video packets over exactly 40.0 seconds, no decoder complaints, and no gap over 200 ms. The second file’s extra Spanish track appeared mid-stream and the client picked it up.

Zero gaps is the number that matters. A stream that decodes but stutters at every segment boundary passes every structural check and is unwatchable.

Constant Bitrate — Two Different Things

“CBR” means two separate mechanisms here, and confusing them is how a channel ends up over its pipe.

1 · The channel’s transport rate — done here, not on a node

Set cbr_bps on a channel and the engine paces its own SRT output, padding each interval with null packets so the total never varies. This is what a modulator, an ASI card or a multiplexer expects. It runs in PlayoutGo; no encode node is involved.

Exact, not approximately right (3.57.0). What is left of a packet each interval, and the fractions of a bit and of a byte, are owed to the next one, so over any minute the stream is the configured rate to within one packet. Before, each 20 ms interval dropped half a packet on average: a 3 Mb/s channel left at about 2.965 Mb/s.

Padding can only ever add. If the programme itself runs above the target the pacer cannot bring it down — that needs re-encoding — and the stream leaves at the content’s rate. Measured: a 4 Mb/s channel playing a 6.5 Mb/s file transmits at 6.75 Mb/s with 2% padding. The channel now says so in the log when an item is above its target, naming both rates.

The rate starts with the receiver (3.56.0). The pacer used to begin its interval when the engine started, or when the last receiver left, and paid that idle time as one burst of padding on the next connect — up to a second’s worth on top of the stream, about 1.7 times the rate in the first second, into the buffer of exactly the equipment a constant rate exists to serve. It now restarts when a receiver connects; measured, the first second carries the rate or less.

2 · Encoding a file at a constant rate — done by the node

Choose Constant bitrate as a channel’s source quality and each encode carries cbr=1 to the node, which holds the encoder to the target and pads the undershoot. That is gpuff’s work, not ours.

The two belong together. Encode the files at or below the rate, then let the transport pacer hold the pipe exactly. Either alone leaves a gap: encoding without pacing gives a stream that dips between pictures, pacing without encoding gives one that overruns.

What PlayoutGo Sends an Encode Node

Two questions come up often enough to answer here: how the QR code reaches the picture, and how an L-shape does. Neither needs an endpoint of its own on the node.

The QR code — a generic image overlay, not a “QR API”

PlayoutGo renders the code itself and sends it as an ordinary PNG. The node never learns it is a QR code, and does not need to: it composites an image at a position and a scale. That is deliberate — a node that had to know about QR codes would need a new release every time the thing being burned in changed.

POST /v1/jobs        (multipart)
  ladder            [{"label":"1080p","height":1080,"video_k":5000,"audio_k":128}, …]
  format            mp4
  segment_seconds   6                # the profile's; the YouTube preset uses 4
  gop_seconds       2
  align             true
  cbr               1                # only for a constant-bitrate profile
  audio_hz          48000            # the source rate, when probed, so the node need not guess
  owner             playoutgo
  overlay           <overlay.png>    # the rendered code, as a file part
  overlay_pos       main_w-overlay_w-(main_h*0.03):main_h-overlay_h-(main_h*0.03)   # bottom-right; other corners follow qr_corner
  overlay_scale     0.1100           # four decimals; only when above 0
  file              <source.mp4>     # or sha, when the node already has it

The scale is a fraction of each rendition's picture height, whatever size the PNG is: 0.11 is about 119 px on 1080p and 79 px on 720p. It rises to 64 px ÷ the shortest rung's height when that is larger (capped at 0.25), so the smallest rung still carries a scannable code. Local encodes on this server apply it the same way. Nothing in the request tells the node which audio tracks to keep or to carry captions; that is up to the node (audio languages, captions).

Verified against gpuff 1.8.3: a white test overlay on a black source encodes with the corner reading luma 235 — the image is on the picture.

The L-shape — a composite session, not an encode job

Graphics do not travel with an encode. A composited channel opens a session on a node that takes the channel’s clean output, squeezes it into a frame and publishes the result.

POST /v1/composite
{
  "id":          "ch7",
  "channel":     "News 24/7",
  "source_url":  "<advertised_base_url>/hls-clean/news-24-7-7/index.m3u8",
  "layout":      "lshape",
  "headline":    "BREAKING",
  "crawl":       "…scrolling text…",
  "bar_background": "#101820",
  "bar_accent":     "#2ea0ff",
  "graphics":    {"headline":"BREAKING","ticker":"…","bg_color":"","text_color":"","accent_color":"","logo_url":"", …}
}

That is a channel on the built-in frame: the two colour fields carry its colours (or the defaults shown) and the node draws the bar. When an operator supplied HTML or a URL instead, the colour fields are left out and graphics becomes {"type":"html","url":"…/graphics/7.html","refresh_seconds":300, …} — the page, and how often to re-capture it (snapshot_sec, default 300, at least 30). A page outranks the node’s own drawn bar, which is why it is sent only when set. Until 3.52.0 the colour fields were never sent at all (they sat under the page branch) and the refresh default was 5 seconds.

Verified against gpuff 1.8.3: bottom bar luma 39, right column 34, programme 125 — the furniture is on the picture, and the session echoes layout, headline, crawl, bar_background and bar_accent back so a caller can see what was accepted.

Text changes go to POST /v1/composite/{id}/update with {headline, ticker} and reach air within a frame without restarting the session. Anything structural — colours, logo, layout — rebuilds it, which a viewer sees.

Added in 3.53.0, for the built-in frame:

  "logo_url":  "<logo_url, or <graphics origin>/graphics/7/logo?v=…>",   # also in graphics.logo_url
  "overlays":  [{"code":"TVG","url":"https://cdn.example/tvg.png","corner":"top-left","width_pct":6,"margin_pct":3}]

POST /v1/composite/ch7/update
{"headline":"…","ticker":"…","overlays":[…]}     # on every change of the traffic graphics; [] clears them

overlays are the traffic graphics on air (rating, daypart logo, E/I label): an image, a corner, a width as a percentage of the frame's and a margin from its edges. Paths on this server are made absolute with advertised_base_url. A node that draws neither field ignores them; drawing them is a node change (roadmap).

Inserting an Ad Avail Now

Scheduled breaks are set on a rundown item, in the 📢 dialog. This is the other case: a channel is on air and an operator needs an avail now.

On the Rundown page, with the channel airing: 📢 Break now, and how many seconds.

curl -s -X POST $BASE/api/channels/7/scte35 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{"seconds":45}'
→ {"inserted":true,"duration_ms":45000,
   "message":"A 45 second avail is going out now — in the transport stream and as
              CUE-OUT in the playlist."}

Queued (3.53.0): splice signals go out from a file item — since 3.54.0 an ABR item too. During gap filler, the slate or a live feed — or in the instant between items — the break waits for the next item, and the answer says so with 202: {"inserted":false,"queued":true,"duration_ms":…,"message":"Queued: the 45 second avail cannot go out yet — the slate is airing …"}. The console shows it as a notice to read, not a success toast. Pressing Break now again replaces a queued break. It is audited as scte35.queued. Until 3.53.0 the answer was "going out now" in every case. On a file item whose SRT receiver has not yet been sent the program map that declares the splice stream, the answer is also queued — it goes out within a second.

An avail asked for while another is open closes the open one first (its return), then starts — see an avail inside an avail.

The picture does not change. An avail tells whatever is downstream that it may insert; the programme keeps playing. Operators expect a break button to cut to black, so the dialog says what actually happens rather than leaving it to be discovered on air.

It goes out on both paths, the same code as a scheduled break: a splice_insert on the transport stream’s SCTE-35 PID, declared in the program map, and #EXT-X-CUE-OUT with #EXT-X-DATERANGE in the playlist. A channel that is not on air is refused with a reason — a break signalled into nothing is worse than a refusal, because an operator would believe it went out.

Every insertion is written to the audit trail with its length and who asked for it.

Collections API

Files are grouped by label, not by folder. A clip airs on more than one channel more often than not — an ident belongs to every channel a brand owns — and a folder tree forces one home, so the same file gets copied into three places and edited in one. A label leaves the file where it is, and moving a file between collections moves no bytes.

curl -s $BASE/api/collections -H "Authorization: Bearer $TOK"
→ {"collections":[{"name":"News","files":42},{"name":"Idents","files":8}]}

curl -s -X POST $BASE/api/collections/assign -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' \
     -d '{"file_ids":[12,13,14],"collection":"News"}'
→ {"updated":3,"collection":"News"}

curl -s -X POST $BASE/api/collections/rename -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{"from":"Idents","to":"News"}'
→ {"updated":8,"from":"Idents","to":"News",
   "message":"renamed \"Idents\" to \"News\" across 8 file(s)"}

A label may not contain control characters or text-direction overrides: they travel from here into XMLTV, where a NUL makes the whole feed unparseable and an override can make one label impersonate another on screen. Sixty characters maximum.

Drop boxes — importing straight into a channel

A watch folder can be pointed at a channel. Anything landing there is imported as that user’s media, labelled with the folder’s collection, and — with append_to_rundown — added to that channel’s rundown. One directory per channel is the simplest possible interface for an editor with an export button and no interest in this system.

curl -s -X POST $BASE/api/admin/watch -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{
       "path":"/srv/dropbox/news","move":true,
       "channel_id":7,"collection":"News","append_to_rundown":true}'

What to expect: a file is added to the rundown only after it probes as playable. Adding first and discovering the file is broken second is how a channel ends up with a gap on air. A file that fails to probe stays in the library, marked, and is not scheduled.

API · Worked Examples

Every call below is real: the request as you would send it, and the answer as the server gives it. Anything marked 🔐 needs Authorization: Bearer <token>. Set BASE and TOK once and the rest can be pasted straight into a terminal.

BASE=https://plt.bozztv.com
TOK=$(curl -s -X POST $BASE/api/auth/login \
       -H 'Content-Type: application/json' \
       -d '{"email":"you@example.com","password":"…"}' | jq -r .token)

1 · Put a file on air from nothing

Upload, make a channel, add the file, start it. Four calls.

# Upload. The response includes the id everything else refers to.
curl -s -X POST $BASE/api/files -H "Authorization: Bearer $TOK" \
     -F 'file=@promo.mp4'
→ {"id":12,"original_name":"promo.mp4","status":"processing"}

# Probing takes a moment. Poll until status is "ready".
curl -s $BASE/api/files -H "Authorization: Bearer $TOK" | jq '.[0] | {id,status,duration_ms,width,height}'
→ {"id":12,"status":"ready","duration_ms":30000,"width":1920,"height":1080}

# A channel. output_mode is "hls", "srt" or "both".
curl -s -X POST $BASE/api/channels -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' \
     -d '{"name":"Promo Loop","output_mode":"hls","loop_playlist":true}'
→ {"id":7,"name":"Promo Loop","status":"stopped","hls_url":"…/hls/promo-loop-7/index.m3u8"}

# Add the file to its rundown, then go to air.
curl -s -X POST $BASE/api/playlist/7 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{"file_id":12,"position":0}'
curl -s -X POST $BASE/api/channels/7/start -H "Authorization: Bearer $TOK"
→ {"status":"started"}   # "already_running" if it was on air; the playlist begins within a second or two

What to expect: the first HLS segment appears a few seconds after start. Until then the playlist exists but is empty, which is normal — a player that connects immediately will wait rather than fail.

2 · Cut to a live feed and back

Point an encoder at the channel's publishing address, check it is arriving, then take it.

# Where to publish, and whether anything is there yet.
curl -s $BASE/api/channels/7/live -H "Authorization: Bearer $TOK"
→ {"channel_id":7,"publish_url":"rtmp://plt.bozztv.com/live/live_3f9c…","key":"live_3f9c…",
   "key_predictable":false,"connected":false,"ready":false,"why":"nothing is publishing to this point"}

# Channels created before 3.48.0 still accept the guessable key ch<id> and report
# "key_predictable":true. Issue a random one (refused while the feed is on air),
# then put the new publish_url in the encoder:
curl -s -X POST $BASE/api/channels/7/live/rekey -H "Authorization: Bearer $TOK"
→ {"publish_url":"rtmp://plt.bozztv.com/live/live_3f9c…","key":"live_3f9c…","key_predictable":false, …}

# From the truck, OBS, or anything that speaks RTMP:
ffmpeg -re -i SOURCE -c:v libx264 -preset veryfast -tune zerolatency -g 50 \
       -c:a aac -f flv rtmp://plt.bozztv.com/live/live_3f9c…

# Now it is arriving — size and rate read from the encoder itself.
→ {"connected":true,"ready":true,"width":1920,"height":1080,
   "has_audio":true,"mbps":8.4,"frames":1402,"keyframes":57,"on_air":false}

# Take it to air. Refused with a reason if the feed is not fit.
curl -s -X POST $BASE/api/channels/7/live/take -H "Authorization: Bearer $TOK"
→ {"on_air":true, …}
→ 409 {"error":"the live feed is not ready to take — no keyframe yet"}

# Hand back to the schedule.
curl -s -X POST $BASE/api/channels/7/live/return -H "Authorization: Bearer $TOK"

What to expect: the take interrupts whatever is playing — it does not wait for the current item to end — and lands on the next keyframe of the incoming feed, so a long GOP delays it by exactly that long (-g 50 at 25 fps is at most two seconds). The return is immediate, and the schedule resumes from the next item. If the feed stops for five seconds the channel returns to the schedule by itself.

Measured on a channel playing a file at luma 125.6: after the take the output reads 78 / chroma 187 (the live feed), and after the return 125.6 again with segments flowing — in and out, both proven from the channel’s own HLS output rather than from a status field.

3 · Encode a rundown to an ABR ladder

# Set the channel's quality once; every encode for it uses this.
curl -s -X PUT $BASE/api/channels/7 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{
       "encode_profile":{"mode":"abr","ladder":[
         {"label":"1080p","height":1080,"video_k":5000,"audio_k":128},
         {"label":"720p","height":720,"video_k":2800,"audio_k":128},
         {"label":"480p","height":480,"video_k":1400,"audio_k":96}]}}'

# Encode everything in the rundown that is not already encoded.
curl -s -X POST $BASE/api/channels/7/encode -H "Authorization: Bearer $TOK"
→ {"queued":14,"already_encoded":33,"profile":"ABR 1080p@5000k · 720p@2800k · 480p@1400k"}

# Watch it. Each job says which machine ran it and on what.
curl -s $BASE/api/encode/nodes -H "Authorization: Bearer $TOK" | jq '.jobs[0]'
→ {"id":3,"file_name":"ep12.mp4","state":"encoding","progress":44,
   "node_name":"gpu-1","encoder":"NVENC h264/hevc","gpu_used":true,
   "remote_id":"j1788298013544974007"}

# A failure names its cause; retry when the cause is dealt with.
→ {"state":"failed","message":"node reported failed: failed at 1080p: no space left on device"}
curl -s -X POST $BASE/api/encode/jobs/3/retry -H "Authorization: Bearer $TOK"
→ {"job_id":9,"message":"ep12.mp4 queued again as ABR 1080p@5000k · 720p@2800k · 480p@1400k"}

What to expect: queued counts only what was actually sent — anything already encoded for these exact settings is skipped, which is why the two numbers rarely add up to the size of the rundown. A partly-encoded file counts as unfinished and is sent again.

4 · Constant bitrate for a modulator, and proving it

curl -s -X PUT $BASE/api/channels/7 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' \
     -d '{"output_mode":"srt","srt_host":"10.0.0.5","srt_port":9000,"cbr_bps":4000000}'

# Measure the real output for up to five minutes. It stops itself.
curl -s -X POST $BASE/api/channels/7/cbr-test -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{"on":true}'
sleep 60
curl -s $BASE/api/channels/7/cbr-test -H "Authorization: Bearer $TOK"
→ {"verdict":"conformant","mean_bps":3970000,"target_bps":4000000,
   "criteria":[
     {"name":"padding is being emitted to hold the rate","pass":true,
      "detail":"1.99 Mb/s of padding, 50% of the pipe (programme 1.98 Mb/s)"},
     {"name":"programme and padding together make the target","pass":true},
     {"name":"no transport continuity errors","pass":true}]}

What to expect: a verdict of inconclusive with “no bytes left the transport output” means no receiver is attached — an SRT listener transmits only while a client is connected. Attach one and run it again.

5 · L-shape graphics, and changing the headline on air

curl -s -X PUT $BASE/api/channels/7 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' -d '{
       "graphics_mode":"composited",
       "graphics":{"headline":"BREAKING","ticker":"…scrolling text…",
                   "bg_color":"#101820","text_color":"#ffffff","accent_color":"#2ea0ff"}}'

# Correcting the text is a live update — the stream is not restarted.
curl -s -X PUT $BASE/api/channels/7 -H "Authorization: Bearer $TOK" \
     -H 'Content-Type: application/json' \
     -d '{"graphics":{"headline":"BREAKING — CORRECTED","ticker":"…"}}'

What to expect: changing only the headline or ticker reaches air within a frame with no discontinuity. Changing colours, the logo or the layout rebuilds the session, which a viewer sees. The channel needs a composite-capable node; without one it serves the clean programme and says so on the Channels page.

6 · The guide, for partners

curl -s $BASE/epg/7                                      # one channel, XMLTV, public
FEED=$(curl -s -H "Authorization: Bearer $TOK" $BASE/api/epg/feed-token | jq -r .token)
curl -s "$BASE/epg/my?token=$FEED"                       # all your channels, XMLTV
curl -s -H "X-API-Key: pgk_…" $BASE/api/app/channels/7   # now_playing and next_up, as JSON

What to expect: one channel's XMLTV (/epg/{id}) is public by design so a partner can poll it without a key; the all-channels feed needs a feed token. Titles come from a file's description when it has one and a cleaned-up filename when it does not — a viewer never sees S01E03_FINAL_v2.mp4.

Errors, and what they mean

No endpoint answers 200 for a request that changed nothing. If a call succeeds, it did something, and the body says what.

Channels API

Files API

Playlist API

Schedule API

Stats API

EPG / XMLTV API

These endpoints generate XMLTV-compatible EPG data for use with Plex, Emby, Jellyfin, Kodi, and other IPTV managers. Per-channel feeds support unauthenticated access so media players can poll without a token.

Admin API

All admin endpoints require both authentication and the admin role.

SRT Output

SRT (Secure Reliable Transport) provides low-latency, resilient TS delivery over UDP. PlayoutGo supports both caller and listener modes.

Caller mode (default)

PlayoutGo dials out to your ingest server. Configure your ingest to listen on the specified host/port.

# Nimble Streamer — listen on port 9000, stream ID "ch1"
srt://0.0.0.0:9000?streamid=ch1&mode=listener

# VLC — listen on all interfaces
vlc srt://:9000

Listener mode

PlayoutGo listens on the specified port. Your ingest server or VLC calls in.

# VLC calls in to PlayoutGo listener
vlc srt://your-server:9000?mode=caller&transtype=live&streamid=ch1&latency=200000

# Flussonic ingest
srt://your-server:9000?mode=caller&transtype=live&streamid=ch1

Connecting a player (listener mode) v1.4

The listener routes by exact stream-ID match. Clients with an empty or wrong stream ID are rejected (REJ_PEER) so a stray puller can never grab a channel's output slot. Use this exact form — the URL parameter is streamid= and latency is in microseconds:

ffprobe -i "srt://SERVER:9000?mode=caller&transtype=live&streamid=YOUR_STREAM_ID&latency=200000"
vlc "srt://SERVER:9000?mode=caller&transtype=live&streamid=YOUR_STREAM_ID&latency=200000"

SRT parameters

HLS Output

HLS segments are written to hls_dir/{channel-slug}-{id}/. The playlist is available at:

http://your-server:8700/hls/{channel-slug}-{id}/index.m3u8

Segments are keyframe-aligned MPEG-TS files: a segment closes on the first keyframe at or after 4 seconds — there is no hard cap: with sparse keyframes a segment simply runs long, and the log warns once after 30 s with no keyframe — so every segment begins with an IDR carrying SPS/PPS and is independently decodable — a requirement for Safari's native HLS. The rolling window keeps the last 6 segments; an atomic rename ensures players always see a consistent playlist.

The master playlist 3.54.0

A channel's directory holds:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aud",NAME="English",LANGUAGE="eng",DEFAULT=YES,AUTOSELECT=YES
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aud",NAME="Español",LANGUAGE="spa",DEFAULT=NO,AUTOSELECT=YES,URI="audio1.m3u8"
#EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS,GROUP-ID="cc",NAME="CC1",INSTREAM-ID="CC1",DEFAULT=YES,AUTOSELECT=YES
#EXT-X-STREAM-INF:BANDWIDTH=474512,RESOLUTION=1280x720,CODECS="avc1.64001f,mp4a.40.2",AUDIO="aud",CLOSED-CAPTIONS="cc"
main.m3u8

• The main language has no URI: RFC 8216 §4.3.4.1 — its audio is in the variant's segments.
• CODECS is read from the SPS and the ADTS header, not assumed; BANDWIDTH is the measured peak of the window's segments plus the largest rendition segment; RESOLUTION (3.55.0) is the picture the SPS describes. All three are measured over the segments in the window — see below.
• Dead air (3.55.0): when nothing can fill a gap — no gap filler and no slate (ffmpeg absent) — the variant carries tables and a clock, and each rendition gets its own segment of the same: its one audio stream declared, on the rendition's PIDs, no frames. Until 3.55.0 the rendition named the variant's segment for that stretch, whose tables declare video and the main language. Gap filler and the slate air as samples, like an item, and always reached every rendition.
• The presentation is fixed when the channel starts, from its rundown, so index.m3u8 is a master from the first segment and never changes kind under a player. Rundown edits take effect at the next start.
• Every URL that worked before still works: a single-language channel without captions is unchanged, and a player given index.m3u8 handles a master and a media playlist alike. A tool that needs a media playlist reads main.m3u8 — the composite node is given it (an ffmpeg-based reader given a master opens every variant it lists).
• A language tag that is not a valid BCP 47 / ISO 639 code (empty, or with a quote) is declared und, and two tracks with one language get distinct names, as RFC 8216 requires.

What the master states, measured 3.55.0

Every EXT-X-STREAM-INF line states what its variant carries now, read from the segments still in the playlist window, so a player choosing a variant chooses on the truth:

• RESOLUTION — the displayed picture from the SPS of each segment's first keyframe: coded size less the cropping, field-coded pictures counted as frames, the cropping unit of the chroma format (4:2:0, 4:2:2, 4:4:4), and every profile whose SPS carries a chroma format read as such, the multiview and depth profiles included. The largest in the window; omitted while nothing has been measured, as RFC 8216 allows.
• CODECS — the most demanding avc1 profile and level in the window and the AAC object type. Until 3.55.0 the channel's very first keyframe decided it for the whole run, so a channel that opened on the slate (Baseline, small) declared the slate while airing High-profile HD.
• BANDWIDTH — the window's peak segment rate, plus the largest audio rendition a player fetches on top.

ABR channels. Each rung's line is measured from that rung's own segments the same way, and the master is rewritten when a figure changes. Until a rung has written a segment its line carries the encode profile's figures (height × 16:9, the profile's bitrates, avc1.640028), so the master is complete from the start. With extra languages, every rung's BANDWIDTH adds the top rung's largest audio rendition. Until 3.55.0 the ABR master stated the profile's figures for the whole run.

Consistent audio for mixed content v1.4

Video-only files (no audio track) automatically receive a synthesized silent 48 kHz stereo AAC-LC track covering the video duration. Files with real audio pass through untouched. Result: the HLS variant presents one stable audio layout across a mixed playlist — without this, strict players (Safari, tvOS) reject the whole stream on seeing an audio track with 0 channels. Discontinuity tags are emitted at every file boundary.

XMLTV / Plex Integration

Add your channels to Plex DVR, Emby, or Jellyfin using the XMLTV feed:

1. In Plex: Settings → Live TV & DVR → Add EPG Source → enter http://your-server:8700/epg/{channelID}
2. In Emby/Jellyfin: Dashboard → Live TV → Add → XMLTV → enter the same URL
3. Programme data comes from the playlist items' short_desc / long_desc and scheduled_at fields

Trim Points v1.38

Play only part of a file without re-encoding it. Useful for topping and tailing a recording, dropping a slate, or cutting a programme down to a slot.

In the Rundown, each row has a ⋯ button. Set an in point (seconds from the start of the file) and an out point; either can be zero to mean "from the beginning" or "to the end". A trimmed row shows its shortened length with a ✂ marker, and its original length on hover.

POST /api/playlist/item/{id}/trim
{ "trim_in_ms": 2000, "trim_out_ms": 8000 }     → plays 6 seconds

What is refused

• An out point at or before the in point.
• An in point at or past the end of the file.
• Any combination leaving nothing to play — the item would vanish from air while still occupying a row in the rundown.

How it works

The in point is a seek, which costs nothing. The out point stops the item once it has played its trimmed length, measured from its own first frame. Frame-accurate to the sample; there is no re-encoding, so a trim is instant however long the file is.

Trim points survive a day repeat — a copy that dropped them would quietly change what airs.

Repeating Days v1.38

Most channels run the same shape every weekday, with a different weekend. Rebuilding that by hand is the most repetitive job in the interface, so 🔁 Repeat Day in the Rundown copies one day onto others.

Pick the day to copy, then say where it goes:

Anchored times shift by whole days, so a programme at 18:00 stays at 18:00. Order and trim points are preserved. You are then asked whether to replace whatever is already on the target days or add alongside it.

POST /api/playlist/{channelID}/repeat
{ "source_date": "2026-08-10",
  "target_days": ["2026-08-11","2026-08-12"],
  "replace": true, "keep_times": true }

Capped at 62 days per operation — enough for two months, low enough that one click cannot generate thousands of rows by accident.

Watch Folders v1.38

Content usually arrives by rsync, SFTP or a mounted share rather than through a browser. A watch folder imports whatever lands in it, so an operator can drop files and find them in the media list.

Add one in Admin → Delivery & Encoding → Watch Folders. The path is checked when you add it, so a typo or an unmounted share is reported immediately rather than silently doing nothing forever. Folders can be paused and resumed, and a new folder starts being watched within one poll — no restart.

The panel shows each folder's state, how many files it has imported, and when it was last scanned, so you can tell at a glance whether it is alive.

Folders declared in config.json as watch_folders continue to work, so existing installations are unaffected; they cannot be paused from the interface.

Why polling, not inotify

Watch folders are very often NFS or CIFS mounts, where inotify silently does not fire for changes made by another host — the folder appears to do nothing and there is no error to find. A poll always works. Thirty seconds is the default; anything under ten is ignored.

Half-written files

A file is imported only once its size has stopped changing between two polls. Without that, a file still being uploaded is imported half-written, probes as broken, and needs manual cleanup. This means a file appears roughly one poll interval after it finishes copying, which is the intended trade.

Only .mp4 files are considered. Dotfiles are ignored, since many tools write .name.mp4 while uploading. A name already in the library is skipped, so a folder left in place is not re-imported on every poll.

Encoding & Quality Modes v1.32

PlayoutGo remuxes rather than transcodes — that is why one modest server runs dozens of channels at a fraction of a percent of CPU each. Encoding is therefore something you do to the library, once, offline. All three modes below keep the playout path itself free of any encoder.

The three modes

Setting a mode

Open a channel's settings and pick under Source quality. Single-bitrate exposes height and bitrates; ABR shows the ladder with a row per rendition plus the segment geometry.

Segment and keyframe seconds default to 6 and 2. The segment length must be a whole multiple of the keyframe interval, or segments cannot start on a keyframe and players cannot switch between renditions cleanly — the interface corrects an impossible combination rather than accepting it.

Encoding nodes

Encoding runs on one or more gpunode servers and, since 3.51.0, on this server's own NVIDIA cards (see below). Add nodes in Admin → Encoding Nodes → + Add Node: URL, a name, and the token gpunode was started with. The node is tested before it is saved, so a wrong URL or token is reported immediately rather than at the first encode — and if the node answers but has no usable GPU, you are told that too.

Each node can be tested, edited, disabled or removed from the same panel. Disabling is the safe way to take a node out of rotation: work already running on it finishes, and nothing new is sent.

Nodes declared in config.json as gpu_nodes still work, so an existing install keeps running after an upgrade; new ones are easier to manage in the interface.

Admin → Encoding Nodes shows each node's encoder (NVENC or CPU), slots in use, free disk and availability, plus recent encode jobs with live progress. Node health is polled concurrently, so one unreachable node does not stall the page.

• PlayoutGo picks the least-loaded node that has a free slot, preferring nodes with a real GPU — a node that has fallen back to CPU encoding is slower than the playout host itself.
• Sources are content-addressed: if the node already holds a file — because VODOTT encoded it, or because you re-ran a job — nothing is uploaded and no GPU time is spent.
• Renditions are collected to encoded_dir and the node's copy is released.

Encoding on this server's own NVIDIA cards v3.51

A playout server with NVIDIA cards of its own can encode on them. Each card becomes an encode node in the same pool as the remote nodes, named local://gpu/0, local://gpu/1 and so on. It is chosen by the same rule — the least-loaded node with a free slot takes the job — and it produces the same output a node does: the same MP4 layout, keyframes at the same times, captions, the channel's QR code and, for a constant-bitrate channel, a constant rate. A file encoded on a card and one encoded on a node are interchangeable.

What counts as a working card. PlayoutGo asks nvidia-smi which cards exist, then runs a one-frame NVENC test encode on each card through this server's ffmpeg. Only a card whose test succeeded takes work: a card that is listed but whose driver is too old for this ffmpeg, or which is out of encoder memory, fails only when an encode starts, and would fail every job sent to it. The list is read again every minute. A card whose test failed is tested again after ten minutes, so a driver fixed in the meantime is noticed without a restart.

Sessions held by other programs count. NVENC sessions opened by other processes on the same card — a compositor, a monitoring tool, another encoder — count against that card's slots. A consumer card refuses sessions past its driver limit rather than queueing them, so a card with three foreign sessions and three slots takes nothing.

A card that fails mid-encode. When an encode fails in a way that points at the device rather than the source — the CUDA library cannot be loaded, the encoder cannot open a session, the device has gone — the card is parked for five minutes and the file goes back to the queue, where another card or node takes it. The attempt that ended is listed as sent back to the queue, with the reason. A failure caused by the source (a corrupt file) fails the job as it would on a node. An encode running on a card when the server stops is sent back to the queue when it starts again.

Settings

In Admin → 🌐 Delivery & Encoding → This server's NVIDIA GPUs, or in config.json. A value saved in Admin takes effect at once and wins over the file.

Decoding and scaling on the card 3.54.0

By default a local encode decodes and scales on this server's processor and only encodes on the card. With local_gpu_decode on, the card does all three — -hwaccel cuda -hwaccel_output_format cuda -hwaccel_device N, then scale_cuda=-2:H:format=nv12 — so frames never leave its memory and the processor the channels on air share does neither.

• A file the card cannot decode (a codec or profile NVDEC lacks, an ffmpeg whose scale_cuda cannot convert formats) does not fail the job: that rung is encoded again with the processor decoding, and so is the rest of the ladder; the encode stays on the card. The job's message and the log say so. The card is not parked for it.
• A rung that carries the channel's QR code decodes on the processor: the code is drawn by the processor's overlay filter, and bringing the frames back from the card for it is the copy GPU decoding exists to avoid. The job says decode on this server's processor: the QR code is drawn there.
• Card numbers. Every ffmpeg run that names a card — the test encode and each rung — runs with CUDA_DEVICE_ORDER=PCI_BUS_ID unless you set it yourself, so card N is nvidia-smi's card N. CUDA numbers cards fastest-first by default, and on a server with two models the same number could name two different cards.
• The job's encoder line says where it decoded: decode and scale on the card, or on the processor. Changes are audited as settings.local_gpu_decode.

Admin lists every card with its model, memory and driver, and its state: ready, not in the list, the test encode's own error, parked (until when, and why), and any sessions held by another process. Until the first detection has finished it says it is still looking rather than that there are none. In Admin → Encoding Nodes the cards are marked this server; they have no Test, Edit or Remove, since there is nothing to configure per card, and a job running on one says which card.

Running an encode

The usual workflow is per channel: set the channel's Source quality, build its rundown, then press 🎛 Encode All in the Rundown. Every distinct file is encoded with that channel's settings — a file used ten times is encoded once — and files already encoded for those exact settings are skipped, so pressing it again after adding content only does the new work.

For one-off jobs, each ready file on the Media tab also has a 🎛 Encode button.

The same file in two channels

A file can be in one channel at 720p 2000k and another at 720p 2800k. Those are different renditions and both are kept: renditions are identified by height and bitrate, and each channel plays the one matching its own settings. Originals are never modified or replaced — encoding only ever adds files alongside them.

If a channel asks for a rendition that does not exist, the nearest height is used, and if there is none at all the original plays. Enabling a mode can never take a channel off air.

Original files are always kept

On the Media tab, each ready file has a 🎛 Encode button. Choose which channel's settings to use — so what is encoded matches what will air — or take a default 720p single-bitrate encode. Progress appears in Admin → Encoding Nodes, where a running job can be cancelled and a finished one cleared from the list.

API

GET    /api/encode/nodes             node health, defaults and recent jobs
GET    /api/encode/nodelist          managed nodes (never includes tokens)
POST   /api/encode/nodelist          add, edit, or test  { "test": true }
DELETE /api/encode/nodelist/{id}     remove a node
POST   /api/encode/start             { "file_id": 12, "channel_id": 3 }
POST   /api/encode/jobs/{id}/cancel  stop a running encode
POST   /api/encode/jobs/{id}/retry   encode this file again with the same settings
DELETE /api/encode/jobs/{id}         clear a finished job

POST   /api/channels/{id}/live/take    cut the RTMP feed to air
POST   /api/channels/{id}/live/return  hand back to the schedule
POST   /api/channels/{id}/live/rekey   issue a new random stream key (refused on air)
GET    /api/channels/{id}/live         is a feed arriving, and is it fit to take
GET    /graphics/{id}.html             a channel's branding, for a compositor to render
                                       (sandboxed opaque origin; moves to graphics_port when set)

When no encoding node is available

Nodes go down, fill up, or get drained for maintenance. What should happen then is a policy decision, so it is one you make rather than one PlayoutGo guesses. Set encode_fallback in config.json:

Admin → Encoding Nodes states which policy is active, what this server could actually do (GPU, CPU, or nothing if ffmpeg is absent), and warns when a fallback would land on the CPU. Recent alerts are listed there too, so a node that disappeared overnight is visible in the morning rather than only in the log.

A local encode produces exactly what a node produces — the same MP4 layout, the same time-forced keyframes — so renditions are interchangeable and nothing downstream can tell which machine made them.

Adaptive delivery v1.64

An ABR channel serves a real variant set. Every rung of the ladder is segmented in parallel, and the channel's playlist is a master listing them, so a player picks a rung and changes it as its bandwidth does.

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-STREAM-INF:BANDWIDTH=2928000,RESOLUTION=1280x720,CODECS="avc1.640028,mp4a.40.2"
720p-1/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1496000,RESOLUTION=852x480,...
480p-1/index.m3u8

The rungs are frame-aligned by construction — every rendition has keyframes forced at the same instants — so the segmenters cut together and a player can switch at any boundary without a gap.

To check a channel, fetch its playlist: #EXT-X-STREAM-INF lines mean variants; only #EXTINF means one bitrate.

Since 3.55.0 each rung's RESOLUTION, CODECS and BANDWIDTH are measured from its own segments, the profile's figures standing in until it has one (what the master states).

ABR items in full 3.54.0

Until 3.54.0 an item airing as an ABR ladder was a lesser item: no breaks, no languages but the main one, no live take until it ended, no as-run row, and rungs that went silent between ABR items. Now:

• The variant set exists from the start. When the rundown has a fully encoded ladder, the set is built when the channel starts and index.m3u8 is its master from the first segment. Every rung carries whatever airs outside ABR items — a single-rendition item, gap filler, the slate, a live feed — so a player on any rung never stalls. (A channel whose ladder finishes encoding while it airs builds the set at its first ABR item; index.m3u8 then becomes the master and stays one.)
• Breaks and Break now go out during an ABR item exactly as during a single-rendition item, on SRT and as cue tags in every rung's playlist, on the same segment of each.
• Every language on every rung, each rung's tracks routed by language. The master names one audio group for every variant — the top rung's renditions — so a player that changes rung keeps its language.
• Captions are declared on every variant when the rundown carries them.
• A live take or Take next cuts in on the next keyframe, and the feed reaches every rung.
• As-run and the rundown: the item gets an as-run row and is marked on air, like any item.
• main.m3u8 on an ABR channel is a continuous single-variant stream: the top rung during ABR items, everything else between them.
• The rungs stay aligned in time. Each rung is read up to the first (tallest) rung's decode time, so a rung with more samples per second than the tallest — another audio track, or audio at a higher sample rate — no longer falls behind it (until 3.54.0 one sample was read from each rung per step, and such a rung lost the end of every item and placed its cues late).

What actually goes to air

Once a file has been encoded, the channel plays the rendition rather than the original. Selection is deliberately forgiving:

• Original files — always the uploaded file, even if renditions exist.
• Single bitrate — the rendition closest to the configured height.
• ABR — every rung, as an HLS variant set behind a master playlist, once the whole ladder is encoded; until then the nearest single rendition. SRT and the RTMP push carry the tallest rung.
• Anything missing — a file that has not been encoded yet, or a rendition deleted from disk, falls back to the original. An unencoded file must never leave a hole in the schedule.

Renditions are requested from the node as MP4, not HLS: the playout engine opens files and does its own segmenting, so a playlist and a pile of fragments would be no use to it. Deleting a media file removes its renditions too.

What this does not do

• No realtime transcoding. Encoding is offline and per-file. A live input would need a realtime encoder, which is a different feature.
• SRT has no ABR. SRT carries a single MPEG-TS; there is no ladder inside it. While an ABR item airs as a variant set, SRT and the push carry its tallest rung (from 3.52.0 — before that they carried nothing for such items), with its breaks and every language (3.54.0).
• Existing rundowns are not rewritten. Setting a mode configures how new material is prepared; it does not retroactively re-encode a library.

CDN Delivery v1.36

The playout host writes HLS segments; in production it should not also be serving viewers. Set a CDN base and every viewer-facing URL is rewritten to point at it — the channel list, the M3U playlist, the XMLTV guide and the App API all move together, which is the point: editing links by hand gets some of them wrong.

Set it in Admin → Delivery & Encoding. It takes effect immediately — no file to edit, no restart. A per-channel override lives in the channel's own settings, for a channel on a different edge or a customer's own CDN.

Admin → Delivery & Encoding → CDN base URL
    https://cdn.bozztv.com

It can also be set in config.json as cdn_url; the interface setting wins if both are present.

Which CDN delivers a channel

Resolved most-specific-first, so a platform with many customers sets each one once:

A path prefix is fine — https://183.bozztv.com/utopia produces https://183.bozztv.com/utopia/hls/<channel>/index.m3u8 — since many CDNs put an origin under a path.

Or per channel, in its settings, which overrides the global value. A channel on a different edge or a customer's own CDN needs no separate deployment.

https://cdn.bozztv.com/hls/<channel-slug>/index.m3u8

Give only the base. PlayoutGo appends the path itself, so a value containing /hls/, ending in .m3u8, or carrying a query string is refused rather than producing links that are subtly wrong.

With no CDN configured, URLs fall back to the origin the request arrived on, so nothing needs changing for a single-server install.

App API — Building Client Applications v1.31

A read-only JSON API for client applications: Roku, Fire TV, tvOS, Android TV, mobile apps, web grids, partner integrations. One call returns everything an app needs to draw a channel grid — names, descriptions, stream URLs, live thumbnails, now-playing and schedule.

1 · Get a key

Client apps cannot use the interface's login token: it expires after 72 hours and a television app has no way to re-authenticate a person. Instead, create an app key under 📡 EPG → App API Keys. Keys are long-lived, read-only, scoped to your channels, and individually revocable.

Key format:  pgk_1a2b3c…       (32 bytes of entropy, hex-encoded)

Pass it either way — use the header in production so keys stay out of logs and browser history:

GET /api/app/channels?key=pgk_…
GET /api/app/channels          with header  X-API-Key: pgk_…

2 · The channel list

GET /api/app/channels?key=pgk_…
GET /api/app/channels?key=pgk_…&live=true      # only channels currently on air

{
  "generated_at": "2026-07-29T13:59:18Z",
  "count": 1,
  "channels": [
    {
      "id": 1,
      "name": "App Demo",
      "description": "Demo channel for apps",
      "status": "running",
      "live": true,

      "stream_hls": "https://utopia.bozztv.com/hls/app-demo-1/index.m3u8",
      "stream_srt": "srt://utopia.bozztv.com:9400?mode=caller&transtype=live&streamid=appdemo&latency=200000",

      "thumbnail_url": "https://utopia.bozztv.com/api/app/channels/1/thumbnail.jpg?t=…&e=1767225600",
      "logo_url":      "https://utopia.bozztv.com/api/app/channels/1/logo?t=…&e=1767225600",
      "epg_url":       "https://utopia.bozztv.com/api/app/channels/1/epg?key=pgk_…",
      "epg_xmltv_url": "https://utopia.bozztv.com/epg/1",

      "now_playing": { "title": "Morning Show", "duration_ms": 1800000, "progress_pct": 42.5, "elapsed_ms": 765000 },
      "next_up":     { "title": "Weather", "starts_at": "2026-08-01T18:30:00Z", "ends_at": "2026-08-01T18:40:00Z", "duration_ms": 600000 },

      "width": 1920, "height": 1080, "fps": 25
    }
  ]
}

Scoping: a key sees its owner's channels; an admin's key sees all of them. Responses are sent private, no-store (varying on the key), so no proxy serves one tenant's list to another. Poll every 10 s. thumbnail_url and logo_url carry a six-hour token for that one resource (?t=…&e=…), not your key; after it expires the URL answers 401 "this link has expired — reload the channel list". logo_url is present only when a logo has been uploaded.

3 · One channel

GET /api/app/channels/{id}?key=pgk_…

Same object as above for a single channel. Requesting a channel you do not own returns 403.

4 · Schedule (JSON EPG)

GET /api/app/channels/{id}/epg?key=pgk_…&limit=20

{
  "channel_id": 1,
  "channel_name": "App Demo",
  "count": 3,
  "programmes": [
    { "title": "Morning Show", "starts_at": "2026-08-01T18:00:00Z", "ends_at": "2026-08-01T18:30:00Z", "duration_ms": 1800000 },
    { "title": "Weather",      "starts_at": "2026-08-01T18:30:00Z", "ends_at": "2026-08-01T18:40:00Z", "duration_ms": 600000 }
  ]
}

Times follow the same flow model the operator sees in the Rundown: anchored items pin the clock, floating items chain after by duration — so your app shows exactly what the schedule shows. Items with no known duration have no starts_at; treat those as "unscheduled" rather than guessing.

XMLTV remains available at /epg/{id} for Plex, Jellyfin, Emby and IPTV clients that expect it. Use the JSON form for your own apps — it is far less work to parse on a TV device.

5 · Thumbnails and logos

GET /api/app/channels/{id}/thumbnail.jpg      # X-API-Key header, or the ?t=…&e=… URL from the list
GET /api/app/channels/{id}/logo

• Thumbnail is a live frame extracted from the channel's most recent segment, scaled to 640 px wide — so a grid shows what is genuinely on air. Regenerated at most once every 10 seconds per channel, then served from cache, so a busy grid cannot overload the server.
• Requires ffmpeg on the server. Without it, the endpoint falls back to the channel logo, then returns 404 with the reason in the body. Apps should treat 404 as "use your own placeholder", not as an error.
• Logo is a static image you upload per channel (PNG or JPEG, max 8 MB):
  curl -X POST "$URL/api/channels/1/logo" -H "Authorization: Bearer $JWT" -F "file=@logo.png"

6 · Worked example: a channel grid

const KEY  = 'pgk_…';
const BASE = 'https://utopia.bozztv.com';

async function loadGrid() {
  const res = await fetch(BASE + '/api/app/channels?live=true', {
    headers: { 'X-API-Key': KEY }
  });
  const { channels } = await res.json();

  return channels.map(ch => ({
    id:        ch.id,
    title:     ch.name,
    subtitle:  ch.now_playing ? ch.now_playing.title : 'Off air',
    image:     ch.thumbnail_url,     // carries a 6-hour token, not the key; reload the list to refresh it
    playUrl:   ch.stream_hls,
    progress:  ch.now_playing?.progress_pct ?? 0
  }));
}

// Refresh every 10s — matches the server's cache window.
setInterval(loadGrid, 10000);

7 · Platform notes

• Roku (SceneGraph) — feed stream_hls to a Video node with streamFormat = "hls". Set poster from thumbnail_url. Roku caches images aggressively; append a cache-buster that is not named t or e (for example &_=+timestamp) when you want a fresh frame — t and e are the URL's signature.
• tvOS / AVPlayer and Android / ExoPlayer — HLS is native; no extra work beyond passing the URL.
• Web — Safari plays HLS natively; elsewhere use hls.js.
• HTTPS — tvOS (ATS) and modern Android require it. Enable built-in TLS; stream URLs then follow the request scheme automatically.
• CORS is permitted on these endpoints, so a browser app can call them directly.

8 · Errors and etiquette

M3U Playlists

The M3U feed at /m3u?token=FEED_TOKEN lists your channels (admins: all) with their HLS or SRT URLs. Copy it from the EPG tab, which fills in your feed token. Import in VLC, Kodi, or any IPTV app:

vlc "http://your-server:8700/m3u?token=FEED_TOKEN"

HLS Proxy

The CORS proxy at /api/hls-proxy?url=... fetches external HLS streams through the server, solving browser CORS restrictions. It rewrites all segment and key URLs to also go through the proxy. It requires authentication — a header, or ?token= with the six-hour scoped token, which is carried into every rewritten URL — and fetches only ordinary public unicast addresses (or the hosts in hls_proxy_allowed_hosts).

Admin Guide v1.5

Everything on this page requires an admin account. The 🛡 Admin tab is hidden for regular users, and every /api/admin/* endpoint returns 403 for non-admin tokens. The first admin is created from admin_email / admin_password in config.json on first start — change that password immediately in production.

User management

• Create users from the Admin tab (or let people self-register if you keep registration open). Each user sees only their own channels, media, rundowns, EPG and stats.
• Roles: admin (sees and manages everything, /m3u and EPG return all channels) and user (scoped to their own resources).
• Edit: change email, role, channel limit and disk quota from the user list. There is no administrator password reset — users change their own (🔑, or POST /api/auth/change-password).
• Suspend: stops the account's channels and refuses starts and uploads, deleting nothing; lifting it brings the account back exactly as it was. It does not block sign-in, and administrators cannot be suspended (Account lifecycle).
• Deleting a user stops their channels and removes the account, its channels, playlist items and media records, and its files on disk — uploads/user_<id>/ and its encoded renditions. The response reports freed_bytes and anything not_removed. Channel logos under uploads/logos/ stay. The dialog asks you to type the email first.

System monitoring & capacity

The Admin tab now leads with a System Utilisation panel: CPU, memory, disk I/O, per-volume disk usage, aggregate channel output, a capacity estimate of how many more channels the host can carry, and automatically generated tuning advice.

Account creation

Two routes: create an account directly (Users → + New User), or issue an invite code that lets someone self-register with a preset channel limit. Tick Require an invite code to sign up to close open registration.

Maintenance operations

• Re-import (Admin → Scan & Re-import Missing Files, POST /api/admin/reimport) — scans the uploads directory and registers any files present on disk but missing from the database (e.g. copied in over SFTP). New records probe automatically.
• Fix statuses (Admin → Re-probe Broken Files, POST /api/admin/fixstatus) — re-probes files stuck in processing, marked error, or ready with no duration, refreshing their metadata and status. It does not touch channels.
• Admin stats — totals: users, channels, channels running, media files. Per-user usage is in the user list and disk quotas.

Operational practices

• Backups: the database is snapshotted automatically every six hours (newest eight kept in backup_dir, each verified); Admin → Backups lists, downloads and restores them. Media lives in the uploads/ tree — copy it, or use tiered storage. Back up the keyring (secrets_key_file) separately. HLS segments are ephemeral and never need backup.
• Upgrades: stop the binary, swap it, start. The schema migrates automatically; rundowns and anchors survive. Then run the Testing Guide acceptance pass.
• Logs: the process logs to stdout — run under systemd or redirect to a file. Watch for auto-restart lines (a file failing repeatedly) and throttled SRT reject lines (a misconfigured puller hammering a port).
• tmpfs: keep hls_dir on /dev/shm; it regenerates on start.

System Utilisation & Capacity Planning v1.8

The 🛡 Admin → System Utilisation panel shows what the host is actually doing, estimates how many more channels it can carry, and turns those measurements into specific tuning advice. Tick live to refresh every 5 seconds.

What each metric means

How the capacity estimate works

The green panel answers "how many more channels can this box run?" It computes headroom three independent ways and reports the tightest one, along with which resource is the limiting factor:

• By CPU — remaining headroom up to a 75% planning ceiling, divided by measured per-channel CPU cost.
• By RAM — remaining headroom up to an 80% ceiling, divided by per-channel memory.
• By tmpfs — free space in the HLS directory versus the rolling segment window at the current bitrate.

Ceilings are deliberately below 100% so bursts, GC and the operating system still have room. When channels are running, per-channel cost is measured from your actual content and the estimate is marked confident. With nothing running it falls back to conservative assumptions and says so — start a few representative channels and re-check for a figure you can plan against.

Tuning suggestions

Below the metrics, PlayoutGo lists advisories generated from the current snapshot — colour-coded by severity, each with a concrete action. Typical guidance:

• Keep hls_dir on tmpfs (/dev/shm/playout_hls). Segments are rewritten every few seconds per channel; on disk this is pure wear and I/O for no benefit. You'll be told if it isn't.
• Put media on SSD/NVMe. If disk utilisation is high while CPU is low, media reads are your bottleneck.
• Watch load-vs-CPU divergence. High load average with low CPU means processes waiting on I/O, not compute.
• Avoid swap. Any meaningful swap usage on a streaming host risks stalls; add RAM or shed channels.

Invite Codes & Signup Control v1.8

Invite codes let you hand out accounts without opening registration to anyone who can reach the server — and each code carries the channel limit for the accounts created with it.

Creating a code

🛡 Admin → Invite Codes → + New Code, then answer three questions:

• Channels allowed — the per-user limit applied at signup (0 = unlimited). Enforced whenever that user tries to create a channel; they see "channel limit reached (n/m)" at the ceiling.
• Uses — 1 for a personal single-use invite (recommended), a higher number for a team, 0 for unlimited.
• Expiry — optional; blank or 0 means it never expires.

Codes look like NVMY-WNND-SXTF — generated with a cryptographic random source and an alphabet that omits easily-confused characters (no O/0, no I/1). The new code is copied to your clipboard automatically.

Requiring codes for signup

Tick "Require an invite code to sign up" to close open registration. New users then must supply a valid code on the signup form. The toggle is persisted to config.json (require_invite_code) so it survives restarts.

Lifecycle

• Revoke stops a code being used but keeps the record (and does not affect accounts already created with it). Re-enable reverses it.
• Delete removes the record entirely; again, existing accounts are unaffected.
• Status is shown per code: active, used up, expired or revoked.
• Redemption is atomic — two people racing to use the last remaining use of a code cannot both succeed.

Changing a user's limit later

The code sets the limit at signup only. To change it afterwards, use Admin → Users → ✏ Edit and set Max channels directly (0 = unlimited).

HTTPS with Automatic Certificates v1.16

PlayoutGo can serve HTTPS on port 443 with certificates obtained and renewed automatically from Let's Encrypt — no reverse proxy, no certbot, no cron job. Enable it in config.json:

{
  "tls": {
    "enabled": true,
    "domains": ["playout.example.com"],
    "email": "ops@example.com",
    "cache_dir": "certs",
    "port": 443,
    "http_port": 80,
    "redirect_http": true,
    "staging": false
  }
}

Requirements

• The domain's DNS A/AAAA record must already point at this server before first start — issuance happens on the first request for that hostname.
• Ports 80 and 443 reachable from the internet. Let's Encrypt validates from outside; a firewall that only allows your office will fail issuance.
• Binding ports below 1024 needs CAP_NET_BIND_SERVICE. Under the shipped unit, grant it in a drop-in — sudo systemctl edit playoutgo, then [Service] and AmbientCapabilities=CAP_NET_BIND_SERVICE — or install with install.sh --tls, which writes one (the installer). setcap on the binary does nothing there: the unit’s NoNewPrivileges=yes drops file capabilities. Without systemd, run as root or sudo setcap 'cap_net_bind_service=+ep' /opt/playoutgo/playout. PlayoutGo prints this hint if the bind fails.

/healthz and /metrics on the loopback interface 3.58.0

With built-in TLS the server is on the TLS ports, and config.json’s port serves /healthz and /metrics — those two and nothing else — over plain HTTP on 127.0.0.1 only. The installer checks the server there after every start, and a Prometheus or a health agent on the host can use it; /metrics keeps its metrics_allow_from list. The console and the API stay on HTTPS. Until 3.58.0 port answered nothing with TLS on, so an upgrade with install.sh on such a host failed its health check and rolled itself back. Keep port apart from tls.port and tls.http_port; playout -healthz-url prints where the server answers.

An ACME CA of your own 3.59.0

A host with no public DNS name cannot get a Let’s Encrypt certificate. If your network runs its own ACME CA — step-ca, a corporate PKI — set tls.acme_directory to its directory URL (https:// only), and tls.acme_ca_file to a PEM bundle when the CA’s own HTTPS is not publicly trusted (the system’s roots stay trusted). The certificates are what that CA issues: browsers trust them only if they trust its root. staging and acme_directory cannot both be set. The server logs which CA it uses (certificates from ACME directory …); playout -check names a bundle that cannot be read or holds no certificate. install.sh --tls … --tls-acme-directory URL --tls-acme-ca FILE writes both, the bundle copied to /var/lib/playoutgo/acme-ca.pem.

"tls": {
  "enabled": true, "domains": ["playout.corp.example"],
  "acme_directory": "https://ca.corp.example:9000/acme/acme/directory",
  "acme_ca_file": "/var/lib/playoutgo/acme-ca.pem"
}

First run

› Set staging:true, start the service, and watch the log:
    🔒 HTTPS on :443 for playout.example.com
    ↪️  HTTP :80 answers ACME challenges and redirects to HTTPS
    📁 Certificate cache: certs (must persist across restarts)
› Visit https://playout.example.com — the browser will warn (staging CA), which
  proves issuance worked end to end.
› Set staging:false, delete the cache directory once, restart.
✓ A trusted certificate is issued on the first request and renewed automatically.

Secrets at Rest 3.48.0

SRT passphrases, live-insert stream keys, encoding-node bearer tokens and YouTube refresh tokens are stored encrypted (AES-256-GCM, each bound to its column so a value cannot be moved into another one). Application keys and passwords are stored only as hashes. A copy of playout.db — a snapshot, a backup, a stolen disk image — reveals none of the four recoverable secrets without the keyring.

• The keyring is secrets.key beside the database, or wherever secrets_key_file points — or, since 3.54.0, it comes from off the host and is never written to disk (below). The file is created on first start with mode 0600 and a header explaining itself. The first key line is the current key; further lines are older keys kept only to decrypt values sealed under them, which are re-sealed under the current key at startup.
• Back it up separately from database snapshots and keep it with the off-box copies. That separation is the protection: a snapshot alone is useless to whoever takes it.
• Restoring onto another host: append the original host’s key line below the first line of the new host’s keyring and restart. A snapshot restored without its key still starts, but the secrets it holds are reported as locked: the channel dialog and locked_secrets name them, a channel with a locked SRT passphrase refuses to start rather than send unencrypted, a channel with a locked stream key accepts no publish (never the guessable default) and reports key_locked, and a locked node token shows token_locked. Saving unrelated settings never discards a locked value; re-entering or clearing it does.
• Rotation: put a new 64-hex-digit key on the first line, keep the old one below it, restart. Every value is re-sealed and the log says how many.
• Upgrading from 3.47.0 or earlier encrypts every plaintext secret on first start, hashes any application key still held in plaintext, rewrites the database once so the old plaintext does not survive in SQLite’s free pages, and from then on runs with secure_delete so deleted rows are zeroed. Snapshots taken by earlier releases still hold plaintext; startup names them. Delete them or move them somewhere as safe as the keyring.
• YouTube refresh tokens were encrypted under a key derived from the JWT secret, so rotating the JWT secret — the advice for a leaked archive — made every connected YouTube account unusable. They now use the keyring; the JWT secret can be rotated freely.

Where the key comes from 3.54.0

A key file beside the database keeps the key out of database copies, but not off the host: whoever can read the data disk — a stolen drive, a host-level backup — has both. These sources keep the key elsewhere. The first one configured is used:

• The content is the keyring format: one 64-hex-digit key per line, the current key first, older keys after it for decryption; # lines are comments. Rotation and restoring a snapshot from another host work as with the file: the key source supplies more than one line.
• Fails closed. A configured source that fails, supplies nothing, or supplies anything that is not a keyring stops the server from starting, naming the source and the reason. It never falls back to the file and never generates a key — a fresh key would start the server with every secret locked, and a fallback would put the key back on the disk it was moved off.
• The keyring is read once per process and kept in memory: a descriptor can be read only once, the variable is gone after the first read, and a restore reopens the database without calling the key service again.
• When an off-host source is used, secrets_key_file is ignored (the log says so), and the log names the source and the current key id: keyring from secrets_key_command (playoutgo-key): current key 1a2b3c4d, 2 key(s); nothing written to disk.
• Only config.json can set secrets_key_command: it runs a program, and no API endpoint accepts it — a test fails the build if one ever decodes it.

# config.json — the key from a KMS-backed wrapper
"secrets_key_command": ["/usr/local/bin/playoutgo-key", "--env", "prod"]

# or a TPM-sealed systemd credential
systemd-creds encrypt --with-key=tpm2 --name=playoutgo-secrets-key secrets.key /etc/credstore.encrypted/playoutgo-secrets-key
# in the unit
LoadCredentialEncrypted=playoutgo-secrets-key:/etc/credstore.encrypted/playoutgo-secrets-key

SRT encryption is enforced in both directions

A channel with an SRT passphrase in listener mode accepts only callers that bring the same passphrase. A caller without one is refused (REJ_UNSECURE, which libsrt reports as “Password required or unexpected”) and a wrong one is refused (REJ_BADSECRET, “Incorrect passphrase”). A channel with no passphrase refuses a caller that asks for encryption, so a receiver can never believe a stream is protected when it is not. Refusals are logged: the first at once, then one summary per five seconds, printed when the five seconds are up even if nothing else arrives. Point receivers at the listener with the passphrase:

ffmpeg -i "srt://PLAYOUT_HOST:9000?mode=caller&streamid=STREAMID&passphrase=THE-PASSPHRASE" …

Security Hardening

Two-factor sign-in 3.60.0

Each account can add a second factor: a six-digit code from an authenticator app (RFC 6238 — Google Authenticator, 1Password, Authy and the rest). Turn it on with 🔐 in the header: your password, then scan the QR code (drawn by the server; the secret goes nowhere else) and enter a code. Ten recovery codes are shown once — each signs in once without the app; only their hashes are kept. From then on sign-in asks for the code after the password.

• A code is good for its 30-second step and one either side, and never twice.
• Wrong codes count like wrong passwords, so the usual limits lock the account out after ten in 15 minutes.
• The secret is sealed under the server’s keyring, like every other secret at rest.
• Turning it on or off, or an administrator resetting it, signs out every other session of the account; the console keeps the one that made the change.
• Turning it off, or making new recovery codes, takes the password and a current code (or a recovery code).
• An account whose owner has lost both the app and the codes is reset by an administrator (Admin → the user, or DELETE /api/admin/users/{id}/2fa); it then signs in with its password and should enrol again.
• Every step is audited: auth.2fa.setup, auth.2fa.enable, auth.2fa.disable, auth.2fa.recovery_codes, auth.2fa.recovery_used, user.2fa.reset.

Two-factor is per account and optional; nothing yet requires it of administrators (see the roadmap).

The content policy (the console since 3.50.0, every page since 3.51.0)

The console — the page an operator's session token lives on — is served with script-src 'self' and nothing else: no 'unsafe-inline', no 'unsafe-eval', no other origin. An injected <script>, an onerror= or onclick= attribute, or a javascript: link does not run, even if some future escaping mistake let one onto the page. The browser refuses it and reports the violation.

That required the console to contain no inline code of its own. Its script lives in files served by this binary (/boot.js, /ui-dispatch.js, /app.js, /traffic.js). Its buttons and fields declare what they do in data-on-click, data-on-change and similar attributes, such as data-on-click="stopCh(12)". ui-dispatch.js parses those attributes and never evaluates them. Its grammar allows a single call to a function on a fixed list, whose arguments may be literals, the element (this, this.value, this.checked, this.files, this.textContent) or the event. It also allows event.stopPropagation() and return false. Anything else is refused and runs nothing.

Since 3.51.0 a value that varies per row — an id, a name — is never written into the handler itself. It goes into a data- attribute of the same element and is read by name: data-on-click="stopCh($num('v-ch-id'))" data-v-ch-id="12". $num reads a number, $str a string and $bool true or false; an attribute that is missing or does not parse refuses the handler instead of passing a guess. The handler text is then the same on every row, and nothing the server sends ever becomes part of it.

Since 3.51.0 every page this binary serves has the same policy: the viewer, the EPG index, the YouTube return page, the manual, the about page and the guides. Their script is in files too (/viewer.js, /epg-index.js, /youtube-done.js), and the viewer's player is served by this binary rather than fetched from a CDN, which the policy forbids. That closes audit U-11. The one exception is the graphics page a compositor renders (/graphics/{id}.html): it runs in a sandbox with an opaque origin and has its own policy, so even script that ran there could not reach a session. Every page refuses framing by other sites. Only the manual may be framed, and only by this origin, because the console's Help tab shows it.

v1.4 security behaviors

• SRT passphrases are never returned by the API — channel create/update/list/stats responses expose only srt_passphrase_set: true|false. To remove encryption intentionally, send {"clear_srt_passphrase": true} on channel PUT; a blank passphrase field means "keep existing".
• /m3u requires a token and returns only the requesting user's channels (admins see all); unauthenticated requests get 401. The EPG tab's copy link carries your feed token (EPG and M3U only, no expiry, revoked by a password change) — never your login token.
• Partial channel updates are safe — PUT merges onto the stored record, so sending only {"name":"x"} no longer zeroes SRT host/port/latency/loop settings.
• HLS proxy pins DNS-validated IPs at dial time and re-checks the allowlist on every redirect hop (DNS-rebinding and redirect-SSRF are closed).
• SRT listener requires an exact stream-ID match; empty/unknown IDs are rejected. The first rejection is logged at once and the rest are summarised every 5 s; since 3.50.0 the summary is printed when the window closes, so a burst that stops is still reported.

Production checklist

• Sign in with the generated admin_password and change it in the interface (editing config.json later has no effect). Replace jwt_secret only if it is an old published default or shorter than 32 characters.
• Serve HTTPS: enable built-in TLS (443, with port 80 for certificate challenges and redirects), or terminate TLS at nginx/Caddy and set trust_proxy_headers. Never serve the console over plain HTTP.
• Leave allow_password_reset off (the endpoint then answers 404). If you enable it for a recovery, also firewall /api/auth/reset and turn it off afterwards.
• Set hls_proxy_allowed_hosts if you know which external HLS servers you need to proxy
• Set hls_dir to tmpfs (/dev/shm) for performance
• Run playout -check (above) after every change to config.json; the unit runs it before every start. Since 3.57.0 an empty jwt_secret — config.sample.json ships one — is generated and written back: before, it signed every session with an empty key, which anyone can compute.
• Run as a non-root user. The Go memory limit defaults to 4 GiB; set GOMEMLIMIT in the unit to change it
• Keep the automatic database snapshots, back up uploads/, and back up the keyring separately

Deployment (systemd) 3.60.0

Each release has a deploy bundle, playoutgo-<version>-linux-amd64.tar.gz: the binary, the systemd unit playoutgo.service, the installer install.sh, INSTALL.md, config.sample.json, VERSION and, since 3.58.0, the Prometheus alert rules playoutgo-alerts.yml (alert rules). release/make-release.sh builds it beside the source archive, from the same tree, with a SHA256SUMS file.

tar xzf playoutgo-3.64.0-linux-amd64.tar.gz && cd playoutgo-3.64.0-linux-amd64
sudo ./install.sh --url https://playout.example.com     # fresh install
sudo ./install.sh --tls playout.example.com             # fresh install with built-in HTTPS (3.58.0)
sudo ./install.sh                                       # on an installed host: upgrade
sudo ./install.sh --rollback                            # the previous binary back

The installer

• Fresh install: creates the playout user (added to video for the GPU when that group exists), installs the binary, writes config.json with absolute paths, a 64-character jwt_secret and a first administrator password, checks it, enables and starts the unit, and waits for /healthz. It prints the password. --port, --url (advertised_base_url) and --hls-dir apply here only; an existing config.json is never rewritten.
• Upgrade: the new binary checks the existing configuration first, and on an error nothing is changed — the running server is not touched. Then the service stops; the database, keyring and config.json are copied to backups/pre-upgrade-<version>-<time>/ (the newest three copies are kept); the binary is replaced, the old one kept as playout.prev; the unit is replaced with the bundle’s; the service starts and must answer /healthz within 60 s (--wait changes that). If it does not, the upgrade rolls itself back — old binary, the unit it ran with, and the copied database — and says so, keeping the new binary as playout.failed.
• The unit is the installer’s. Local settings — ReadWritePaths=, AmbientCapabilities=, Environment= — go in a drop-in (sudo systemctl edit playoutgo), which no upgrade or rollback touches. The installer recognises every unit a release has shipped by its checksum; a unit with local changes is not replaced — the upgrade is refused before anything changes, and says how to move them into a drop-in.
• --rollback puts playout.prev back, and the unit it ran with, and restarts. It does not restore the database, which may hold days of work; if the earlier version refuses it, the output names the copy taken before the upgrade. A binary from before 3.57.0 has no -check, so for one the installer adds a drop-in that skips the unit’s ExecStartPre, and removes it on the next upgrade.
• --tls DOMAINS (3.58.0, a fresh install only): built-in HTTPS — tls enabled for the comma-separated domains, the certificates cached in /var/lib/playoutgo/certs, advertised_base_url https:// the first domain unless --url says otherwise, --tls-email for Let’s Encrypt, --tls-port and --tls-http-port (443 and 80). For a port below 1024 it writes the drop-in playoutgo.service.d/10-install-sh-tls.conf granting CAP_NET_BIND_SERVICE. --port then serves /healthz and /metrics on 127.0.0.1 (loopback), which is where the installer checks the server — it asks the binary (playout -healthz-url) rather than reading the port out of the JSON. On an installed host --tls is refused before anything changes: set tls in config.json and the capability in a drop-in.
• --tls-acme-directory URL and --tls-acme-ca FILE (3.59.0, with --tls): certificates from an ACME CA of your own instead of Let’s Encrypt; the bundle is copied to /var/lib/playoutgo/acme-ca.pem. Checked before anything is written: an https:// URL, a readable file holding a certificate.
• A start that fails (3.59.0): on a real systemd, systemctl start waits for the service and fails when it does not come up. Until 3.59.0 that failure ended the installer before its health check, so a broken upgrade was left in place with the service down instead of being rolled back. Now the health check decides, and a failed start is rolled back like any other.
• --no-systemd starts and stops the server directly (a pid file in the state directory), for a host without systemd; there playout.log is rotated at each start once it passes 50 MiB, the three newest kept (3.58.0). --root DIR stages an install under a directory; --systemctl names a stand-in systemctl, for testing.
• An existing install from another layout — a server already answering on the port, or a hand-made playout.service — is refused rather than run beside; INSTALL.md lists the eight steps to move it over once. A binary from before 3.57.0 takes no arguments, so asked for -version it would start a second server on the live database: the installer never runs one, and recognises a 3.57+ binary by its usage text.

playout -check and -version

playout -check reads config.json in the working directory and reports, without creating, writing or changing anything: an ERROR for what the server would fail on or an attacker could use — an unparsable or invalid file, a directory the service cannot write, an unreadable keyring, a published secret — and a WARN for what an operator should decide: relative paths, plain HTTP (neither tls nor trust_proxy_headers), no advertised_base_url, the reset endpoint on, /metrics open to everyone, allowed_origins of *, a database without its keyring, missing ffmpeg, ports below 1024 without the capability, files readable by others. It exits 1 on an error. The unit runs it before every start (ExecStartPre), so a mistake appears by name in journalctl -u playoutgo instead of as a restart loop.

cd /var/lib/playoutgo && sudo -u playout /opt/playoutgo/playout -check
WARN  advertised_base_url is empty: links given to other machines … will use whatever address a request arrived on
PlayoutGo 3.57.0: 0 error(s), 1 warning(s)

playout -version prints the version and touches nothing. playout -healthz-url (3.58.0) prints where the configured server answers /healthz on this host — port, which with built-in TLS is the loopback listener — and changes nothing either. Without arguments the binary serves, as it always has.

The unit

[Service]
Type=notify                      # READY once serving; a heartbeat only while HTTP and the database answer
WatchdogSec=90                   #   — so a wedged process is restarted
User=playout
WorkingDirectory=/var/lib/playoutgo
StateDirectory=playoutgo
ExecStartPre=/opt/playoutgo/playout -check
ExecStart=/opt/playoutgo/playout
Restart=always
KillSignal=SIGTERM               # channels stop; airing items closed in the as-run log at the signal
TimeoutStopSec=30
LimitNOFILE=65536
UMask=0077
NoNewPrivileges=yes
ProtectSystem=strict             # everything read-only except the state directory and /dev
ProtectHome=yes
PrivateTmp=yes
…                                # kernel, clock, namespaces, address families restricted
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

Local settings go in a drop-in, never in the unit — the installer replaces the unit on an upgrade, and refuses to while it carries local changes. sudo systemctl edit playoutgo opens /etc/systemd/system/playoutgo.service.d/override.conf:

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE      # built-in TLS on 443/80
ReadWritePaths=/data1/playout-media           # directories config.json names elsewhere
Environment=GOMEMLIMIT=6GiB                   # the memory limit (default 4 GiB)

Not set, on purpose: PrivateDevices and MemoryDenyWriteExecute — local NVENC encodes and GPU decoding need /dev/nvidia*, and the NVIDIA driver maps writable code. A directory config.json names outside /var/lib/playoutgo — mirror_dir, failover_cache_dir, a watch folder that moves files, an hls_dir off /dev/shm — must be added to ReadWritePaths= in the drop-in; the start-up check names any the service cannot write.

nginx reverse proxy (with TLS)

server {
    listen 443 ssl;
    server_name playout.example.com;

    ssl_certificate /etc/letsencrypt/live/playout.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/playout.example.com/privkey.pem;

    # Block emergency reset from public internet
    location /api/auth/reset {
        allow 10.0.0.0/8;
        deny all;
    }

    location / {
        proxy_pass http://127.0.0.1:8700;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # Required for SSE
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Troubleshooting

A page is blank, or dropdowns/buttons do nothing

This is almost always a JavaScript error aborting the page script. Open the browser console (Safari: Develop → Show JavaScript Console; Chrome: ⌥⌘J) and look for "X is not defined". Then:

• Hard-refresh first (⇧⌘R / Ctrl+Shift+R) — the UI is embedded in the binary, so an upgraded server with a cached old page is a common cause.
• If you are on v1.4.0–v1.6.0, upgrade to v1.6.1: those builds had a genuine missing-function bug affecting Rundown and Stats.
• Developers: run go test -run TestUI ./... — the shipped UI static tests detect undefined functions and missing element IDs.

SRT does not connect but HLS works

Work through these in order — they cover almost every case:

1. Include the stream ID. The listener matches it exactly; a URL with no streamid is rejected. Use the connect URL printed in the server log when the listener starts:
   ffprobe -i "srt://HOST:9000?mode=caller&transtype=live&streamid=YOUR_ID&latency=200000"
2. Check the channel's Stats → error log. Since v1.11 a failed listener bind is recorded there, e.g. "SRT output unavailable: SRT port 9000 already in use with different listener settings". Two channels may share a port only when passphrase, latency, buffer and max-bandwidth match — then they are routed by stream ID. Otherwise give them separate ports.
3. Confirm something is listening: ss -lunp | grep 9000 on the server, and check the log for "[SRT] Listener on :9000". If it is absent, no channel currently owns that port.
4. Remember SRT is single-consumer — one client per channel at a time. Disconnect VLC before testing with ffprobe.
5. Firewall: SRT is UDP. Confirm the port is open for UDP, not just TCP.

The Help tab (or another tab) is not visible

Fixed in v1.6.1 — tabs used to overflow on narrow windows. On older builds, widen the browser window or scroll the tab strip horizontally.

Channel stuck in "connecting"

Stop and start the channel (⏹ then ▶, or POST /api/channels/{id}/stop then /start). In SRT caller mode "connecting" means the far end is not accepting — check it is listening. /api/admin/fixstatus re-probes media and does not touch channels.

HLS stream shows "Stream starting, please wait…"

The channel is running but no segments have been flushed yet. Wait about 4 seconds plus one GOP for the first segment, then reload. If it persists, check the channel error log via GET /api/channels/{id}/diag.

SRT connection fails immediately

In caller mode, verify the downstream server is listening before starting the channel. In listener mode, verify the port is open in your firewall. Check the channel stats for the last SRT error message.

File stuck in "processing" status

The background probe goroutine may have failed. Use POST /api/admin/fixstatus (Admin → Re-probe Broken Files) to re-trigger probing on stuck files; reimport only registers files the database is missing. Check server logs for MP4 parse errors — the file may be corrupt or use an unsupported codec (H.265, VP9, etc.).

All playlist items show "failed"

The engine marks items failed when it can't read samples. This usually means the files are HEVC/H.265 — only H.264/AAC MP4 is supported. Re-encode with: ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4

HLS proxy returns 403 "upstream host not permitted"

The proxy blocked the request because the target hostname resolves to a private IP. If you need to proxy an internal host, add it to hls_proxy_allowed_hosts in config.json.

Testing Guide — verify every feature v1.4

A step-by-step acceptance checklist. Run it after every upgrade. Replace SERVER, TOKEN, CH (channel id) and stream IDs with your values. Get a token via the login call in step 1.

1 · Authentication

› curl -s -X POST http://SERVER:8700/api/auth/login -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"..."}'
✓ Returns {"token":"..."} — export it:  TOKEN=eyJ...
› curl -s http://SERVER:8700/api/channels
✓ 401 without a token; 200 JSON array with -H "Authorization: Bearer $TOKEN"

2 · Media upload & probe

› Upload an MP4 in the Files tab (or POST /api/files)
✓ Status shows "processing", then "ready" with real width×height, fps, duration, bitrate
✓ Restart the server → metadata persists (no re-probe of already-probed files)
› Upload a renamed non-MP4 (e.g. a .txt renamed .mp4)
✓ Status becomes "error", not "ready"

3 · Channel lifecycle

› Create a channel (output=both, listener, port 9000, stream id "test1"), press Start
✓ Status: connecting → running; logs show HLS segmenter + SRT listener with a connect URL
› Press Stop during an auto-restart back-off (kill the engine by removing its media)
✓ Channel stays stopped — no zombie resurrection

4 · Rundown — anchors & flow

› Add 3 files; drag to reorder
✓ Grey floating times reflow instantly while dragging
› "Schedule day from" a time 1h ahead → Set & flow
✓ Item 1 shows 🔒 bold yellow; items 2–3 show 🔓 grey computed times
› Drag item 3 above item 2
✓ Floating times swap; the anchor does not move
› Lock item 3 at a time 10 min AFTER item 2's flow end
✓ Amber "GAP — 10:00" row appears between them
› Edit that anchor to a time BEFORE item 2's flow end
✓ Red "+MM:SS over" badge appears on the anchor

5 · Rundown — bulk, undo, safety

› Shift-click to select a range → bulk bar appears
✓ Move Top / Move Bottom / Clear times / Remove all work on the range
› Press ↩ Undo after each mutation
✓ Previous schedule/order returns exactly
› Try to remove the row marked ▶ playing
✓ Confirmation prompt appears
› API atomicity:
  curl -s -X POST http://SERVER:8700/api/playlist/CH/schedule_bulk \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"items":[{"id":REAL_ID,"scheduled_at":"2030-01-01T00:00:00Z"},{"id":999999,"scheduled_at":""}]}'
✓ Error response AND the real item's time is unchanged (rolled back)

6 · Schedule engine & restart resume

› Anchor item 1 at now−25min with three 10-min items flowing after; restart the channel
✓ Log shows resume in item 3 at ≈5:00 offset (flow-aware restart)
› Anchor an item 1 min in the future on a stopped channel; wait
✓ Scheduler auto-starts the channel ~15 s before air

7 · SRT output

› With no other client connected:
  ffprobe -i "srt://SERVER:9000?mode=caller&transtype=live&streamid=test1&latency=200000"
✓ Connects; shows your video (h264 …); NO "non-existing PPS" spam; brief keyframe wait is normal
› Same URL with streamid=WRONG (or none)
✓ Rejected with ERROR:PEER; server log shows throttled reject lines
› Connect VLC with the correct URL, then run ffprobe simultaneously
✓ ffprobe is rejected — single consumer per channel is enforced
› Wrong passphrase on an encrypted channel
✓ Rejected (bad secret) — this is the one legitimate password error

8 · HLS output

› curl -s http://SERVER:8700/hls/SLUG-ID/index.m3u8
✓ #EXTM3U, EXT-X-VERSION:3, segments with ~real durations, DISCONTINUITY at file changes
› Download any segment and probe it:
  ffprobe -v error -select_streams a -show_entries stream=channels,sample_rate SEG.ts
✓ channels=2, sample_rate=48000 — including for VIDEO-ONLY source files (silent track)
  ffprobe -v error -select_streams v -show_entries frame=key_frame -read_intervals %+#1 SEG.ts
✓ first frame of every segment is a keyframe (key_frame=1)
› Play the m3u8 in Safari (private window) and VLC
✓ Both play; audio-bearing files have sound, video-only files are silent

9 · EPG / M3U

› curl -s http://SERVER:8700/m3u            → ✓ 401 unauthorized
› FT=$(curl -s -H "Authorization: Bearer $TOKEN" http://SERVER:8700/api/epg/feed-token | jq -r .token)
› curl -s "http://SERVER:8700/m3u?token=$FT"
✓ M3U with only YOUR channels; SRT URLs use streamid= and transtype=live
› /epg/my?token=… returns XMLTV for your channels

10 · Security checks

› Create/update/list a channel with a passphrase set
✓ API responses contain srt_passphrase_set:true and NEVER the passphrase itself
✓ /api/stats/CH likewise
› PUT {"name":"renamed"} only
✓ SRT host/port/latency and loop flag survive (no zeroing)
› PUT {"clear_srt_passphrase":true}
✓ Encryption removed; unencrypted client now connects
› Channel name with quotes/<script> renders inert in UI and M3U

11 · Stats & admin

› Stats tab while a channel runs
✓ Live viewer/bitrate numbers update; history renders; no passphrase in the payload
› Admin tab (admin account): user list, create/edit/suspend user, per-user channels
✓ Non-admin token on /api/admin/* → 403

12 · In-app Help v1.5

› Click the 📚 Help tab
✓ Full manual loads inside the interface (this document)
› On Channels / Media / Rundown / Player / EPG / Stats / Admin, click the ? next to the title
✓ Help opens scrolled to that page's manual section
› Click ↗ in the header
✓ Manual opens in a separate browser tab
› Developers, before deploying:  go test ./...
✓ TestUIHasNoUndefinedFunctions and TestUICriticalElementsExist pass
  (these catch UI functions/IDs broken by refactoring — invisible to the compiler)

13 · Gap filler & duplicate v1.6

› Upload a short slate clip; set it as Gap filler in a channel's settings
› Rundown: one 6s item, then a second item anchored ~30s ahead → GAP row names the filler
› Start the channel and watch the log
✓ Item 1 plays, then "Filler: covering 29s with … (1s null-padded)"
✓ Anchored item starts on its exact scheduled second
✓ Live stats show "⏸ Filler: name" during the gap; HLS keeps flowing with discontinuities
› Clear the filler (None) and repeat
✓ The gap airs the built-in black slate; segments decode as black with silence
› Select two rundown rows → ⧉ Duplicate
✓ Floating copies appear at the end in order

14 · Multi-tenant isolation & admin users v1.7

› As admin: 🛡 Admin → + New User (email, password ≥8 chars, choose role)
✓ User is created and can log in
✓ Duplicate email → "already exists"; short password → rejected
› Log in as that user and try to use ANOTHER tenant's media:
  curl -X POST .../api/playlist/<your-channel> -d '{"file_id":<other-users-file>}'
✓ 403 "media file belongs to another user"
  curl -X PUT .../api/channels/<your-channel> -d '{"filler_file_id":<other-users-file>}'
✓ 400 "filler file belongs to another user"
  curl -X PUT .../api/channels/<your-channel> -d '{"filler_file_id":999999}'
✓ 400 "filler file not found"
› Own media still works normally in both places
✓ Added / set without error
› Developers:  go test ./...
✓ tenant_isolation_test.go and ui_static_test.go all pass

15 · System metrics & invite codes v1.8

› 🛡 Admin → System Utilisation
✓ CPU, memory, disk I/O and disk usage all show real figures (not "—")
✓ Capacity panel names a limiting factor (CPU / RAM / tmpfs) and a per-channel cost
✓ Tick "live" → values refresh every 5 s; untick and leave the tab → refresh stops
› Start several channels, refresh
✓ Capacity switches from "(estimated)" to measured, per-channel cost reflects your content
› Admin → Invite Codes → + New Code (e.g. 3 channels, 1 use, 30 days)
✓ Code appears, is copied to clipboard, shows "active"
› Sign out, register with that code
✓ Account created; the new user may create exactly 3 channels, then sees "channel limit reached"
› Try the same code again
✓ "already been used the maximum number of times"
› Revoke a code, then try it
✓ Rejected; Re-enable restores it
› Tick "Require an invite code to sign up" with no usable codes
✓ Refused — create a code first (prevents locking everyone out)
› With a code available, tick it, then register without a code
✓ "an invite code is required to sign up"
› Developers:  go test ./...
✓ invite_sysinfo_test.go covers redemption, expiry, revocation, concurrency and metric sanity

16 · Restart resume v1.9

› Start a channel that has a schedule; let it run a minute
› Kill the process hard:  kill -9 $(pgrep -x playout)    then start it again
✓ Log: "[resume] restoring N channel(s)…" then "back on air"
✓ Log: "Time-aware restart: seeking to item X (+NNNNms)"
✓ Playing what the SCHEDULE says should be on now — not from the top of the rundown
› Press ⏹ Stop, then restart the process
✓ Channel stays stopped (explicit stop clears the auto-resume intent)
✓ Stopped-but-marked channels show the ⟳ auto-resume badge
› Verify disk figures against the OS:  df -h
✓ System Health percentages match df (measured against usable space)
✓ Each volume listed once even when uploads and the app share a filesystem

17 · As-Run log v1.10

› Run a channel for a few minutes, then open 🧾 As-Run
✓ One row per item that aired, oldest first, with real start/end times
✓ Duration reflects actual airtime; Status shows completed
✓ Header summarises item count, total airtime hours and bytes
› Try the 1d / 7d / 30d buttons and the channel filter
✓ Row counts and the summary change accordingly
› Press ⬇ Export CSV
✓ A .csv downloads and opens cleanly in a spreadsheet with a header row
› Kill the process mid-item (kill -9) and restart it
✓ Log line: "as-run: closed N play record(s) interrupted by the last shutdown"
✓ That item shows status "interrupted" — not stuck on "playing" — with its airtime to within 5 s (3.58.0)
› Stop a channel mid-item, then stop the server cleanly (SIGTERM) with another on air
✓ Each item shows status "stopped", ending when it stopped, with its airtime (3.57.0)
✓ The next start logs no "interrupted by the last shutdown" line
› As a non-admin user, open As-Run
✓ Only your own channels appear
✓ curl .../api/asrun?channel_id=<another user's> → 403

18 · Disk I/O attribution & SRT diagnostics v1.11

› Admin → System Utilisation, compare with the host:
  iostat -x 2     and     df -h
✓ The DISK I/O card names the device(s) actually backing uploads/HLS/the app —
  not whichever device has the largest kernel counter
✓ A device with no reads/writes shows 0% utilisation (an idle or hung disk that
  the kernel parks at 100% util is no longer reported as system disk load)
✓ Percentages match df; each volume appears once

› Capacity: compare "more channels" with uptime/load
✓ On a host whose load per core is already ≥ 1, the CPU headroom figure is ~0
  even when instantaneous CPU% looks low (processes blocked on I/O)

› SRT not working while HLS is fine? Check the channel's Stats → error log
✓ A bind/settings clash now appears there, e.g.
  "SRT output unavailable: SRT port 9000 already in use with different listener settings"
› Two channels may share one SRT port only if passphrase, latency, buffer and
  max-bandwidth all match; they are then routed by stream ID.
✓ Give clashing channels distinct ports, or identical settings + distinct stream IDs

19 · Channel health indicators v1.12

› Run a channel with output mode "both" and no SRT client connected
✓ Card shows an amber "SRT waiting" chip (normal — the listener is up)
› Connect VLC to it
✓ Chip turns green "SRT live"
› Create a second channel on the same SRT port with a DIFFERENT latency, start it
✓ Chip turns red "SRT error"; hovering shows the reason
✓ A red count badge appears on the Channels tab from any page
✓ Hovering the badge lists each channel and its problem
› Watch a running channel card for ~30 s
✓ An OUTPUT BITRATE sparkline appears with the current Mb/s (works for HLS-only
  channels too — segment bytes are counted, not just SRT socket writes)
› Admin → System Utilisation → click the DISK I/O card
✓ Expands to a per-device breakdown naming what each disk holds
✓ Only disks backing uploads/HLS/the application are listed

20 · System figures sanity-check v1.13

› Run several HLS-only channels, then open Admin → System Utilisation
✓ CHANNEL OUTPUT is non-zero (HLS segment bytes count as egress, not just SRT)
✓ The capacity box says "measured from N running channel(s)" — it must never
  claim nothing is running while the card beside it shows channels running
✓ PROCESS shows "service up …" (this process) and "host up …" separately;
  after a redeploy service uptime resets while host uptime does not
✓ Compare with the OS:   iostat -x 2   ·   df -h   ·   uptime
  Disk device, percentages and load should agree

21 · Reading System Utilisation correctly v1.14

› Compare the CPU card with:  uptime  and  iostat -x 2
✓ The headline is LOAD PER CORE, not instantaneous usage — a host at 1% CPU with
  load 9 across 8 cores is saturated and must not appear green
✓ "using N%" and, when significant, "iowait N%" appear beneath it
✓ iowait ≥ 20% raises a "CPU is waiting on storage" advisory naming the disk as
  the bottleneck rather than the processor
› Click the CHANNEL OUTPUT card
✓ Expands to a per-channel list, with a ⚠ SRT marker on any channel whose SRT
  output is failing
✓ The rows always add up exactly to the headline figure
› Before the second sample arrives (immediately after a restart)
✓ Cards show "—" with "awaiting a second sample", never a misleading 0.0

22 · Resource cleanup & silent-failure checks v1.15

› Note the segment directories:  ls -d /dev/shm/playout_hls/*/
› Delete a channel from the Channels tab
✓ Its directory disappears; the log records "removed segment directory …"
› Create and delete a few channels, then restart the service
✓ Log records "cleaned N orphaned segment directories" — nothing accumulates
› Start a channel, then clear its rundown while it is on air
✓ Channel stays up transmitting padding (correct) BUT reports
  "Playlist is empty — channel is on air but transmitting padding only"
✓ It appears in Stats → error log and is counted by the nav issues badge
› Admin → System Utilisation, cross-check against the OS:
  uptime · iostat -x 2 · df -h
✓ Channel Output expands to a per-channel breakdown; parts sum to the total

23 · HTTPS & sign-up codes v1.16

› Set tls.enabled true with staging:true and your real domain; restart
✓ Log shows HTTPS listener, HTTP challenge/redirect listener and cache path
✓ http://your-domain/ returns 301 to https://your-domain/ (path and query kept)
✓ /.well-known/acme-challenge/… is answered, not redirected
✓ Certificate cache directory is mode 0700
› Set tls.enabled true but leave domains empty
✓ Startup refuses with a message naming the problem

› Admin → Invite Codes → generate a code with max_channels = 2, max_uses = 1
✓ With require_invite_code=true, signing up WITHOUT a code is refused
✓ Signing up WITH the code succeeds and grants max_channels = 2
✓ The user can create 2 channels; the 3rd returns "channel limit reached (2/2)"
✓ Re-using the code returns "already been used the maximum number of times"

24 · Generate & import schedules v1.19

› Rundown → 🎲 Generate → enter "20"
✓ 20 items appear; no file plays twice in a row
✓ Files still probing or marked error are NOT scheduled (the note says how many)
› Generate again with "5m"
✓ Items are added until ~5 minutes of content is reached; the toast reports the total
› Via API with the same "seed" twice
✓ Identical ordering both times

› Rundown → ⬆ Import → choose a CSV with a file,start header
✓ Toast reports format, added and anchored counts
✓ Rows with a start time appear 🔒 anchored; rows without flow after the previous item
✓ An unknown filename is reported by line number instead of failing the import
› Repeat with native XML, a BXF export and an XMLTV guide
✓ Each is detected automatically (format shown in the toast)
› Import a file with no recognisable entries
✓ Refused with a message naming what was expected

25 · Multi-clip gap filler v1.27

› Upload three short clips of different lengths (say 0:30, 0:10, 0:05)
› Channel settings → Gap filler content → select all three (⌘/Ctrl-click) → Save
› Rundown: one short item, then a second item anchored ~1 minute ahead
› Start the channel and watch the log
✓ "Filler: covering 55s with a.mp4 + b.mp4 ×2 + c.mp4 (2s null-padded)"
✓ The anchored item still starts on its exact scheduled second
✓ The same clip is not played twice in a row while an alternative fits
› Clear the filler selection and repeat
✓ The gap airs the built-in black slate; the stream stays up and the channel stays running
› Select a clip that has no duration
✓ It is greyed out and cannot be chosen (re-probe it first)

26 · App API v1.31

› EPG tab → App API Keys → + New Key
✓ A pgk_… key appears with copy buttons for the key and the channels URL
› curl "$URL/api/app/channels?key=pgk_…"
✓ Every channel returns stream_hls, thumbnail_url, epg_url, now_playing, next_up
✓ Over HTTPS the URLs are https:// — never mixed content
› curl -o t.jpg "$URL/api/app/channels/1/thumbnail.jpg?key=pgk_…"
✓ A real JPEG of what is on air right now (needs ffmpeg on the server)
✓ Requesting again within 10s is served from cache in milliseconds
› curl "$URL/api/app/channels/1/epg?key=pgk_…"
✓ Programmes with start/end times matching the Rundown
› Try without a key, with a bogus key, and with another user's key
✓ 401, 401, and an empty list / 403 respectively
› Revoke the key, then repeat the first call
✓ 401 immediately

27 · App API — keys, thumbnails, logos v1.31

› EPG tab → App API Keys → + New Key
✓ A pgk_… key appears; "Copy Channels URL" gives a ready-to-paste endpoint
› curl "https://your-host/api/app/channels?key=pgk_…"
✓ Returns your channels with stream_hls, thumbnail_url, epg_url, now_playing
✓ URLs use https:// when the request did — paste one into a player and it plays
› curl with no key, and with a wrong key
✓ Both return 401
› curl -H "X-API-Key: pgk_…" (no query parameter)
✓ Works — use this form in production so keys stay out of logs
› Open the thumbnail URL for a RUNNING channel in a browser
✓ A JPEG of what is on air right now; reload after 10s and the frame has moved
› Open it for a STOPPED channel
✓ 404 with the reason in the body (apps should show their own placeholder)
› Upload a logo:  curl -X POST .../api/channels/1/logo -H "Authorization: Bearer $JWT" -F "file=@logo.png"
✓ logo_url appears in the channel payload and is used when no thumbnail exists
› As a second user, request the first user's channel by id
✓ 403 — keys are scoped to their owner
› Revoke the key in the interface, then retry
✓ 401 immediately

28 · Trim points, repeating days, watch folders v1.38

› Rundown → any row → ⋯ → in 2, out 8 on a 12-second file
✓ Duration shows 0:06 with a ✂ marker; hovering shows the original length
✓ Every air time after it moves earlier by 6 seconds
✓ The EPG for that channel shows a 6-second programme, not 12
› Try out=3 with in=5, then in=999 on a 12-second file
✓ Both refused with a specific reason
› Start the channel and watch the log
✓ "Trim in: starting 2000ms into …" then "Trim out reached …" 4 seconds later
› Rundown → 🔁 Repeat Day → pick today → enter "weekdays 4"
✓ Four weekday copies appear, same clock times, weekend skipped
✓ Trimmed items stay trimmed in every copy
› Repeat a day that has no anchored items
✓ Refused — a loop rundown has no days to copy
› Drop an MP4 into a configured watch folder
✓ Nothing happens on the first poll (size is still being confirmed)
✓ It appears in Media on the next poll, probed and ready
✓ With move=true the source file is gone
› Copy a large file in slowly, or touch it during the copy
✓ It is not imported until its size stops changing

Fuzzing and combinations 3.56.0

Beyond the checklist above, two kinds of automated test run with the suite.

Fuzz targets feed generated input to every part of the server that reads bytes from outside. Each checks more than survival: a traffic log that parses writes back byte for byte; a token signed with one secret never verifies with another; a sample comes back out of the muxer's packets unchanged; a splice section parses back to what was asked for. Each fails an input that takes over a second (five for a whole MP4).

# one target, for as long as you like (seconds here; 10m or 1h for a soak)
go test -run '^$' -fuzz '^FuzzRTMPMessages$' -fuzztime 300s .

An input that fails is written to testdata/fuzz/<target>/; committed there, it runs in every go test from then on. The muxer the programme leaves through on air is a library (gomedia) and is outside these targets.

Combination tests (TestCombo…) air features together to a real SRT receiver and read what arrived with an independent stream reader — tables and their CRCs, every declared stream carrying data, continuity, a clock that never jumps more than 100 ms or runs backwards, the rate per second — then ffmpeg decodes the capture for picture and sound per language. The combinations: constant rate with dead air and a receiver joining in the gap; a live take during a gap; two languages with a break at a constant rate; DVB with two languages; DVB through dead air; filler with fewer tracks than the channel; a break that outlasts its item into dead air; a one-track live feed on a two-language channel; and DVB at a constant rate with a receiver joining mid-programme, between keyframes.

Encoding API

Traffic: Broadcast Logs, Library, Templates 3.49.0

The 📡 Traffic tab is where a broadcast day is planned before it is played. It reads and writes ProTrack RPX logs, keeps a library of programs and interstitials, builds days from templates, and loads a released day into the Rundown. The format and every rule below were taken from three real 3ABN logs (English, International, Russian, 14 October 2026 — 775 events), which the test suite uses as fixtures.

The workflow

1. Import a ProTrack RPX file. It is read field by field and can be written back out byte-for-byte. A file with data in columns the samples never use is refused rather than trimmed. The first import into a channel also learns the channel's profile: list number, log name, outputs, control codes, graphics timings, station-ID code and logo dayparts.
2. Check. The log view shows the integrity check — the day must run from 00:00:00 to 24:00:00 with no gap or overlap; on a grid channel every program starts on a quarter hour and fills whole quarter hours with its breaks; every graphic sits inside its program — and which house codes have no playable file. The English sample has one real one-second gap (promo BF190020A ends at 02:59:59, the next program starts at 03:00:00) and the check reports exactly that.
3. Assign media. A file plays a house code when its house ID is that code, or when its file name without the extension is (SFS220020S.mp4). Assign file… gives a file the house ID.
4. Release. Only a released log can be loaded; releasing another log for the same day supersedes the first. An imported log with integrity errors can be released only with an acknowledgement and a reason, which go into the audit log. A generated log with errors cannot be released at all — the template or library is what needs fixing.
5. Load into Rundown. A dry run says what will happen first. Each program's first part is anchored at its time, everything else is chained after it, and every file is trimmed to the length the log gives it, so the rundown keeps the log's clock to the second. Pending rundown items for that day are replaced; loading the same day again replaces it again rather than doubling it. Events less than 30 seconds away are not loaded (they would replay the past), and the first event loaded is always anchored. Loading refuses while any house code has no playable file.
6. Export RPX writes any log back out: an imported one exactly as it came in, a generated one with the channel profile's values.

Building days

Learn from this log turns a real day into library entries (each program with its parts and the breaks between them, every promo, filler and ID) and a day template, and can assign that template to a weekday. Generate a day then builds any date from the template assigned to its weekday. Learned from each of the three samples, the generator rebuilds that sample day with every program, part, start time and graphic where ProTrack put it, every station ID that closes a block, and every break filled to the second — and for the English day without the one-second hole. Since 3.53.0 that includes the 24 hour spots, and so the one English ID that does not close a block — X050000S at 23:58:30, the spot for Thursday's midnight, which opens the last break of the day.

• Grid templates (ENG, INTL) are blocks on the quarter-hour grid: start, length, program (or a series and an episode rule), optional breaks between its parts, optional station ID at the end.
• Flat templates (RUSS) are programs back to back from midnight; a block can be anchored to an exact time.
• Breaks are filled exactly from active promos and fillers. Where the same break length repeats, rotation keeps the same promo from airing in consecutive breaks. A break no combination fills is left open and named, and the generated log cannot be released until it is fixed.
• Airing numbers: ProTrack gives every airing of a program its own number in columns 88–94, shared by all of that airing's parts. Generated days continue the sequence above the highest number seen.

The template editor 3.53.0

Templates → Edit (or + Template) opens a table with one row per block. In a grid template each block starts where the one before it ends, so only its length is typed — in minutes, whole quarter hours — and the start times below it and the day's coverage (Covers 00:00 to 24:00 ✓, or how much is missing or over) update as you type. In a flat template the start and length columns become an Anchor column. Every row has a program (offered from the library while typing), a series and an episode rule, the breaks between the program's parts (blank keeps the program's own), and ID at end; ↑ ↓ move a row, + inserts one below, ✕ removes it. Fixed spots are a second table: house code and time. Save checks everything first and names the first problem in the editor — nothing is sent until the template is whole; the server checks again. Leaving with unsaved changes (Cancel, another view, another channel) asks first. Until 3.53.0 a template was edited as one line of text per block.

Series 3.53.0

A house code is a series and an episode: CR001622S is episode 1622 of CR, RUP_BDV041018 episode 41018 of RUP_BDV — everything before the last run of digits is the series, the digits the episode. A program's Series field overrides that when the codes do not follow it. A template block names a series and a rule instead of (or as well as) a program:

• same — the series' most recent airing again: today's, or the days before's (TDYC airs at 08:00, 15:00, 20:00 and 23:00 in the ENG sample, one episode four times).
• next — the episode after the most recent airing, in episode order (CR 1622 at 11:00, 1623 at 11:30). When the library has no later episode the last one airs again and the generation notes say so — add the next episode, or use cycle.
• cycle — as next, but after the last episode the series starts over at the first, also with a note.

The block's program, when set, is where the series starts if it has never aired. "Most recent" reads the channel's logs for the 92 days before the day being built — the released log of each day when there is one — and then follows what the day itself has scheduled so far.

Learning marks a block same when its program is the series' most recent airing again, and next when it is the episode straight after it — no other known episode (in the library or that log) lies in between, so the RUSS bumpers RUP_OFC000001 and RUP_OFC000017, numbered but not consecutive, stay fixed. A series' first airing in a log is compared with the logs of the days before it; with none it stays a fixed program, because one log cannot say whether it is a new episode or a repeat. Learned from the samples: ENG — CR next at 11:30, TDYC same at 15:00, 20:00 and 23:00, MH and IIW same; INTL — TTK same at 09:30 and next at 23:30; RUSS — RUP_BDV next three times.

Hour spots and fixed spots 3.53.0

Every one of the 24 breaks that end on the hour in the ENG sample opens with a spot named for its hour: X{DOW}{HH}00S, with the day of the week (Sunday = 01, so Wednesday 14 October is 04) and the hour — X040100S at 00:58:30, X040200S at 01:58:00 … and X050000S at 23:58:30, because midnight belongs to Thursday. INTL uses IDX{DOW}{HH}00S; RUSS has none. The profile's hour spot holds the pattern, learned from a log when at least 12 of the day's hours agree on one. The generator puts that hour's spot first in the break whose slot ends on the hour (through a closing station ID); codes that match the pattern never fill other breaks. A spot the library lacks is listed in the notes and its break is filled without it — so a Thursday needs Thursday's 24 spots in the library. Before 3.53.0 the 24 spots were ordinary promos to the filler and could land anywhere.

A fixed spot (template, fixed_spots) airs one promo, filler or ID at an exact second of the day, inside whichever break holds it whole: the break is filled exactly up to it and after it. One that would cut into a program, or that the library does not have, is not placed and the notes say so. A fixed spot's code never fills other breaks.

Rotation 3.53.0

Breaks are filled with the fewest items that add up exactly, and an item used within the last four hours costs more the more recently it aired, so the same promo does not air in consecutive breaks. That was all rotation knew, and it looked back over the day before only. The profile's rotation_days (1–14; 0 or 1 is the old behaviour) looks back that many days of logs, and an item that aired more recently within them costs a little more — so the promos that have not aired for longest come first and the whole library gets air.

Promo minimum gap 3.59.0

Rotation prefers promos that aired longest ago, but a cheap fill can still bring one back soon. The profile’s promo_min_gap_secs is a hard limit: a promo (type PR) that started less than that many seconds before a break is left out of it — 3600 for “not twice in an hour”, 0 (the default) for no limit. The previous days’ logs count, so a promo at 23:55 is not repeated at 00:20. When no combination fills a break without breaking the limit, the break is still filled and the day’s notes name the promo (could not keep promos … apart): add promos, or lower the limit. Fillers and filler programs are not limited. On 3ABN’s 14 October ENG library rotation alone already keeps each promo about four hours apart; the limit matters with a smaller library. It is ready for 3ABN’s answer on promo rules.

Flat anchors and filler programs 3.53.0

A flat day drifts: each program starts where the one before it ended. In the RUSS sample the openings at 06:00:00, 12:00:00 and 18:00:00 (and 03:00:00) are exact anyway. A block with an anchor starts at exactly that second: the time before it is filled like a break — from promos, fillers and programs marked filler — and a day that runs past it is noted and left as an overlap the integrity check refuses. More than an hour to fill before an anchor is noted rather than attempted. Learning a flat log anchors every program that starts exactly on the hour, and marks one-part programs of five minutes or less as fillers (the RUSS openings, bumpers, music clips); the notes say how many, and Filler in the program dialog changes it.

Graphics (secondary events)

Graphics are not placed by hand. They follow from the program and the profile by the rules all 197 graphics events in the ENG and INTL samples obey:

• Rating (TVG, TVPG, TVY7 — the TV parental guideline): 15 seconds at the start of every part, including parts after a break.
• Logo: from 1:30 into each part until 2:00 before it ends, and not at all on a part too short for that. Which logo depends on the daypart: in the English sample ENG_6 from 00:00 to 08:00 and from 17:00, ENG_8 from 08:00 to 17:00 — so 3ABN Today carries ENG_8 at 08:00 and ENG_6 at 20:00.
• E/I label (ENG_8_E, on its own output): from 1:30 into each part to its end, replacing the logo, on children's programs (every one is rated TV-Y7).

On air, a composited channel shows them, with the images the profile assigns to each code, in the corner and size given, while the code's event is on. A channel whose graphics are a page (HTML or URL) draws them in the page, which polls /graphics/{id}/cues.json twice a second. A channel on the built-in frame sends them to the node as overlays, in the session and through the update endpoint whenever the set changes (3.53.0 — before, they never reached air there; the node must support the field, see the node contract). A normal channel passes video through without re-encoding and cannot draw them.

Dayparts per day of the week 3.58.0

The dayparts above were learned from one Wednesday, and every day used them. A day of the week can now have its own: the profile’s Dayparts for one day of the week, one line each (Sat 00:00 ENG_6, Sat 09:00 ENG_8). A day with lines uses only its own; a day without uses the dayparts above. Learning a log sets its own day’s. A Monday-to-Friday log also sets the default, as learning always did; a weekend log sets the default only while there is none, so learning a Saturday no longer changes the weekdays. Generation uses the day’s dayparts, and learning a library from a log reads that log’s programs against its own day’s — so a program carrying a weekend daytime logo is not given it as its own, to carry on every other day. Templates were per weekday already (Assign to weekday).

Clock-change days 3.58.0

A broadcast day on a clock change is 23 or 25 hours long, and a 24-hour log cannot cover it exactly. How ProTrack writes such a day is a question for 3ABN, so the profile’s Clock-change days chooses:

• By elapsed time (the default, as before): events are placed that many seconds after local midnight, so clock times after the change are an hour off and the day ends an hour early (25-hour day) or an hour into the next (23-hour day). Loading such a day asks for an acknowledgement first.
• By clock time (dst_mode wallclock): every event at its clock time, no acknowledgement asked. When the clocks go forward, events that start in the hour that does not exist (02:00–03:00 in the United States) are not loaded, the plan lists them, and the first event after them is anchored so it does not follow whatever aired before the skipped hour. When they go back, the hour that repeats airs the log’s events once, in its first occurrence, and the channel’s filler covers the second; the plan says so.

Either way a log is 24 hours of the clock, checked from 00:00:00 to 24:00:00 as on any other day.

3ABN’s answers 3.61.0

3ABN answered PlayoutGo’s ProTrack questions on 13 October 2026 (Moses Primo, Jon Bivin). What each answer changed:

• Acceptance. A generated log can be imported to the player.
• Event ID, columns 86–105, is generated by the scheduler — by PlayoutGo. Airing numbers are ours. The field is read and written across all 20 columns (88–105 for the number; before 3.61.0 columns 95–105 were refused as unknown). Promos, fillers and IDs with no library number (number_every_event) can each be given an event ID from the same counter as the airings, kept from then on, and named in the day’s notes.
• Fixed fields follow 3ABN’s RapidPlay X2000 protocol. Columns 693–696 are the discrepancy code (0000), which also shows a reader that every line is the full length. They stay profile settings, copied from the channel’s log.
• Logos. _6 carries the local 618 number, _8 the 800 number, shown only in business hours, 08:00–17:00 Monday to Thursday. So ENG uses ENG_8 from 08:00 to 17:00 Monday to Thursday and ENG_6 at every other time, Friday to Sunday all day: dayparts per day of the week. An E/I program carries _8_E in business hours and _6_E otherwise. The profile’s E/I suffix (ei_suffix, learned as _E from the ENG log) makes the E/I graphic the daypart logo plus the suffix; blank keeps each program’s own E/I code.
• Clock-change days. Every schedule runs 00:00:00;00 to 23:59:59;29 — 24 hours. Timecodes written with ; before the frames (drop-frame notation) are read and written back as they came; a file mixing : and ; is refused. The profile’s Timecodes setting writes generated logs either way.
• Up Next spots. Sunday is 01. A code like X051000S is “Up Next” for the program starting Thursday at 10:00 — the day of the week and the start time of the next program — always 15 seconds, a promo. The pattern takes {MM}: X{DOW}{HH}{MM}S is learned (on the hour it reads as before). A break before a program opens with that program’s Up Next spot when the library has one; a missing spot is reported only for the hours, where every sample had one. X050000S, an ID in the sample, “may have been mis-marked”: learning adds an Up Next spot marked ID as a promo, and says so.
• Series. Whether a day starts with a new episode depends on the program: each block’s rule (same or next/cycle) says it. When the episodes run out, 3ABN usually starts over: learned blocks now cycle (they were next). To pick a starting point, the profile’s series starting points (series_starts: series, episode, first day) make that series’ first series block air the chosen episode from that day, once, the series continuing from it.
• RUSS is autonomous: its schedules arrive timed and complete. A channel marked autonomous is imported, released and loaded, never generated; Learn makes no template for it and marks no fillers.
• List numbers are channel numbers, telling which player the schedule is for: 0001 ENG, 0003 INTL, 0005 RUSS.
• Promos are rotated at the will of administration, with limits and specific rules on what can air on which channel at what time of day. Each promo, filler or ID can carry airing rules: the days and times it may air (Mon-Thu 08:00-17:00; Sat-Sun), the first and last day, and at most so many a day. The filler leaves an item out of any break outside its rules, and never relaxes them; a break that cannot be filled within them is left open and named in the notes. Rotation and promo_min_gap_secs work as before inside the rules.

The RapidPlay X2000 format and the weekend logs 3.62.0

3ABN sent the format’s document (Product Architecture for RapidPlayX2000 File Format, version 1.01) and the weekend logs of eight channels (CANADA, CHILD, DARE, ENG, INTL, LAT, PRAIZ, PRO) on 14 October 2026. What they changed:

• Every documented column is read, kept and written back. The house code is the Material ID, columns 6–35 (up to 30 characters; 3.61.0 read 6–85); 36–85 is the media locator. The output is the Video Source, 139–158 (3.61.0: 139–151). The title (269–318) is a field of its own. The optional fields — media locator, backup video, audio and backup audio sources, comment, end method, cache flag, end action, machine mode, EOM, linked event ID, switcher levels, antenna, receiver, satellite, transponder, aural subs, record sources, record material and locator — are kept with the event and exported unchanged. Only the reserved columns, 367 and 379–406, must be blank: data there is refused. All 19 logs 3ABN sent import and export byte for byte.
• Record types. Column 1 is C (event), B (break event — played as an ordinary event; the document gives it no other meaning), - (comment) or H (header, which may carry parameters). Comment and header lines are kept in place and written back. The first line need not be ProTrack’s Log for: header; without one, the log’s date is its first event’s.
• Event types (331–332): PR primary, CO comment — listed, never aired, not part of the day’s timing — OS secondary timed from its primary’s start, OE secondary timed from its end (read as that long before the end). A secondary is one by its event type; FCC type SI is not needed. FCC types CA (spot, also when blank) and PS (public service) are accepted; a blank type is stored as CA and written back blank. Learning adds spots and PSAs to the library with those types; they air only as fixed spots, never to fill a break.
• What 3ABN’s codes mean. S\ (323–325) is a slow fade-cut. C and F (326–327) are the start method: clock start, and follow the event before. PRNEMPL (331–337) is a primary, normal (audio and video) event whose duration is set by hand (M), that plays (PL); OSVKPPL a video-key secondary timed by the play list; RUSS’s PRNEPPL the same with the play list’s duration.
• What PlayoutGo cannot do as the player would is a warning on the log, never a refusal: a manual (M) or external (Xn) start starts when the event before ends; a record, dead-roll or switch-only start action plays the material; a playback rate other than 1 plays at normal speed. A traffic start time left blank on a follow event is taken from where the event before ends, and written back blank.
• SOM (341–351) is where loading cues the file: the rundown item starts that far in (frames ignored; the frame rate is not in the file), and ends the log’s duration later.
• Gaps before clock starts. A clock-start event “starts when TOD >= Event Start Time”. 3ABN’s weekend logs leave 1–4 seconds before many clock-start programs, and two end 1–3 seconds before midnight. A gap of up to 10 seconds before a clock-start event, or at the end of the day, is a warning (clock_gap, end_short), not an error; the channel’s filler covers it. Longer gaps, and any gap before a follow event, stay errors. A generated day still fills each break exactly when the promos allow; when no combination fits, the break may end up to 10 seconds early, before the next clock start — after its station ID — as ProTrack’s do.
• Clock start on every event (clock_every_event, learned). CANADA and PRAIZ mark every event C, including a program’s later parts. A part continues its program when it has the same code with a later part letter (TDYQA250016A, then TDYQA250016B at 12:55:34), or the same code off the quarter-hour grid (LAT’s DLDL000155A at 04:00:00 and 04:14:19). Generated logs for such a channel write C on every event.
• Titles (titles, learned). CANADA’s logs carry each program’s title on its first part. Learning takes the title into the library — a program still titled with its house code takes the log’s; one an operator titled keeps its title — and generated logs write it there.
• File extension (file_ext, learned): CANADA’s logs are .txt, and its generated logs export as CANADA20261024.txt.
• Station ID rotation (id_codes, learned when a log has more than one). DARE rotates six IDs (IDDD210001S–006S), PRO four of 15 and 30 seconds. Where a template block ends with an ID, the one aired least recently goes in, among those that leave room for the break’s Up Next spot.
• Logos. A secondary at a program’s start is its rating only when it lasts 60 seconds or less: CANADA’s logo, CAN_W, runs from the start of each program to 3:30 before its end, and was taken for a rating. The weekend logs confirm 3ABN’s rule: ENG_6 all day on Saturday and Sunday.
• Up Next spots are learned per channel: X (ENG), IDX (INTL), CX (CANADA), DDX (DARE), LX (LAT), PX (PRO); CHILD and PRAIZ have none. Station IDs are part of the rotation history, like promos.

3ABN requirements: built and tested 3.64.0

Every requirement 3ABN gave the traffic system, where it came from and the test that proves it: 73 requirements, 72 built and tested, 1 partly tested, 0 not built; 13 wait on something only 3ABN can do. Sources: LOG the three sample logs of 14 October 2026, ANS-n 3ABN’s answer n of 13 October, DOC the RapidPlay X2000 format document, WKD the weekend logs of eight channels, OPS what airing their channels needs. This table is the code’s own (requirements3abn.go); a test fails if a row names a test that does not exist or claims a test it does not have.

Log format (ProTrack / RapidPlay X2000)

Integrity check and release

Loading a day and playing it

Learning from 3ABN's logs

Building days

Graphics

Waiting on 3ABN

• Does ProTrack (the player) import PlayoutGo's generated logs? The test packs of 3.58.0, 3.61.0 and 3.62.0 are ready.
• Does the player accept PlayoutGo's event IDs on Up Next spots, promos, fillers and IDs?
• How does the player air a clock-change night (1 November 2026)?
• Some hours of the weekend logs have no Up Next spot: on purpose?
• PRO's PX071400S airs at 13:29 but names 14:00.
• LAT's DLDL000155A airs twice: at 04:00:00 and 04:14:19.
• Do the channels other than ENG have business-hours _8 logos?
• Does the player accept a few seconds before a clock start?
• Does ProTrack ever write B, H, '-' or CO records?
• Which programs repeat and which air new episodes; any starting points?
• Administration's promo rules: which promo may air on which channel, and when.

What the RPX format holds

Lines of 696 characters, CRLF after each. The first is usually ProTrack’s header (-, 22 spaces, the log name, 2 spaces, Log for: MM/DD/YYYY); then one record per event. Columns 2–5 are the channel (player) number (0001 ENG, 0002 LAT, 0003 INTL, 0004 DARE, 0005 RUSS, 0006 CHILD, 0007 PRO, 0009 PRAIZ, 0020 CANADA). Columns 6–35 are the material ID — the house code. Columns 86–105 are the event ID, the scheduler’s (3.61.0): 86–87 the library (PG program, FI everything else), 88–105 its number — per airing for programs. Start and duration appear twice on primary events (106–138 and 407–428); a graphic has no absolute start, only a duration and an offset from its program in 407–428. Columns 139–158 name the output, 269–318 the title, 319–322 the type. Columns 326–327 are the start method: C on the first part of a program (on every event for CANADA and PRAIZ) and F on everything else. The rest are described in the RapidPlay X2000 format; rpx.go has the full column map.

Traffic API

Application Keys

Playback, As-Run and Metrics

Changelog

v3.64.0 — 3ABN’s Requirements, Each Traced to Its Test

Every requirement 3ABN gave the traffic system — from the sample logs, the ten answers, the RapidPlay X2000 document and the weekend logs — is now a row in a table the code keeps true, each with the test that proves it: 3ABN requirements. Tracing them found eleven requirements with no test, or only part of one, and one wrong message on the clock-change days, which matter to 3ABN on 1 November.

New

• The 3ABN requirements table (requirements3abn.go), shown in the manual: 73 requirements, where each came from, what is left for 3ABN, and the tests. A test fails when a row names a test that does not exist, claims a test it lacks, or leaves one of 3ABN’s answers out.
• Every kind of problem the log check reports has a test, and a test fails when a new kind is added without one. Eight had none: the wrong channel’s log (list number, outputs), a program with no rating, an event with no duration, a graphic before its program, on a promo or naming no output, a program and its breaks not filling whole quarter hours, times with frames, and the record and playback-rate warnings.
• Tested for the first time: media matched by house ID (Assign file) over the file name, two candidate files, a file not ready, a short file; generated logs in drop-frame, with 3ABN’s fixed fields on every record; the two clock-change Sundays (1 November 2026, 14 March 2027) generated, released and loaded by the clock.

Fixed

• 3ABN’s channels were told a clock-change day would air “an hour off”. The log’s warning always described placing events by elapsed time; 3ABN’s channels place them by clock time (dst_mode wallclock). It now says what loading will do on that channel: on 1 November, that the hour from 01:00 to 02:00 happens twice and its events air once; on 14 March, that the events from 02:00 to 03:00 are not loaded and the next is anchored. The hours come from the channel’s time zone.
• An alert raised as a channel stopped could outlive the database. A webhook notification (3.63.0) read the server’s database and address when its goroutine ran, not when it was raised: at shutdown it could run after the database had closed, and between tests the race detector caught it reading settings another test was replacing. It now takes both when raised, and shutdown waits up to 5 seconds for those in flight before the database closes.

Verification

• Suite: 774 tests and 16 fuzz targets (main), 10 tests (gpupool); 10 of the tests are new, two of them permanent checks (every requirement traced, every integrity kind tested). The full suite passes, and passes under the race detector with no race reported.
• Mutations: 34 mutations of this release’s changes, each putting one defect back — the clock-change warning, each integrity check, media matching, drop-frame and fixed fields on generated logs, the requirements table and its manual section — all caught by a test, none by a build failure. The first run left one survivor: an event in the repeated hour placed in its second occurrence. Go’s clock picks the first occurrence in American zones but the second in London and Sydney, and the tests used only American ones; a test across four zones now catches it. Two more put back the webhook race above, and are caught.
• Real binary: 3ABN’s clock-change weekend pack built with the 3.64.0 binary through its API — eight channels, Saturday 31 October and Sunday 1 November 2026: no integrity error, every record 696 characters, every file released and read back into a fresh channel, every Sunday log 24 hours of the clock with the warning that the hour from 01:00 to 02:00 happens twice and its events air once.

Known gaps

• Waiting on 3ABN (13 requirements): a test import of a generated pack; event IDs on Up Next spots; how the player airs the clock-change night; the Up Next gaps in the weekend logs, PRO’s PX071400S, LAT’s repeated DLDL000155A; business-hours logos on the other channels; a few seconds before a clock start; B, H, '-' and CO records; the series rules and starting points; administration’s promo rules.
• Traffic graphics on the built-in frame are sent to the node but drawn only by a gpuff release that draws overlays (GFX-06, partly tested).
• Carried from 3.63.0: no FEC, 2022-7 or SAP on the UDP output; multicast beyond this server and IPv6 destinations untested; webhooks send no e-mail. SDI untested on a DeckLink card, main language only, no captions, timecode, key/fill or genlock.
• Carried from earlier: conform on this server’s processor only; subtitle and data streams dropped by conform; live inserts not loudness-managed; two-factor cannot be required; the features not built; no Let’s Encrypt certificate itself; the real systemd without the distribution’s services; no TPM; gomedia not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: a multicast network and a head-end or IRD; a DeckLink card; NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service; Firefox, WebKit, Safari and tvOS runs.

v3.63.0 — UDP/RTP Multicast Output and Alert Webhooks

Two of the features the roadmap listed as not built: the transport stream over UDP or RTP to a multicast group or an address (UDP / RTP output), and alert webhooks, so the server tells an operator’s systems when something goes wrong on air (alert webhooks).

New

• UDP / RTP output: per channel, multicast or unicast, IPv4 or IPv6; raw UDP or RTP (payload type 33); TTL, egress interface and DSCP; paced at the constant bitrate or a set rate; the channel dialog, the API, the status, four metrics and two alert rules. It carries the same transport stream as SRT — service tables, SCTE-35, constant-rate padding.
• SRT joins a running stream when a UDP output runs: a receiver connecting is held to the next keyframe and given the program map, and the multicast is not restarted.
• Alert webhooks: channel down/up, output down/up (SRT, UDP, SDI), unplayable files, dead air, channel errors; signed with HMAC-SHA256; queued and retried; a delivery log; Send test and New secret; Admin ▸ Alert Webhooks and /api/admin/webhooks; administrators only, audited.
• SDI in the metrics: playoutgo_channel_sdi_up and playoutgo_channel_sdi_restarts_total, and a PlayoutGoSDIDown alert rule.

Fixed while building this release

• An SRT receiver joining could be given a video packet as its PAT: the table cache took any packet starting a payload with 00 00 01 — every PES start — for table 0, and the receiver saw a continuity break on the video PID. The PAT is now taken only from PID 0 and the program map only from the PID the PAT names, noted packet by packet while a receiver joins (found by a stricter join test).
• Short datagrams on a healthy stream: a write more than 50 ms after the last sent what was waiting as a short datagram, so ordinary muxer bursts split 1.7% of a 4 Mb/s constant-rate stream (found on the real binary). Packets now wait for a full datagram, and go out short only after a quarter of a second.
• RTP timestamps were the time a datagram was queued, not sent: behind a paced queue that had backed up, the 90 kHz clock ran 2.7 s behind the datagrams (found on the real binary, on a host starved of CPU). It is now stamped at transmission, as RFC 3551 has it.

Verification

• Suite: 764 tests and 16 fuzz targets (main), 10 tests (gpupool); 22 of the tests are new. The full suite passes, and passes under the race detector with no race reported.
• Mutations: 53 mutations of this release’s changes, each putting one defect back — among them the three bugs fixed above. All are caught by a test, none by a build failure. The first run had three that did not compile (rewritten) and seven survivors, which new tests now catch: the join filter packet by packet, the RTP clock, short datagrams, pacing after a stall and past the queue, retry spacing and a disabled webhook. One more pointed at the wrong test and was rerun against the right one.
• Real engine: the 3.63.0 binary through its own API (real363.py), 18 of 18 checks. A 4 Mb/s constant-rate channel sent RTP to a local receiver for 15 s: about 5,800 datagrams, every one seven packets, one SSRC, no sequence gap, the 90 kHz clock moving with the wall clock (15.38 s on both), each second 3.95–3.98 Mb/s. ffmpeg joined its SRT listener midway: the RTP stream had no continuity error and one program-map version, and what ffmpeg received decoded, with the 440 Hz tone. A webhook received Send test, signed with the secret shown once; a channel whose SRT receiver was a closed port raised output.down for srt.

Known gaps

• No FEC (SMPTE 2022-1) and no seamless protection switching (SMPTE 2022-7) on the UDP output; no SAP/SDP announcement of the multicast.
• Multicast beyond this server is the network’s: verified on the loopback interface and to a unicast receiver; IGMP/PIM routing and a real head-end are untested here. IPv6 destinations are untested too: the build host has no IPv6, so the hop limit and traffic class are set by code that has not run.
• Webhooks carry no e-mail: an e-mail relay or chat service takes the webhook; the server sends no mail itself. Delivery is at least once — a receiver should use the event ID to drop a repeat.
• Carried from 3.62.0: SDI untested on a DeckLink card, main language only, no captions, timecode, key/fill or genlock; the meaning of break records; 3ABN’s open questions (pack README).
• Carried from earlier: conform on this server’s processor only; subtitle and data streams dropped by conform; live inserts not loudness-managed; two-factor cannot be required; the features not built; no Let’s Encrypt certificate itself; the real systemd without the distribution’s services; no TPM; gomedia not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: a multicast network and a head-end or IRD; a DeckLink card; NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service; Firefox, WebKit, Safari and tvOS runs.

v3.62.0 — The RapidPlay X2000 Format, Eight 3ABN Channels, and SDI Output

3ABN sent the RapidPlay X2000 format document and the weekend logs of eight channels. The traffic system now reads every column the document defines and handles what the weekend logs showed: the RapidPlay X2000 format and the weekend logs says what each changed. And a channel can now play out of an SDI port on a Blackmagic DeckLink card (SDI output).

New

• SDI output: per channel, through ffmpeg’s DeckLink output — HD and SD formats with their field order, 4:2:2, 2/8/16 embedded audio channels, restarted when ffmpeg exits; /api/channels/{id}/sdi and /api/sdi/devices; administrators only.
• The RapidPlay X2000 field model: every documented column kept and written back; H, '-' and B records; CO and OE events; FCC types CA and PS; follow events without a start time; the SOM cues the file at load.
• Gaps of up to 10 seconds before a clock start, and at the end of the day, are warnings, as ProTrack’s own logs have them; a generated break may end that early when nothing fills it exactly.
• Clock start on every event (CANADA, PRAIZ), titles (CANADA), .txt exports (CANADA), station ID rotation (DARE, PRO) — each learned from the log.
• The console: the log shows titles and marks comment, break, manual and external events; the profile has the new settings and names the columns by the document.

Fixed

• CANADA’s logs were refused (“columns 152–318 hold HELP IN DAILY LIVING”): the title column was not known.
• Every weekend log showed integrity errors for the 1–4 seconds ProTrack leaves before clock-start programs, and two for ending 1–3 seconds before midnight; an imported log needed an acknowledgement to release.
• CANADA’s logo was learned as its rating graphic: a secondary starting with its program was always a rating.
• On CANADA and PRAIZ every later program part started a new program, so their days were learned as flat, not grid, and their programs lost their later parts.
• A break that could not be filled exactly was left open in front of the station ID, which then failed the integrity check; the ID now follows the break, and a few seconds may be left before the clock start.
• A toast followed by another was replaced at once (after Learn the counts were overwritten by the notes), and an earlier toast’s timer hid a later one early. Toasts now queue: each stays at least 1.5 seconds when another waits, and its own full time otherwise.
• A log opened just after Generate could blank to the bare list: Generate’s refresh of the Logs view, returning after the Open, replaced the log being shown. A refresh overtaken by a newer one now stops.

Verification

• Suite: 742 tests and 16 fuzz targets (main) and 10 tests (gpupool), 18 of the tests new; the full suite passes, and passes under the race detector with no race reported. All 19 of 3ABN’s logs round-trip through the parser, the stored events and the API; each weekend day is learned and rebuilt by the generator with its programs and graphics where ProTrack put them.
• Mutations: 50 mutations of this release’s changes, each putting one defect back, all caught by a test (one by the test timing out on a blocked engine), none by a build failure. In the first run five did not compile and were rewritten, and one survived — a follow event with no start time placed at the start of the day; the documented-fields test now has a follow event with both start times blank.
• Real binary: the 3ABN weekend pack built with the 3.62.0 binary through its API — eight channels, Saturday 24 and Sunday 25 October: no integrity error, 7 warnings of a short gap before a clock start in 4 files, every record 696 characters, every file read back into a fresh channel. The test guide’s console steps for all eight channels in Chromium, 92 of 92, its 16 exports byte-identical to the pack; the test guide itself, 81 of 81. SDI on a real engine with the stand-in for the card: 1920×1080 4:2:2 at 29.97 frames a second and 48 kHz PCM carrying the programme’s tone.

Known gaps

• SDI output is untested on a DeckLink card. It was verified with a stand-in for the card: the real ffmpeg ran the server’s exact command line with only the final -f decklink device replaced by files — 1920×1080 4:2:2 at 29.97 frames a second and 48 kHz PCM carrying the programme’s tone. That a card accepts each format, the field order on the wire, and the audio on the right SDI channels need a server with a card and a DeckLink-enabled ffmpeg.
• SDI carries the main language only, and no captions in the ancillary data, no timecode, no key/fill and no genlock setting.
• The meaning of a break record (B) is not in the document: B records play as ordinary events. OE secondaries are read as an offset before the program’s end; 3ABN’s logs have none.
• From 3ABN, still to come: why some hours of the weekend logs have no Up Next spot, PRO’s PX071400S at 13:29, LAT’s repeated DLDL000155A, whether other channels have business-hours logos, whether the player accepts a few seconds before a clock start, administration’s promo rules, the series rules, the clock-change night, and whether the player accepts PlayoutGo’s event IDs on Up Next spots.
• Carried from 3.61.0: conform on this server’s processor only; subtitle and data streams dropped by conform; live inserts not loudness-managed; two-factor cannot be required; the features not built; no Let’s Encrypt certificate itself; the real systemd without the distribution’s services; no TPM; gomedia not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service; Firefox, WebKit, Safari and tvOS runs; a DeckLink card.

v3.61.0 — 3ABN’s Answers in the Traffic System

3ABN answered the ProTrack questions (Moses Primo, Jon Bivin, 13 October 2026), and the traffic system now follows the answers instead of the guesses made from three sample logs: 3ABN’s answers says what each one changed.

New

• Event IDs are ours: columns 86–105 read and written in full; number_every_event gives every promo, filler and ID without a library number an event ID from the airing counter.
• E/I follows the daypart (ei_suffix): ENG_8_E in business hours, ENG_6_E otherwise, learned from the log.
• Up Next spots: the pattern takes {MM} (X{DOW}{HH}{MM}S, learned), and a spot can announce a program at any start time.
• Promo airing rules: days and times, first and last day, at most per day — set in the promo’s dialog, kept by the filler without exception.
• Series starting points (series_starts); learned series blocks start over when the episodes run out.
• Autonomous channels: import and load only (3ABN RUSS).
• Drop-frame timecodes (HH:MM:SS;FF) read, kept and written.

Fixed

• An Up Next spot marked ID in a log was learned as an ID (X050000S in the ENG sample); it is a promo, and learning now adds it as one.
• A ProTrack log with an event ID longer than seven digits was refused as data in unknown columns (95–105).

Verification

• Suite: 724 tests and 16 fuzz targets (main) and 10 tests (gpupool), 11 of the tests new; the full suite passes, and passes under the race detector with no race reported. The traffic tests learn from 3ABN’s three sample logs and check each answer on generated days: Friday’s logos, E/I by daypart, Up Next before a half-hour program, a starting point, airing rules, an autonomous channel, event IDs, drop-frame files round-tripped.
• Mutations: 29 mutations of this release’s changes, each putting one defect back, all caught by a test, none by a build failure: the event-ID columns, drop-frame reading, writing and storage, E/I by daypart and its learning, Up Next minutes and types, each airing rule, series starting points, the autonomous refusals, event IDs and their counter, learned cycling, the profile checks, the manual and the console. The first run left one survivor, the E/I suffix’s length check; a test case now catches it.
• Real binary: the 3ABN test pack rebuilt with the 3.61.0 binary through its API — ENG and INTL for 15, 16 and 21 October: no integrity error, every record 696 characters, every file read back into a fresh channel, Friday ENG_6 all day with ENG_6_E on the E/I programs, every Up Next spot a promo with an event ID; generating RUSS refused. The test guide’s steps done in the console in Chromium, 47 of 47, its six exports byte-identical to the pack; the test guide itself in Chromium, 46 of 46.

Known gaps

• The RapidPlay X2000 document and the Saturday and Sunday logs 3ABN attached did not arrive. The fixed columns other than the discrepancy code are still copied, not understood; the weekend dayparts come from 3ABN’s rule, not from a weekend log.
• 3ABN’s actual promo rules are not entered: the rules can be set per promo, but which promo may air where and when is administration’s list, not yet received.
• How the player places a 24-hour schedule on a clock-change day was not answered; 3ABN’s channels are set to place by clock time.
• Event IDs PlayoutGo gives promos without a library number are its own; whether the player needs ProTrack’s library numbers for them is still to be seen in a test import.
• Carried from 3.60.0: conform on this server’s processor only; subtitle and data streams dropped by conform; live inserts not loudness-managed; two-factor cannot be required; the features not built; no Let’s Encrypt certificate itself; the real systemd without the distribution’s services; no TPM; gomedia not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service; Firefox, WebKit, Safari and tvOS runs.

v3.60.0 — Conform on Ingest, Loudness, and Two-Factor Sign-In

Three of the features the code check found missing. A file with AC-3 audio — the usual audio of a US broadcast master — no longer airs mute, and MOV, MXF, transport streams and HEVC or ProRes masters are converted at ingest instead of refused. Every file’s loudness is measured, and with a target set (−24 LUFS for the CALM Act) a file outside it is normalised. Accounts can add an authenticator-app code to their password. The features still not built are listed in the roadmap.

New

• Conform on ingest (conform): uploads, watch folders and re-imports take MOV, MXF, MPEG-TS, MKV and WebM; video other than 8-bit 4:2:0 H.264 is re-encoded (captions kept), audio other than AAC converted, every language kept, the original replaced atomically after the result is checked. A file on air is never replaced. ⚙ Conform converts a file already in the library.
• Loudness (loudness): integrated loudness, true peak and range per audio track, for every file, shown in the library and the API and as /api/media/loudness.csv; loudness_target_lufs, loudness_tolerance_lu and loudness_true_peak_dbtp normalise at ingest.
• Two-factor sign-in (two-factor): TOTP per account, recovery codes, replay refused, wrong codes throttled like passwords, the secret sealed, other sessions signed out on every change, an administrator’s reset, all audited.

Fixed

• Audio other than AAC aired as silence in “Original files” mode: AC-3, E-AC-3, MP3, PCM. It is now converted at ingest. (The engine’s silence remains for a file that could not be converted.)
• MOV, MXF, MPEG-TS and MKV uploads were refused, and HEVC, ProRes, MPEG-2 or 10-bit H.264 failed the probe; they are now converted.

Verification

• Suite: 713 tests and 16 fuzz targets (main) and 10 tests (gpupool), 15 of the tests new; the full suite passes, and passes under the race detector with no race reported. The conform and loudness tests convert real files with ffmpeg: a MOV with PCM, HEVC with two AC-3 tracks, 4:2:2 H.264 with A/53 captions, and a programme 5 dB too loud.
• Mutations: 36 mutations of this release’s changes, each putting one defect back, all caught by the test written for it: conform’s decisions, the conversion (captions, languages, the original left behind, a file on air), the record of what was done, loudness (tolerance, ceiling, defaults, normalising, the figures afterwards, the report), two-factor (skew, replay, the used step, recovery codes, sign-in, throttling, sessions signed out, the password and code asked for, the sealed secret), the console’s handler list and the manual.
• Real binary: the 3.60.0 binary over HTTP, 22 of 22: an AVI refused naming what is taken; a MOV with PCM 5 dB too loud re-wrapped, converted and normalised to −24 LUFS; HEVC with two AC-3 tracks stored as H.264 and two AAC tracks, English and Spanish; that programme on air with sound in its HLS segments (it aired mute before); Conform refused on air; the CSV report; two-factor enrolment, sign-in, replay refused, a recovery code once, the old session signed out, an administrator’s reset, all audited with no secret in the trail. In Chromium, 11 of 11: the code field at sign-in, the Media card’s conform note and loudness, 🔉 Measure from the card, turning two-factor on with the server’s QR code and staying signed in, with no policy violation. The 3.55.0 real-binary checks: API 21/21 and Chromium 9/9.
• The installer on a real systemd: the 3.59.0 harness on the 3.60.0 bundle, 38 of 38 over two boots.

Known gaps

• Conform runs on this server’s processor, one file at a time; a video re-encode of a long master takes about real time or longer. It does not use the encoding nodes or the cards.
• Subtitle and data streams are dropped by conform, SCTE-35 in a transport-stream upload included.
• Live inserts and the slate are not loudness-measured or normalised; only files are.
• Two-factor cannot be required of administrators or of every account yet; it is each account’s choice.
• The features in the roadmap’s list are not built.
• Carried from 3.59.0: no certificate from Let’s Encrypt itself (tested against Pebble); the real systemd ran without the distribution’s other services; no TPM; 3ABN’s answers and the ProTrack import.
• Carried from 3.56.0: the on-air muxer (gomedia) is not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service behind secrets_key_command; Firefox, WebKit, Safari and tvOS runs.

v3.59.0 — The Installer on a Real systemd, HTTPS from Your Own ACME CA, and a Promo Gap for 3ABN

Until now the installer’s systemd path had only met a stand-in systemctl, and built-in TLS had never been issued a certificate. This release ran both for real: the shipped bundle on a real systemd (version 255, as PID 1 of its own namespaces) and built-in TLS against Pebble, Let’s Encrypt’s ACME test server, on the real ports 443 and 80. That found two installer defects, fixed here. Built-in TLS can now use an ACME CA of your own, and traffic gains the promo limit 3ABN’s answer on promo rules will set.

New

• An ACME CA of your own (HTTPS): tls.acme_directory and tls.acme_ca_file, for a host on an internal network with its own CA (step-ca, a corporate PKI); checked when the configuration loads and by playout -check. install.sh --tls-acme-directory and --tls-acme-ca write both.
• Promo minimum gap (traffic): promo_min_gap_secs keeps two airings of a promo that far apart, across midnight too; a break that cannot be filled within it is filled anyway and named in the notes. Off by default.

Fixed

• A broken upgrade on a real systemd host was left in place, with the service down. A real systemctl start fails when the service does not come up; under set -e that ended install.sh before the health check that decides on a rollback. The stand-in systemctl the tests used returned success, so this was never seen. Now the health check decides, and the stand-in fails a start the way systemd does, so the installer tests catch this.
• The server warned at every start after an upgrade that it could not make backups/last-upgrade owner-only: the installer wrote it as root, mode 0644, where the playout user cannot change it. It is now written 0600 and owned by the service user.
• Installer tests could leave a server running when they failed (found after the 3.58.0 mutation runs). Each now stops every process running from its work directory.

Verification

• Suite: 698 tests and 16 fuzz targets (main) and 10 tests (gpupool), 12 of the tests new; the full suite passes, and passes under the race detector with no race reported.
• Mutations: 28 mutations of this release’s changes, each putting one defect back, all caught by the test written for it: the ACME settings, their checks and the certificate manager, the promo gap, the installer’s start and its upgrade record, its ACME options, the test reaper, and the manual. The start that fails is caught by the stand-in systemctl, which now fails a start the way systemd does.
• The installer on a real systemd (the shipped bundle, the real systemctl): 38 of 38 checks, two boots. A fresh install with --tls and the test CA: enabled, notify-ready, -check before the start, the playout user with only CAP_NET_BIND_SERVICE, and the confinement seen from inside the service. The certificate issued on 443 and 80 and reused after a restart and an upgrade. A restart after kill -9 with the as-run row closed; the watchdog; the keyring from an encrypted credential; an upgrade, --rollback, and a broken version rolled back by itself. After a power-off and a boot, the server up with no start command, the certificate from its cache, and the row open at power-off closed as stopped. Nothing written to the build host.
• Real binary: the 3.55.0 real-binary checks against the 3.59.0 binary: API 21/21 and Chromium 9/9.

Known gaps

• No certificate from Let’s Encrypt itself yet. No public DNS name reaches the build host; issuance is tested against Pebble. The first start on a host whose DNS points at it is the last step.
• The real systemd ran without the distribution’s other services (their links hidden, so a boot starts only journald, the test CA and PlayoutGo). The first install on a production host, and moving plt.bozztv.com over, remain.
• No TPM here: the encrypted credential is tested with the host key, not --with-key=tpm2.
• 3ABN’s answers decide the traffic defaults, promo_min_gap_secs among them; the ProTrack import of the test pack is untested.
• Carried from 3.56.0: the on-air muxer (gomedia) is not fuzzed; no real-binary run for 3.56.0’s own changes.
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; a gpuff release that draws overlays and the logo; gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service behind secrets_key_command; Firefox, WebKit, Safari and tvOS runs.

v3.58.0 — Crash-Safe As-Run, Alert Rules, HTTPS from the Installer, and Traffic Options for 3ABN

The as-run log keeps an item’s airtime even when the process dies, the bundle ships alert rules, and the installer sets up built-in HTTPS — and upgrades a host that runs it, which until now always rolled itself back. Traffic gains the two options 3ABN’s answers will choose between: how a clock-change day is placed, and dayparts per day of the week. A test pack of generated days for 3ABN to import into ProTrack was built with the real binary.

New

• Crash-safe as-run (as-run): the airing row is stamped every 5 s, whatever is airing — a file, an ABR item, a live insert — and a row the process left open (kill -9, a crash, a power cut) is closed by the next start at its last stamp. Until now it ended where it started: the item on air recorded no airtime at all. 3.57.0 closed a clean stop at the moment of the stop; this covers the rest.
• Alert rules (alert rules): playoutgo-alerts.yml in the bundle, thirteen Prometheus alerts for the conditions the manual says to watch, every metric checked against what /metrics exports, with promtool rule tests.
• install.sh --tls DOMAINS (the installer): a fresh install with built-in HTTPS — the TLS settings, advertised_base_url on https://, and the drop-in granting the capability to bind 443 and 80. --tls-email, --tls-port, --tls-http-port.
• playout -healthz-url (the check): where the configured server answers /healthz on this host. The installer asks the binary instead of reading the port out of the JSON, where the TLS block’s own port could come first.
• Log rotation without systemd: with --no-systemd, playout.log is rotated at each start once over 50 MiB, three kept.
• Traffic: clock-change days (clock-change days): per channel, by elapsed time (as before) or by clock time — the skipped hour’s events not loaded and the first after them anchored, the repeated hour aired once.
• Traffic: dayparts per day of the week (weekday dayparts): learned from that day’s log, used by generation and by learning; a weekend log no longer replaces the dayparts every other day uses.

Fixed

• An upgrade on a host with built-in TLS always rolled itself back. With tls on, the server listened on the TLS ports only and config.json’s port answered nothing; the installer checks http://127.0.0.1:<port>/healthz after every start, so the new version never passed, and the rollback failed the same check. That is the setup INSTALL.md’s first step recommends. port now serves /healthz and /metrics — only those — on 127.0.0.1 in TLS mode (loopback).
• The capability advice did not work under the 3.57.0 unit. The manual and the server’s bind-failure hint said to setcap the binary (at the pre-3.57 path); the unit’s NoNewPrivileges=yes drops file capabilities. Both now name the drop-in.

Verification

• Suite: 686 tests and 16 fuzz targets (main) and 10 tests (gpupool), 14 of the tests new; the full suite passes, and passes under the race detector with no race. The alert-rule test ran with promtool 2.53.2.
• Mutations: 29 mutations of this release’s changes, each putting one defect back, and all 29 caught by the test written for it: the heartbeat and recovery, the loopback listener, -healthz-url, the installer’s TLS path and log rotation, the alert rules (one through promtool’s rule tests), the bundle, both traffic options, and the manual.
• A crash, on the real binary: two channels on air, the server killed with SIGKILL 22.5 s into a 60-second item and started again: each row interrupted, recording 19.99 s of the 22.5 s aired — the loss inside one heartbeat — where 3.57.0 recorded none; both channels back on air.
• The installer: against the real binary, a fresh install with --tls and then an upgrade that passes its health check on the loopback listener — with the tls block first in config.json, where reading the first port out of the JSON finds the TLS one — rotating a 60 MiB log on the way; --tls on an installed host refused, nothing changed; under the stand-in systemctl, the capability drop-in written and loaded before the start. The 3.57.0 cycle and systemd-path tests pass unchanged; shellcheck reports nothing.
• The 3ABN test pack: six RPX days generated by the real binary from the three 14 October samples — ENG, INTL and RUSS for Thursday 15 and Wednesday 21 October — each without integrity errors, released, in 696-character records, and read back into a fresh channel without an error.
• Soak: 15 minutes, the real binary, the five channels of 3.57.0’s hour: 46 goroutines throughout (41, and one heartbeat per channel), 22–23 open files, 8–9 threads, 26.8 MB resident after warm-up and 26.7 MB at the end, the constant-rate channel at 2.9966–3.0013 Mb/s in every 30-second window; SIGTERM closed all five airing items as stopped. Shorter than 3.57.0’s hour: what changed on the running path is one goroutine per channel and one write every 5 s.
• Real binary, API and browser: the 3.55.0 real-binary checks against the 3.58.0 binary: API 21/21 and Chromium 9/9.

Known gaps

• Built-in TLS has not issued a real certificate here. No public DNS name reaches this host: the tests run the server with TLS on and check the loopback listener, the installer’s upgrade through it, and the capability drop-in, not Let’s Encrypt. The first start on a real host, with the domain’s DNS pointing at it, is that test.
• The installer has not run on a real systemd host (from 3.57.0): its systemd path, the TLS drop-in included, is tested against a stand-in systemctl.
• 3ABN’s answers decide the traffic defaults. Clock-change days and weekday dayparts are options; which is right, and whether ProTrack accepts generated logs, waits for 3ABN. The test pack is ready for a ProTrack import.
• From 3.56.0: the on-air muxer (gomedia, a library) is not fuzzed; no real-binary run was written for 3.56.0’s own changes (the combination tests cover them).
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; graphics on a real GPU node (the node drawing overlays and the logo); gpuff mp4mux; a real YouTube OAuth client; a real A/53 master and the captions menu on Apple players; a key-management service behind secrets_key_command and a TPM-sealed credential; Firefox, WebKit, Safari and tvOS runs.

v3.57.0 — The Production Release: a Deploy Bundle, an Installer That Rolls Back, a Hardened Unit, a Configuration Check, Process Metrics, an Hour-Long Soak

Everything needed to put PlayoutGo on a server and keep it there: one archive with the binary, the unit and an installer; an upgrade that checks itself first and undoes itself if the new version does not come up; a unit that confines the service; a check that names configuration mistakes before a start; and figures for a monitoring system to see a leak coming. The server was run for an hour with five channels on air to prove it holds steady. Five defects found on the way are fixed.

New

• The deploy bundle (deployment): playoutgo-3.57.0-linux-amd64.tar.gz holds the binary, playoutgo.service, install.sh, INSTALL.md, config.sample.json and VERSION. make-release.sh builds it from the same tree as the source archive, with a SHA256SUMS file; a test checks its contents and modes, and that its binary reports the version VERSION names.
• The installer (install.sh): a fresh install — user, layout, config.json with absolute paths and generated secrets, the unit enabled and started, /healthz waited for; an upgrade that has the new binary check the configuration before anything is touched, copies the database, keyring and configuration, swaps the binary and the unit, and rolls itself back — binary, unit and database — if the new version does not answer within 60 s; and --rollback. The unit is the installer’s, recognised by checksum: local settings go in a drop-in, and an upgrade refuses to replace a unit with local changes. A binary from before 3.57.0, put back by a rollback, is never run with -check.
• A hardened unit (the unit): notify and watchdog, its own user, the file system read-only except the state directory and /dev, no new privileges, kernel, clock, namespaces and address families restricted, 65,536 files, the configuration checked before every start — and GPU devices still reachable.
• playout -check and -version (the check): the configuration checked for production without changing anything — errors for what would fail or could be attacked, warnings for what to decide — exiting 1 on an error. Until now the binary took no arguments at all.
• Process metrics (monitoring): goroutines, heap, resident memory, open files, threads and uptime in /metrics.
• /guide/deploy, the deployment section and the 24/7 tutorial are rewritten around the bundle and the installer; the three unit files they showed did not agree with one another.

Fixed

• An empty jwt_secret signed every session with an empty key. config.sample.json ships the value empty and says to copy it to config.json, promising one would be generated. It was — but only when config.json did not exist; an existing file’s empty value replaced the generated one, and anyone can compute a token signed with an empty key, for any account. An empty jwt_secret or admin_password is now generated and written back, keeping the file’s other keys and comments; found by running the new check against the sample.
• A live take left on when a channel stopped was resumed with no feed. The next start took the stale take to air: five seconds of nothing — only padding on a constant-rate channel — a live as-run row and a live.lost entry for an event that had ended. It is now resumed only while the feed is sending. Found by following up 3.56.0’s unexplained constant-rate test failure, which was this.
• playoutgo_channel_bytes_sent_total included HLS segment bytes, under a description that says transport stream: a constant-rate channel read about 15% above its rate. It is now the transport stream alone, and playoutgo_channel_hls_bytes_total counts the HLS segments. Found by the soak.
• An item on air when a channel stopped got no airtime in the as-run log. The engine left the row open when it was stopped mid-item, and a shutdown did not wait for the engines, so the process exited first. The next start closed each row as interrupted, ending where it started: after every clean restart or upgrade, the items that had been on air read as zero seconds, and after an operator’s Stop the row read playing until the process restarted. The row is now closed as stopped at the moment of the stop, with its bytes, and a shutdown waits for the channels (up to 10 s). Found by the soak’s restart check.
• A constant-rate channel went out about 1% under its configured rate: 1.2% at 3 Mb/s, nearly 4% at 1 Mb/s. Every 20 ms the padding was rounded down to whole packets and the rest of the budget dropped, half a packet on average. What is left of a packet is now owed to the next interval, and the budget keeps its fractions of a bit and of a byte, so over a minute the stream is exact to within one packet. The clock derived from the byte count, used while a new receiver waits for a keyframe, ran slow by the same amount. Found by the soak, once the figure above was the transport stream alone; the pacer’s test had allowed ±10%.

Verification

• Suite: 672 tests and 16 fuzz targets (main) and 10 tests (gpupool), 22 of the tests new; the full suite passes, and passes under the race detector with no race.
• Mutations: 37 mutations of this release’s changes, each putting one defect back, and all 37 caught by the test written for it: the stale take, the byte metrics, the empty secrets, the check, the installer’s cycle and its systemd path, the unit, the bundle, the pacer, the shutdown and the manual.
• The installer: the whole cycle against the real binary with --no-systemd — a fresh install, an upgrade, a manual rollback, a binary that will not serve (rolled back by itself), a failing check (refused before anything changes), a fresh install onto a port a server answers on (refused), an upgrade from a binary older than 3.57.0 (never run); and the systemd path against a stand-in systemctl — the unit loaded before every start, replaced by an upgrade with the operator’s drop-in kept, put back by a rollback, a unit with local changes refused, a rolled-back pre-3.57 binary never asked to -check, the newest three pre-upgrade copies kept, fresh installs refused over a hand-made unit. shellcheck reports nothing; the unit passes systemd-analyze verify.
• Soak: one hour, the real binary, five channels on air — single-language HLS, two languages, ad breaks, a 3 Mb/s constant-rate DVB channel over SRT to a real receiver, and an ABR ladder encoded on this server: 41 goroutines throughout, 18–24 open files, 9 threads, 24–30 MB resident (26.7 MB in the first ten minutes after warm-up, 26.4 MB in the last), heap 5.6 → 4.8 MB; every HLS channel’s newest segment under 4.2 s old at every sample; the constant-rate channel at 2.9967–3.0029 Mb/s in every 30-second window; 6% of one core. SIGTERM stopped it at once, and every channel came back writing segments within 10 s. A ten-minute run of the final build, after the shutdown fix, passed the same checks and two more: every airing item closed as stopped at the signal, and nothing left for the next start. Three earlier runs — of 35 and 18 minutes, cut off by host restarts, and of 36 minutes, stopped to take the pacer fix — held as flat.
• Real binary, API and browser: the 3.55.0 real-binary checks against the 3.57.0 binary: API 21/21 and Chromium 9/9.

Known gaps

• The installer has not run on a real systemd host, since none runs where it is built. Its systemd path is tested against a stand-in systemctl that runs the unit as last loaded: the order of reloads, enables, starts and stops; the unit replaced, saved and put back; drop-ins kept; a unit with local changes refused; a binary from before 3.57.0 never run with -check. The whole cycle also runs with --no-systemd, and the unit passes systemd-analyze verify. Only a real host shows the start at boot, the confinement against the server’s real file use, and the watchdog restarting a wedged process.
• From 3.56.0: the on-air muxer (gomedia, a library) is not fuzzed; no real-binary run was written for 3.56.0’s own changes (the combination tests cover them).
• Needs the operator: NVENC and NVDEC on real cards; NVENC filler on the production ffmpeg; graphics on a real GPU node (the node drawing overlays and the logo); gpuff mp4mux; a real YouTube OAuth client; 3ABN's answers; a real A/53 master and the captions menu on Apple players; a key-management service behind secrets_key_command and a TPM-sealed credential; Firefox, WebKit, Safari and tvOS runs.