RealtimeVoiceConversation

RealtimeVoiceConversation is the browser-side helper for Speko speech-to-speech (S2S) sessions. It connects directly to the S2S WebSocket returned by POST /v1/sessions, captures the microphone as PCM16, plays streamed PCM16 responses, and forwards transcript and status callbacks.

Use it when you want the lowest-latency S2S path and do not need the browser media transport used by VoiceConversation.

import { RealtimeVoiceConversation } from '@spekoai/client';

Mint the session on your server

Create S2S sessions on your backend so SPEKO_API_KEY never reaches the browser. Return only the short-lived WebSocket credentials.

app.post('/api/realtime-session', async (_req, res) => {
  const response = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 's2s',
      s2s: {
        provider: 'openai',
        model: 'gpt-realtime',
        voice: 'alloy',
        systemPrompt: 'You are a concise voice assistant.',
      },
      ttlSeconds: 900,
    }),
  });

  if (!response.ok) {
    res.status(response.status).json({ error: 'Could not start realtime session' });
    return;
  }

  const session = await response.json();
  res.json({
    sessionId: session.sessionId,
    wsUrl: session.wsUrl,
    wsToken: session.wsToken,
    expiresAt: session.expiresAt,
    inputSampleRate: session.inputSampleRate,
    outputSampleRate: session.outputSampleRate,
  });
});

Connect from the browser

import { useEffect, useRef, useState } from 'react';
import { RealtimeVoiceConversation } from '@spekoai/client';

export function RealtimePanel() {
  const convRef = useRef<RealtimeVoiceConversation | null>(null);
  const [status, setStatus] = useState('idle');
  const [transcript, setTranscript] = useState<string[]>([]);

  async function start() {
    setStatus('connecting');
    const session = await fetch('/api/realtime-session', {
      method: 'POST',
    }).then((r) => r.json());

    const conv = await RealtimeVoiceConversation.create({
      ...session,
      onConnect: ({ conversationId }) => {
        console.log('connected', conversationId);
      },
      onStatusChange: setStatus,
      onMessage: ({ source, text, isFinal }) => {
        if (isFinal) setTranscript((items) => [...items, `${source}: ${text}`]);
      },
      onError: (err) => console.error(err),
      onDisconnect: () => setStatus('idle'),
    });

    convRef.current = conv;
  }

  async function stop() {
    await convRef.current?.endSession();
    convRef.current = null;
  }

  useEffect(() => () => { void convRef.current?.endSession(); }, []);

  return (
    <div>
      <button onClick={start} disabled={status !== 'idle'}>Start</button>
      <button onClick={stop} disabled={status === 'idle'}>Stop</button>
      <p>Status: {status}</p>
      <ul>{transcript.map((item, i) => <li key={i}>{item}</li>)}</ul>
    </div>
  );
}