Streaming speech to text API (WebSocket)

wss://sandbox.voice.miraiminds.co/v1/audio/transcriptions/stream?language_code=hi-IN&encoding=mulaw&sample_rate=8000&endpointing=manual

{ "event": "audio_input", "audio": "AACaADABvQE9AqwCBgNJA3QDgwN4A1MDFAO+AlMC1gFLAbYA" }

{ "event": "speech_start" }
{ "event": "speech_end" }
{ "event": "flush" }
{ "event": "ping" }
{ "event": "end" }

{
  "event": "session.begin",
  "request_id": "mira_5f0c2b6e9d1a4c7e8b3f6a2d9e0c1b4a",
  "session_id": "sttws_01K7C2M3Q4R7T9V2X5Y8A1B4C7",
  "config": {
    "language_code": "hi-IN",
    "model": "mira-stt:v5-realtime",
    "stream_type": "balanced",
    "mode": "transcribe",
    "prompt": null,
    "encoding": "mulaw",
    "sample_rate": 8000,
    "return_timestamps": false,
    "threshold": 0.3,
    "prefix_padding_ms": 300,
    "silence_duration_ms": 1000,
    "min_speech_duration_ms": 250,
    "turn_detection": "manual"
  },
  "capabilities": {
    "audio_language_identification": false,
    "final_orthography": "off",
    "provisional_finals": false,
    "provisional_policy": "off"
  },
  "limits": { "max_session_secs": 3600, "idle_timeout_secs": 120 }
}

{ "event": "vad.speech_start", "utterance_idx": 0, "confidence": 0.91 }

{ "event": "vad.speech_end", "utterance_idx": 0, "confidence": 0.12 }

{ "event": "transcript.partial", "utterance_idx": 0, "text": "नमस्ते मुझे कल शाम" }

{ "event": "transcript.final", "utterance_idx": 0, "text": "नमस्ते मुझे कल शाम पाँच बजे का appointment book करना है" }

{
  "event": "config.updated",
  "applied": ["language_code=en-IN"],
  "config": {
    "language_code": "en-IN",
    "model": "mira-stt:v5-realtime",
    "stream_type": "balanced",
    "mode": "transcribe",
    "prompt": null,
    "encoding": "mulaw",
    "sample_rate": 8000,
    "return_timestamps": false,
    "threshold": 0.3,
    "prefix_padding_ms": 300,
    "silence_duration_ms": 1000,
    "min_speech_duration_ms": 250,
    "turn_detection": "manual"
  }
}

{ "event": "pong" }

{ "event": "session.draining", "reason": "max_duration" }

{
  "event": "session.end",
  "request_id": "mira_5f0c2b6e9d1a4c7e8b3f6a2d9e0c1b4a",
  "total_duration_s": 48.212,
  "total_utterances": 7,
  "audio_duration_s": 41.36,
  "audio_seconds_billed": 42,
  "cost_paise": 21
}

{
  "event": "error",
  "code": "utterance_too_long",
  "message": "Utterance exceeds 60 second limit; provide a speech boundary",
  "is_fatal": true
}

# pip install "websockets>=14"
"""Stream WAV files to Mira STT, one utterance per file, and print the transcript.

    export MIRA_API_KEY=sk_live_...
    python stream_stt.py hello.wav order.wav      # 16-bit mono, 8 or 16 kHz
"""
import asyncio
import base64
import json
import os
import sys
import time
import wave
from urllib.parse import urlencode

import websockets

URL = "wss://sandbox.voice.miraiminds.co/v1/audio/transcriptions/stream"
CHUNK_SECS = 0.02  # 20 ms of audio per message, like a phone line


def read_wav(path):
    with wave.open(path, "rb") as w:
        if w.getnchannels() != 1 or w.getsampwidth() != 2 or w.getframerate() not in (8000, 16000):
            sys.exit(f"{path}: need a 16-bit mono WAV at 8 or 16 kHz")
        return w.getframerate(), w.readframes(w.getnframes())


async def main(paths):
    clips = [read_wav(p) for p in paths]
    rate = clips[0][0]
    if any(r != rate for r, _ in clips):
        sys.exit("all files need the same sample rate")
    query = urlencode({"language_code": "hi-IN", "encoding": "linear16",
                       "sample_rate": rate, "endpointing": "manual"})
    headers = {"Authorization": f"Bearer {os.environ['MIRA_API_KEY']}"}
    ended_at = {}  # utterance_idx -> when we sent its speech_end

    async with websockets.connect(f"{URL}?{query}", additional_headers=headers) as ws:
        begin = json.loads(await ws.recv())
        print("session", begin["session_id"], "on", begin["config"]["model"])

        async def send():
            step = int(rate * CHUNK_SECS) * 2  # bytes: 2 per 16-bit sample
            for idx, (_, pcm) in enumerate(clips):
                await ws.send(json.dumps({"event": "speech_start"}))
                for i in range(0, len(pcm), step):
                    chunk = base64.b64encode(pcm[i:i + step]).decode()
                    await ws.send(json.dumps({"event": "audio_input", "audio": chunk}))
                    await asyncio.sleep(CHUNK_SECS)  # real time, as a live call would
                ended_at[idx] = time.monotonic()
                await ws.send(json.dumps({"event": "speech_end"}))
            await ws.send(json.dumps({"event": "end"}))

        sender = asyncio.create_task(send())
        async for message in ws:
            event = json.loads(message)
            kind = event["event"]
            if kind == "transcript.partial":
                print("   …", event["text"])
            elif kind == "transcript.final":
                ms = (time.monotonic() - ended_at[event["utterance_idx"]]) * 1000
                print(f"[{event['utterance_idx']}] {event['text']}  ({ms:.0f} ms after speech_end)")
            elif kind == "error":
                print("error:", event["code"], event["message"])
                if event["is_fatal"]:
                    break
            elif kind == "session.end":
                print(f"{event['audio_seconds_billed']} s billed, {event['cost_paise']} paise")
                break
        sender.cancel()
        await asyncio.gather(sender, return_exceptions=True)


asyncio.run(main(sys.argv[1:]))