Playout
Formerly design.md §9.1 (playout backends, the channel packager, admission, playout status) and
§6’s Tunarr and Live TV wiring contracts. Loomarr plays out its own channels (decision
0009); Tunarr remains a supported alternative backend. What
plays and when is decided by the scheduler (scheduling.md); a backend decides only
how the bytes reach the television. Tuning, pause and the Android TV client are in
playback-clients.md.
The decisions behind the beta.8 packager are records 0031–0033 and 0035–0041 in the index.
The channel packager
A channel encodes only while someone watches it. Nothing is encoded ahead of time, and with no
viewer no encoder process runs. Each channel and format has one long-lived Go packager
(PackagerHLS in internal/playout, the timeline core in internal/playout/packager) that owns the
channel’s segment timeline. It starts on the first tune and stops DefaultGrace (30 s) after the last
viewer leaves. There is no boot warm-up, and the channel packager is the only live path.
The pipeline.
- One encoder per item. Each scheduled item (a programme part, a break clip or a card) gets its own
ffmpeg, built by the pipeline builder (
BuildandBuildItem, thenFragmentArgs). The encoder emits fMP4 fragments already placed on the channel’s timeline, and the packager forwards them into one gapless playlist: one init, 1 s closed-GOP segments and aDVRHorizon(15 min) window. Segments live on disk underplayout.hls_dir(default<data dir>/hls, never tmpfs). Each process’s scratch root is owned by aflock, and a later process sweeps only roots whose lock it can take. - Uniform output, always transcoded. Every item is transcoded into the format’s fixed geometry,
frame rate, codec profile, colour labels and AAC-LC stereo 48 kHz, with identical encoder arguments
per class. No boundary changes decoder state, so a programme-to-break handoff needs no decoder reset.
Item commands drop source metadata and chapters (
-map_metadata -1,-map_chapters -1) so the init never inherits a source’s tags. The builder sets a square sample aspect ratio (setsar=1) so a scope film and a 16:9 episode write identical SPS fields. There is no live loudness filter; filler clips get one static gain (FillerGain). - Run-ahead and the listing gate. The encoded timeline may lead the wall clock by at most
RunAhead(12 s), enforced by back-pressure. The next item’s encoder must be producingSlateLead(2 s) before its air time. The playlist lists media only up to now +ListAhead(6 s), which is also itsHOLD-BACK. The first manifest waits untilFirstManifest(4 s) of media is listable and a real item has defined the init; the tune-in item getsFirstItemWait(10 s). The wait is bounded byStartDeadline(FirstItemWait+SlateRetry+FirstManifest, 24 s), so a tune-in item that fails once still rejoins. Past it, the master fails the start with the item’s last failure, such as a source file the server can’t read, and the client shows the shared start-failure problem. A tune-in that lands on a card (a break with no ads, the generated bumper card) has no item until the card ends, and its slate leads by onlyRunAhead. So the packager opens the first item after the card just until its first fragment, takes that encoder’s init, and closes it (probeInit, at mostInitLookAheadpast the card, #3960). The card’s slate then makes the first manifest, and the item opens again when it airs. Without this, a card with more thanRunAhead+StartDeadlineleft failed the start. Web clients setliveSyncDurationto the same 6 s, so the playhead lands on the wall clock. - Slate and rejoin. An empty slot, a failed schedule lookup or an item that is not producing by its
deadline is filled with house-format slate. The slate is shared per (host, output) and starts only
when needed, never beside the tune-in encoder. It never defines the channel init, because it goes
through the same builder tail as items and so matches their sample descriptions. After at most
SlateRetry(10 s) the schedule is asked again and the programme rejoins in progress at the right offset. A decoder-configuration mismatch between items is logged with both sample descriptions. An item whose source ran out before its slot filled (its encoder read the input to the end and exited 0: a commercial whose audio outlasts its picture, a file shorter than its listed runtime) is not reopened: the rest of its slot is slate (packager.SourceEnd), at mostSlateRetry, after which the schedule is asked again. ffmpeg also exits 0 on a truncated or unreadable file, so a programme that stops minutes early still rejoins as a failure would. Reopening a clip at its last frame started an encoder that produced nothing and failed, which on VAAPI reads as a GPU fault (A hardware frames reference is required, 2026-10-24). Any other early end, including a stream that ended on a bad fragment, rejoins at once. An item that cannot be opened, or whose encoder ends without a frame, reportsItem.Faulted; a late item, a decoder mismatch and a stopped channel do not, since they say nothing about the item’s own bytes. For a filler clip the app counts these per clip: three airings in a row feed the clip back to the filler pipeline, which rejects it asunplayablewith the cause and takes it out of rotation (filler); an airing that puts frames on the channel starts the count again. The count is per process. A slot with less than half a frame left, an item or a card alike, airs nothing: the schedule is asked what airs at its end instead. For a card this is not cosmetic. Its slate would round to no frames, the timeline would never pass the boundary, and the packager would ask for that same instant forever. That happened live at the end of a break whose clips ran out before the break did (2026-10-29): a core spun and the picture froze on the last commercial. - Two audiences, one timeline. A browser tunes a master playlist naming a
<format>.m3u8variant, withBANDWIDTH,CODECS(read from the channel init),RESOLUTIONandFRAME-RATE. Asset names are flat:<format>-init.mp4and<format>-segNNNNNNNN.m4s. A media server’s tuner reads the same timeline as one continuous MPEG-TS from the packager’s TS writer (Attach), which joins each tuner at the segment airing now and keeps its own continuity counters. A channel watched in a browser and on a TV is one encode. A 376 s tuner read across six item boundaries, measured live, had no continuity breaks on any PID, video timestamp steps of exactly one frame and audio steps of exactly one AAC frame, and no decode errors. A media-playlist request withmode=warmis an admitted-only speculative snapshot: it may keep that rendition warm but cannot start a new packager or promote one to viewing. Premium snapshots require the viewer’s learned premium preference. The hint is stripped from init and segment URLs, so prefetched bytes use the same signed addresses as the real player. These requests never count as household viewing or as evidence that the client chose premium. What a warm packager airs is not watched either: while no viewer holds it and none has released it in the lastwatchedWithin(10 s), its item lookups carryWithUnwatched, and the commercials it resolves are not recorded in the household’s rotation (scheduling.md, Rotation). A browser player holds a lease only while a playlist request is in flight; a tuner holds one for its whole session. Playlist acquisition is ordered with lifecycle changes; waiting for media readiness releases that lifecycle lock so stop, pause and quiesce can cancel a pending response. - Stills. A warm channel’s still is decoded once per segment from its newest listed segment. A cold channel gets one CPU-decoded frame of the airing on now, read from the source file and cached per airing; nothing is pre-encoded, and a break has no still. The channel-switch overlay shows it before video plays.
Formats. Every channel airs a baseline of 1080p SDR H.264 (High profile) for every device.
DeriveChannelFormats derives one optional premium HEVC format from the lineup’s measured
inventory facts. Top resolution and dynamic range are derived independently: any 4K item together with
any HDR item gives 4k-hevc-hdr (Main10, BT.2020, PQ), 4K items without HDR give 4k-hevc-sdr, and
anything else gets the baseline alone. A channel therefore costs at most two encodes, and its dynamic
range never changes mid-stream: on an HDR stream, SDR and HLG items are converted on the GPU
(libplacebo, no inverse tone-map) and the channel’s static HDR10 SEI is the packager’s to write. The
10-bit letterbox is never pad_vaapi, which writes all-zero (green) bars into P010 frames (#1673): the
libplacebo conversion draws an SDR or HLG item’s box itself at the output size (boxing at source size
and upscaling after blended the edge row into the bar), and a letterboxed PQ item is padded by
pad_opencl on the surface mapped from VAAPI, or refused on a host without that mapping. A host
drops a premium format, and says why, when it is software-only, when its encoder has no GPU graph
(QSV, AMF and other generic families) or, for HDR, when libplacebo is missing.
The premium is served on a client’s opt-in. The master names the premium beside the baseline from
its output alone: CODECS (the running init’s own, or the HEVC Main/Main 10 string predicted before one
runs), RESOLUTION, FRAME-RATE and VIDEO-RANGE=PQ for HDR10. Only a request for the premium’s media
playlist starts its packager, so a baseline viewer never starts a 4K encode. That packager holds one
premium_4k lease for the channel’s whole lineup. The class probe measures premium_4k at 2160p on GPU
hosts through the packager’s own item builder, taking the costlier of its item paths (a PQ item, an SDR
item converted to HDR10). A measured host without that cell, or without room, leaves the premium out of
the master and refuses a premium play with 503. An HDR10 packager inserts the channel’s static SEI
before the first slice of every IDR and writes mdcv/clli (and colr when missing) into the served
init; decoder comparisons keep reading the encoder’s own init. A browser plays the premium only when
MediaSource.isTypeSupported accepts its exact CODECS, and pins that one level for the tune. On TV,
ExoPlayer’s default track selector picks it only when the device’s decoder can play it.
One builder, full-GPU graphs per hardware family. playout.Build takes a host profile, a source
and an output, and returns the ffmpeg pieces. Frames stay on the GPU from decode to encode, and a stage
leaves it only through a declared fallback recorded in Pipeline.Fallbacks. Scaling comes before
tone-mapping, and padding stays on the GPU.
| Family | Graph | Status |
|---|---|---|
| VAAPI (Intel iGPU and Arc) | decode, scale_vaapi, OpenCL tone-map, pad_vaapi, h264_vaapi or hevc_vaapi | measured on an Arc |
| VAAPI (AMD) | same, with the CPU tone-map after the GPU downscale | unverified at runtime |
| NVENC | CUDA decode, scale_cuda, tone-map, pad_cuda, h264_nvenc or hevc_nvenc | measured on a GeForce |
| Software | libx264 veryfast, on a degradation ladder (below) | measured |
| VideoToolbox | scale_vt and h264_videotoolbox, HDR tone-mapped on the CPU | unverified: no Mac has run it |
| Generic (QSV, Vulkan, AMF, RKMPP, V4L2M2M) | CPU filters and the encoder’s own upload | unverified fallback |
VideoToolbox encodes unpaced (realtime=0): the packager controls run-ahead and wall-clock
delivery, so the encoder must not use its camera-capture realtime hint. Hardware encoding remains
required, with the same bitrate budget and closed GOP on both H.264 and HEVC outputs.
VideoToolbox uses GPU deinterlacing only when the configured ffmpeg binary advertises
yadif_videotoolbox. Otherwise interlaced sources use a declared CPU decode/deinterlace fallback
before scaling, retaining the hardware encoder. GPU-decoded frames download in their original
software pixel format before any conversion to the channel’s output; 10-bit SDR therefore downloads
as P010 before converting to NV12. On builds without the GPU deinterlacer, the capacity probe runs
both progressive and CPU-deinterlace graphs at every class/rung (including premium), reserving the
higher measured CPU cost and lower measured throughput for that class. Previous progressive-only
cost tables are invalidated. Live CPU refinement may raise these conservative costs, but may not
lower them below the measured envelope after a run of cheaper progressive items. These fallbacks
still require real-host capacity certification. Before the class probe completes, admission uses
the conservative unmeasured policy. Once it completes, a missing class is refused even if the
entire table is empty; failed measurements never restore the older whole-stream allowance.
Rate control is quality-based VBR at quality 22 on every rung. The 1080p budget is an 8 Mbit/s target with a 12 Mbit/s cap, and lower rungs scale both by pixel count (720p 3.6/5.3 Mbit/s, 480p 1.6/2.4, floor 1.0/1.5). Host capability profiles are data, so every family is golden-tested on any machine.
The encode vocabulary is shared (#2121). The encoders, their engines and HEVC siblings, the
host profile (HostFor), the GPU decode rule (HostProfile.DecodeRefusal), the device and decode
arguments, and each family’s encoder flags and rate control (VideoArgs) live in internal/media/encode,
so the filler pipeline encodes on the same hardware path without importing playout. The per-family
graphs above stay here: every one fits the item to the channel’s uniform output, which a filler
derivative (source geometry and cadence preserved) does not want. Which encoder a host runs is still
playout’s trial encode (DetectObserved); internal/media/encode never probes.
Tone mapping is a given, never black and never silent. Every HDR source is tone-mapped on every
SDR output. playout.tone_curve picks the one curve (hable by default; mobius, reinhard,
bt2390, bt2446a, spline), and each tone-mapper spells it its own way. tonemap_opencl has no BT.2390, so the three
libplacebo-only curves run libplacebo and then the CPU with a declared Mobius substitute.
- Intel HDR maps the surface into OpenCL (
tonemap_opencl) and back, zero-copy.tonemap_vaapiis banned from every path after it aired an all-black picture. The image ships Intel’s compute runtime and an NVIDIA OpenCL ICD file; Intel Gen8–11 iGPUs would need a legacy runtime too large to ship, so they use the CPU tone-map (docs/reference/hardware.md). - NVENC tries
tonemap_opencl, thenlibplaceboon its own Vulkan device, then the CPU. - A tone-mapper whose runtime is missing fails before any output, and the retry ladder demotes exactly that tone-mapper.
- A boot self-check encodes a few HDR frames through the live builder and reads them back with
signalstats. The darkest frame’s maximum luma must exceed 64 and the mean must sit within 24–220 of the 16–235 scale. A black picture is a red Diagnostics failure and is not demoted, because the ladder demotes only on errors and would air it; HDR is then dropped from the budget, so HDR channels show a card instead of black.
The software ladder: never refuse for speed. On a CPU-only host a heavy title degrades instead of
being refused. Rung 0 is full quality. Rung 1 skips the loop filter (with a 720-line working size only
for HDR or above-1080p sources). Rung 2 also skips non-reference frames. Rung 3 decodes keyframes only
at 480 lines. Every rung ends in the same scale, pad and colour labels, so the output format stays
constant, and audio never degrades. StartRung picks the best rung projected to reach 1.2× from the
measured cost: SDR up to 1080p starts at full quality, and 4K or HDR starts keyframes-only when nothing
is measured. RungMonitor steps down after 8 s below 0.97× (or 3 s of accumulated lag) and steps up
only after a 60 s dwell with headroom of the next rung’s measured cost ratio times 1.2. The packager
drives it live (#1551): a software item’s encoder is watched by its lease’s RungMonitor, and a step
restarts the airing on the new rung at its current offset, with ladderResumeWait (10 s) to produce.
The retry ladder. An item whose encoder fails before any output proves something about its source
on this host, and the next attempt demotes the failing stage: a GPU decode fault
(IsHardwareDecodeFault) retries with a CPU decode into the same encoder, and a failed GPU tone-mapper
retries with the next tone-mapper for the curve, ending at the CPU. The encoder never changes,
because every item must match the channel’s init. A slow item cancelled at its deadline is not a fault
and demotes nothing. ⚠ The chain’s reactive step of evicting the resident suggester model when a
hardware encode produced nothing (suggester) left with the chain: the packager’s ladder has no eviction
step, and internal/playout no longer references the evictor.
Direct files, Loomarr-owned facts. Playout reads the media file directly: the playing file Loomarr’s
own scan found for the library item (library). It never streams from a media server
(0046): an item whose file is gone or unreadable,
or an id the Library does not hold, has nothing to play and airs the offline card. Stream facts, the keyframe index, loudness and break candidates
come from Loomarr’s own per-source measurements (inventory, inventory_source_analysis), never from the
media server at airtime. An unmeasured local source gets one synchronous probe recorded against its
revision; without facts, ffmpeg probes and the gap is logged. Background analysis runs one source at a
time at low priority, reads only a bounded sample of each file (a 95 GiB remux costs about 34 MiB) and
never decodes a whole file. Audio selection follows playout.audio_language, described below.
Natural mid-programme breaks are placed by the scheduler
(scheduling.md). The packager only sees their result: a
part resumes at its cut through the packager item’s Seek.
Watermarks. Every programme carries a burned-in channel bug by default, blended on the GPU
(overlay_cuda on NVENC; on VAAPI, Loomarr’s own OpenCL kernel through program_opencl on the surface
mapped from VAAPI, #1613) and hidden during filler, bumpers and IDs. The programme’s frames never go
through a CPU filter for it. Software,
generic, VideoToolbox and HDR10 premium outputs never draw it, the programme still airs, and the
pipeline says why in Fallbacks. policy.watermark holds {enabled, corner, opacity, look, color, holiday, motifs, size, margin, image, callsign}, and a nil field means the default (on, top-right). A nil opacity or look
means the install setting, playout.watermark_opacity_pct (default 40%) or playout.watermark_look
(default text), both on Settings → Playback (#1617) and read per programme item, so a change
re-renders the bugs from each channel’s next programme. The generated callsign bug has four looks:
plate (the callsign knocked out of a rounded plate), text (the Plate’s letters, no plate),
outline (the letters as a hollow stroke) and small-plate (the Plate at 75% size, no shadow); an
uploaded image keeps its own shape. POST /v1/channels/{id}/watermark uploads a custom PNG or WebP. Placement anchors to the measured active
picture, so a letterboxed film gets the bug inside its picture. A self-check encodes a clip with and
without a test bug and asserts that the programme is unchanged outside it, that the test bug’s blend
is 65% white (its own alpha, independent of the channel default) over the measured background in
coded (limited-range) luma and neutral in chroma, that the SPS and PPS are byte-identical, and that
the overlay adds at most 10 ms per frame to the bug-off encode (the household Arc’s overlay_vaapi
drew a correct bug at 1.25x realtime, #1595). If it fails, including on a VAAPI host without an
OpenCL runtime, the watermark is off on that host and a watermark.disabled Diagnostics event says
so.
On-screen logo designs (#1659). The household-facing name is “On-screen logo” (the two
Settings → Playback labels say so). The approved design (project/prototypes/watermark.html,
answers recorded in project/evidence/watermark-2026-10-13.md) adds six looks to the four:
tint (Colour plate), twotone (Number + name), badge (Number badge), lockup (Number | name,
white), glass (frosted plate, white, gradient alpha) and stripe (Era stripe). They are drawn by
internal/playout/watermark (RenderDesign) from the mock’s own geometry, supersampled and reduced, and are
still one still PNG with straight alpha. A number look on a channel without a number draws the
callsign instead (Colour plate, or Text for Number | name). A built look with no holiday picture is
byte-identical to before and keeps its cache key. Colours come only from the design tokens:
policy.watermark.color is era (the default) or one of amber, cyan, green, red, pink,
yellow, and only the four coloured looks use it. era reads the decade the channel’s date scope
centres on (the earliest from to the latest to): the 1970s are yellow/amber/red, the 1980s
red/amber/cyan, the 1990s cyan/pink/green, and every other decade, or no bounded window, is amber
(the stripe amber/cyan/green). That table lives in one place, watermark.EraPalette.
Holiday versions. While a calendar holiday is on, a generated logo carries a small picture to
its left: Halloween a pumpkin, bat or ghost; Thanksgiving a leaf; Christmas holly or a snowflake;
New Year a firework; Valentine’s Day a heart (policy.watermark.motifs picks where there is a
choice; the first is the default). The other calendar holidays (Easter, Mother’s Day and the
rest, see #2030) have no holiday version yet: the logo airs plain through them. While a holiday is on, the coloured looks take the holiday’s colours whatever colour is chosen (the holiday version is one design);
a fixed colour gives way too. policy.watermark.holiday false turns it off; omitted is on, except that
a channel whose seasonal mode is off (Ignore holidays) never shows one and a channel limited to some
holidays shows only those. An uploaded image airs unchanged (no holiday version). The holiday comes
from schedule.ActiveHolidayAt, the scheduler’s own calendar and selection, so the logo cannot
disagree with the programming; it is evaluated at the airing’s start (Airing.StartedAt), so a
retried open or a mid-programme tune-in gets the same logo and the version changes only at the next
programme. The holiday version keeps the channel’s opacity. Holiday windows are whole dates on the
channel’s wall clock (guide.timezone, the same zone the schedule reads, #1930), so the logo flips
at the same local instant as the programming: on a US/Eastern channel 9 pm on Oct 31 is still
Halloween. The section’s holiday rows (HonouredHolidays) use the same zone.
The channel page’s On-screen logo section. It reads two endpoints and holds no copy of the
calendar. GET /v1/channels/{id}/watermark/options returns the holidays this channel honours that
have a holiday version, soonest first (empty when its seasonal mode is Ignore holidays; only the
chosen ones when limited), each with its date
window, whether it is in effect today, and its pictures (the first is the default), plus the era label
and the auto name the logo would carry. The section draws one bordered row per holiday from that list:
its name, dates and an “In effect now” badge, then its picture chips (a small picture and its name; a
holiday with one picture shows it inline, with no choice), and the chosen picture is written to
policy.watermark.motifs. GET /v1/channels/{id}/watermark/preview returns the PNG that airs for a
given look, holiday and picture (query parameters, all optional), and carries the host’s overlay state in
X-Loomarr-Watermark-Drawable so the page can say plainly when the server cannot draw a logo. The
preview is white whenever any working encoder airs the logo white, since the channel may air on that
one. Previews render under their own lock, never the one a tune’s bug renders under, into a preview
cache pruned to the 64 most recently used files (#1949). It
refuses with 422, rather than drawing a default, a look, colour, holiday or picture it does not know
and a picture that is not one of the named holiday’s own. With
motifOnly=1 (and a holiday) it returns that holiday’s picture alone as a 48 px square, drawn by the
same renderer in the same colours (white on a host without colour); the chips use it. Every thumbnail,
chip and preview frame is that PNG, never a client-side imitation, so what the section shows is what
airs. The preview frames are the mock’s bright (sun and dunes), dark (room with a lit window) and old
4:3 film scenes, drawn as token-coloured shapes behind the PNG; the selected one is large and the other
two sit beneath it. The frame sizes the logo from the PNG’s own height over 1080 (Image.getSize,
which works on web and native; onLoad carries no source size on web), anchored with the margin inside
the active picture, so on the 4:3 film it stays off the bars.
Colour on the GPU. A coloured bug needs the right RGB→YUV matrix: the NVENC graph converts the
bug with scale=out_color_matrix=bt709:out_range=tv (as the VAAPI kernel path already did), and
declares the main BT.709 limited range (conformColour, metadata only, the same declaration the
graph ends with) before overlay_cuda, which negotiates one colourspace for both inputs. Measured
on an RTX 3080 Ti with ffmpeg n9.0.2: the previous graph blended the coloured test bug at luma 158
where BT.709 is 168.2 (the BT.601 shift); this one passes. The self-check runs a second, coloured
test bug (the token green, whose BT.601 and BT.709 luma differ by ~9 coded levels at the check
alpha) through the same assertions; if the white check passes and the coloured one fails, coloured
looks and holiday pictures air in white on that host (watermark.colour_disabled in Diagnostics,
logged once), never without a logo.
Admission is one ledger. See “Admission is one measured ledger” below.
What this replaced. Beta.7 and earlier ran a three-process live chain per channel, and beta.8 development briefly built a second one to serve it:
- The per-programme chain (a shared channel session, an MPEG-TS block mux, an HLS remux and a loopback self-reach) is SUPERSEDED (retired 2026-09-27, #1542). It paid 15–20 s to first frame at worst and could not hold a decoder steady across a boundary.
- Prepared media (pre-encoding channels ahead of time, V55–V56, with its adjacent warm probe and readiness planner) is SUPERSEDED. The maintainer ruled it the wrong architecture on 2026-09-26, after it starved a household server’s CPU and wedged its store, and withdrew it (#1509, #1510) along with the continuous-stream design (#1460, #1507). Phase 4 of #1512 (#1547) removed its code (decision 0040).
- Load certification (
playout-load-cert,internal/playoutcert) retired with the chain. - Per-client encode plans, direct-play stream copy and the HEVC-follows-content rule (V47, V48, V50) are SUPERSEDED by the uniform-output packager above: a channel’s format follows its lineup, never the watching device, and there is no copy path.
The exit criteria (G1–G11) live in #1512.
Which backend plays a channel
A channel names its backend. playout.backend is a registry setting (§15) with a per-channel
override. A channel set to “Follow the default” resolves the live global value; a channel pinned to
internal or tunarr keeps that choice when the default changes. This inherited shape is intentional:
the UI says which channels follow the default, while a per-channel pin is the way to exclude one from
a fleet-wide default change. Reconciliation resolves the effective backend once per attempt so one
operation never straddles two targets.
A global backend write is a fleet transition, not a URL flip: Loomarr first records the durable
in-progress target, then reconciles every active inherited channel against it before rewiring the
media server’s single owned tuner/listing pair. Pinned, paused, and detached channels are excluded.
If convergence fails, the existing tuner registration remains in place and the transition stays
pending for retry (configuration mechanics in config-design.md §8).
The publication checkpoint is a system-owned row in the §5 settings KV, not a registry setting:
system.playout_backend_transition stores versioned JSON {version, applied, prepared}. applied
names the backend whose tuner/listing pair is currently published to the media server; prepared is
empty in steady state and names the durable in-progress target during a transition. It is recorded
before fleet convergence and therefore is not proof that convergence completed; every retry runs
the idempotent fleet barrier again before publisher work.
Internal device routes are readable while internal is either applied or prepared, so the target
M3U/XMLTV exists before the connector points the media server at it. Publication may advance applied
only to non-empty prepared, then clears prepared. The row has no environment variable, Settings API
field, or UI control — it records transition progress, not operator intent. On upgrade, a missing row
initializes applied from the currently resolved desired backend and initializes prepared empty.
Older supported releases had no separate applied checkpoint, and channel presence is not evidence of
which tuner was published. Unknown versions, malformed JSON, missing fields, and unknown backend names
fail closed without replacing the row, so corruption can never silently point the media server at an
unprepared backend.
| Loomarr (internal) | Tunarr | |
|---|---|---|
| Streams | Loomarr, via bundled ffmpeg | Tunarr |
| Break placement | between programs and mid-roll (§10) | between programs only |
| Transcode telemetry | real, per-session (§12) | none — Loomarr can’t see inside Tunarr |
| Extra service to run | no | yes |
| Right when | the default for every install — mid-roll, real telemetry, no extra service | you already run Tunarr and want to keep using it |
Tunarr is not deprecated, but it is optional. Internal playout is the default for every install;
Tunarr remains first-class for a household that already runs it, and that install should never be
forced to migrate. An unrecognised playout.backend value falls back to internal and logs a warning
rather than silently assuming Tunarr (§15).
⚠ Per-channel overrides are not yet a complete mixed-tuner installation. Reconciliation, playback routing, and now/next resolve the backend per channel, but the media-server connector owns one Loomarr tuner/listing pair selected by the global backend. A channel pinned to the non-global backend therefore does not automatically appear in Emby/Jellyfin Live TV. Full mixed delivery needs two owned tuner/listing pairs (or one aggregate Loomarr feed) and is follow-up work; the override is still useful for direct/in-app internal playback and controlled backend migration, but the UI must not imply that a mixed media-server guide is already wired.
A committed internal schedule change is a playout cutover. Reconciliation persists the new
Desired cycle before retiring any process-local packager that may still be reading the previous
cycle; the next viewer request starts at the new cycle’s current wall-clock offset. An unchanged
reconcile leaves the running packager alone. In Postgres deployments the channel invalidation carries
a compact fingerprint of the accepted cycle, so every replica retires its stale packager—not only
the replica that performed the reconcile. This ordering keeps the Guide and pixels on the same
committed cycle without interrupting playback for deadline-only reconcile writes.
What internal playout serves
- Segments over both HLS and MPEG-TS, from the one packager timeline. Both, because media
servers differ in what they accept and the compatibility matrix is not ours to police. The MPEG-TS
stream (
/playout/stream/{id}) is what a media server or ffmpeg pulls. The HLS pair (a master playlist, then<format>.m3u8and its init and segment files) is what a browser or a native app plays, because a<video>element cannot consume raw MPEG-TS. Both read the same fMP4 segments, so a channel is one encode however many people and devices watch it. - A channel still (
GET /playout/still/{id}, signed like the HLS pair; the play-url carries its signed URL) is one JPEG frame. A warm channel’s still comes from its newest listed segment, so it is never older than one segment. A cold channel’s still is one frame of the airing on now, decoded from the source on the CPU and cached per airing (HDR sources are tone-mapped with the CPU after a 960-pixel downscale). A request never starts an encoder. It exists so the channel-switch overlay (#1458) has a picture to show before video plays; a break has no still and answers 404, and the overlay then shows its card on the plain background. - Scheduled break fallback is not an empty Channel. If a filler pod has no playable clip, the synthetic card says “We’ll be right back,” preserves the break’s wall-clock identity, and is bounded by the time remaining in that break so it cannot cover the next programme. “Nothing scheduled” is reserved for a genuinely empty/unairable lineup; transient source failures remain “Program unavailable.”
- An M3U tuner (
/playout/tuner.m3u) — the channel list the media server registers. - An XMLTV guide (
/playout/guide.xml) — the listings provider.
Both device-facing documents expose the transport-published internal catalog: effective-internal
channels that are on air. This normally equals the in-app surfable catalog; while internal is the
durable prepared target it additionally includes inherited channels so the media server can read
the target feed before cutover, without exposing that target through ordinary UI routing. Paused,
detached, and empty channels remain visible in
Loomarr’s own Guide as channel rows for diagnosis and control, but their now/next and upcoming
programme answers are empty; they are absent from M3U/XMLTV and direct internal tune requests return
404. When an internal channel leaves this catalog through a lifecycle write (pause, detach, purge,
or an effective-backend change), the committed write immediately stops every packager
of that channel and re-scans the media-server tuner. Reconciliation from live to empty
also re-scans so the dead channel is removed. Additions re-scan too: a transition from empty to its
first playable programme changes the tuner channel list and cannot use only an EPG refresh.
On Postgres that stop is cross-replica and commit-ordered. Lifecycle-sensitive channel writes and
the system-owned backend-publication checkpoint emit a LISTEN/NOTIFY invalidation from the same
database statement or transaction as the durable write; Postgres delivers it only after commit.
Every replica holds a dedicated listener, applies each committed stop transition to its process-local
packagers, and performs a full durable reconciliation after subscribing or
re-subscribing. A listener disconnect or a durable reconciliation/read failure closes new playout
admission and retires every local live delivery before reconnecting, so a missed notification cannot
leave an encoder running or admit a replacement session. Admission reopens only after LISTEN is
active and the durable channel/checkpoint state has converged locally. A five-second connection
heartbeat bounds detection of a half-open listener socket; it probes liveness, not lifecycle state.
The Postgres playout seam also revalidates durable channel/checkpoint eligibility at each MPEG-TS,
HLS playlist, and HLS asset admission boundary; a read failure denies admission, and ordering that
check with teardown prevents a request admitted just before commit from escaping the stop. This is
event-driven delivery,
not the channel scheduler’s periodic sweep: “immediately” means Postgres queues the invalidation at
commit and a connected replica handles it on receipt, subject to ordinary database/network scheduling;
there is no polling interval in the off-air path. SQLite remains single-replica and uses the existing
post-commit in-process stop.
Pause is local ownership state in v1. Loomarr stops its own playout and guide answers, but a retained managed Tunarr projection keeps playing its last lineup; detach and internal/Tunarr transitions likewise preserve that historical projection until explicit purge. Making a remote Tunarr projection durably off-air requires persisted projection lifecycle state and retry, not a one-shot lineup clear.
Admission
One ledger, playout.ResourceBudget, admits every stream against what this host measured, not a
static number. A packager takes one lease when it starts, and a stream is admitted against
min(GPU throughput at 1.2×, CPU allowance ÷ measured CPU per stream, encoder sessions), per stream
class and ladder rung. The classes are 8-bit SDR up to 1080p, 10-bit up to 1080p, and 4K or HDR with
tone-mapping. A new stream drops a rung before it is refused, and a live session is never evicted.
- Measured capacity. A boot class probe runs synthetic clips per class through the live builder’s
real graphs and stores the result under
playout.state_dir, keyed to the ffmpeg, GPU and encoder fingerprint. The HDR class is re-measured at every start, because a driver update can break a tone-mapper without changing the fingerprint. Live encodes refine the CPU term within bounds; speed cannot be observed at 1× pacing. - The probe is background work. It runs at nice 19 and yields the moment a live transcode is
admitted (
BackgroundContextis cancelled insideReserve), so a tune never waits on it. An interrupted measurement is discarded and rerun once playback is idle, never taken for a failed tone-mapper. - Encoder sessions are capacity. The probe records
opened + in useNVIDIA encoder sessions, so sessions held by another application count against the cap. - Operator cap.
playout.max_channelscan only lower the result, never raise it. - Priced by the first item. Starting a packager resolves the item airing now and books that item’s class, so a heavy first item on a nearly full host is demoted or refused (503) before any encoder starts. A card slot or a failed lookup books SDR until a real item re-prices the lease. The schedule reuses the resolved item, so it is not resolved twice.
- The CPU-only case. On a software host, admission picks the best software rung whose measured CPU cost fits the allowance. A class measured below 1.2× is never refused for speed and degrades instead. Admission refuses only when even keyframes-only does not fit, and the viewer gets a 503.
- Live steps re-price the lease (
Lease.StepSoftware): a step down always applies and releases the CPU, and a step up applies only if it fits beside the other leases. - CPU cost is learned from delivered media. An item’s encoder CPU is divided by the frames it put on the timeline, not by its slot, so an early close cannot over-count.
- Background media work yields when playout is near capacity. Filler media work waits while
live playout could not take two more streams like the ones running: one for the filler work, one
for the next viewer (
PlaybackBusy). Each measured limit is checked: encoder sessions, GPU share and CPU allowance. An install with no measurement keeps the older rule and waits while any live transcode runs. The boot capacity probe still yields to any live transcode.
The dashboard’s capacity and the status endpoint’s budget read this ledger. The ledger still has a
copy class that costs nothing, but packager items are always transcoded, so it is unused there.
Watching from Loomarr’s own UI (V46). The Web UI plays a channel in the browser directly — a
Watch sub-section on the channel-detail page (§12), also reachable from the guide’s per-row menu.
It plays the HLS pair above. Two facts make this a real feature and not just a <video src>:
- A browser needs HLS, and on most browsers a JS shim. Safari/iOS play
.m3u8natively; Chrome/ Firefox/Edge needhls.js(§14) over Media Source Extensions. The player picks the native path when the browser advertises it and falls back to the shim otherwise — the same.m3u8a future native app hands to AVPlayer/ExoPlayer unchanged, which is why the transport is HLS rather than anything browser-specific. - A person is watching, but the stream still authenticates a device. The browser must not hold the
playout_token(§11: it is the media server’s device secret, not a per-person credential). So a session-authenticated op —POST /v1/channels/{id}/play-url— mints a short-lived signed URL the client feeds to its player. The signature is an HMAC overchannel + expirykeyed by the existingplayout_token: no new secret, the token never leaves the server, and the URL self-expires (the mock’s “signed with the playout token, good for 8 hours”). The HLS routes accept either the device token (a media server) or a valid signed URL (a browser/native app); everything else about segment auth below is unchanged. The op takes no request body and no device capabilities: the optionalqualityquery is its only per-viewer input.
Audio track selection is ours to make, because nobody else is left to make it. With no explicit
-map, ffmpeg picks one stream per type by “best” — for audio that means the most channels,
ties broken by lowest index. It does not read language tags and it does not honour the default
disposition. So a release whose Russian dub is 5.1 and whose English track is 2.0 plays in
Russian, every time, deterministically — which is exactly what a dev-install channel did. Direct
playback never showed it because the media server applies the viewer’s language preference; internal
playout calls ffmpeg itself and bypasses that entirely.
playout.audio_language (§15, default en) names the preferred track; any ISO 639 spelling
resolves to the language catalog’s code, so eng reads back as en. The selection is
preference, not requirement: -map 0:a:m:language:<pref>? with the trailing ? making the
match optional, plus a -map 0:a:0 fallback so a file with no tagged track of that language still
gets audio. A hard map without the ? fails the whole encode on an untagged file — a channel that
goes black rather than one that speaks the wrong language, which is strictly worse. Empty means
“whatever ffmpeg would have picked”, preserving today’s behaviour for anyone who wants it.
The channel picks the default track; the viewer picks between renditions (#2088). What one-encoder-per-channel forbids is a per-viewer encode, not a per-viewer choice. An HLS alternate rendition is one output per channel that every viewer pulls, and each player picks which one it plays. So:
policy.playout.audio_language(with precedence over the global, like every other channel policy, §15) is the channel’s default audio language, set by an admin in the channel’s settings. It is the track the video rendition group’s default audio carries.- When the airing item also carries another language, playout emits at most one alternate audio rendition, so the master playlist carries two audio renditions at most. That is one extra audio-only encode per channel while such an item airs, and nothing per viewer. The viewer chooses between the two in the player.
- Before #2088 the Watch tab’s Audio control re-picked the single shared track for everyone. That is superseded; the admin control is the default language only.
- The per-title decision (a subtitled original vs a dub, one programme at a time) remains a separate, unscoped feature.
Subtitles are soft, served beside the stream, with GPU burn-in only for image formats (#2088 decision 5). The encoder maps video plus one audio stream and never carries subtitles; a player draws them over the picture:
- Text subtitles (SRT, ASS/SSA, mov_text, WebVTT, inside the file or in a file beside it) are
served by
GET /v1/channels/{id}/subtitles?from=&to=&track=, not as an HLS rendition: a player reads the master playlist once per tune, while a channel’s languages change programme by programme. The answer is the text tracks of the programme on air atfrom(from the Library’slibrary_streams, so no probe at request time) and the chosen track’s cues on the channel’s wall clock fromfromtoto(at most ten minutes). The cues are placed by walking the accepted cycle the encoder airs (internal/app/playoutresolve/subtitles.go): a programme part airs its media from its source offset, a break has none, and a cue cut by a break never airs. - A track is chosen by key (the language, then
-sdhand-forced), so a viewer’s remembered choice picks each programme’s matching track; a programme without that key plays the language’s first unforced track. Each viewer turns subtitles on or off in the player. - Each track is read once:
internal/playout/subtitlesruns one low-priority ffmpeg (-map 0:<stream> -f webvtt) per track on a single worker, keeps the cues in memory for the tracks in use and as WebVTT under<playout.state_dir>/subtitles/across restarts (unread for 60 days, a file is removed). Until a track has been read, the answer sayspendingand the player asks again. Reading a track demuxes the whole file, so a large film over a network share takes minutes the first time; nothing about the video encode changes. - Image subtitles (PGS, VOBSUB) cannot become text cheaply, so they are not offered by default. An admin can set a channel to always burn in an image track. That is a GPU overlay in the video graph, and it applies to everyone on the channel. Where the GPU path cannot do it, the track is dropped: never a CPU filter in the playout graph.
- Nothing the server did not supply is invented: a programme without a subtitle stream shows no subtitle choices.
Both files carry a playout_token (§15, a generated secret): every segment request is signed, so
only the operator’s media server can pull the stream. Regenerating it invalidates the media server’s
old wiring credential and invokes the durable Live TV publication repair, so the UI gates it behind
a typed confirmation. On Postgres the durable generated-secret row is read at publication and
request-authorization boundaries, so a rotation handled by one replica cannot leave another accepting
the old token, rejecting the new tuner URL, or repairing the registration back to stale credentials.
SQLite keeps the in-process value because its contract permits only one replica.
Segment auth is a second authorization path, and §11 says so explicitly. A television cannot hold a session cookie, so segment routes authenticate a device by token, not a person by session. This is the only route family that bypasses the allowlist model, it is read-only, and it is scoped to playout. It is described in §11 alongside the credential paths rather than left implicit here.
Playout status
Playout has several ways to fail that all present identically to a viewer (a black frame) but have
different causes: a codec the target can’t decode, a hardware encode starved of VRAM by the resident
LLM (§8.2), a transcode running below realtime, a channel with no session at all. Diagnosing which
one, this build learned, means correlating three things the running app knows but did not expose
together: the live encoders (Stats() — per (channel, target): encoder, hardware/software, and
crucially realtime speed, where a sustained value below 1.0× is the stutter/stall signal), the
GPU + its VRAM (nvidia-smi), and the resident LLM sharing that VRAM (Ollama /api/ps).
GET /v1/playout/status (admin-only, §11) composes exactly those into one health picture:
- A GPU/VRAM header — total and used VRAM, encoder-engine utilisation, and the resident LLM’s footprint — because the shared-GPU contention (§8.2) is invisible from the encoder rows alone.
- One health row per running (channel, format): its encoder + hardware/software, its speed, and a
verdict —
ok(comfortably ≥1.0×),degraded(near 1.0×, at risk), orstalled(below 1.0× — the channel is losing to wall-clock and will buffer) — each with a one-line reason an operator can act on.
It is a read-only projection of live state, never a control surface: it changes nothing, so it is
safe to poll and safe to hand a support request. It is the in-app twin of scripts/playout-diag.sh
(the shell-level process/GPU forensics), and it is what the dashboard’s playout panel renders. Where
GET /v1/playout/sessions reports raw per-encoder telemetry, the doctor adds the verdict and the
context — the GPU/LLM picture and the ok/degraded/stalled judgement — so “why is it black?” has an
answer without shelling into the box.
Tunarr
On a Tunarr-backed channel the scheduler projects its lineup through tunarr.Adapter, the single
seam for the optional Tunarr backend (Refs #1564); call sites ask the Adapter rather than a concrete
client. The Adapter composes the Programmer port — a hand-written client for only the Tunarr
endpoints Loomarr uses — with guide reads and media-source wiring. Tunarr has no authentication, so
Loomarr stores only its URL. Tunarr owns transcoding, streaming and its M3U/XMLTV; Loomarr owns the
lineup and filler.
- Each Adapter operation reads
tunarr.url,tunarr.transcode_config_idand the filler attach policy from one settings snapshot, so one reconcile never straddles two Tunarr instances. Endpoint-derived caches are scoped to the normalised Tunarr URL. POST /v1/setup/tunarr-connectwires the media server as Tunarr’s media source (reusing the admin API key), enables the movie and show libraries and scans them./v1/setup/statusreports atunarr_librarycheck until that is done. The wizard’s dedicated “Give Tunarr your library” step (web-ui.md§13 step 5) is the only UI that triggers this connect; it exists only on the Tunarr path and is never shown to an internal-playout install. Saving a media-server or Tunarr connection setting re-runs the connect, which pushes the current library token to the source Loomarr created. Channel maintenance re-runs it whenever this process has not yet wired the current library connection: after a restart (an environment-set token can change with no save) or after a failed connect. Tunarr redacts the token it stores, so the process’s own last push is the only staleness signal.- Programming entries need Tunarr’s own program id, so the adapter maps media-server item ids through
Tunarr’s persisted
/programsindex (never the ephemeral browse handles). An unindexed item airs as flex, and a reconcile with misses triggers one best-effort library scan.
Live TV wiring
For Loomarr’s channels to appear in the family’s TV guide, the media server consumes the tuner + guide surface of the durably applied playout backend: Loomarr’s own M3U/XMLTV routes for internal playout, or Tunarr’s routes for Tunarr playout. This is one owned tuner/listing pair, never per-channel registration. Once wired, channel changes propagate through the selected backend’s output; Loomarr then pokes the media server so the change appears in minutes rather than after its nightly refresh. The poke is operation-specific (§9): a new or removed channel needs a tuner re-scan (re-read the M3U channel list — a guide refresh alone won’t surface it); an existing channel’s lineup change needs a guide refresh (EPG data).
- Endpoints (both flavors, Emby lineage):
POST /LiveTv/TunerHosts(typem3u,Url= the applied backend’s playlist URL) andPOST /LiveTv/ListingProviders(typexmltv,Url= its guide URL), using the adminLIBRARY_TOKEN. M3U is preferred over HDHomeRun emulation — explicit and discovery-free, so registration is deterministic. - One-time & never silent. There is no per-channel media-server registration. Wiring is an idempotent consequence of saving a relevant backend, URL, media-server connection, or playout-token setting. Those mutations and every prepare/publish/retire effect run inside the durable transition coordinator described in §9.1 and
config-design.md§8.POST /v1/setup/livetv-reconnect(admin — §7) force-repairs the durably applied internal or Tunarr target under that same cross-replica lock when a stale channel→stream binding needs clearing: it enumerates, removes, and re-adds both the Loomarr-owned tuner and listing provider, and fails visibly if any wiring operation fails. There is nolivetv-connectroute; it was removed when wiring became automatic, andscripts/check-retired.shbans the name. - Idempotent & self-healing on URL change. Enumerate first via
GET /System/Configuration/livetv— one read that returns{TunerHosts, ListingProviders}— and if the applied pair is already registered the connect is a no-op. Duplicate tuners are a classic Emby mess; tests assert second-call-no-op (Phase 10 gate). Reconcile is by identity, not URL string. Loomarr tags every tuner it registers withFriendlyName: "loomarr", soConnectowns exactly the tuners it created: when the applied URL pair changes (for example, the operator repointsTUNARR_URL), it first prepares the new pair by adding and verifying both the target tuner and target listing while the old pair remains registered. Only after both target registrations exist does it retire the stale Loomarr-owned pair (DELETE /LiveTv/TunerHosts?Id=<id>andDELETE /LiveTv/ListingProviders?Id=<id>→ 204, Phase-0 capture). A failed tuner or listing add therefore leaves the working pair untouched; a retry completes the missing half idempotently. A tuner the household added by hand (any otherFriendlyName) is never touched (§9 ownership: Loomarr owns only what it created). Listing providers carry noFriendlyName, so the stale one is identified as the Loomarr-shapedxmltvprovider whosePathis a Tunarr or internal-playout guide URL that no longer matches. Preparation, freshness, and retirement are separate connector operations: a backend transition may publish a prepared internal feed before asking the media server to re-scan it, durably activate that backend, and retire the old pair afterward. The ordinaryConnectcomposition still performs all three in one call. A connect that changed anything (added or retired a tuner/listing) then pokes the media server — a tuner re-scan and a guide refresh — so the freshly-registered tuner’s channels are discovered and their EPG populated immediately, rather than after the media server’s nightly scan (the newly-wired tuner has zero channels in the media server’s view until it re-reads the M3U — a guide refresh alone won’t surface them; §9 poke semantics). Both pokes are best-effort: a poke failure degrades freshness but never fails the wiring. A no-op connect (nothing changed) skips the pokes — there is nothing new to discover. The Emby-lineageGET /LiveTv/TunerHosts/GET /LiveTv/ListingProvidersare write-only on Jellyfin —POSTworks,GETreturns 405 (verified against Jellyfin 10.10.3). Enumerating through them therefore failed on every Jellyfin install, so the idempotency check could not run and the connect either errored or duplicated the tuner on each attempt. The Phase-10 capture was Emby-only, which is how it survived: §6 claims both flavors, and only Emby was ever exercised. The config endpoint answers 200 on both, so this is one code path rather than a flavor branch. - Version fragility → live capture. The endpoints exist on both flavors, but payload fields and the guide-refresh task id drift across versions. A Phase-0-style maintainer-supervised capture (folded into Phase 10, §21) pins the exact accepted request/response payloads + the guide-refresh task id from the real Emby/Jellyfin into
internal/testkit/fixtures/; the adapter is written against those pins, not memory. Any contract deviation ⇒ update this doc first. - Division of labor follows the selected backend (§9.1): Loomarr always decides what plays and when. With internal playout it also owns streaming/transcode and M3U/XMLTV publication; with Tunarr playout it projects the schedule through
Programmerand Tunarr owns those runtime surfaces. Emby/Jellyfin consume whichever one the durable applied checkpoint publishes.
Constraints that follow from owning playout
The consequences recorded when Loomarr took over playout are archived in
playout-2026-07-consequences.md.
These still bind:
- ffmpeg and ffprobe are core runtime dependencies and ship in the single image.
- Capability is per ffmpeg build. Every optional encoder and filter is probed from the binary,
never inferred. A card whose
drawtextis unavailable degrades to an unlabelled colour field, never to a dead channel. - Every “what is on now” reader answers for the backend actually streaming that channel, or not
at all. Internal now/next comes from
BroadcastsBetween, the resolver the encoder and XMLTV share. - Restart interrupts internal channels. Restart copy is per backend: internal channels drop for a
few seconds, Tunarr channels keep playing, and
GET /v1/playout/sessionssupplies the count. - One process-tree owner. Every encoder and filler ffmpeg runs under the same supervisor and
Unix process group, so cancellation, a crash or an in-process restart sweeps descendants. A bare
exec.CommandContextaround a lifecycle-owned encoder is a violation.