Skip to content
utter docs

Quickstart

Two steps: get a key, then stream a WAV file at it.

1. Create a key

Section titled “1. Create a key”
  1. Sign in to the console at utter.cc.
  2. Open API keys and create one.
  3. Copy the plaintext key. It is shown once, at creation, and never again. If you lose it, create another one and revoke the old one.

A key looks like this:

utt_live_8f3Kq2Vd0pLzR7nWx4YsBc1TmJhE6uAo

Keep it in an environment variable, never in client side code:

Terminal window
export UTTER_API_KEY="utt_live_…"

Test keys (utt_test_…) exist too, and are the right thing to wire into CI. See Authentication.

2. Stream a file

Section titled “2. Stream a file”

The stream wants raw float32 mono little endian PCM at 16 kHz. The server does not resample, so convert first if your file is at another rate:

Terminal window
ffmpeg -i meeting.m4a -ac 1 -ar 16000 meeting.wav

Then, with pip install websockets soundfile numpy:

first_call.py
import asyncio, json, os
import numpy as np
import soundfile as sf
import websockets


URL = (
    "wss://api.utter.cc/v1/stream"
    "?tier=turbo&language=hi-IN%2Ben-IN&sample_rate=16000"
)


async def main(path: str) -> None:
    audio, sr = sf.read(path, dtype="float32")
    if sr != 16000:
        raise SystemExit(f"{path} is {sr} Hz, resample it to 16000 first")
    if audio.ndim > 1:
        audio = audio.mean(axis=1)          # mono


    headers = {"Authorization": f"Bearer {os.environ['UTTER_API_KEY']}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        ready = json.loads(await ws.recv())
        assert ready["type"] == "ready", ready


        # 320 ms of audio per frame.
        step = 16000 * 320 // 1000
        for i in range(0, len(audio), step):
            await ws.send(audio[i : i + step].tobytes())
        await ws.send("eof")


        async for raw in ws:
            event = json.loads(raw)
            if event["type"] == "partial":
                print("…", event["text"], end="\r")
            elif event["type"] == "final":
                print(event["text"])
            elif event["type"] == "done":
                print(f"[{event['audio_s']}s of audio, billed {event['billed_s']}s]")
                break
            elif event["type"] == "error":
                raise SystemExit(event["error"]["message"])


asyncio.run(main("meeting.wav"))
Invoice share kar diya hai, meeting 5 baje start hoti hai.
[8.52s of audio, billed 8.52s]
Section titled “What to read next”