Speechmatics STT

Overview

Speechmatics speech-to-text is available in LiveKit Agents through LiveKit Inference and the Speechmatics plugin. With LiveKit Inference, your agent runs on LiveKit's infrastructure to minimize latency. No separate provider API key is required, and usage and rate limits are managed through LiveKit Cloud. Use the plugin instead if you want to manage your own billing and rate limits. Pricing for LiveKit Inference is available on the pricing page .

LiveKit Inference

Use LiveKit Inference to access Speechmatics STT without a separate Speechmatics API key.

A checkmark in the EU endpoint column means the model has a dedicated EU endpoint, in addition to the global endpoint. To learn more, see Data residency.

Usage

To use Speechmatics, use the STT class from the inference module:

from livekit.agents import AgentSession, inference

session = AgentSession(
    stt=inference.STT(
        model="speechmatics/linden-1",
        language="en"
    ),
    # ... llm, tts, vad, turn_handling, etc.
)

import { AgentSession, inference } from '@livekit/agents';

const session = new AgentSession({
    stt: new inference.STT({
        model: "speechmatics/linden-1",
        language: "en"
    }),
    // ... llm, tts, vad, turnHandling, etc.
});

Voice activity detection

This section applies to LiveKit Inference. With the plugin, turn detection is set by turn_detection_mode, which defaults to EXTERNAL and needs a VAD running in your agent. See Turn detection.

Used through LiveKit Inference, speechmatics/linden-1 detects the end of speech server-side, so your agent doesn't need a VAD and the vad parameter is ignored.

The speechmatics/enhanced and speechmatics/standard models don't detect end of speech server-side, so LiveKit Inference relies on a VAD running in your agent. The SDK runs the VAD on incoming audio locally, and when the speaker stops, it signals the LiveKit Inference gateway to flush the final transcript.

For those models, the framework loads a VAD for you by default. To tune it, or to use a different VAD, pass one with the vad parameter:

from livekit.agents import AgentSession, inference

session = AgentSession(
    stt=inference.STT(
        model="speechmatics/enhanced",
        # optional; the framework loads one if omitted
        vad=inference.VAD(min_silence_duration=0.4),
    ),
    # ... llm, tts, etc.
)

import { AgentSession, inference } from '@livekit/agents';

const session = new AgentSession({
    stt: new inference.STT({
        model: "speechmatics/enhanced",
        // optional; the framework loads one if omitted
        vad: new inference.VAD({ minSilenceDuration: 0.4 }),
    }),
    // ... llm, tts, etc.
});

Parameters

Model parameters

Pass the following parameters inside extra_kwargs (Python) or modelOptions (Node.js):

For more details on these options, see the Agent STT API reference  for speechmatics/linden-1, or the real-time API reference  for the deprecated models.

Plugin

The Speechmatics plugin connects directly to the Speechmatics Agent STT API with your own API key.

Installation

Install the plugin from PyPI:

uv add "livekit-agents[speechmatics,silero]~=1.8"

Authentication

The Speechmatics plugin requires an API key .

Set SPEECHMATICS_API_KEY in your .env file.

Endpoint

The plugin connects to wss://eu2.rt.speechmatics.com/v2/agent by default. To use a different region or a self-hosted deployment, set the base_url parameter:

stt = speechmatics.STT(
    base_url="wss://global.rt.speechmatics.com/v2/agent",
)

Speechmatics automatically routes each connection to its nearest regional server through the global endpoint. If you have data residency requirements, pin to a region instead:

For the full list, see Supported endpoints .

Usage

Use Speechmatics STT in an AgentSession or as a standalone transcription service. For example, you can use this STT in the Voice AI quickstart.

from livekit.plugins import speechmatics

session = AgentSession(
    stt=speechmatics.STT(),
    # ... llm, tts, etc.
)

Turn detection

The turn_detection_mode parameter sets which component detects the end of a turn. It supports two modes:

The default EXTERNAL mode needs no extra configuration, as shown in the Usage example.

To have Speechmatics detect the end of a turn instead, set turn_detection_mode to VAD, and set turn_detection="stt" in the turn handling options. Without turn_detection="stt", the session ignores the end-of-speech events the plugin emits:

from livekit.agents import AgentSession, TurnHandlingOptions
from livekit.plugins import speechmatics

