Speechmatics STT plugin for LiveKit Agents

Support for Speechmatics STT.

See https://docs.livekit.io/agents/integrations/stt/speechmatics/ for more information.

Installation

pip install livekit-plugins-speechmatics

Model

model selects the transcription model and defaults to linden-1, currently the only Agent STT model. Pass it as a string or as speechmatics.Model.LINDEN_1.

operating_point is a deprecated alias for model and warns when used. The RT operating points enhanced and standard are not Agent STT models and are rejected by the service.

Turn detection modes

The turn_detection_mode parameter controls how end-of-turn (endpointing) is detected:

VAD (default) — Speechmatics runs its own VAD and closes turns itself (service-side endpointing). No vad is required. Pair it with turn_detection="stt" on the AgentSession, otherwise the session's own turn detector decides and Speechmatics' end-of-turn is ignored.
EXTERNAL — Speechmatics does not endpoint on its own. Turns close when the caller calls finalize(). In practice you pass a vad to the plugin and its end-of-speech drives finalize(); LiveKit does not call finalize() for you, and no VAD is auto-loaded. Without a vad (and without calling finalize() yourself) turns never close, so nothing is finalized. The session's own turn detector decides when the user's turn ends; finalize() only makes Speechmatics flush what it has as a final segment.

The earlier FIXED, ADAPTIVE and SMART_TURN modes each selected one of the old engine's service-side endpointing strategies. Agent STT exposes a single one, so all three are deprecated and resolve to VAD with a warning. FIXED additionally loses its end_of_utterance_silence_trigger timing, which Agent STT does not support.

Usage — service-side endpointing (`VAD`, default)

Let Speechmatics detect turns and tell the session to act on them:

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

agent = AgentSession(
    stt=speechmatics.STT(),
    turn_detection="stt",
    ...
)

Usage — caller-driven endpointing (`EXTERNAL`)

Pass a vad to the plugin; its end-of-speech drives finalize(). AgentSession loads its own VAD when none is given, so pass the same instance to both and a single VAD serves the session and the plugin:

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

vad = inference.VAD()

agent = AgentSession(
    stt=speechmatics.STT(
        turn_detection_mode=speechmatics.TurnDetectionMode.EXTERNAL,
        # The VAD passed here drives finalize() on end-of-speech.
        vad=vad,
        speaker_format="[Speaker {speaker_id}] {text}",
    ),
    vad=vad,
    ...
)

Interim transcripts

The service sends partial segments by default, emitted as interim transcripts. Set include_partials=False to receive final segments only:

stt = speechmatics.STT(include_partials=False)

Diarization

Speechmatics attributes each transcript segment to a speaker. Diarization is enabled by default (enable_diarization=True); the segment is the unit of attribution, so each result carries a single speaker_id and there is no per-word speaker data. To fold the speaker label into the transcript text, set speaker_format using the {speaker_id} and {text} placeholders:

speaker_format="<{speaker_id}>{text}</{speaker_id}>" -> <S1>Hello</S1>
speaker_format="[Speaker {speaker_id}] {text}" -> [Speaker S1] Hello

Segments the service did not attribute — including every segment when diarization is off — are labelled UU.

Adjust your system instructions to inform the LLM of this format so it can attribute speakers.

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

agent = AgentSession(
    stt=speechmatics.STT(
        enable_diarization=True,
        max_speakers=4,
        speaker_format="[Speaker {speaker_id}] {text}",
        additional_vocab=[
            speechmatics.AdditionalVocabEntry(
                content="LiveKit",
                sounds_like=["live kit"],
            ),
        ],
    ),
    ...
)

Speaker identification

Speaker labels are per session by default, so S1 in one session is unrelated to S1 in the next. To carry labels across sessions, read the identifiers out of a live session with await stt.get_speaker_ids() (call it once each speaker has said a few words), then pass them back as known_speakers on a later session:

speakers = await stt.get_speaker_ids()

stt = speechmatics.STT(known_speakers=speakers)

Each entry maps a human-readable label to the identifiers the engine recognizes it by. With more than one open stream the call returns one list per stream instead.

Pre-requisites

You'll need to specify a Speechmatics API Key. It can be set as environment variable SPEECHMATICS_API_KEY or in a .env.local file.

The plugin connects to wss://eu2.rt.speechmatics.com/v2/agent by default. To use another region or a self-hosted endpoint, set base_url or the SPEECHMATICS_RT_URL environment variable.

Metadata

Release files for livekit-plugins-speechmatics 1.8.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for livekit-plugins-speechmatics 1.8.4
File	Size	Uploaded
livekit_plugins_speechmatics-1.8.4.tar.gz	21.3 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for livekit-plugins-speechmatics 1.8.4
File	Interpreter	ABI	Platform	Reset
livekit_plugins_speechmatics-1.8.4-py3-none-any.whl 22.7 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 44.1 kB

Release files / livekit_plugins_speechmatics-1.8.4.tar.gz

Download URL	livekit_plugins_speechmatics-1.8.4.tar.gz
Size	21.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`4b168c38a8fac837a4be80fca052877327170b5fe5ebe137bb91a02d3202938f`
BLAKE2b-256 checksum How to use checksums	`1b46977ac4e985d2b8ac18ccf24a13c12baa2a118cb3b4ac8bd31ecbea2ee744`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/livekit/agents
Publishing commit: github.com/livekit/agents/tree/e684c2379e1c385afe8edcd1f02ea422051b035f

Workflow

Publishing configuration: github.com/livekit/agents/blob/e684c2379e1c385afe8edcd1f02ea422051b035f/.github/workflows/publish.yml
Publishing logs: github.com/livekit/agents/actions/runs/36936222051/attempts/1

Artifact

Subject: livekit_plugins_speechmatics-1.8.4.tar.gz
SHA-256 checksum: 4b168c38a8fac837a4be80fca052877327170b5fe5ebe137bb91a02d3202938f Verifying attestations

Release files / livekit_plugins_speechmatics-1.8.4-py3-none-any.whl

Download URL	livekit_plugins_speechmatics-1.8.4-py3-none-any.whl
Size	22.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`67ba3f91438b24508a57a2029a23c4b39ca01bf8e416c9742d84547f3f60cc64`
BLAKE2b-256 checksum How to use checksums	`453f9d6233fd3670a0100ee3ce913dec1d60e29541a6bf2367adb062914f8ea5`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/livekit/agents
Publishing commit: github.com/livekit/agents/tree/e684c2379e1c385afe8edcd1f02ea422051b035f

Workflow

Publishing configuration: github.com/livekit/agents/blob/e684c2379e1c385afe8edcd1f02ea422051b035f/.github/workflows/publish.yml
Publishing logs: github.com/livekit/agents/actions/runs/36936222051/attempts/1

Artifact

Subject: livekit_plugins_speechmatics-1.8.4-py3-none-any.whl
SHA-256 checksum: 67ba3f91438b24508a57a2029a23c4b39ca01bf8e416c9742d84547f3f60cc64 Verifying attestations