Skip to main content

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)

Sentence segments

By default the service closes a segment at the end of each turn, so a turn arrives as one final transcript. Set emit_sentences=True to close a segment at every end of sentence as well, so each sentence is emitted as its own final transcript:

stt = speechmatics.STT(emit_sentences=True)

Sample rate

Audio is sent at 16 kHz by default. The service also accepts 8 kHz; any other rate raises a ValueError. LiveKit resamples incoming audio to the rate you choose:

stt = speechmatics.STT(sample_rate=8000)

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.11

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.11
File Size Uploaded Provenance Actions
livekit_plugins_speechmatics-1.8.11.tar.gz 21.7 kB With provenance Details for livekit_plugins_speechmatics-1.8.11.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for livekit-plugins-speechmatics 1.8.11
File Interpreter ABI Platform Actions
livekit_plugins_speechmatics-1.8.11-py3-none-any.whl Python 3 none any Details for livekit_plugins_speechmatics-1.8.11-py3-none-any.whl

Total release size: 44.9 kB

Release files / livekit_plugins_speechmatics-1.8.11.tar.gz

Download URL livekit_plugins_speechmatics-1.8.11.tar.gz
Size 21.7 kB
Tags Source
SHA-256 checksum
How to use checksums
60c3c97c5245e0b08f99b4ee7a99520ae5973b931b9bb4ea101556b0709bd90f
BLAKE2b-256 checksum
How to use checksums
477332d58ef633eda960dccef634b97f2f059fdb51d1d61570b3675c4b4a22b4
Upload date
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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

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

Download URL livekit_plugins_speechmatics-1.8.11-py3-none-any.whl
Size 23.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ee3d47267e9e22603e5a7c5349177ffc1058c330b55656faee87e91985054b1
BLAKE2b-256 checksum
How to use checksums
204479e2aa51118337c628902c60f266d6ce106736a7ea19e9b596464c9dee1f
Upload date
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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for livekit-plugins-speechmatics 1.8.11

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for livekit_plugins_speechmatics-1.8.11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.8.11 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page