Quickstart

const SAMPLE_RATE = 16000;
// The default limits: 2 seconds of audio per message, 8 seconds queued.
const MAX_MESSAGE_SAMPLES = 2 * SAMPLE_RATE;

function createSpeechRelayStream({
  url, token, onTranscript, onError, onComplete
}) {
  const speakers = new Map();
  let socket;
  let accepted = false;
  let finished = false;
  let disposed = false;
  let terminal = false;
  let resolveReady, rejectReady;
  const ready = new Promise((resolve, reject) => {
    resolveReady = resolve;
    rejectReady = reject;
  });
  const timer = setTimeout(() => {
    fail("Session acceptance timed out.");
  }, 15000);

  function dispose() {
    if (disposed) return;
    disposed = true;
    clearTimeout(timer);
    if (!accepted) rejectReady(new Error("Stream disposed before ready."));
    if (socket) {
      for (const [type, handler] of Object.entries(handlers)) {
        socket.removeEventListener(type, handler);
      }
      socket.close();
    }
  }

  function fail(message) {
    if (terminal || disposed) return;
    terminal = true;
    if (!accepted) rejectReady(new Error(message));
    dispose();
    onError(message);
  }

  function send(value) {
    try {
      socket.send(value);
      return true;
    } catch {
      fail("Could not send to the stream.");
      return false;
    }
  }

  function receive(event) {
    if (terminal || disposed) return;
    let message;
    try {
      message = JSON.parse(event.data);
      if (!message || typeof message !== "object") throw new Error();
    } catch {
      fail("Invalid stream message.");
      return;
    }
    if (message.type === "session.accepted" && !accepted) {
      if (!send(JSON.stringify({ type: "stream.start" }))) return;
      accepted = true;
      clearTimeout(timer);
      resolveReady();
    } else if (message.type === "error") {
      // Do not echo server messages or transport errors: they may contain input.
      fail("The server reported a stream error.");
    } else if (message.type === "session.completed") {
      if (!accepted || message.reason !== "end_of_stream") {
        fail("The session ended without normal completion.");
        return;
      }
      terminal = true;
      dispose();
      onComplete();
    } else if (accepted && (
      message.type === "transcript.partial" ||
      message.type === "transcript.final"
    )) {
      const state = speakers.get(message.speaker) ?? {
        committed: [], open: "", incomplete: false, finalText: null
      };
      speakers.set(message.speaker, state);
      if (message.type === "transcript.final") {
        state.finalText = message.text;
        state.open = "";
        state.incomplete = false;
      } else {
        if (state.incomplete || state.finalText !== null) return;
        if (state.committed.length !== message.stable_prefix_words) {
          state.incomplete = true;
        } else {
          state.committed.push(...message.appended);
          state.open = message.open_word;
        }
      }
      onTranscript({
        speaker: message.speaker,
        text: state.finalText ?? [...state.committed, state.open]
          .filter(Boolean).join(" "),
        final: state.finalText !== null,
        incomplete: state.incomplete
      });
    }
  }

  const handlers = {
    open() {
      if (terminal || disposed) return;
      send(JSON.stringify({
        type: "session.create", protocol_version: "1.0",
        mode: "mt_asr", expected_num_speakers: 2
      }));
    },
    message: receive,
    error() { fail("WebSocket connection failed."); },
    close() { fail("Stream closed before completion."); }
  };
  try {
    const protocols = ["dicon.v1"];
    if (token) protocols.push("bearer." + token);
    socket = new WebSocket(url, protocols);
    for (const [type, handler] of Object.entries(handlers)) {
      socket.addEventListener(type, handler);
    }
  } catch {
    fail("Could not open the WebSocket.");
  }

  return {
    ready,
    // Sends one message as given; the caller keeps to the audio's pace.
    sendAudio(chunk) {
      if (!accepted || finished || disposed) {
        throw new Error("Audio requires a ready, unfinished stream.");
      }
      if (!(chunk instanceof Int16Array)) {
        throw new TypeError("Audio must be an Int16Array.");
      }
      if (chunk.length > MAX_MESSAGE_SAMPLES) {
        throw new RangeError("One message holds at most 2 seconds of audio.");
      }
      if (chunk.length === 0) return;
      const bytes = new ArrayBuffer(chunk.length * 2);
      const view = new DataView(bytes);
      for (let i = 0; i < chunk.length; i++) {
        view.setInt16(i * 2, chunk[i], true);
      }
      send(bytes);
    },
    finish() {
      if (finished) return;
      if (!accepted || disposed) {
        throw new Error("Finish requires a ready stream.");
      }
      finished = true;
      send(JSON.stringify({ type: "stream.end" }));
    },
    dispose
  };
}

// url: your authorized WebSocket endpoint, including /v1/stream.
// Illustrative parameters: "wss://api.speechrelay.online/v1/stream",
// "YOUR_TOKEN". These do not grant access.
// pcmChunks: an array or async iterable of 16 kHz mono signed 16-bit PCM
// Int16Arrays of any length, from a live source or already recorded.
async function transcribePcm(url, token, pcmChunks) {
  // One second per message, never more than two seconds ahead of the
  // audio's own duration, so recorded audio stays inside both limits.
  const PIECE_SAMPLES = SAMPLE_RATE;
  const AHEAD_MS = 2000;
  const transcripts = new Map();
  let error = null;
  let ended = false;
  const completed = new Promise((resolve) => {
    function end() {
      ended = true;
      resolve();
    }
    const stream = createSpeechRelayStream({
      url, token,
      onTranscript(update) { transcripts.set(update.speaker, update); },
      onError(message) { error = message; end(); },
      onComplete() { end(); }
    });
    async function upload() {
      try {
        await stream.ready;
        let due = Date.now();
        for await (const chunk of pcmChunks) {
          if (!(chunk instanceof Int16Array)) {
            throw new TypeError("Audio must be an Int16Array.");
          }
          for (let i = 0; i < chunk.length; i += PIECE_SAMPLES) {
            const piece = chunk.subarray(i, i + PIECE_SAMPLES);
            const pieceMs = (piece.length * 1000) / SAMPLE_RATE;
            const now = Date.now();
            due = Math.max(due, now);
            const wait = Math.ceil(due + pieceMs - AHEAD_MS - now);
            if (wait > 0) await new Promise((r) => setTimeout(r, wait));
            stream.sendAudio(piece);
            due += pieceMs;
          }
        }
        stream.finish();
      } catch {
        // After the stream ends, sendAudio and finish throw; that is not an error.
        if (ended) return;
        error = "Could not finish sending PCM audio.";
        stream.dispose();
        end();
      }
    }
    void upload();
  });
  await completed;
  // Preserve received output even when the stream fails.
  return { transcripts, error };
}