# LiveKit Plugins Resemble
Agent Framework plugin for voice synthesis with the [Resemble AI](https://www.resemble.ai/) API, using both their REST API and WebSocket streaming interface.
## Installation
```bash
pip install livekit-plugins-resemble
```
## Pre-requisites
You'll need an API key from Resemble AI. It can be set as an environment variable: `RESEMBLE_API_KEY`
Additionally, you'll need the voice UUID from your Resemble AI account.
## Examples
### Recommended
```python
import asyncio
from livekit.plugins.resemble import TTS
async def run_tts_example():
# Use TTS with async context manager for automatic resource cleanup
async with TTS(
api_key="your_api_key", # or set RESEMBLE_API_KEY environment variable
voice_uuid="your_voice_uuid",
# Optional parameters
sample_rate=44100, # Sample rate in Hz (default: 44100)
precision="PCM_16", # Audio precision (PCM_32, PCM_24, PCM_16, MULAW)
output_format="wav", # Output format (wav or mp3)
) as tts:
# One-off synthesis (uses REST API)
audio_stream = tts.synthesize("Hello, world!")
# Process chunks as they arrive
async for chunk in audio_stream:
# Audio data is in the 'frame.data' attribute of SynthesizedAudio objects
audio_data = chunk.frame.data
print(f"Received chunk: {len(audio_data)} bytes")
# Alternative: collect all audio at once into a single AudioFrame
audio_stream = tts.synthesize("Another example sentence.")
audio_frame = await audio_stream.collect()
print(f"Collected complete audio: {len(audio_frame.data)} bytes")
# Real-time streaming synthesis (uses WebSocket API)
# Only available for Business plan users in Resemble AI
stream = tts.stream()
await stream.synthesize_text("Hello, world!")
# Run the example
asyncio.run(run_tts_example())
```
### Alternative: Manual Resource Management
If you prefer to manage resources manually, make sure to properly clean up:
```python
import asyncio
from livekit.plugins.resemble import TTS
async def run_tts_example():
# Initialize TTS with your credentials
tts = TTS(
api_key="your_api_key",
voice_uuid="your_voice_uuid",
)
try:
# TTS operations
audio_stream = tts.synthesize("Hello, world!")
async for chunk in audio_stream:
# Access audio data correctly
process_audio(chunk.frame.data)
finally:
# Always clean up resources when done
await tts.aclose()
# Run the example
asyncio.run(run_tts_example())
```
### Resource Management
When using this plugin outside of the LiveKit agent framework, it's important to properly manage the TTS instance lifecycle:
1. **Preferred method**: Use the async context manager pattern (`async with TTS(...) as tts:`)
2. If managing manually, always call `await tts.aclose()` in a finally block
3. If you prefer to provide your own HTTP session, you can pass it using the `http_session` parameter:
```python
import aiohttp
async def with_custom_session():
async with aiohttp.ClientSession() as session:
async with TTS(
api_key="your_api_key",
voice_uuid="your_voice_uuid",
http_session=session
) as tts:
# Use TTS...
# No need to manually close anything - context managers handle it all
```
## Implementation Details
This plugin uses two different approaches to generate speech:
1. **One-off Synthesis** - Uses Resemble's REST API for simple text-to-speech conversion
2. **Streaming Synthesis** - Uses Resemble's WebSocket API for real-time streaming synthesis
The WebSocket streaming API is only available for Resemble AI Business plan users.
Raw data
{
"_id": null,
"home_page": "https://github.com/livekit/agents",
"name": "livekit-plugins-resemble",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": null,
"keywords": "webrtc, realtime, audio, video, livekit, resemble, tts",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/02/bd/8f598191cce9eed754456f3f8fdc2008514e55506c7484f45a3de1ac5eb8/livekit_plugins_resemble-0.1.1.tar.gz",
"platform": null,
"description": "# LiveKit Plugins Resemble\n\nAgent Framework plugin for voice synthesis with the [Resemble AI](https://www.resemble.ai/) API, using both their REST API and WebSocket streaming interface.\n\n## Installation\n\n```bash\npip install livekit-plugins-resemble\n```\n\n## Pre-requisites\n\nYou'll need an API key from Resemble AI. It can be set as an environment variable: `RESEMBLE_API_KEY`\n\nAdditionally, you'll need the voice UUID from your Resemble AI account.\n\n## Examples\n\n### Recommended\n\n```python\nimport asyncio\nfrom livekit.plugins.resemble import TTS\n\nasync def run_tts_example():\n # Use TTS with async context manager for automatic resource cleanup\n async with TTS(\n api_key=\"your_api_key\", # or set RESEMBLE_API_KEY environment variable\n voice_uuid=\"your_voice_uuid\",\n # Optional parameters\n sample_rate=44100, # Sample rate in Hz (default: 44100)\n precision=\"PCM_16\", # Audio precision (PCM_32, PCM_24, PCM_16, MULAW)\n output_format=\"wav\", # Output format (wav or mp3)\n ) as tts:\n # One-off synthesis (uses REST API)\n audio_stream = tts.synthesize(\"Hello, world!\")\n \n # Process chunks as they arrive\n async for chunk in audio_stream:\n # Audio data is in the 'frame.data' attribute of SynthesizedAudio objects\n audio_data = chunk.frame.data\n print(f\"Received chunk: {len(audio_data)} bytes\")\n \n # Alternative: collect all audio at once into a single AudioFrame\n audio_stream = tts.synthesize(\"Another example sentence.\")\n audio_frame = await audio_stream.collect()\n print(f\"Collected complete audio: {len(audio_frame.data)} bytes\")\n \n # Real-time streaming synthesis (uses WebSocket API)\n # Only available for Business plan users in Resemble AI\n stream = tts.stream()\n await stream.synthesize_text(\"Hello, world!\")\n \n\n\n# Run the example\nasyncio.run(run_tts_example())\n```\n\n### Alternative: Manual Resource Management\n\nIf you prefer to manage resources manually, make sure to properly clean up:\n\n```python\nimport asyncio\nfrom livekit.plugins.resemble import TTS\n\nasync def run_tts_example():\n # Initialize TTS with your credentials\n tts = TTS(\n api_key=\"your_api_key\", \n voice_uuid=\"your_voice_uuid\",\n )\n\n try:\n # TTS operations\n audio_stream = tts.synthesize(\"Hello, world!\")\n async for chunk in audio_stream:\n # Access audio data correctly\n process_audio(chunk.frame.data)\n finally:\n # Always clean up resources when done\n await tts.aclose()\n\n# Run the example\nasyncio.run(run_tts_example())\n```\n\n### Resource Management\n\nWhen using this plugin outside of the LiveKit agent framework, it's important to properly manage the TTS instance lifecycle:\n\n1. **Preferred method**: Use the async context manager pattern (`async with TTS(...) as tts:`)\n2. If managing manually, always call `await tts.aclose()` in a finally block\n3. If you prefer to provide your own HTTP session, you can pass it using the `http_session` parameter:\n\n```python\nimport aiohttp\n\nasync def with_custom_session():\n async with aiohttp.ClientSession() as session:\n async with TTS(\n api_key=\"your_api_key\",\n voice_uuid=\"your_voice_uuid\",\n http_session=session\n ) as tts:\n # Use TTS...\n # No need to manually close anything - context managers handle it all\n```\n\n## Implementation Details\n\nThis plugin uses two different approaches to generate speech:\n\n1. **One-off Synthesis** - Uses Resemble's REST API for simple text-to-speech conversion\n2. **Streaming Synthesis** - Uses Resemble's WebSocket API for real-time streaming synthesis\n\nThe WebSocket streaming API is only available for Resemble AI Business plan users. \n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "LiveKit Agents Plugin for Resemble AI",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://docs.livekit.io",
"Homepage": "https://github.com/livekit/agents",
"Source": "https://github.com/livekit/agents",
"Website": "https://livekit.io/"
},
"split_keywords": [
"webrtc",
" realtime",
" audio",
" video",
" livekit",
" resemble",
" tts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1199a260f36429ed9afa32bf2d24cc49bf21fb1dd38ffff7e94b1a3e7b50ad0c",
"md5": "7116c696a3dd06f6cefb98209f476135",
"sha256": "9cfcfb915d5a9a8d127477af175ea77ea91443547a739c7c66159adacc2d862e"
},
"downloads": -1,
"filename": "livekit_plugins_resemble-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7116c696a3dd06f6cefb98209f476135",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 9212,
"upload_time": "2025-04-07T13:45:14",
"upload_time_iso_8601": "2025-04-07T13:45:14.093940Z",
"url": "https://files.pythonhosted.org/packages/11/99/a260f36429ed9afa32bf2d24cc49bf21fb1dd38ffff7e94b1a3e7b50ad0c/livekit_plugins_resemble-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "02bd8f598191cce9eed754456f3f8fdc2008514e55506c7484f45a3de1ac5eb8",
"md5": "1c3e2448c9dc8fba0c958f8767167c9b",
"sha256": "b7b9d98be12c0f2a96bebdabad5985a5f544d1291cc45eef387d165632b6646d"
},
"downloads": -1,
"filename": "livekit_plugins_resemble-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1c3e2448c9dc8fba0c958f8767167c9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 9307,
"upload_time": "2025-04-07T13:45:18",
"upload_time_iso_8601": "2025-04-07T13:45:18.600650Z",
"url": "https://files.pythonhosted.org/packages/02/bd/8f598191cce9eed754456f3f8fdc2008514e55506c7484f45a3de1ac5eb8/livekit_plugins_resemble-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-07 13:45:18",
"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-resemble"
}
JSON
