LiveKit

livekit-plugins-slng adds speech to text (STT) and text to speech (TTS) adapters for LiveKit Agents. Pass a model identifier and the plugin builds the bridge endpoint itself, so every streaming model on the platform works with the same code. This page is the plugin reference. For a walkthrough that sets up your models in the dashboard and applies the change, see the LiveKit integration guide.

The plugin is realtime WebSocket only, so HTTP-only models (such as batch STT) are not available through it. This page documents version 1.6.7 and later; upgrading from 1.6.6 or earlier? Read Migrating from earlier versions first.

Prerequisites

Python 3.10+ and livekit-agents>=1.6.10
A LiveKit Agents project
An SLNG API key. See Create your API key.

Install

uv add livekit-plugins-slng
# or: pip install livekit-plugins-slng

Quickstart

The plugin reads your key from SLNG_API_KEY, or pass it with api_key. Create an STT and a TTS instance and hand them to your agent session:

from livekit.plugins import slng

stt = slng.STT(model="deepgram/nova:3", language="en")
tts = slng.TTS(
    model="deepgram/aura:2",
    voice="aura-2-thalia-en",  # provider voice ID, required
    language="en",
)

Language codes are sent verbatim. Use the exact value the model expects, for example BCP-47 hi-IN for Sarvam Bulbul, not hi.

Full voice agent example

agent.py

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import silero, slng


class MyAgent(Agent):
    async def on_enter(self):
        await self.session.say("Hi, how can I help you today?")


async def entrypoint(ctx: JobContext):
    await ctx.connect()

    stt = slng.STT(model="deepgram/nova:3", language="en", sample_rate=16000)
    tts = slng.TTS(
        model="deepgram/aura:2",
        voice="aura-2-thalia-en",
        language="en",
        sample_rate=24000,
    )

    session = AgentSession(stt=stt, tts=tts, vad=silero.VAD.load())
    await session.start(agent=MyAgent(), room=ctx.room)


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

Model identifiers

Models follow provider/model:variant. A bare identifier is the external passthrough route; prefix with slng/ for an SLNG-hosted instance.

model="deepgram/nova:3"          # external passthrough
model="slng/deepgram/nova:3-en"  # SLNG-hosted, English

See the model catalog for the full list.

STT reference

slng.STT streams speech to text over WebSocket. Provide either model or connections; there is no default. Only 16-bit PCM (pcm_s16le) input is supported, and batch recognize() is not available, so use stream().

stt = slng.STT(model="deepgram/nova:3", language="en")

Parameter	Default	Description
`api_key`	`None`	SLNG API key. Falls back to `SLNG_API_KEY`.
`model`	`None`	Model identifier. Required unless `connections` is set.
`connections`	`None`	Ordered failover candidates (see Failover).
`provider_api_key`	`None`	Your own provider credential (BYOK, external routes only).
`language`	`"en"`	Language code, sent verbatim.
`sample_rate`	`16000`	Audio sample rate in Hz.
`enable_partial_transcripts`	`True`	Stream interim results.
`enable_diarization`, `min_speakers`, `max_speakers`	`False`, `None`, `None`	Speaker identification (model support required).
`vad_threshold`, `vad_min_silence_duration_ms`, `vad_speech_pad_ms`	`0.5`, `300`, `30`	VAD tuning (model support required).
`final_timeout_s`	`None`	Watchdog for stalled finals. Disabled unless set.
`base_url`	`"api.slng.ai"`	Gateway host. Point at a regional host to pin execution (see Region routing).
`external_agent_id`, `external_session_id`	`None`	Tracking IDs on usage events.
`fallback_recovery_cooldown_s`	`60.0`	Seconds before retrying a failed candidate.

Any extra keyword argument is forwarded to the bridge init payload; the bridge applies the options the model’s catalog declares and ignores the rest (for example Deepgram’s endpointing and smart_format).

TTS reference

slng.TTS streams text to speech over WebSocket. voice is required and passed verbatim as the provider’s voice ID. Use tts.stream() for voice agents and tts.synthesize(text) for one-shot previews. Change voice, language, and speed at runtime with tts.update_options(...).

tts = slng.TTS(model="deepgram/aura:2", voice="aura-2-thalia-en", language="en")

Parameter	Default	Description
`api_key`	`None`	SLNG API key. Falls back to `SLNG_API_KEY`.
`model`	`None`	Model identifier. Required unless `connections` is set.
`voice`	required	Provider voice ID, passed verbatim.
`connections`	`None`	Ordered failover candidates (see Failover).
`provider_api_key`	`None`	Your own provider credential (BYOK, external routes only).
`language`	`"en"`	Language code, sent verbatim.
`sample_rate`	`24000`	Audio sample rate in Hz.
`speed`	`1.0`	Speech speed multiplier.
`text_chunking`, `phrase_max_chars`	`"auto"`, `60`	How streamed text is batched (see Text chunking).
`warm_standby_enabled`	`False`	Pre-open the next connection (see Warm standby).
`first_audio_timeout_s`	`None`	Fail over if no audio arrives in time. Disabled unless set.
`base_url`	`"api.slng.ai"`	Gateway host. Point at a regional host to pin execution (see Region routing).
`external_agent_id`, `external_session_id`	`None`	Tracking IDs on usage events.
`fallback_recovery_cooldown_s`	`60.0`	Seconds before retrying a failed candidate.

