Soniox STT (Async)

Transcribe an audio file for me with OpenTranscription, using the model soniox/stt-async.

Set it up first:
  npm install -g @opentranscription/cli
  ot login
  npx skills add opentranscription/skills

Then run:
  ot transcribe <my-file> --model soniox/stt-async

Ask me one question at a time, and give me options to pick from rather than open questions. Look for audio files here before asking which one I mean. Leave the language alone unless I tell you what it is, since the model detects it.

This model can also label speakers with --diarize. Offer that one at a time, and only if I have not already said.

The login step opens my browser and waits for me to approve it, so stop and tell me when you reach it. The skill covers the rest.

// npm install @opentranscription/sdk
import { readFile } from 'node:fs/promises';
import { OpenTranscription } from '@opentranscription/sdk';

const ot = new OpenTranscription({ apiKey: process.env.OT_API_KEY! });

// Uploads the audio and opens the job. The signed-URL round trip is inside.
const job = await ot.transcribe({
  file: await readFile('interview.mp3'),
  fileName: 'interview.mp3',
  model: 'soniox/stt-async',
  language: 'en',
  diarization: true,
  webhookUrl: 'https://your-app.com/webhooks/ot',
});

// We POST a signed event to that URL when the job finishes: no polling required.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "transcript": {
    "text": "Welcome to the meeting, everyone.",
    "language": "en",
    "confidence": 0.97,
    "segments": [
      {
        "id": 0,
        "start": 0,
        "end": 3.5,
        "text": "Welcome to the meeting, everyone.",
        "speaker": "A"
      }
    ],
    "word_timestamps": "available",
    "words": [
      {
        "text": "Welcome",
        "start": 0,
        "end": 0.42,
        "confidence": 0.99
      }
    ]
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// Your signing secret from Settings → API keys.
const SECRET = process.env.OT_WEBHOOK_SECRET ?? "";

function verify(
  rawBody: string,
  header: string,
  nowSeconds = Math.floor(Date.now() / 1000),
): boolean {
  const segments = header.split(",");

  // Exactly one t= segment, finite, within the replay window.
  const tValues = segments.filter((s) => s.startsWith("t=")).map((s) => s.slice(2));
  if (tValues.length !== 1) return false;
  const t = Number(tValues[0]);
  if (!Number.isFinite(t) || Math.abs(nowSeconds - t) > 300) return false;

  const expected = createHmac("sha256", SECRET)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Header may carry multiple v1 sigs (key rotation). Match any.
  return segments
    .filter((s) => s.startsWith("v1="))
    .some((s) => {
      const got = Buffer.from(s.slice(3), "hex");
      const exp = Buffer.from(expected, "hex");
      return got.length === exp.length && timingSafeEqual(got, exp);
    });
}

// Express example. Use the RAW body buffer, not the parsed JSON.
// The X-OT-Signature header carries t=<unix>,v1=<hmac-hex>.
app.post("/webhooks/ot", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-ot-signature"] as string;
  if (!verify(req.body.toString(), sig)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body.toString());
  // Dedupe on event.id (at-least-once delivery), then enqueue + return 2xx fast.
  res.sendStatus(200);
});