Reference

WebSocket events

Every socket and every frame, with its fields and an example.

accountEvents /v1/events

The owner's dashboard: `events.ready` once the socket is listening, then `lists.changed` whenever a list of transcriptions or broadcasts of any principal the caller may act for is out of date — a recording changed state, a transcription settled, a title was written, or the owner changed something from another device. It says that, not what: re-read `GET /v1/transcriptions` and `GET /v1/broadcasts`. It replaces polling those lists. A user may hold a few of these at once (5 by default): opening one more closes their oldest with code 4001. One is closed with code 4002 after a day. After either, do not reconnect at once — a client that does takes its place straight back; reconnect when the user next uses that screen.

  • events.ready
  • lists.changed

broadcastEvents /v1/broadcasts/{id}/events

What a screen waiting on a broadcast needs: when a recording starts in it (`recording.started`: it is live), when that recording ends (`recording.ended`), a file job's progress (`job.progress`), and a pulled stream's state (`stream.ingest`). Each frame's `transcriptionId` is the transcription the recording is made in: on a broadcast's socket, the live transcription feeding it.

  • recording.started
  • recording.ended
  • job.progress
  • stream.ingest

realtimeSession /v1/realtime/sessions/{token}/socket

Connect to the `streamUrl` a realtime session returned (treat it as opaque).

  • session.loading A heartbeat while the machine gets ready (`stage`: `download`, then
  • session.ready The realtime session is ready: send audio from now on.
  • transcript.committed One final segment, with word timings, numbered by `seq` (0, 1, 2…,
  • transcript.draft The live tail: the words heard since the last commit, still
  • transcript.words Word timings for the live tail as they firm up (`events.words`);
  • transcript.amended An already-delivered committed segment was rewritten by the engine
  • transcript.latency A delivered segment's latency, measured again now that the engine's
  • transcript.speaker A tentative speaker label on a delivered segment was settled:
  • transcript.speakerGender A speaker's gender, as the pitch band heard it, once it settles
  • transcript.speakerIdentified A diarized speaker turned out to be somebody the caller has a
  • transcript.sentence Full-replacement upsert of one sentence, keyed by `sentenceId`.
  • transcript.translated
  • transcript.voice A spoken rendering of one definitive sentence (`SessionOptions::voice`).
  • transcript.voiceStatus Why a listener who picked a voice is not hearing it yet — or will
  • transcript.progress
  • stream.pull `input.kind = "stream"`: how the engine's pull of the stream is
  • source.progress `input.prepare`: the source on its way in. `phase` "fetching"
  • source.prepared `input.prepare`: the source is stored and ready to transcribe.
  • session.done
  • error

subscribe /v1/recordings/{id}/subscribe

Follow a recording: first frame `subscribe.ready {lastSeq}`, then `GET /v1/recordings/{id}/transcript` and discard buffered frames with `seq <= lastSeq`. `voice` picks which voice speaks the language for this listener; two listeners on the same (lang, voice) share one synthesis, so changing voice means reopening the socket. Send `{"type":"subscribe.update","lang":"ja"}` to switch language, `{"type":"subscribe.update","audio":true}` to receive live Opus.

  • session.loading A heartbeat while the machine gets ready (`stage`: `download`, then
  • session.ready The realtime session is ready: send audio from now on.
  • transcript.committed One final segment, with word timings, numbered by `seq` (0, 1, 2…,
  • transcript.draft The live tail: the words heard since the last commit, still
  • transcript.words Word timings for the live tail as they firm up (`events.words`);
  • transcript.amended An already-delivered committed segment was rewritten by the engine
  • transcript.latency A delivered segment's latency, measured again now that the engine's
  • transcript.speaker A tentative speaker label on a delivered segment was settled:
  • transcript.speakerGender A speaker's gender, as the pitch band heard it, once it settles
  • transcript.speakerIdentified A diarized speaker turned out to be somebody the caller has a
  • transcript.sentence Full-replacement upsert of one sentence, keyed by `sentenceId`.
  • transcript.translated
  • transcript.voice A spoken rendering of one definitive sentence (`SessionOptions::voice`).
  • transcript.voiceStatus Why a listener who picked a voice is not hearing it yet — or will
  • transcript.progress
  • stream.pull `input.kind = "stream"`: how the engine's pull of the stream is
  • source.progress `input.prepare`: the source on its way in. `phase` "fetching"
  • source.prepared `input.prepare`: the source is stored and ready to transcribe.
  • session.done
  • error
  • subscribe.ready First frame after the upgrade: where the live sequence stands, so
  • recording.state Recording state changed (LIVE ⇄ PAUSED → ENDED → FINALIZED).
  • recording.settings Capture settings changed mid-recording (mode, language, labels).
  • recording.silence The silence watchdog will pause the recording soon.
  • recording.expiring The max-duration cutoff is near.
  • transcript.corrected A human correction was applied — distinct from an engine amend.
  • transcript.speakerGender A speaker's gender, once the pitch band settles on it
  • transcript.speakerIdentified A speaker and the saved voice they turn out to be.
  • transcript.speakerNamed A per-recording speaker label.
  • recording.started Broadcast or transcription topic: a recording started in it (it is
  • job.progress A file / URL transcription job moved (both topics: the recording's
  • stream.ingest A stream source's server-side publisher moved (both topics): what
  • recording.ended Broadcast or transcription topic: the recording that was live in it
  • audience Admin subscribers: the audience aggregate, every few seconds.
  • subscribe.gap The frame sequence jumped; the client should re-snapshot from its cursor.

transcriptionEvents /v1/transcriptions/{id}/events

What a screen waiting on a transcription needs: when a recording starts in it (`recording.started`: it is live), when that recording ends (`recording.ended`), a file job's progress (`job.progress`), and a pulled stream's state (`stream.ingest`). Each frame's `transcriptionId` is the transcription the recording is made in.

  • recording.started
  • recording.ended
  • job.progress
  • stream.ingest