Streaming

Murf Speech to Text uses a single WebSocket connection. You send audio as binary frames and control messages as JSON; the server sends back partial transcripts while the caller is speaking, and a final transcript when you end the turn.

Endpoint

wss://in.api.murf.ai/v1/transcription/stream-input

Pass your API key as the api_key query parameter or api-key header. See Authentication.

Quickstart

export MURF_API_KEY="your_api_key_here"

pip install websockets pyaudio

import asyncio
import json
import os
import wave
import websockets
API_KEY = os.environ["MURF_API_KEY"]
URL = f"wss://in.api.murf.ai/v1/transcription/stream-input?api_key={API_KEY}&language=hi"
CHUNK_MS = 100  # send 100 ms of audio per frame
async def send_audio(ws, path):
    with wave.open(path, "rb") as wav:
        # Declare the WAV's format. Sample rate must be one of:
        # 8000, 12000, 16000, 24000, 32000, 44100, 48000.
        await ws.send(json.dumps({
            "type": "AudioConfig",
            "codec": "pcm_s16le",
            "sample_rate": wav.getframerate(),
            "channels": wav.getnchannels(),
        }))
        frames_per_chunk = wav.getframerate() * CHUNK_MS // 1000
        while chunk := wav.readframes(frames_per_chunk):
            await ws.send(chunk)
            await asyncio.sleep(CHUNK_MS / 1000)  # pace the file like live audio
    # Flush the remaining speech and close the connection with code 1000.
    await ws.send(json.dumps({"type": "CloseStream"}))
async def receive_results(ws):
    try:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] in ("partial", "final"):
                if msg["transcript"]:
                    print(f'[{msg["type"]}] {msg["transcript"]}')
                if msg["type"] == "final":
                    print("-- end of turn --")
            elif msg["type"] == "QuotaWarning":
                print(f'Low balance: ${msg["remaining_funds"]}')
            elif msg["type"] == "Error":
                print(f'Error: {msg["message"]}')
    except websockets.ConnectionClosedError:
        pass  # closed with an error code; printed below
    print(f"Connection closed with code {ws.close_code}")
async def main(path):
    async with websockets.connect(URL) as ws:
        sender = asyncio.create_task(send_audio(ws, path))
        await receive_results(ws)
        sender.cancel()
if __name__ == "__main__":
    asyncio.run(main("sample.wav"))

Session lifecycle

A connection is a session. A session can contain many turns, for example one per caller utterance in a voice agent.

Partial and final transcripts

Each message carries the transcript of the current turn in transcript. The same text is also in rawEvent.transcript.

• partial: the transcript of the turn so far. Each partial contains the whole turn up to that point, so replace the text you are showing instead of appending to it.
• final: the completed transcript of the turn. Use this text as the caller’s utterance, and read rawEvent.words if you need word timestamps.

Ending a turn with Finalize

The server does not end a turn on silence. It keeps sending partial updates, and the turn ends only when you send Finalize or CloseStream. In a voice agent, send Finalize when your own end-of-turn detection fires: the server transcribes any pending speech immediately and sends a final message with rawEvent.event set to EndOfTurn and rawEvent.trigger set to manual.

If there was no pending speech when you sent Finalize, you still receive a final message. Its transcript is empty.

After Finalize, keep sending audio on the same connection to start the next turn. rawEvent.turn_index goes up by one, rawEvent.sequence_id keeps counting, and audio_window_start / audio_window_end remain relative to the start of the session, so all turns share one timeline.

Keeping the connection open

While you are not sending audio, for example while your agent is speaking, send a KeepAlive message so the connection is not closed for inactivity:

{ "type": "KeepAlive" }

Prefer KeepAlive over streaming silence. Silence still counts as audio on the wire.

If the server receives no audio and no KeepAlive for too long, it sends an Error message and closes the connection with code 4008. See Errors.

Reading results

A partial message:

{
  "type": "partial",
  "transcript": "मेरा नाम मर्फ़ है",
  "rawEvent": {
    "type": "TurnInfo",
    "request_id": "a1b2c3d4-...",
    "event": "Update",
    "turn_index": 0,
    "sequence_id": 4,
    "audio_window_start": 4.20,
    "audio_window_end": 5.25,
    "transcript": "मेरा नाम मर्फ़ है"
  }
}

A final message has the same shape. rawEvent.event is EndOfTurn, and rawEvent also includes trigger and words:

{
  "type": "final",
  "transcript": "मेरा नाम मर्फ़ है",
  "rawEvent": {
    "type": "TurnInfo",
    "request_id": "a1b2c3d4-...",
    "event": "EndOfTurn",
    "turn_index": 0,
    "sequence_id": 5,
    "audio_window_start": 4.20,
    "audio_window_end": 5.25,
    "transcript": "मेरा नाम मर्फ़ है",
    "trigger": "manual",
    "words": [
      { "word": "मेरा", "start": 4.30, "end": 4.52 },
      { "word": "नाम", "start": 4.54, "end": 4.71 },
      { "word": "मर्फ़", "start": 4.75, "end": 5.12 },
      { "word": "है", "start": 5.15, "end": 5.25 }
    ]
  }
}

Word times are already on the session timeline, so you don’t need to convert them. Quote rawEvent.request_id when you contact support.

Authentication

Speech to Text does not accept tokens from GET /v1/auth/token.

Query parameters

Coming soon

The following parameters are accepted on the connection URL but have no effect yet. Do not rely on them in production.

Concurrency

Each open Speech to Text connection uses one slot until it closes, whether or not you’re sending audio. Speech to Text limits are separate from Text to Speech concurrency. If you hit the limit, new connections close with code 4004. See Rate Limits & Concurrency for plan details.

Best practices

• Replace partial transcripts, don’t append them. Each partial contains the whole turn so far. Use the final transcript as the completed turn.
• Send audio in small frames. Send 20 to 100 ms of audio per frame. Larger frames delay transcription.
• Stream at real-time pace when sending pre-recorded audio.
• Send your telephony codec as-is. If your provider sends 8 kHz µ-law, declare mulaw at 8000 instead of converting the audio yourself. See Audio formats.
• Use Finalize at the end of each turn in voice agents. The server does not end a turn on silence.
• Keep one connection per call. Use Finalize between turns rather than reconnecting.
• Handle errors by close code, not by message text. See Errors.
• Quote rawEvent.request_id when you contact support.

FAQs

Next steps