# LiveKit Ultravox Plugin
LiveKit plugin for Ultravox's real-time speech-to-speech AI models, providing seamless integration with the LiveKit Agents framework.
## Installation
```bash
pip install livekit-plugins-ultravox
```
## Prerequisites
You'll need an API key from Ultravox. Set it as an environment variable:
```bash
export ULTRAVOX_API_KEY="your_api_key_here"
```
Optional: enable debug logs for the plugin (disabled by default):
```bash
export LK_ULTRAVOX_DEBUG=true
```
## Basic Usage
### Simple Voice Assistant
```python
import asyncio
from livekit.agents import Agent, AgentSession, JobContext, JobProcess, WorkerOptions, cli
from livekit.plugins import silero
from livekit.plugins.ultravox.realtime import RealtimeModel
async def entrypoint(ctx: JobContext):
await ctx.connect()
session: AgentSession[None] = AgentSession(
allow_interruptions=True,
vad=ctx.proc.userdata["vad"],
llm=RealtimeModel(
model_id="fixie-ai/ultravox",
voice="Mark",
),
)
await session.start(
agent=Agent(
instructions="You are a helpful voice assistant.",
),
room=ctx.room,
)
def prewarm(proc: JobProcess) -> None:
proc.userdata["vad"] = silero.VAD.load()
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))
```
### Voice Assistant with Tools
```python
from livekit.agents import function_tool, Agent, AgentSession, JobContext, JobProcess, WorkerOptions, cli
from livekit.plugins import silero
from livekit.plugins.ultravox.realtime import RealtimeModel
@function_tool
async def get_weather(location: str) -> str:
"""Get weather information for a location."""
return f"The weather in {location} is sunny and 72°F"
@function_tool
async def book_appointment(date: str, time: str) -> str:
"""Book an appointment."""
return f"Appointment booked for {date} at {time}"
async def entrypoint(ctx: JobContext):
await ctx.connect()
session: AgentSession[None] = AgentSession(
allow_interruptions=True,
vad=ctx.proc.userdata["vad"],
llm=RealtimeModel(model_id="fixie-ai/ultravox"),
)
await session.start(
agent=Agent(
instructions="You are a helpful assistant with access to weather and scheduling tools.",
tools=[get_weather, book_appointment],
),
room=ctx.room,
)
def prewarm(proc: JobProcess) -> None:
proc.userdata["vad"] = silero.VAD.load()
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))
```
## Configuration Options
### Ultravox API (/api/calls) Parameters
```python
RealtimeModel(
model_id="fixie-ai/ultravox", # Model to use (warn + pass-through if unknown)
voice="Mark", # Voice to use (warn + pass-through if unknown)
api_key=None, # API key (defaults to env var)
base_url=None, # API base URL (defaults to Ultravox API)
system_prompt="You are helpful.", # System prompt
input_sample_rate=16000, # Input audio sample rate
output_sample_rate=24000, # Output audio sample rate
client_buffer_size_ms=60, # Audio buffer size (min 200ms used on WS)
http_session=None, # Custom HTTP session
)
Notes:
- Unknown models/voices: the plugin logs a warning and sends them as-is; the server validates.
- Metrics: the plugin emits a single `metrics_collected` event per generation. To log them,
add a listener in your app and call the helper:
```python
from livekit.agents import metrics
@session.on("metrics_collected")
def on_metrics_collected(ev):
metrics.log_metrics(ev.metrics)
```
```
Raw data
{
"_id": null,
"home_page": null,
"name": "livekit-plugins-ultravox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": null,
"keywords": "audio, livekit, realtime, video, webrtc",
"author": null,
"author_email": "LiveKit <hello@livekit.io>",
"download_url": "https://files.pythonhosted.org/packages/67/d1/16ea53fe620f4b2328c56b2c40e7a22ce2e66a7ff30af85f0c7e182d5e70/livekit_plugins_ultravox-1.2.9.tar.gz",
"platform": null,
"description": "# LiveKit Ultravox Plugin\n\nLiveKit plugin for Ultravox's real-time speech-to-speech AI models, providing seamless integration with the LiveKit Agents framework.\n\n\n\n## Installation\n\n```bash\npip install livekit-plugins-ultravox\n```\n\n## Prerequisites\n\nYou'll need an API key from Ultravox. Set it as an environment variable:\n\n```bash\nexport ULTRAVOX_API_KEY=\"your_api_key_here\"\n```\n\nOptional: enable debug logs for the plugin (disabled by default):\n\n```bash\nexport LK_ULTRAVOX_DEBUG=true\n```\n\n## Basic Usage\n\n### Simple Voice Assistant\n\n```python\nimport asyncio\nfrom livekit.agents import Agent, AgentSession, JobContext, JobProcess, WorkerOptions, cli\nfrom livekit.plugins import silero\nfrom livekit.plugins.ultravox.realtime import RealtimeModel\n\nasync def entrypoint(ctx: JobContext):\n await ctx.connect()\n \n session: AgentSession[None] = AgentSession(\n allow_interruptions=True,\n vad=ctx.proc.userdata[\"vad\"],\n llm=RealtimeModel(\n model_id=\"fixie-ai/ultravox\",\n voice=\"Mark\",\n ),\n )\n \n await session.start(\n agent=Agent(\n instructions=\"You are a helpful voice assistant.\",\n ),\n room=ctx.room,\n )\n\ndef prewarm(proc: JobProcess) -> None:\n proc.userdata[\"vad\"] = silero.VAD.load()\n\nif __name__ == \"__main__\":\n cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))\n```\n\n### Voice Assistant with Tools\n\n```python\nfrom livekit.agents import function_tool, Agent, AgentSession, JobContext, JobProcess, WorkerOptions, cli\nfrom livekit.plugins import silero\nfrom livekit.plugins.ultravox.realtime import RealtimeModel\n\n@function_tool\nasync def get_weather(location: str) -> str:\n \"\"\"Get weather information for a location.\"\"\"\n return f\"The weather in {location} is sunny and 72\u00b0F\"\n\n@function_tool\nasync def book_appointment(date: str, time: str) -> str:\n \"\"\"Book an appointment.\"\"\"\n return f\"Appointment booked for {date} at {time}\"\n\nasync def entrypoint(ctx: JobContext):\n await ctx.connect()\n \n session: AgentSession[None] = AgentSession(\n allow_interruptions=True,\n vad=ctx.proc.userdata[\"vad\"],\n llm=RealtimeModel(model_id=\"fixie-ai/ultravox\"),\n )\n \n await session.start(\n agent=Agent(\n instructions=\"You are a helpful assistant with access to weather and scheduling tools.\",\n tools=[get_weather, book_appointment],\n ),\n room=ctx.room,\n )\n\ndef prewarm(proc: JobProcess) -> None:\n proc.userdata[\"vad\"] = silero.VAD.load()\n\nif __name__ == \"__main__\":\n cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))\n```\n\n\n## Configuration Options\n\n### Ultravox API (/api/calls) Parameters\n\n```python\nRealtimeModel(\n model_id=\"fixie-ai/ultravox\", # Model to use (warn + pass-through if unknown)\n voice=\"Mark\", # Voice to use (warn + pass-through if unknown)\n api_key=None, # API key (defaults to env var)\n base_url=None, # API base URL (defaults to Ultravox API)\n system_prompt=\"You are helpful.\", # System prompt\n input_sample_rate=16000, # Input audio sample rate\n output_sample_rate=24000, # Output audio sample rate\n client_buffer_size_ms=60, # Audio buffer size (min 200ms used on WS)\n http_session=None, # Custom HTTP session\n)\n\nNotes:\n- Unknown models/voices: the plugin logs a warning and sends them as-is; the server validates.\n- Metrics: the plugin emits a single `metrics_collected` event per generation. To log them,\n add a listener in your app and call the helper:\n\n```python\nfrom livekit.agents import metrics\n\n@session.on(\"metrics_collected\")\ndef on_metrics_collected(ev):\n metrics.log_metrics(ev.metrics)\n```\n```\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Agent Framework plugin for services from Ultravox",
"version": "1.2.9",
"project_urls": {
"Documentation": "https://docs.livekit.io",
"Source": "https://github.com/livekit/agents",
"Website": "https://livekit.io/"
},
"split_keywords": [
"audio",
" livekit",
" realtime",
" video",
" webrtc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cc758f7dc999f27650768a58122ddfa758dca70b847552a928c648e02e5fc118",
"md5": "1a576cf45379d754e5c9bcd0c8cb4cd5",
"sha256": "3bf1a59d687fa9abf80bc99e678c5aa21c08dd8dbce2c841a1a1ce56350d88db"
},
"downloads": -1,
"filename": "livekit_plugins_ultravox-1.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a576cf45379d754e5c9bcd0c8cb4cd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 20321,
"upload_time": "2025-09-15T18:06:22",
"upload_time_iso_8601": "2025-09-15T18:06:22.830561Z",
"url": "https://files.pythonhosted.org/packages/cc/75/8f7dc999f27650768a58122ddfa758dca70b847552a928c648e02e5fc118/livekit_plugins_ultravox-1.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "67d116ea53fe620f4b2328c56b2c40e7a22ce2e66a7ff30af85f0c7e182d5e70",
"md5": "b4aee056bdc18ebe9a8a28505def81f8",
"sha256": "ce8cb53b025e0ed1d5f9661c6a6ace5d78b3593dba9735a78c80e1807ddbe2f5"
},
"downloads": -1,
"filename": "livekit_plugins_ultravox-1.2.9.tar.gz",
"has_sig": false,
"md5_digest": "b4aee056bdc18ebe9a8a28505def81f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 18578,
"upload_time": "2025-09-15T18:06:23",
"upload_time_iso_8601": "2025-09-15T18:06:23.845027Z",
"url": "https://files.pythonhosted.org/packages/67/d1/16ea53fe620f4b2328c56b2c40e7a22ce2e66a7ff30af85f0c7e182d5e70/livekit_plugins_ultravox-1.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-15 18:06:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "livekit",
"github_project": "agents",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "livekit-plugins-ultravox"
}
JSON
