Listen

import { VocalStack } from '@vocalstack/sdk';

const vs = new VocalStack({ baseUrl: 'https://api.vocalstack.com', apiKey: process.env.VOCALSTACK_API_KEY });
const recordingId = process.argv[2]!; // a grant's recording.id, or a transcription's currentRecording.recordingId

// The owner, with the key. A share link's reader: new VocalStack({ baseUrl })
// and { shareCode: 'CODE', asOwner: false }; a public broadcast's listener: { asOwner: false }.
const sub = await vs.recordings.subscribe(recordingId, { lang: 'es' });

// subscribe() resolves once subscribe.ready and the snapshot are in: what
// was said before you came, then only frames past its cursor, gaps healed.
for (const s of sub.snapshot?.sentences ?? []) console.log(s.text, s.translations?.es ?? '');

for await (const ev of sub) {
  if (ev.type !== 'frame') continue;
  const f = ev.frame;
  if (f.type === 'transcript.committed') console.log(f.segment.text);
  if (f.type === 'transcript.translated') console.log(`  es: ${f.translations.es}`);
  if (f.type === 'recording.state') {
    console.log(`[${f.state}]`);
    if (f.state === 'finalized') sub.close();
  }
}

import asyncio
import json
import os
import sys

from vocalstack import VocalStack


async def main() -> None:
    async with VocalStack("https://api.vocalstack.com", api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
        recording_id = sys.argv[1]  # a grant's recording.id, or a transcription's current_recording

        # The owner, with the key. A share link's reader: share_code="CODE", as_owner=False.
        socket = await vs.recordings.subscribe(recording_id, lang="es")
        ready = json.loads(await socket.recv())  # subscribe.ready {lastSeq, state}
        print("state:", ready["state"])

        snapshot = await vs.recordings.transcript(recording_id, lang="es")
        for s in snapshot.sentences:
            print(s.text, (s.translations or {}).get("es", ""))
        cursor = snapshot.last_seq

        async for message in socket:
            if isinstance(message, bytes):
                continue  # live audio, when asked for
            frame = json.loads(message)
            at = frame.get("cursor")
            if at is not None:
                if at <= cursor:
                    continue  # already in the snapshot
                if at > cursor + 1:  # a gap: read what was missed, then go on
                    missed = await vs.recordings.transcript(recording_id, lang="es", after=cursor)
                    for seg in missed.segments:
                        print(seg.text)
                    cursor = max(cursor, missed.last_seq)
                    if at <= cursor:
                        continue
                cursor = at
            if frame["type"] == "transcript.committed":
                print(frame["segment"]["text"], flush=True)
            elif frame["type"] == "transcript.translated":
                print("  es:", frame["translations"].get("es"))
            elif frame["type"] == "recording.state":
                print(f"[{frame['state']}]")
                if frame["state"] == "finalized":
                    await socket.close()


asyncio.run(main())

// No SDK, no key: a share link's reader (shareCode), with the built-in
// WebSocket (Node 22 or newer, or a browser).
const API = 'https://api.vocalstack.com';
const [recordingId, shareCode] = [process.argv[2]!, process.argv[3]!];
const q = new URLSearchParams({ shareCode, lang: 'es' });

const ws = new WebSocket(`${API.replace(/^http/, 'ws')}/v1/recordings/${recordingId}/subscribe?${q}`);
let cursor: number | null = null; // null until the snapshot is in
const early: any[] = []; // frames that arrive while it is read

ws.addEventListener('message', async (m: MessageEvent) => {
  if (typeof m.data !== 'string') return;
  const f = JSON.parse(m.data);
  if (f.type === 'subscribe.ready') {
    const r = await fetch(`${API}/v1/recordings/${recordingId}/transcript?${q}`);
    const snap = (await r.json()) as { lastSeq: number; sentences: { text: string }[] };
    for (const s of snap.sentences) console.log(s.text);
    cursor = snap.lastSeq;
    for (const e of early.splice(0)) apply(e);
    return;
  }
  if (cursor === null) early.push(f);
  else apply(f);
});

function apply(f: any): void {
  if (typeof f.cursor === 'number') {
    if (f.cursor <= cursor!) return; // already in the snapshot
    cursor = f.cursor; // (a jump: read /transcript?after=<cursor> again)
  }
  if (f.type === 'transcript.committed') console.log(f.segment.text);
  if (f.type === 'transcript.translated') console.log(`  es: ${f.translations.es}`);
  if (f.type === 'recording.state') console.log(`[${f.state}]`);
  if (f.type === 'recording.state' && f.state === 'finalized') ws.close();
}