Metadata-Version: 2.5
Name: livekit-plugins-speechmatics
Version: 2.0.0b2
Summary: Agent Framework plugin for Speechmatics
Project-URL: Documentation, https://docs.livekit.io
Project-URL: Website, https://livekit.io/
Project-URL: Source, https://github.com/livekit/agents
Author-email: LiveKit <hello@livekit.io>
License-Expression: Apache-2.0
Keywords: ai,audio,livekit,realtime,speechmatics,video,voice
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11.0
Requires-Dist: livekit-agents>=2.0.0b2
Description-Content-Type: text/markdown

# Speechmatics STT plugin for LiveKit Agents

Support for Speechmatics STT.

See [https://docs.livekit.io/agents/integrations/stt/speechmatics/](https://docs.livekit.io/agents/integrations/stt/speechmatics/) for more information.

## Installation

```bash
pip install livekit-plugins-speechmatics
```

## Model

`model` selects the transcription model and defaults to `linden-1`
(`speechmatics.Model.LINDEN_1`). It is sent as given. `operating_point`, which Speechmatics
deprecated in favour of `model`, is not accepted.

## Turn detection modes

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

- `VAD` — Speechmatics runs its own VAD and closes turns itself (service-side
  endpointing). No `vad` is required. Pair it with `turn_detection="stt"` in the `VoiceSession`'s `turn_handling`,
  otherwise the session's own turn detector decides and Speechmatics' end-of-turn is ignored.
- `EXTERNAL` (default) — Speechmatics does not endpoint on its own. Turns close when the caller
  calls `finalize()`. The plugin's `vad` drives `finalize()` on end-of-speech; when none is passed,
  `livekit-plugins-silero` is loaded if it is installed. LiveKit does **not** call `finalize()` for
  you, so with `vad=None` (and without calling `finalize()` yourself) turns never close.
  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 were removed: Agent STT exposes a single
service-side endpointing strategy, so select `VAD` or `EXTERNAL`. There is no replacement for
`FIXED`'s `end_of_utterance_silence_trigger` timing, nor for speaker focus (`focus_speakers`,
`ignore_speakers`, `focus_mode`, `update_speakers()`); the other pre-Agent-STT arguments were removed
too, and `diarization_sensitivity`, `enable_partials` and `speaker_active_format` are now
`speaker_sensitivity`, `include_partials` and `speaker_format`.

## Usage — service-side endpointing (`VAD`)

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

```python
from livekit.agents import TurnHandlingOptions, VoiceSession
from livekit.plugins import speechmatics

session = VoiceSession(
    stt=speechmatics.STT(turn_detection_mode=speechmatics.TurnDetectionMode.VAD),
    turn_handling=TurnHandlingOptions(turn_detection="stt"),
    ...
)
```

## Usage — caller-driven endpointing (`EXTERNAL`, default)

Pass a `vad` to the plugin; its end-of-speech drives `finalize()`. `VoiceSession` 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:

```python
from livekit.agents import VoiceSession, inference
from livekit.plugins import speechmatics

vad = inference.VAD()

session = VoiceSession(
    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:

```python
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.

```python
from livekit.agents import VoiceSession
from livekit.plugins import speechmatics

session = VoiceSession(
    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:

```python
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.
