Skip to content

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" }],
});
});
  1. Mints the creating token from tokens.create.
  2. Allocates the session, then runs onAllocated with the session, the grant and the owner record, before the session connects.
  3. 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.
  4. Returns a Source whose lifetime is 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.

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({ 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.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" }],
});

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.

  • H3Source drives H3 Reference Turbo Realtime only; resume refuses a record of another model.
  • A LocalSource renders 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.