Registry / llm-agents / livekit-plugins-deepgram

livekit-plugins-deepgram

JSON →
library1.7.1pypypi✓ verified 23d ago

livekit-plugins-deepgram is an Agent Framework plugin that provides integrations for Deepgram's Speech-to-Text (STT) and Text-to-Speech (TTS) services within LiveKit agents. Currently at version 1.5.2, it is part of the actively developed LiveKit Agents ecosystem, which sees frequent updates and new features.

pip install livekit-plugins-deepgram
INSTALL
IMPORT
SIG · LIVEKIT-PLUGINS-DE
L
livekit-plugins-deepgram
llm-agentspythonv1.7.1
Install
15.5s avg
Import
5442ms
Disk
301MB
Pass rate
9/ 10
Env Coverage9 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ 0.1s
✓ 20.9s
py 3.11
✕ timeout
✓ 18.5s
py 3.12
✓ —
✓ 15.4s
py 3.13
✓ —
✓ 15.3s
py 3.9
✓ —
✓ 23s
301MB installed
● package 301MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

deepgram
from livekit.plugins import deepgram
STT
from livekit.plugins.deepgram import STT
from livekit.plugins.deepgram.stt import STT
While functional, direct import from 'livekit.plugins.deepgram' is the canonical path.
TTS
from livekit.plugins.deepgram import TTS
from livekit.plugins.deepgram.tts import TTS
Direct import from 'livekit.plugins.deepgram' is preferred for consistency.

This quickstart demonstrates how to initialize Deepgram STT and TTS plugins for use within a LiveKit Agent. It highlights the use of `deepgram.STT` and `deepgram.TTS` classes, alongside a VAD and LLM, typically within a `VoiceAssistant` or `AgentSession`. It's crucial to set the `DEEPGRAM_API_KEY` environment variable.

