Stream a microphone

// Node: ffmpeg captures the microphone, the SDK streams it.
import { spawn } from 'node:child_process';
import { RealtimeSession, VocalStack } from '@vocalstack/sdk';

const vs = new VocalStack({ baseUrl: 'https://api.vocalstack.com', apiKey: process.env.VOCALSTACK_API_KEY });

const { sessionId, streamUrl } = await vs.realtime.createSession({ spokenLanguage: 'en', translate: ['es'] });

const session = await RealtimeSession.connect({
  sessionId,
  streamUrl,
  onLoading: (stage) => console.error(`warming up (${stage})…`),
});

// Raw PCM: f32le, 16 kHz, mono. macOS: -f avfoundation -i :0, Linux: -f pulse -i default.
const mic = spawn('ffmpeg', ['-loglevel', 'error', '-f', 'avfoundation', '-i', ':0', '-f', 'f32le', '-ac', '1', '-ar', '16000', '-']);
mic.stdout.on('data', (chunk: Buffer) => session.sendAudio(new Uint8Array(chunk)));

mic.on('close', () => session.eof()); // the server flushes, then sends session.done
process.once('SIGINT', () => mic.kill()); // Ctrl-C ends the audio

for await (const ev of session) {
  if (ev.type === 'transcript.draft') {
    // The live tail: replace it, never append it.
    process.stdout.write(`\r\x1b[K\x1b[2m${ev.segments.map((s) => s.text).join(' ')}\x1b[0m`);
  } else if (ev.type === 'transcript.committed') {
    // Final: append it (seq 0, 1, 2…), and the tail it covers is gone.
    process.stdout.write(`\r\x1b[K${ev.segment.text}\n`);
  } else if (ev.type === 'transcript.translated') {
    console.log(`  es: ${ev.translations.es}`);
  }
}

console.log(`done (${session.doneReason})`, session.stats);

// In a web page: your server creates the session (the API key stays
// there), and the page streams the microphone to its streamUrl.
import { RealtimeSession, VocalStack } from '@vocalstack/sdk';
import { streamMicrophone } from '@vocalstack/sdk/mic';

// On your server, behind a route of yours (POST /api/transcribe, say):
const vs = new VocalStack({ baseUrl: 'https://api.vocalstack.com', apiKey: process.env.VOCALSTACK_API_KEY });
export async function createStream(): Promise<{ sessionId: string; streamUrl: string }> {
  const { sessionId, streamUrl } = await vs.realtime.createSession({ spokenLanguage: 'en' });
  return { sessionId, streamUrl };
}

// In the page, with what your route returned:
export async function transcribeMicrophone(
  stream: { sessionId: string; streamUrl: string },
  render: (committed: string, tail: string) => void,
): Promise<void> {
  const session = await RealtimeSession.connect(stream);
  const mic = await streamMicrophone(session); // asks for the microphone, sends 16 kHz PCM
  document.querySelector('#stop')?.addEventListener('click', () => {
    void mic.stop();
    session.eof();
  });
  let committed = '';
  for await (const ev of session) {
    if (ev.type === 'transcript.draft') render(committed, ev.segments.map((s) => s.text).join(' '));
    if (ev.type === 'transcript.committed') {
      committed += `${ev.segment.text} `;
      render(committed, '');
    }
  }
}

import asyncio
import os
import signal

from vocalstack import RealtimeSession, VocalStack

# Raw PCM: f32le, 16 kHz, mono. macOS: -f avfoundation -i :0, Linux: -f pulse -i default.
MIC = ["ffmpeg", "-loglevel", "error", "-f", "avfoundation", "-i", ":0",
       "-f", "f32le", "-ac", "1", "-ar", "16000", "-"]


async def main() -> None:
    async with VocalStack("https://api.vocalstack.com", api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
        created = await vs.realtime.create_session(spoken_language="en", translate=["es"])

        session = await RealtimeSession.connect(created.session_id, created.stream_url)

        mic = await asyncio.create_subprocess_exec(*MIC, stdout=asyncio.subprocess.PIPE)

        async def feed() -> None:
            assert mic.stdout is not None
            while chunk := await mic.stdout.read(8000):  # 125 ms of audio
                await session.send_audio(chunk)
            await session.eof()  # the server flushes, then sends session.done

        feeder = asyncio.create_task(feed())
        asyncio.get_running_loop().add_signal_handler(signal.SIGINT, mic.terminate)  # Ctrl-C ends the audio

        async with session:
            async for event in session:
                if event.type == "transcript.draft":
                    # The live tail: replace it, never append it.
                    tail = " ".join(s.text for s in event.segments)
                    print(f"\r\x1b[K\x1b[2m{tail}\x1b[0m", end="", flush=True)
                elif event.type == "transcript.committed":
                    # Final: append it (seq 0, 1, 2...), and the tail it covers is gone.
                    print(f"\r\x1b[K{event.segment.text}", flush=True)
                elif event.type == "transcript.translated":
                    print(f"  es: {event.translations.get('es')}")
            await feeder
            print(f"done ({session.done_reason})", session.stats)


asyncio.run(main())

// No SDK: fetch for the session, the built-in WebSocket for the stream
// (Node 22 or newer, or a browser once your server has created the session).
import { spawn } from 'node:child_process';

const API = 'https://api.vocalstack.com';

const res = await fetch(`${API}/v1/realtime/sessions`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.VOCALSTACK_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ spokenLanguage: 'en', translate: ['es'] }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); // the error envelope: { code, message, … }
const { streamUrl } = (await res.json()) as { sessionId: string; streamUrl: string; expiresAt: string };

const ws = new WebSocket(streamUrl); // the token is in the URL: no header
ws.binaryType = 'arraybuffer';

ws.addEventListener('message', (m: MessageEvent) => {
  if (typeof m.data !== 'string') return;
  const f = JSON.parse(m.data);
  switch (f.type) {
    case 'session.loading':
      console.error(`warming up (${f.stage})…`);
      break;
    case 'session.ready':
      startMicrophone(); // send audio only after session.ready
      break;
    case 'transcript.draft': // the live tail: replace it
      process.stdout.write(`\r\x1b[K\x1b[2m${f.segments.map((s: { text: string }) => s.text).join(' ')}\x1b[0m`);
      break;
    case 'transcript.committed': // final: append it
      process.stdout.write(`\r\x1b[K${f.segment.text}\n`);
      break;
    case 'transcript.translated':
      console.log(`  es: ${f.translations.es}`);
      break;
    case 'session.done':
      console.log(`done (${f.reason})`, f.stats);
      break;
    case 'error':
      console.error(f.code, f.message);
      break;
  }
});

function startMicrophone(): void {
  // Raw PCM: f32le, 16 kHz, mono, as binary frames.
  const mic = spawn('ffmpeg', ['-loglevel', 'error', '-f', 'avfoundation', '-i', ':0', '-f', 'f32le', '-ac', '1', '-ar', '16000', '-']);
  mic.stdout.on('data', (chunk: Buffer) => ws.send(new Uint8Array(chunk)));
  mic.on('close', () => ws.send(JSON.stringify({ type: 'eof' })));
  process.once('SIGINT', () => mic.kill());
}