Extra keyword arguments are forwarded per the model’s contract (for example Rime Arcana speakingStyle or Cartesia Sonic emotion). Pass pronunciation={"mode": "rewrite", "name": "my-dictionary"} to apply a pronunciation dictionary. Pick a voice that matches your model from the text to speech catalog.

Text chunking

text_chunking="auto" (the default) batches words into phrases, flushing at punctuation or phrase_max_chars. This avoids the choppy audio that word-by-word streaming causes on some providers. Set "word" only if you need per-word forwarding.

Warm standby connections

By default each turn opens a fresh connection, adding setup time to its first audio. With warm_standby_enabled=True, the plugin pre-opens the next connection while the current turn plays, so time to first audio drops to roughly the provider’s generation time.

tts = slng.TTS(model="cartesia/sonic:3", voice="<voice-id>", warm_standby_enabled=True)

The standby is a single connection per instance and counts toward your concurrency limit while it waits. If it expires during a long silence, the plugin reconnects at regular latency with no error. Where a provider exposes an inactivity option, pass it as a model option to keep the standby alive through pauses.

Failover

Pass connections=[...], an ordered list of candidates (model identifiers, bridge endpoint URLs, or STTConnectionConfig / TTSConnectionConfig objects). When connections supplies the full list, model is not needed.

stt = slng.STT(connections=["deepgram/nova:3", "soniox/speech-ai:rt-v5"])

Each candidate gets APIConnectOptions.max_retry attempts before the next is tried. Deterministic 4xx errors advance immediately; HTTP 413 is terminal.
STT fails over at safe stream boundaries and replays buffered audio, so no speech is lost. TTS switches only before its first audio, and all TTS candidates must share a sample rate and channel count.
After fallback_recovery_cooldown_s (60s default), the primary is retried on the next request. A single candidate reconnects and replays on a transient drop instead of ending the stream.

STTConnectionConfig and TTSConnectionConfig keep endpoint-specific headers, init payloads, and voices together; simple candidates inherit the global settings.

Bring your own key (BYOK)

Pass provider_api_key to use your own provider credential. The plugin sends it as the X-Slng-Provider-Key header on external (passthrough) routes only. See Bring your own key.

tts = slng.TTS(model="cartesia/sonic:3", voice="<voice-id>", provider_api_key="<your-key>")

Region routing

Route to a sovereign hub by pointing base_url at a regional gateway host, for example eu.api.slng.ai or us.api.slng.ai. Data stays in-jurisdiction and every hub runs the full stack. See the regions map for the available hosts.

stt = slng.STT(model="deepgram/nova:3", base_url="eu.api.slng.ai")

Plugin events

Subscribe to slng_event for typed events covering gateway session identifiers (gateway.session) and failover activity (fallback.attempt_failed, fallback.switch_succeeded, fallback.primary_recovered, fallback.exhausted).

@tts.on("slng_event")
def on_slng_event(event: slng.PluginEvent) -> None:
    print(event.name, event.component, event.data)

external_agent_id and external_session_id (max 128 characters) attach your own identifiers to usage events as the X-SLNG-Agent-Id and X-SLNG-Session-Id headers, so you can correlate gateway usage with your analytics.

Migrating from earlier versions

Version 1.6.7 is a breaking rewrite:

All traffic goes through the bridge. model_endpoint and model_endpoints were removed; pass a model or connections instead.
STT has no default model, and recognize() (HTTP batch) is gone; use stream() with pcm_s16le input.
TTS voice is required and passed verbatim.
Language codes are no longer normalized client-side.
api_token is deprecated; use api_key.
Provider-specific defaults were removed; configure candidates via connections.

Next steps

LiveKit integration guide for the migration walkthrough.

Unmute

SDKs

Skills

Plugins

Prerequisites

Install

Quickstart

Model identifiers

STT reference

TTS reference

Text chunking

Warm standby connections

Failover

Bring your own key (BYOK)

Region routing

Plugin events

Migrating from earlier versions

Next steps

​Prerequisites

​Install

​Quickstart

​Model identifiers

​STT reference

​TTS reference

​Text chunking

​Warm standby connections

​Failover

​Bring your own key (BYOK)

​Region routing

​Plugin events

​Migrating from earlier versions

​Next steps

Prerequisites

Install

Quickstart

Model identifiers

STT reference

TTS reference

Text chunking

Warm standby connections

Failover

Bring your own key (BYOK)

Region routing

Plugin events

Migrating from earlier versions

Next steps