import os import asyncio from livekit.agents import llm, stt, tts, vad from livekit.agents.voice_assistant import VoiceAssistant from livekit.agents.utils import AudioStream from livekit.plugins import deepgram, openai, silero # Ensure Deepgram API key is set in environment variables or passed directly os.environ['DEEPGRAM_API_KEY'] = os.environ.get('DEEPGRAM_API_KEY', 'your_deepgram_api_key_here') os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your_openai_api_key_here') async def main(): # Example using Deepgram for STT and TTS, and OpenAI for LLM deepgram_stt = deepgram.STT(model='nova-2') deepgram_tts = deepgram.TTS(model='aura-2-asteria-en') openai_llm = openai.LLM(model='gpt-4o-mini') silero_vad = silero.VAD.get_default_vad() assistant = VoiceAssistant( stt=deepgram_stt, tts=deepgram_tts, llm=openai_llm, vad=silero_vad, context_timeout=15, # seconds interrupt_sensitivity=0.5, ) print("VoiceAssistant initialized. You can now use deepgram_stt, deepgram_tts in your agent session.") # In a real agent, you would integrate this into an AgentSession # For example: AgentSession(llm=openai_llm, stt=deepgram_stt, tts=deepgram_tts, ...) # Simulate text-to-speech async for chunk in deepgram_tts.synthesize('Hello from LiveKit and Deepgram!'): if chunk.type == AudioStream.Type.ELEMENT: print(f"Received audio chunk: {len(chunk.data)} bytes") if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingLiveKit Agents v1.5.0 introduced a new `TurnHandlingOptions` API. Old keyword arguments like `min_endpointing_delay` and `allow_interruptions` in `AgentSession` are deprecated and will be removed in v2.0. This affects how turn detection and interruption handling are configured for agents using Deepgram STT.
fix
Migrate agent session configuration to use the new `turn_handling` dictionary argument with `TurnHandlingOptions` for endpointing and interruption settings. For example: `AgentSession(turn_handling={'turn_detection': 'stt', 'endpointing': {'min_delay': 0.5}, 'interruption': {'enabled': True}})` [11].
affects: livekit-agents >= 1.5.0
gotchaWhen using Deepgram plugins directly (not via LiveKit Inference), a Deepgram API key is required. This key must be provided either as an argument to the plugin constructor (e.g., `deepgram.STT(api_key='...')`) or, more commonly, by setting the `DEEPGRAM_API_KEY` environment variable. Failure to provide it will result in authentication errors.
fix
Ensure the `DEEPGRAM_API_KEY` environment variable is correctly set in your deployment environment or pass the `api_key` argument explicitly during plugin instantiation. [3, 6, 7]
affects: All versions
gotchaSpecific combinations of Deepgram's `nova-3-general` model with certain non-English languages (e.g., Spanish, French) and parameters like `endpointing=false` and `vad_events=true` can lead to `WSServerHandshakeError: 400`. While this might be a Deepgram API-side issue, it manifests when using the LiveKit plugin.
fix
If encountering 400 errors with `nova-3-general` for non-English languages, try using `nova-2-general` for those languages or adjust `endpointing` and `vad_events` parameters. Monitor Deepgram's documentation for updates on model support for these specific parameter combinations. [19]
affects: All versions using nova-3-general with specific configurations
deprecatedThe `keywords` parameter for Deepgram STT is deprecated and should be replaced with `keyterm` for improved recognition accuracy, especially when using Nova-3 models. Using `keywords` may still work but is not recommended and might be removed in future versions.
fix
Update your STT configuration to use `keyterm` instead of `keywords` when specifying terms to boost recognition accuracy. Example: `deepgram.STT(model='nova-3', keyterm=['LiveKit', 'agents'])`. [6]
affects: livekit-plugins-deepgram >= 1.4.x
gotchaEven when using Deepgram Flux (e.g., `turn_detection='stt'`) for advanced turn detection, it's recommended to still include a Voice Activity Detection (VAD) plugin like Silero. Flux handles turn detection, but a separate VAD is crucial for responsive interruption handling, allowing the agent to detect when a user speaks over the agent's response.
fix
Always include a VAD plugin (e.g., `silero.VAD.get_default_vad()`) in your `AgentSession` or `VoiceAssistant` configuration, even when Deepgram Flux is used for turn detection. [4, 5]
affects: All versions
Errors
Common errors & fixes
aiohttp.client_exceptions.WSServerHandshakeError: 400, message='Invalid response status'
This error often indicates that invalid parameters, an unsupported model, or an incorrect language code was sent to the Deepgram API via the livekit-plugins-deepgram plugin, resulting in a bad request.
fix
Review the parameters passed to `deepgram.STT()` or `deepgram.TTS()`, ensuring that the model, language, and other options are valid and supported by Deepgram's API and your Deepgram account's features. Refer to the Deepgram documentation and the `livekit-plugins-deepgram` API reference for correct usage.
deepgram connection failed, retrying in 2s
This warning/error message typically signifies a temporary network issue, an invalid Deepgram API key, or a problem with Deepgram's service availability, preventing the plugin from establishing a stable connection.
fix
Check your internet connection, verify that your `DEEPGRAM_API_KEY` environment variable is correctly set and valid, and confirm the Deepgram API status. Persistent issues may require checking firewall settings or contacting Deepgram support.
AttributeError: module 'livekit.plugins.deepgram' has no attribute 'TTS'
This error usually occurs when trying to use the `TTS` class from `livekit.plugins.deepgram` with an older version of the library where TTS functionality was not yet available or its import path has changed due to updates.
fix
Ensure you have the latest version of `livekit-plugins-deepgram` installed (`pip install --upgrade livekit-plugins-deepgram`). If the issue persists after upgrading, verify the correct import path for `TTS` according to the most recent LiveKit Agents and Deepgram plugin documentation.
livekit.agents.utils.api.APIStatusError: 401, message='Unauthorized'
This is an authentication error, indicating that the Deepgram API key provided is either missing, invalid, expired, or does not have the necessary permissions to access the requested Deepgram service.
fix
Set your Deepgram API key as an environment variable named `DEEPGRAM_API_KEY`. If it's already set, double-check its accuracy in your Deepgram console and ensure it's loaded correctly by your application.
Upgrade
Version history
1.7.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
livekit-agentsrequiredCore framework for building LiveKit agents
deepgram-sdkrequiredUnderlying Deepgram API client
Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
1
Resources
livekit-plugins-deepgram — pip install livekit-plugins-deepgram · libregistry