Sources
A playout gets its sessions from an open effect, which it calls for the first session and for
each replacement. H3Source.open opens a paid H3 session, and LocalSource.open renders clips
in your own process. Both return a Playout.Source, so the same programme runs on either. A paid
session opens through a Ledger, which records it before it connects:
import { Effect } from "effect";import { CoordinatorClient, H3, H3Source, Ledger, Playout,} from "reactor-effect-client";
export const recordedChannel = Effect.gen(function* () { const coordinator = yield* CoordinatorClient.CoordinatorClient; const ledger = yield* Ledger.Ledger; return yield* Playout.make({ open: ledger.source( H3Source.opener({ tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "1 hour", }), canvas: "16:9", }), ), lanes: [{ name: "show" }], });});H3Source.open
Section titled “H3Source.open”- Mints the creating token from
tokens.create. - Allocates the session, then runs
onAllocatedwith the session, the grant and the owner record, before the session connects. - Connects and sets H3 up: autoplay off until the playout turns it on, the last frame held between clips, and the canvas set before the first enqueue.
- Returns a
Sourcewhoselifetimeis what remains of the token’s cap, counted from the allocation request, so the playout never plans past the session’s end.
| Option | Default | What it does |
|---|---|---|
tokens |
required | The session’s Tokens; the API key never reaches the opener |
onAllocated |
none | Records the owner after allocation and before connecting |
canvas |
as H3 has it | 16:9, 1:1, 9:16 or 4:3, set before the first enqueue |
holdLastFrame |
true |
Holds the last frame between clips; false flushes to black |
recovery |
20 seconds | How long a dropped connection may take to come back |
provider |
defaults | The H3 provider’s options |
create |
none | Other reactor.create options, such as resumeTracks |
H3Source.opener takes the same options but onAllocated, which the ledger supplies, and
resumes a recorded session with them. An uncapped session has no end the playout can plan for: it
is replaced only when it is lost. If onAllocated fails, the session is closed and open fails
with an AcquisitionFailure carrying its close report, as any failure after allocation does.
The session reconnects a dropped connection itself. The source reports Reconnecting, then
Reconnected with how long it took, and gives the session recovery to be ready again and H3 to
be read afresh. Past that, or at once for a session that will not come back (reconnect turned
off, ended by moderation, or no longer trying), the source counts the session lost and the
playout replaces it. The playout sends the session nothing meanwhile.
Owner records
Section titled “Owner records”A paid session must be on record before it connects, so whoever comes after a crash can find it.
A Ledger keeps those records in a Ledger.Store the application provides, and
ledger.source(H3Source.opener({ tokens })), or FastH3Source.opener for FastH3, is a playout’s
open. Before it allocates, source settles every session recorded for its coordinator that the
ledger does not hold: it resumes the one that ends last, while a minute of its cap remains, and
ends the others, waiting until Reactor confirms each end. Then it opens a fresh session and
records it before it connects. Closing the source ends the session and forgets it once Reactor
confirms the end; an end Reactor does not confirm is marked ending and asked again until it is.
import { Layer } from "effect";import { CoordinatorClient, Ledger } from "reactor-effect-client";
// Only the API key, here from REACTOR_API_KEY, ends a session whose owner died.export const LedgerLive = Ledger.layerFile("evidence/ledger.json").pipe( Layer.provideMerge(CoordinatorClient.layerConfig),);Ledger.layerMemory() keeps the entries in memory, for tests, and Ledger.layer() takes a store
of your own, such as a database. One store belongs to one process and one Reactor account: two
processes on one store would end each other’s sessions as leftovers. ledger.release ends every
recorded session the ledger does not hold, as a process does when it shuts its channel down.
An application that records its sessions itself passes onAllocated, which receives an
H3Source.Allocation: the owner record of the session, without a token. It is a Schema, so it
encodes to JSON and decodes back.
| Field | What it is |
|---|---|
sessionId |
The session’s id |
ownership |
owned or attached |
model |
The model, H3.modelName |
endsAt |
When the session’s cap ends, in seconds since the epoch, counted from the allocation request; absent for an uncapped session |
The cap starts no earlier than the request, so the cap cannot end the session before endsAt.
With the record, a process that takes over can find the session again, adopt it with a token
bound to it, or end it with the API key, asking until Reactor confirms the end:
import { CoordinatorClient } from "reactor-effect-client";import type { H3Source } from "reactor-effect-client";
export const endOrphan = (allocation: H3Source.Allocation) => CoordinatorClient.terminateUntilConfirmed(allocation.sessionId);H3Source.resume
Section titled “H3Source.resume”H3Source.resume({ allocation, tokens }) adopts a session open allocated, after its owner
died. This process then owns its remote lifetime. The session keeps its canvas, queue and
playback, and a session its owner already set up gets only reads. Its lifetime is what remains
until the record’s endsAt.
import { Effect, Schema } from "effect";import { CoordinatorClient, H3, H3Source } from "reactor-effect-client";
const decodeOwner = Schema.decodeEffect( Schema.fromJsonString(H3Source.Allocation),);
export const takeOver = Effect.fn("takeOver")(function* ( record: string,) { const coordinator = yield* CoordinatorClient.CoordinatorClient; const allocation = yield* decodeOwner(record); return yield* H3Source.resume({ allocation, // Reactor takes no other token for a session this process did not create. tokens: { bind: (id) => coordinator.mintToken({ modelName: H3.modelName, bind: [id] }), }, });});resume refuses, as InvalidInput, a record of another model or one whose endsAt has passed.
A resume that fails ends the session it adopted.
On hosted Reactor, an owner was killed 12.7 s into the run. H3Source.resume started 0.57 s
after the creating token had expired, was ready 2.71 s later on the owner’s playing clip, and
enqueued a clip with an image and an audio reference on a refreshed 12 s bound token
(0.8.0-api adoption,
2026-09-28).
LocalSource
Section titled “LocalSource”LocalSource.open renders clips in this process instead of on Reactor, with H3’s autoplay
semantics: one build slot and a playout queue. Use it for material you render yourself, such as
speech or stills, and for demos. It costs nothing, and closing it ends no paid session.
import { Effect } from "effect";import { LocalSource, Playout } from "reactor-effect-client";
/** Your speech engine: 48 kHz mono PCM for a line of text. */declare const synthesize: ( text: string,) => Effect.Effect<Int16Array<ArrayBuffer>>;
const block = 480; // 10 ms at 48 kHz
export const announcer = Playout.make({ open: LocalSource.open({ // Renders a clip before it is Ready, and says how long it really is. build: (clip) => Effect.map(synthesize(clip.request.prompt), (pcm) => ({ value: pcm, seconds: pcm.length / 48_000, })), // Plays it into the source's audio, in real time. The clip ends // when this completes. present: (_clip, pcm, sink) => Effect.forEach( Array.from( { length: Math.ceil(pcm.length / block) }, (_, index) => index, ), (index) => sink .audio({ _tag: "AudioFrame", track: "main_audio", sampleRate: 48_000, channels: 1, sequence: BigInt(index), samples: pcm.slice(index * block, (index + 1) * block), }) .pipe(Effect.andThen(Effect.sleep("10 millis"))), { discard: true }, ), }), lanes: [{ name: "line" }],});| Option | What it does |
|---|---|
model |
The model the source runs, H3’s by default; pass the same model to Playout.make |
build |
Makes a clip’s value, and its built length when that differs from what its model builds (seconds) |
present |
Plays the value through the sink’s video and audio; without it, a clip plays for its length |
lifetime |
Caps the session, as a paid session’s cap does, so the playout renews it; unending by default |
buildRatio |
Without hooks: a stand-in whose clips build for this share of their requested length and play for the length their model builds |
build and present run in a scope the clip owns, which closes once the clip leaves the source,
so a finalizer releases what they made. A hook that fails with your own error fails that clip
alone: Failed with reason Clip, your error pretty-printed and Redacted in provider. A hook
that dies stops the source, and the playout replaces its session. The playout checks every
request against its model, H3’s by default. A renderer with its own lengths passes the same
ClipModel to LocalSource.open and Playout.make, so speech can air below H3’s 5 s minimum.
Its builtSeconds is the length the model builds for a requested length, which the playout plans
a clip not built yet at; speech builds what it is asked:
import { Effect } from "effect";import { H3, LocalSource, Playout } from "reactor-effect-client";const speech: Playout.ClipModel<H3.Request> = { name: "speech", lengths: { min: 0.5, max: 30 }, defaultSeconds: 2, builtSeconds: (seconds) => seconds, check: () => [],};export const spoken = Playout.make({ model: speech, open: LocalSource.open({ model: speech, build: (clip) => Effect.succeed({ value: clip.request.prompt }) }), lanes: [{ name: "speech" }],});Writing a source
Section titled “Writing a source”Playout.Source is an interface: a sessionId, a lifetime, events, the commands enqueue,
remove, move, setAutoplay, stop and play, the video and audio streams, and close.
Its optional model names the model it runs. The playout refuses a different model name at
open, before sending commands; a source without model is not checked.
Its doc comment lists what the playout relies on, such as events starting with a State and
reporting a clip’s start or end before the State that shows it. Write one only for a model or
renderer the SDK does not cover.
Limits
Section titled “Limits”H3Sourcedrives H3 Reference Turbo Realtime only;resumerefuses a record of another model.- A
LocalSourcerenders in your process: its builds and presentations use your CPU, and one slow build holds its one build slot. - H3’s 5 to 15.084 s request bounds apply by default. A local renderer with another range declares its own model and passes it to both the source and the playout.