Playout
Playout airs a schedule of clips across Reactor sessions. You submit keyed items into priority
lanes; one plan decides what to build, in what order, what to withdraw, and when a fresh session
takes over before the current one reaches its cap. What actually aired comes back as as-run
evidence, kept apart from what you asked for.
import { Console, Effect } from "effect";import { CoordinatorClient, H3, H3Source, Playout,} from "reactor-effect-client";
const house = [ "A slow dolly shot through a sunlit greenhouse", "Waves on a black sand beach",];
export const channel = Effect.gen(function* () { const coordinator = yield* CoordinatorClient.CoordinatorClient; const playout = yield* Playout.make({ // Called for the first session and for each replacement. open: H3Source.open({ tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "10 minutes", }), }), lanes: [{ name: "breaking", cut: true }, { name: "show" }], filler: { runway: { floor: "5 seconds", target: "10 seconds" }, clip: ({ index, seconds }) => ({ prompt: house[index % house.length] ?? "", seconds, }), }, renewal: { lead: "30 seconds" }, }); const opening = yield* playout.submit({ key: Playout.ItemKey.make("opening"), lane: "show", request: { prompt: "A hand-painted sign that reads OPENING NIGHT", seconds: 5, }, }); const outcome = yield* opening.outcome; yield* Console.log(`opening: ${outcome._tag}`);}).pipe(Effect.scoped);The same program runs on the simulated Reactor, on paid H3, or on a renderer of your own: only
the source behind open changes. A pure policy makes
every decision, and the service applies them one provider command at a time on each session. It
wakes on a submission, a session’s evidence or the plan’s next deadline, and never polls.
For another model, pass its ClipModel to Playout.make and the source. The Playout service
tag and layer stay H3’s; an application can name its own service with Playout.Service<Req>.
Items and keys
Section titled “Items and keys”An item is one clip: a key, a lane and a request for its model
(H3 by default),
with an optional start, window, cues and continuity. submit returns an ItemHandle whose
started resolves with the clip’s start (or how it settled without one) and whose outcome
resolves with how it settled.
Keys make submissions idempotent. Submitting the same spec under a key again returns the same
handle, and a different spec under it fails with KeyMismatch, so a caller can retry a
submission safely. The playout remembers 4,096 settled keys (maxHistory).
A submission is refused before anything is sent with one of these tagged errors:
| Error | When |
|---|---|
InvalidItem |
The request is outside its model’s limits (H3’s by default), naming each field and limit, or names an unknown lane or anchor |
KeyMismatch |
The key is in use with a different spec |
LaneBusy |
The lane skips new items while one waits or plays |
WouldMissDeadline |
A new firm item cannot meet startBy, or a protected edit newly makes an admitted item late |
PlayoutClosed |
The playout is draining or closed |
An item whose request omits seconds is sent at its model’s defaultSeconds (5 s for H3).
A filler request without seconds is sent at the length passed to its clip callback in
FillContext.seconds. A request that names its length is sent unchanged. The plan counts a clip
not built yet at the length its model builds for the request (ClipModel.builtSeconds): H3
aligns 5 s up to its frame grid, 124 frames or 5.167 s.
Lanes are listed from the highest priority to the lowest, and each has a conflict rule:
import type { Playout } from "reactor-effect-client";
export const lanes: ReadonlyArray<Playout.LaneSpec> = [ // Stops a lower lane's clip once its own item is Ready. { name: "breaking", cut: true }, // Refuses an item while one waits or plays. { name: "viewer", conflict: "skip" }, // A new item replaces the one waiting. { name: "ticker", conflict: "replace" }, // Airs its items in the order of their places, whatever their times. { name: "line", strict: true }, // Waits behind its lane's items: the default. { name: "show" },];queue(the default): a new item waits behind its lane’s items.replace: a new item replaces the lane’s waiting items, make-before-break. They stay as cover until it is Ready, then settleDroppedwith reasonreplaced.skip: a new item is refused withLaneBusywhile the lane has one waiting or playing.cut: true: once its own item is Ready, the lane stops a playing clip of a strictly lower lane, or filler, unless that clip ends within a second. A clip is stopped at most once.strict: true: the lane airs its items in the order of their places, submissions at the end and inserts beside their anchors, whatever their starts: an item waits while one placed before it is live and not on air yet, unless that one was sent with its outcome never seen, or is being withdrawn. A slow item holds up those after it until it airs or its own deadline drops it, so give the lane’s items deadlines.AsapandManualstarts are refused there withInvalidItem. On one Linux machine, admitting 600 waiting items into one strict lane took 7.7 s in all after indexing its places, down from 174.5 s on the same workload; a lane that was not strict took 7.5 s. A forecast of that strict lane took 85 ms, down from 1.31 s. These measurements do not set a queue-size guarantee: forecasting still grows with the plan and projects at most ten minutes or 4,000 looks ahead.
On hosted H3, stop names no clip and lands after its reply, so a cut goes a step at a time: the
playout turns autoplay off, stops the clip if it still plays, waits for H3 to report it ended,
plays the cutter and turns autoplay back on. In the two show runs on hosted H3 (2026-09-28 and
2026-09-29), the cut took one stop and paused 168 ms, then 165 ms, with no dark frame.
Playout.lineup(filler) is the simplest shape: one lane, line, above filler.
Filler and its runway
Section titled “Filler and its runway”Filler is the bottom lane, and nothing is owed to it: the playout asks for a filler clip
whenever the air it has secured runs low. The air secured, state.runwaySeconds, is the rest of the clip playing
and the Ready clips that will air after it, on the session on air and then on its replacement.
runway: { floor, target }: belowfloor, filler refills up totarget. Once three builds are measured, the floor covers at least one of filler’s slow (p95) builds, so a refill started there is Ready in time.clip(context): called once per filler clip, with itsindex, therunwaySecondsand thesecondsto ask for. Keep it pure. A request outside its model’s limits fails the playout withInvalidFiller, since asking again would get the same request.lengths: the lengths a filler clip may take, the model’s request range by default. Before anAtitem, filler tiles the gap in equal clips. Where a tile would air past a capped session’s cap, the playout asks for the longest clip that airs before it, iflengths.minfits. H3 aligns each up to its frame grid, so theAtitem may air up to 0.7 s late for each tile. The plan counts a filler clip not yet sent at the length its model builds for thesecondsit asksclipfor, so a callback that returns another length moves the tiling, andplace’sstartsAt, by the difference.protect: what goes first when an item’s build would outlast the air secured. With"air", the default, once three builds are measured, such an item waits for one filler clip that builds sooner and covers the rest. An item with a time to meet (anAtstart, astartBy, anAsapstart, a releasedManualone or a cutting lane) goes at once."order"builds each item as soon as it may: it airs sooner, but the air may go dark while it builds.
Starts and windows
Section titled “Starts and windows”An item’s start says when it may air. Only Follow keeps its lane’s order, and any start in a
strict lane.
start |
Airs |
|---|---|
Follow |
At its lane’s next boundary, in order: the default |
Asap |
At the next boundary, ahead of everything waiting in every lane |
Manual |
Held until release(key), then as Asap; built ahead only while filler holds the runway at its floor, else once released |
At { time, late } |
At the first boundary after time (epoch milliseconds, wall clock) |
late says what to do when that boundary comes late: nextBoundary, skipIfLaterThan a
duration, drop, or readyBy a duration. readyBy judges the item once, that long after its
time: it is kept if it was Ready by then and nothing but filler airs before it, the clip on air and
the Ready clips ahead of it, and then airs at the next boundary however late; otherwise it is
dropped as late then. So a clip made in time may wait out an idle clip that cannot be cut short,
while one not made by then, or waiting behind another item, goes. A firm startBy still applies,
and a replacement of a kept item is kept too. Items judged at the same moment are judged in the
order they air, after what goes late by its own time then, so an item that goes then holds back
none of them, whatever order they were sent in. While a removal that breaks a group is in flight,
the judgment waits for it to land, since the group’s later parts go with it.
A window adds notBefore and startBy, measured from submission on the monotonic clock. A firm
item is dropped at startBy with reason late, and refused up front with WouldMissDeadline when
the plan cannot make it; a soft one may still air, with lateByMillis on its start. A start already
under way at a deadline, a clip H3 holds armed for its seam or a play of it in flight, may still
land, up to a command’s round trip past it.
import { Clock, Effect } from "effect";import { Playout } from "reactor-effect-client";
export const schedule = Effect.fn("schedule")(function* ( playout: Playout.Playout["Service"],) { const now = yield* Clock.currentTimeMillis; // The next full minute, skipped if it would start over 2 s late. yield* playout.submit({ key: Playout.ItemKey.make("ident"), lane: "show", request: { prompt: "A station ident spinning into view", seconds: 5, }, start: { _tag: "At", time: now - (now % 60_000) + 60_000, late: { _tag: "skipIfLaterThan", by: "2 seconds" }, }, }); // Built ahead while filler covers the air; aired when released. yield* playout.submit({ key: Playout.ItemKey.make("reveal"), lane: "show", request: { prompt: "A curtain rising on a painted forest", seconds: 8, }, start: { _tag: "Manual" }, }); // Dropped unless it can start within 20 s. yield* playout.submit({ key: Playout.ItemKey.make("viewer-17"), lane: "show", request: { prompt: "A paper lantern drifting along a canal", seconds: 5, }, window: { startBy: "20 seconds", firm: true }, });});On hosted H3, an At item aired 559 ms after its time on 2026-09-28 and 545 ms on 2026-09-29,
at the end of a filler tile H3 had built a little longer than asked, and never before its time.
Cues and continuity
Section titled “Cues and continuity”Cues fire at offsets from a clip’s observed start or end, as Cue events on playout.events.
continuity: "previous" builds the clip continuing from the one that airs just before it.
import { Effect, Stream } from "effect";import { Playout } from "reactor-effect-client";
export const segment = Effect.fn("segment")(function* ( playout: Playout.Playout["Service"],) { yield* playout.submit({ key: Playout.ItemKey.make("kitchen-2"), lane: "show", request: { prompt: "The chef plates the dish, close up", seconds: 8, }, continuity: "previous", cues: [ { name: "caption-in", at: { from: "start", offset: "1 second" } }, { name: "caption-out", at: { from: "end", offset: "2 seconds" } }, ], }); return playout.events.pipe( Stream.filter((event) => event._tag === "Cue"), Stream.map((event) => `${event.event.key}: ${event.event.name}`), );});A continued build takes longer: on hosted H3 a continued 5 s clip built in 5.45 s, against about
2.2 s for an independent one (published 0.7.0, 2026-09-28). When a continued build would be late,
the playout continues from the clip that will be playing by then instead. It never asks for
continuity across a switch of sessions, and H3 may build an independent clip without saying so, so
as-run never claims continuity. In the passing edits and show runs on hosted H3 (2026-09-28 and
2026-09-29), a continued seam changed the picture 2.3 to 5.8 times as much as the clip’s own motion,
against 11 to 20 times at their independent seams; one cut seam measured 6.5 times.
Edits, make-before-break
Section titled “Edits, make-before-break”Every edit is make-before-break: what it replaces stays on air, or ready to air, until what replaces it is Ready.
| Method | What it does |
|---|---|
submitGroup(group) |
Parts aired in order, each once the one before it started; a higher lane may go between. See Groups |
insert(spec) |
A clip right before or after an item, taking its lane, place, group and start |
insertGroup(spec) |
A group right before or after an item in a strict lane, its first part taking the item’s start as an insert does. See Lines |
replace(key, next) |
A new clip for a queued item’s place; if the item starts first, next is dropped as withdrawn |
edit(edits) |
Several of these, checked together and applied as one change |
withdraw(key) |
Answers withdrawn, already-started or not-found |
release(key) |
Airs a held Manual item at the next boundary; a group’s key releases its first part |
drain({ finish }) |
Admits nothing more. playing, the default, withdraws what has not started; accepted airs everything accepted first, except held Manual items |
import { Effect } from "effect";import { Playout } from "reactor-effect-client";
export const correct = Effect.fn("correct")(function* ( playout: Playout.Playout["Service"],) { const batch = yield* playout.edit([ { _tag: "Withdraw", key: Playout.ItemKey.make("weather") }, { _tag: "Insert", insert: { key: Playout.ItemKey.make("correction"), after: Playout.ItemKey.make("headlines"), request: { prompt: "A newsroom desk with a single corrected headline", seconds: 5, }, }, }, ]); // All it adds is Ready or settled, or some of it started; what it removes went at once. yield* batch.committed;});A batch is admitted all or nothing. It holds what it adds behind the clips queued until all of it
is Ready or settled, or until any of it starts, as H3 may start a held clip with nothing else to
air. It commits then: what it withdraws goes, while an item it replaces stays as cover until its
replacement is Ready, and what waits in a lane that replaces until the item it adds there is. An
item it submits or inserts, or a group’s first part, due by a firm startBy is checked against
the plan as the batch will run and is not held: it airs as soon as it can, and builds ahead of
every other item waiting in its lane except an Asap one. So one edit can carry an insert due
right after the clip on air, a replacement of the clip after it and the withdrawals that go with
them. An insert may anchor on an item or group the same batch adds, and beside one the batch holds
it is held too, whatever its window: a firm one is then checked as the batch will run, or as it
would be alone if it follows a clip or cuts, and while held is dropped as late only at its
startBy. A batch whose Withdraw or Replace names an
item or group it adds is refused with InvalidItem. An insert placed before an add its batch does
not hold, with no firm window of
its own, is held like any other add, so it may air after that add: give it a firm window too, or
send it as its own edit.
Use edit(edits, { protect: "deadlines" }) when an edit must respect items already admitted.
Before accepting the batch, the playout compares the plan before and after it using the same
projection as firm admission. It refuses with WouldMissDeadline { key } for the first item
newly projected to drop as late: a firm startBy, readyBy judgment or skipIfLaterThan bound.
Items the batch withdraws or replaces do not count, nor do items already projected late. A refusal
admits nothing and performs no withdrawal or replacement. Without the option, admission checks
only the new firm items.
This is a projection using measured build timing, with the same ten-minute horizon and at most one renewal. Cutting lanes are included in admission’s projected order, but the projection does not simulate interrupting a clip already playing. Slower builds, uncertain outcomes and work beyond the projection can still change what airs.
A replacement builds ahead of every other item waiting in its lane except an Asap one and the
adds a pending batch does not hold. It takes its item’s start and window, notBefore and
startBy measured from the item’s own submission. A firm item’s replacement is not refused for
that deadline. While the item it replaces may still air as cover, it is not dropped for a projected
miss of it either, only as late at the deadline it took over; once nothing covers the place, as
when nothing was built for that item, it is dropped as soon as it is projected to miss it.
In the two show runs on hosted H3, an edit batch took effect 0.91 s before its boundary
(2026-09-28) and 1.05 s before it (2026-09-29), and the clip it withdrew never aired.
Groups
Section titled “Groups”A group is material that must air in order, such as a host’s line of several beats. Each of its
places, a part and any replacement of it, airs once the one before it has started; a higher lane
may still go between, and a clip inserted beside a part keeps its place among them. A place that
fails, on air too as when its session is lost, is dropped, or is sent with its outcome never known
ends the group: every part and insert after it goes as withdrawn. A place that may have aired
unseen (Unobserved) does not end it. An insert with continuity whose build would be Ready only
after the clip before it ends continues, as anywhere, from the clip playing by then, and when that
is a later part of its group, it airs right behind that part from then on, as do its replacements
and the inserts placed right before or after it. The group’s start is any Start for its first
part, Follow by default, and the rest follow it; release takes the group’s key. The handle’s
started resolves with the first place’s start, and outcome with how many places played out in
order and where the group stopped.
import { Clock, Effect } from "effect";import { Playout } from "reactor-effect-client";
export const answer = Effect.fn("answer")(function* ( playout: Playout.Playout["Service"],) { const now = yield* Clock.currentTimeMillis; // Its first beat at the moment it answers, the second right behind it. const line = yield* playout.submitGroup({ key: Playout.ItemKey.make("answer-3"), lane: "show", start: { _tag: "At", time: now + 10_000, late: { _tag: "nextBoundary" } }, parts: [ { key: Playout.ItemKey.make("answer-3a"), request: { prompt: "The host leans in and smiles", seconds: 5 }, }, { key: Playout.ItemKey.make("answer-3b"), request: { prompt: "The host turns to the window", seconds: 5 }, }, ], }); const outcome = yield* line.outcome; switch (outcome._tag) { case "Aired": { const { played, stopped } = outcome; if (stopped === undefined) return `all ${played} beats played`; return `${played} played, then beat ${stopped.part}: ${stopped.outcome._tag}`; } case "NotAired": return `never aired: ${outcome.first._tag}`; case "Indeterminate": return "the playout died before it could settle the group"; }});After a session is lost unplanned, the next session takes a part that would air there before the part ahead of it off before its autoplay comes on; if that removal fails, the part may air once out of order, and the as-run shows it. Group order has run only on the simulated Reactor and in the policy’s property checks, not on hosted H3.
A stream of groups that answer moments on air, such as a host’s lines, goes in a strict lane, so
that the lines air first in, first out: one written late for an older moment never overtakes the
line before it. Each line is a group whose At start is its moment, judged by readyBy: made in
time, it may wait out the idle clip playing then; not made, it goes, and the lines after it move
up. An acknowledgement of something on air is a group inserted beside a line, sent with the
replacement it calls for in one edit.
import { Clock, Effect } from "effect";import { Playout } from "reactor-effect-client";
export const say = Effect.fn("say")(function* ( playout: Playout.Playout["Service"], moment: number,) { // The line airs at its moment, or behind the line before it, if made within 4 s of it. yield* playout.submitGroup({ key: Playout.ItemKey.make(`line-${moment}`), lane: "line", start: { _tag: "At", time: moment, late: { _tag: "readyBy", by: "4 seconds" } }, parts: [ { key: Playout.ItemKey.make(`line-${moment}-a`), request: { prompt: "The host looks up from the desk", seconds: 5 }, }, { key: Playout.ItemKey.make(`line-${moment}-b`), request: { prompt: "The host answers, smiling", seconds: 5 }, }, ], });});
export const acknowledge = Effect.fn("acknowledge")(function* ( playout: Playout.Playout["Service"], moment: number,) { const now = yield* Clock.currentTimeMillis; // A nod right after the line's first beat, and its second beat rewritten to follow it. const batch = yield* playout.edit([ { _tag: "InsertGroup", insert: { key: Playout.ItemKey.make(`nod-${now}`), after: Playout.ItemKey.make(`line-${moment}-a`), parts: [ { key: Playout.ItemKey.make(`nod-${now}-a`), request: { prompt: "The host nods at the caller", seconds: 5 }, }, ], }, }, { _tag: "Replace", key: Playout.ItemKey.make(`line-${moment}-b`), next: { key: Playout.ItemKey.make(`line-${moment}-b2`), request: { prompt: "The host answers the caller", seconds: 5 }, }, }, ]); yield* batch.committed;});An inserted group takes the anchor’s lane and a place right beside it, its first part the
anchor’s start as an insert does (after an At anchor without its lateness, and before one kept
by readyBy at the next boundary), and its window;
the rest follow it. It is refused with InvalidItem in a lane that is not strict, where what is
placed after it need not wait for it, and its anchor and side are part of it, as an insert’s are.
In a batch it follows the batch’s rules: a first part due by a firm startBy is not held, and it
may anchor on what the batch adds. Strict lanes, readyBy and inserted groups have run only on
the simulated Reactor and in the policy’s property checks, not on hosted H3.
Placement
Section titled “Placement”Some clips depend on the clips around them, such as an acknowledgement written for what just
aired. place projects where a clip would land if you submitted it submitIn from now, before
you write it. Submitted with follows: placement.after, the clip airs right after that clip,
across a renewal too, or is dropped as displaced.
import { Effect } from "effect";import { Playout } from "reactor-effect-client";
export const acknowledge = Effect.fn("acknowledge")(function* ( playout: Playout.Playout["Service"], write: (placement: Playout.Placement) => Effect.Effect<string>,) { const key = Playout.ItemKey.make("ack-1"); const placement = yield* playout.place({ key, seconds: 5, submitIn: "3 seconds", }); // Null: no boundary can be made yet. if (placement === null) return undefined; const request = { prompt: yield* write(placement), seconds: 5 }; const follows = placement.after; return placement.anchor === "next" ? yield* playout.submit({ key, lane: "show", request, start: { _tag: "Asap" }, follows, }) : yield* playout.insert({ key, after: placement.anchor, request, follows, });});A Placement names the clip it would follow (after), the clip projected after it (before),
when it would start (startsAt), how to submit it (anchor: insert after that item, or
"next", an Asap submission to the lowest lane) and what the projection rests on (basis:
ready, projected or unmeasured).
place projects the plan as it is, at the median build rates, and reserves nothing: each lane’s
items and filler at their own rate once three of their builds are measured, per second of the
length their model builds. before is not enforced, since a clip submitted after the call may
come between. A clip not built yet counts at the length the last clip that asked for as much aired
at, else at the length its model builds for it. A follows clip gets no filler cover, and a
cutting lane refuses it.
While a follower waits, autoplay is fenced before its build once a clip H3 reported starting plays
on that session, so an early end cannot air it before the clip it follows. A follower not Ready,
on a session still open, when that clip ends, fails on air or is lost on air with its session, is
dropped as displaced; a planned switch keeps it. While it waits, its session starts each clip
with a provider command, a round trip after the boundary that startsAt does not project, so a
command whose outcome is unknown can hold the air dark there until H3’s reply deadline. A follower
of an item in a pending batch may be built and then dropped before the batch commits. place
answers a boundary only with a clip projected Ready a readiness margin and one provider command
before it, and on a replacement only if it airs there before that session’s cap.
Forecast
Section titled “Forecast”An application that writes for a slot needs to know when what it queued will play: when a clip
starts, to bring a page on air just before it, and when everything queued will have played, to
pace what it writes next. forecast reads that from the plan’s own forward run, the one place
and firm admission use. Each clip it projects to air, from the one on air up to the last item it
places, comes with its start and end in epoch milliseconds (startsAt, endsAt), how far it is
from air (state: playing, ready, building or queued) and the session it airs on, the
one on air or its replacement. drops lists the items it projects to go without airing, why and
when, and drainsAt is when the last item it projects to air ends.
import { Clock, Effect } from "effect";import { Playout } from "reactor-effect-client";
export const lookAhead = Effect.fn("lookAhead")(function* ( playout: Playout.Playout["Service"], key: Playout.ItemKey,) { const forecast = yield* playout.forecast; const now = yield* Clock.currentTimeMillis; const item = Playout.forecastFor(forecast, key); return { // Null when it does not air in the forecast: `item` says why. startsIn: item._tag === "Airs" ? item.clip.startsAt - now : null, // Null when nothing queued airs. drainsIn: forecast.drainsAt === null ? null : forecast.drainsAt - now, item, };});forecastFor says where a forecast puts one item: it Airs, it Drops (late, displaced,
withdrawn or replaced, with when), it is Unplaced, or it is Absent, settled already or
never submitted. forecastGroup gives a group’s places that air, from the first one’s start to
the last one’s end, and the places it drops. It is undefined when none of the group’s places airs,
and the places it drops then appear only in drops.
A forecast does not project what the plan cannot know. unplaced lists each item it neither airs
nor drops, and why: a held Manual item (held), one whose enqueue’s outcome is unknown
(unknown), one waiting to cut a lower lane (cut), one waiting behind any of these as a member
of its group, as the clip it follows or as another add of its pending batch (blocked), and one
beyond what it projects: past the ten minutes it looks ahead or the looks its run takes, or with
no session on air yet (beyond). It projects one renewal at most, and basis is unmeasured
until three builds were measured, when every build counts as instant.
A forecast is a projection at the build rates the plan has measured, not a promise. It changes as
builds are measured and items arrive, and it ages between changes: a build that runs longer than
projected shows only once it ends. Between a renewal’s lead and the replacement opening, a forecast
puts new work on the replacement, but the plan keeps sending what fits to the session on air,
where such a clip may air a few hundred milliseconds early. A build projected Ready right at a
boundary’s readiness margin can flip which clip airs first there, and the forecast is then a whole
clip off. forecasts gives a forecast now and a new one each time the plan changes, and none while
it holds still; a slow reader skips to the newest.
Forecasts have run only on the simulated Reactor, not on hosted H3. There, with nothing submitted
after the forecast, items submitted as a filler clip started began within 0.1 s of their
startsAt, and a renewal’s items, submitted once the replacement had opened, within 0.15 s.
Renewal across sessions
Section titled “Renewal across sessions”A capped session builds only what can air before its cap. The replacement opens lead before the
cap, and never earlier, since a replacement opened earlier would bill while it waits to air. It
builds what cannot air on the retiring session in time, and holds it Ready with autoplay off.
Once the retiring session has nothing left to play and grace has passed since its last clip
ended, the replacement takes the air at that boundary, and the retiring session is closed.
A renewal. B opens lead before A’s cap and builds clip 3, which cannot air on A in time, holding it Ready with autoplay off. A airs what it has, here a filler clip. When that clip ends and grace has passed, B takes the air at the boundary and A is closed, so the two sessions bill together only from B’s start (its ready, by Reactor’s billing page) to A’s close.
renewal option |
Default | What it does |
|---|---|---|
lead |
30 seconds | Opens the replacement this long before the session’s cap |
grace |
250 ms | Waits this long after the retiring session’s last clip before switching |
openTimeout |
3 minutes | Bounds one open, the wait for a GPU included |
maxSetupFailures |
3 | Failed setups in a row that end the playout |
A session lost before a planned switch is closed, and the clips it never aired are rebuilt on
the next one (Replaced, with the number carried). A failed open is tried again a second later
for each failure in a row, at most maxSetupFailures seconds later, and never sooner than a
refusal’s Retry-After. After maxSetupFailures failures in a row the playout fails, unless a
session still holds the air: it then airs on and tries once more when that session ends. An open
refused with nothing allocated, such as a 4xx, billed nothing, and while a session holds the
air it does not count.
When content moderation ends a session, the playout blames the item whose enqueue was sent there
last, since the verdict names no clip, and fails it as Moderated. It stops after
maxModerations (2) moderated sessions rather than keep opening paid ones.
On hosted H3, the planned switch left a gap of 420 ms on air on 2026-09-28, and 432 ms on 2026-09-29. When moderation ended a session in the first of those runs, the clip it had Ready was rebuilt on a new session opened 3.17 s after the verdict, and aired 5.3 s after the lost session’s clip left the air.
As-run evidence
Section titled “As-run evidence”playout.asRun streams what became of each item, kept apart from what was asked for:
| Status | Meaning |
|---|---|
Accepted |
Admitted; with carried when it is rebuilt after its session was lost |
Building |
Sent to a session, building |
Ready |
Built, waiting to air |
Started |
Seen to start: at, sessionId, seconds, and lateByMillis for a late soft window |
Ended |
finished or stopped, with airedSeconds |
Dropped |
late, withdrawn, replaced or displaced |
Failed |
With a reason: Clip, Command, Lost, Moderated or Closed |
Unobserved |
Acknowledged, but its start was never seen |
Unknown |
Sent, but its acknowledgement was never seen; terminal once nothing can settle it |
An Unknown item is never sent again, and no time is invented for it. A Clip failure keeps the
provider’s own words Redacted in provider, out of messages, logs and spans.
import { Console, Stream } from "effect";import type { Playout } from "reactor-effect-client";
export const asRunLog = (playout: Playout.Playout["Service"]) => playout.asRun.pipe( Stream.map(({ key, status }) => status._tag === "Started" ? `${key} started on ${status.sessionId}` : `${key} ${status._tag}`, ), Stream.runForEach(Console.log), );playout.events adds cues, session events (Opened, Switched, Replaced, SetupFailed,
Moderated, Reconnecting and Reconnected), each filler clip’s start and end, a
ReaderOverflow when a reader of the picture or sound falls behind, and Starved when nothing is
left to play. playout.state holds the clip on air, the lanes, each session’s role (on-air,
replacement or retiring), the runway and the build estimates the playout has learned: over
every build, and each lane’s and filler’s apart (estimates.lanes, estimates.filler), which
it projects that lane’s items and filler with.
playout.video and playout.audio are the on-air picture and sound as decoded frames, continuing
across renewals.
On hosted H3, one playout aired 20 clips over three 75 s sessions, with filler holding the air: 2,372 frames at 22.2 fps, none lost, and seams of 53–169 ms with no dark frame. A second run, on the 0.8.0 release candidate, measured seams of 46–168 ms. Both passed every criterion (0.8.0-api, 2026-09-28; 0.8.0-rc, 2026-09-29).
Failure and cleanup
Section titled “Failure and cleanup”playout.failure completes with why the playout stopped: a session it could not open or keep,
InvalidFiller, Moderated, or Closed when its scope closed. A supervisor restarts it by
failing with that reason under a Schedule:
import { Effect, Schedule } from "effect";import { Playout } from "reactor-effect-client";
export const supervised = Effect.fn("supervised")( function* <R>(options: Playout.Options<R>) { const playout = yield* Playout.make(options); // Submit the programme here. Closing the scope closes the // playout and its sessions. return yield* Effect.flatMap(playout.failure, Effect.fail); }, Effect.scoped, Effect.retry(Schedule.exponential("5 seconds")),);playout.cleanup holds the close reports of retired sessions and of opens that failed after
allocating: every one that may still bill, and the latest others. Closing the playout’s scope
retires every session.
| Option | Default | What it does |
|---|---|---|
maxBuildsInFlight |
1 | Builds at once on the session that takes new work |
maxHistory |
4,096 | Settled keys kept for idempotency |
unknownTimeout |
60 seconds | How long an enqueue’s outcome may stay unknown before its session is replaced |
maxModerations |
2 | Sessions moderation may end before the playout fails |
An enqueue whose outcome stays unknown holds no build slot meanwhile, since H3 builds in order.
Limits
Section titled “Limits”- The hosted numbers on this page come from 2026-09-28 and 2026-09-29: the two
showruns of the 0.8.0 playout, each over three 75 s sessions, and one-sessioneditsandcutruns of 0.7.0 and of 0.8.0 in development. On 0.9.0 only the one-sessionshowreelcheck has run on hosted Reactor (five scenes, seams of 89–120 ms, 2026-10-01): itsplaceandfollows, its renewal and its changes to how the air ahead is counted have run only on the simulated Reactor. No multi-hour run on hosted H3 has been made. - A
Startedstatus is H3’s report that a clip started, not proof that a frame was presented or encoded. - On a host with only platform tracks, such as a browser,
playout.videoandplayout.audiofail withUnsupportedCapability. - Editorial priority, pricing and what counts as on air for your audience stay with your application.