LTX tutorial

​

Installation and setup

• Node.js 18.18+ (the example runs Next.js 15 and React 19).
• pnpm (npm or yarn work but regenerate the lockfile).
• A Reactor API key (starts with rk_).
• Familiarity with the Next.js App Router.

git clone https://github.com/reactor-team/js-sdk
cd js-sdk/examples/ltx2

cp .env.example .env.local
# then edit .env.local and set REACTOR_API_KEY to your API key

pnpm install
pnpm dev

​

How LTX works

​

What you can change once a take is running

• Commands are asynchronous; messages are the source of truth. A command method resolves when the command is on the wire, not when the model has acted on it. The model confirms with its own event (script_accepted, avatar_image_accepted, …) and a fresh state_update.
• Errors arrive out-of-band. A broken precondition surfaces later as a command_error message, not as a thrown exception.

​

Authentication and the provider

import { Ltx2Provider } from "@reactor-models/ltx2";
import { REACTOR_API_URL } from "@/app/lib/config";

// The coordinator URL rides along as a query parameter purely as a cache key:
// tokens are signed per-coordinator, so moving this app between environments
// must not let the browser replay a JWT cached for the previous one.
async function fetchToken(): Promise<string> {
  const r = await fetch(`/api/reactor/token?coordinator=${encodeURIComponent(REACTOR_API_URL)}`);
  if (!r.ok) throw new Error(`Token fetch failed: ${r.status}`);
  const { jwt } = (await r.json()) as { jwt: string };
  return jwt;
}

export function Ltx2App() {
  return (
    <Ltx2Provider
      apiUrl={REACTOR_API_URL}
      getJwt={fetchToken}
      connectOptions={{ autoConnect: false }}
    >
      <Workspace />
    </Ltx2Provider>
  );
}

​

The stage: one element, both tracks

const { tracks } = useLtx2();
const videoTrack = tracks["main_video"] ?? null;
const audioTrack = tracks["main_audio"] ?? null;

const mediaStream = useMemo(() => {
  const list: MediaStreamTrack[] = [];
  if (videoTrack) list.push(videoTrack);
  if (audioTrack) list.push(audioTrack);
  return list.length ? new MediaStream(list) : null;
}, [videoTrack, audioTrack]);

useEffect(() => {
  const el = videoRef.current;
  if (!el) return;
  el.srcObject = mediaStream;
  if (!mediaStream) return;
  el.play().catch(() => {
    // Autoplay with audio needs a user gesture. The model's voice matters
    // here, so we ask for the gesture rather than falling back to muted.
    setNeedsAudioUnlock(true);
  });
}, [mediaStream]);

​

Setting up a take

​

Crop before upload

​

Wait for the image before you start

​

Everything else commits straight to the wire

const { setScript, setPrompt, setWpm, setDurationSeconds, setSeed } = useLtx2();

switch (edit.field) {
  case "script":
    return setScript({ script: edit.value }); // up to 10,000 characters
  case "prompt":
    return setPrompt({ prompt: edit.value }); // up to 800 characters
  case "wpm":
    return setWpm({ wpm: edit.value }); // default 140
  case "duration_seconds":
    return setDurationSeconds({ duration_seconds: edit.value }); // 0 = derive from the script
  case "seed":
    return setSeed({ seed: edit.value });
}

• The pace slider reads its bounds off the snapshot (wpm_min / wpm_max); the range is deployment-configured. It commits on release rather than on every drag step, which would put one command per pixel on the wire.
• Free text commits after a 600 ms idle, not on blur alone. Blur alone deadlocks the script field: a disabled Start button swallows the mousedown that would have blurred the textarea, so the script never commits and ready never turns true.
• An emptied field is an abandoned edit, not a value. A blank script is the one thing set_script refuses, and 0 is a meaningful duration_seconds (“derive the length from the script”). The panel keeps a per-field dirty set so a snapshot cannot clobber half-typed input, and every edit ends by committing or reverting.

​

Presets are macros

set_avatar_image → set_script → set_prompt → set_wpm → set_seed
                 → set_duration_seconds → start

Locked-off tripod shot, fixed framing from the first frame to the last. (the scene and voice description) The camera never moves, never pans, never zooms, and never pushes in; the framing at the end of the video is identical to the framing at the start.

​

Driving UI from the snapshot

const [ui, setUi] = useState<Ltx2UiState>(DEFAULT_UI_STATE);

