Speechmatics Voice Agent Python Client

0.2.8 verified Fri May 01 auth: no python

Official Python client for Speechmatics Real-Time API for voice agents. Supports WebSocket-based streaming for real-time transcription and agent interaction. Current version: 0.2.8, release cadence: irregular.

pip install speechmatics-voice

Common errors

error ModuleNotFoundError: No module named 'speechmatics' ↓

cause Incorrect import path; package name on PyPI is speechmatics-voice but import uses speechmatics.voice

fix

Install with pip install speechmatics-voice and import as from speechmatics.voice import VoiceAgentClient

error websockets.exceptions.ConnectionClosedError: no close frame received ↓

cause Server closes connection due to invalid auth token or audio format mismatch.

fix

Check that auth token is correct and audio is 16kHz 16-bit PCM mono.

error TypeError: object dict can't be used in 'await' expression ↓

cause Trying to await a non-async method, e.g., `await client.connect` instead of `await client.start()`

fix

Use await client.start() to initiate connection.

Warnings

breaking The client expects audio in 16kHz, 16-bit linear PCM format. Using other formats will fail silently. ↓

fix Ensure audio is resampled to 16kHz mono 16-bit PCM before sending.

gotcha The `auth_token` must be provided as a string, not as a dict or header. Passing via headers is not supported. ↓

fix Pass `auth_token='your_token'` directly to the constructor.

gotcha The library uses asyncio; opening multiple connections without proper async management can cause resource leaks. ↓

fix Always use `async with` or explicitly call `await client.stop()` to close connections.

Imports

VoiceAgentClient

wrong

from speechmatics_voice import VoiceAgentClient

correct

from speechmatics.voice import VoiceAgentClient

Library uses dot in package name, not underscore

Quickstart

Connect to Speechmatics Voice Agent, send audio, and receive real-time transcriptions.

import asyncio
from speechmatics.voice import VoiceAgentClient

async def main():
    client = VoiceAgentClient(
        url='wss://realtime.voice.speechmatics.com/v1',
        auth_token=os.environ.get('SPEECHMATICS_AUTH_TOKEN', ''),
    )
    await client.start()
    # Send audio data
    await client.send_audio(b'\x00' * 16000)
    # Receive messages
    async for msg in client:
        print(msg)
        if msg.get('type') == 'utterance_end':
            break
    await client.stop()

asyncio.run(main())