{"id":4086,"library":"livekit-plugins-deepgram","title":"LiveKit Deepgram Plugin","description":"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.","status":"active","version":"1.5.2","language":"en","source_language":"en","source_url":"https://github.com/livekit/agents","tags":["livekit","deepgram","speech-to-text","text-to-speech","ai-agents","realtime","voice-ai"],"install":[{"cmd":"pip install livekit-plugins-deepgram","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core framework for building LiveKit agents","package":"livekit-agents","optional":false},{"reason":"Underlying Deepgram API client","package":"deepgram-sdk","optional":false}],"imports":[{"symbol":"deepgram","correct":"from livekit.plugins import deepgram"},{"note":"While functional, direct import from 'livekit.plugins.deepgram' is the canonical path.","wrong":"from livekit.plugins.deepgram.stt import STT","symbol":"STT","correct":"from livekit.plugins.deepgram import STT"},{"note":"Direct import from 'livekit.plugins.deepgram' is preferred for consistency.","wrong":"from livekit.plugins.deepgram.tts import TTS","symbol":"TTS","correct":"from livekit.plugins.deepgram import TTS"}],"quickstart":{"code":"import os\nimport asyncio\nfrom livekit.agents import llm, stt, tts, vad\nfrom livekit.agents.voice_assistant import VoiceAssistant\nfrom livekit.agents.utils import AudioStream\nfrom livekit.plugins import deepgram, openai, silero\n\n# Ensure Deepgram API key is set in environment variables or passed directly\nos.environ['DEEPGRAM_API_KEY'] = os.environ.get('DEEPGRAM_API_KEY', 'your_deepgram_api_key_here')\nos.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your_openai_api_key_here')\n\nasync def main():\n    # Example using Deepgram for STT and TTS, and OpenAI for LLM\n    deepgram_stt = deepgram.STT(model='nova-2')\n    deepgram_tts = deepgram.TTS(model='aura-2-asteria-en')\n    openai_llm = openai.LLM(model='gpt-4o-mini')\n    silero_vad = silero.VAD.get_default_vad()\n\n    assistant = VoiceAssistant(\n        stt=deepgram_stt,\n        tts=deepgram_tts,\n        llm=openai_llm,\n        vad=silero_vad,\n        context_timeout=15, # seconds\n        interrupt_sensitivity=0.5,\n    )\n\n    print(\"VoiceAssistant initialized. You can now use deepgram_stt, deepgram_tts in your agent session.\")\n    # In a real agent, you would integrate this into an AgentSession\n    # For example: AgentSession(llm=openai_llm, stt=deepgram_stt, tts=deepgram_tts, ...)\n    \n    # Simulate text-to-speech\n    async for chunk in deepgram_tts.synthesize('Hello from LiveKit and Deepgram!'):\n        if chunk.type == AudioStream.Type.ELEMENT:\n            print(f\"Received audio chunk: {len(chunk.data)} bytes\")\n        \n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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].","message":"LiveKit 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.","severity":"breaking","affected_versions":"livekit-agents >= 1.5.0"},{"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]","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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]","message":"Specific 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.","severity":"gotcha","affected_versions":"All versions using nova-3-general with specific configurations"},{"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]","message":"The `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.","severity":"deprecated","affected_versions":"livekit-plugins-deepgram >= 1.4.x"},{"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]","message":"Even 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}