Documentation

Back to Home

Python SDK

Server-side integration for Avatario avatars

Introduction

The Avatario Python SDK enables real-time audio streaming and video communication integration with Avatario services. This SDK is typically used on the server side to stream audio to avatars displayed in web browsers.

Prerequisites

  • Avatario API key (available in your dashboard)
  • Python >= 3.8
  • Stable internet connection

Installation

python
pip install avatario-python-sdk

Core Methods

Constructor

python
Avatario(api_key: str, room_name: str)

Initializes the Avatario client connection.

Parameters:

  • api_key (str): Your Avatario API key.
  • room_name (str): Target room name for communication.

initialize()

python
initialize() -> None

Establishes connection to the Avatario room and starts background services.

Example:

python
client.initialize()

send_audio()

python
send_audio(audio_frame: bytes) -> None

Streams audio data to the Avatario service.

Parameters:

  • audio_frame (bytes): Raw audio data in PCM16 format.

Requirements:

  • Audio data must have sample rate >= 16KHz.

Example:

python
# Generate or stream audio frames
sample_audio = b'\x00' * 320  # 20ms of silence
client.send_audio(sample_audio)

interrupt()

python
interrupt() -> None

Immediately stops current media playback and clears the audio buffer.

Example:

python
client.interrupt()  # Stop current playback

resume()

python
resume() -> None

Resumes media playback after interruption.

Example:

python
client.resume()

close()

python
close() -> None

Stops the client session.

Example:

python
client.close()
Warning: Always call close() when done to prevent unnecessary resource usage and billing.

Supported Integrations

We officially support integration with LiveKit Agents, allowing you to use Avatario avatars with LiveKit-powered AI agents. Visit the LiveKit Agents documentation to learn more about building AI agents with LiveKit.

Coming soon: Integration with Pipecat for enhanced AI agent capabilities.

We are continuously adding more integration options. If you have specific integration needs, please contact our support team.

Troubleshooting

Common Errors

  • Connection Issues: Verify API key validity and network connectivity
  • Audio Problems: Validate audio has sample rate >= 16KHz
  • Room Connection Failures: Check that the room name is correct

Audio Format Requirements

  • Format: PCM16 (16-bit PCM)
  • Sample Rate: >= 16KHz (recommended 24KHz for best quality)
  • Channels: Mono

Related Topics