// The snapshot is the only thing that mutates UI state.
useLtx2StateUpdate((msg) => setUi((prev) => reduce(prev, msg)));

• valid_commands is the authoritative list of what the session would accept right now. validCommands() (app/lib/machine.ts) is the single place every component asks; it adds the one thing the snapshot cannot know, whether there is a session at all. Buttons the model would refuse go dead on their own.
• queued_changes names the fields edited during the take in flight; the panel renders a queued chip next to each. The values are already in the snapshot; the field only says “you will hear this on the next take”.
• ready reports “an avatar image and a script are both set” as one flag. Since that is two conditions in one bit, startBlockedReason() tells the user which one a dead Start button is waiting on (the pre-filled scene prompt makes it easy to think the script is already written).

1. Only state_update mutates the reducer. The confirmation events are notifications; every one is followed by a snapshot carrying the same information. Reconstructing state from those events is a second, racier path to the same place.
2. Clear session state on disconnect. The SDK emits no final state_update, so without a reset on status === "disconnected", a reconnect renders the previous session’s conditions. The same effect drops any pending image waiter and the stage flag.

​

Transport

const valid = validCommands(status, ui);

<Button disabled={!valid.has("start") || held} onClick={() => fire("start")}>Start take</Button>
<Button disabled={!valid.has("pause")} onClick={() => fire("pause")}>Pause</Button>
<Button disabled={!valid.has("resume")} onClick={() => fire("resume")}>Resume</Button>
<Button disabled={!valid.has("stop")} onClick={() => fire("stop")}>Stop</Button>
<Button disabled={!valid.has("reset")} onClick={() => fire("reset")}>Reset</Button>

​

Chaining takes into a continuous performance

• Drive the loop off the snapshot, never off your own sends. A take has ended when generating flips false in state_update. When it does and a chunk is waiting, send set_script and start.
• Settle before starting. start is refused while a take is in flight. To cut a running take short, send stop, then poll the snapshot until generating reads false on a bounded wait (the demo gives it 4 seconds).
• Guard every start with a grace timer. A take that never begins streaming must not wedge the loop. The demo waits 25 seconds, then abandons that chunk and chains the next.
• Know how much speech is left. For the running take that is effective_seconds - seconds_sent; before the model reports effective_seconds, estimate from the script (words / wpm * 60).
• Refill early, write small. The demo asks its writer for the next chunk when less than about 12 seconds of speech is ahead, and keeps chunks to two or three sentences that end where a sentence ends. A take boundary is a hard cut, and a cut inside a clause is heard.
• Pin the conditions once. The portrait, prompt, pace and seed are set before the first take and never re-sent, which is what keeps one face and one voice across every cut. Re-sending set_prompt re-casts the voice.
• Skip the unchanged sends. Re-sending an unchanged value is harmless, but every send is a round-trip plus a snapshot echo, and the noise buries the command that mattered.

​

Surfacing errors

useLtx2CommandError((msg) =>
  setNotice({ kind: "error", text: `${msg.command} refused: ${msg.reason}` }),
);
useLtx2GenerationFailed((msg) =>
  setNotice({ kind: "error", text: `Generation failed: ${msg.reason}` }),
);

​

Saving a take

​

Going further

• Waiting for the avatar image (app/Ltx2App.tsx). Register the waiter before sending the command, or a fast confirmation lands before the listener exists. has_avatar_image is a sound fallback for the first image only: it is a level, not an edge, so on later uploads a snapshot already in flight satisfies it before the model has decoded anything. The waiters carry no correlation ids, so the Upload control is disabled while one is outstanding.
• Measuring time to first frame (app/Ltx2App.tsx). Start the clock when start goes on the wire; stop it at the first newly-composited frame, observed with requestVideoFrameCallback on the <video> element, so the number is measured at the display. Arm it on generation_started: the track keeps compositing frames between takes, so the next frame after start reads a few milliseconds instead of a few seconds. Expect a few seconds warm, more on a cold pod: a measurement, not a spec.
• Noticing a stalled stream (app/components/Stage.tsx). The snapshot and the frames travel on different transports and fail on their own: a take can die mid-sentence while state_update keeps reporting generating: true, and no message announces it. The only client-side signal is requestVideoFrameCallback going quiet. Watch it while the snapshot says frames should be flowing (generating, not paused, and seconds_sent > 0, so warm-up never counts), and recover with the transport the user already has: stop then start keeps every condition.

​

What’s intentionally left out