session = AgentSession(
    stt=speechmatics.STT(
        turn_detection_mode=speechmatics.TurnDetectionMode.VAD,
    ),
    turn_handling=TurnHandlingOptions(
        turn_detection="stt",
    ),
    # ... llm, tts, etc.
)

Parameters

This section describes the key parameters for the Speechmatics STT plugin. See the plugin reference for a complete list of all available parameters.

Keyterms

Speechmatics supports keyterms through the additional_vocab parameter, on all models including speechmatics/linden-1. Speechmatics calls this feature the custom dictionary . You can only set keyterms when the session starts. Speechmatics doesn't accept changes to additional_vocab mid-session.

With the plugin, pass it to the STT constructor. Each entry takes a content value and optional sounds_like pronunciation variants, for when the spelling doesn't match how the word is said:

from livekit.plugins import speechmatics
from livekit.plugins.speechmatics import AdditionalVocabEntry

stt = speechmatics.STT(
    additional_vocab=[
        AdditionalVocabEntry(content="Speechmatics"),
        AdditionalVocabEntry(content="LiveKit", sounds_like=["live kit"]),
    ],
)

With LiveKit Inference, pass the same entries as plain dicts inside extra_kwargs:

from livekit.agents import inference

stt = inference.STT(
    model="speechmatics/linden-1",
    extra_kwargs={
        "additional_vocab": [
            {"content": "Speechmatics"},
            {"content": "LiveKit", "sounds_like": ["live kit"]},
        ],
    },
)

To manage keyterms across providers, or detect them automatically from the conversation, see Keyterm management.

Speaker diarization

Speaker diarization attributes speech to individual speakers. When enabled, the STT reports capabilities.diarization = True, and the transcription output can include speaker information through the speaker_id and text attributes.

Agent STT labels one speaker per transcript segment, not per word. A segment is the unit the service emits: AddSegment for a final transcript and AddPartialSegment for an interim one. Each segment has at most one speaker, so overlapping speech from two people is never labeled within the same segment. The plugin surfaces each segment as a LiveKit transcript event, which means the speaker label changes between events, never inside one.

Speakers are labeled in the order they are first heard: S1, S2, and so on. Labels hold for the session but aren't stable across sessions unless you carry them over with known_speakers.

With diarization enabled, wrap the Speechmatics STT with MultiSpeakerAdapter to detect the primary speaker and format transcripts by speaker.

Enable diarization in the STT constructor. LiveKit Inference uses a string diarization mode, while the plugin uses the boolean enable_diarization:

stt = inference.STT(
    model="speechmatics/linden-1",
    extra_kwargs={
        # "none" or "speaker"
        "diarization": "speaker",
    },
)

stt = speechmatics.STT(
    enable_diarization=True,
    speaker_format="<{speaker_id}>{text}</{speaker_id}>",
)

Segments the service can't attribute to a speaker are labeled UU, so a format string renders them as <UU>Hello</UU>. With diarization disabled, every segment is labeled UU.

Include the format in your agent instructions so the language model reads the labels as speaker attribution rather than as part of what was said. Two settings help when speakers are hard to separate: raise speaker_sensitivity to split similar-sounding voices more aggressively, and set prefer_current_speaker to reduce switching mid-turn. To learn more, see Speaker diarization .

Reusing speaker labels across sessions

Speaker labels are assigned per session, so the same person is usually S1 in one session and something else in the next. To keep labels stable, call get_speaker_ids() on the STT once each speaker has said at least five words, then pass the result as known_speakers when you create the STT for the next session:

speakers = await stt.get_speaker_ids()

# ... later, in a new session
stt = speechmatics.STT(
    enable_diarization=True,
    known_speakers=speakers,
)

get_speaker_ids() returns the speakers for the STT's open stream. If the STT has more than one stream open, it returns a list of results, one per stream.

Additional resources

The following resources provide more information about using Speechmatics with LiveKit Agents.

Python package

The livekit-plugins-speechmatics package on PyPI.

Plugin reference

Reference for the Speechmatics STT plugin.

GitHub repo

View the source or contribute to the LiveKit Speechmatics STT plugin.

Speechmatics plugin guide

Speechmatics' own guide to this plugin.

Agent STT API reference

The WebSocket API the plugin speaks.