most-match-32106
11/30/2025, 11:08 AMlively-winter-88668
12/01/2025, 9:59 AMmost-match-32106
12/03/2025, 7:19 AMlively-winter-88668
12/03/2025, 9:31 AMmost-match-32106
12/03/2025, 10:46 AMlively-winter-88668
12/03/2025, 11:52 AMmost-match-32106
12/03/2025, 11:58 AMmost-match-32106
12/11/2025, 1:32 PMrefined-appointment-81829
12/11/2025, 2:25 PMAvatarSession class that manages the connection between the voice agent and the avatar service. The avatar appears as a separate participant in the LiveKit room, receiving audio from the agent and publishing video back.
Implementation Steps
1. Create Plugin Structure
Create a new plugin package with the following structure:
# livekit/plugins/yourservice/__init__.py
from .avatar import AvatarSession
from .api import YourServiceException
__all__ = ["AvatarSession", "YourServiceException"]
2. Implement AvatarSession Class
The AvatarSession class is the core component that manages the avatar lifecycle:
class AvatarSession:
"""Your Service avatar session"""
def __init__(
self,
*,
api_key: NotGivenOr[str] = NOT_GIVEN,
api_url: NotGivenOr[str] = NOT_GIVEN,
avatar_participant_identity: NotGivenOr[str] = NOT_GIVEN,
avatar_participant_name: NotGivenOr[str] = NOT_GIVEN,
# Add your service-specific config here
) -> None:
# Initialize your API client and configuration
3. Implement the start() Method
The start() method handles the connection flow:
async def start(
self,
agent_session: AgentSession,
room: rtc.Room,
*,
livekit_url: NotGivenOr[str] = NOT_GIVEN,
livekit_api_key: NotGivenOr[str] = NOT_GIVEN,
livekit_api_secret: NotGivenOr[str] = NOT_GIVEN,
) -> None:
# 1. Get local participant identity
job_ctx = get_job_context()
local_participant_identity = job_ctx.local_participant_identity
# 2. Create LiveKit token for avatar participant
livekit_token = (
api.AccessToken(api_key=livekit_api_key, api_secret=livekit_api_secret)
.with_kind("agent")
.with_identity(self._avatar_participant_identity)
.with_name(self._avatar_participant_name)
.with_grants(api.VideoGrants(room_join=True, room=room.name))
.with_attributes({ATTRIBUTE_PUBLISH_ON_BEHALF: local_participant_identity})
.to_jwt()
)
# 3. Call your service API to start session
session_data = await self._api.start_session(
livekit_url=livekit_url,
livekit_token=livekit_token,
# Your service-specific parameters
)
# 4. Configure audio output routing
agent_session.output.audio = DataStreamAudioOutput(
room=room,
destination_identity=self._avatar_participant_identity,
sample_rate=SAMPLE_RATE,
wait_remote_track=rtc.TrackKind.KIND_VIDEO,
)
4. Create API Client
Implement an API client to communicate with your avatar service:
class YourServiceAPI:
async def start_session(
self,
livekit_url: str,
livekit_token: str,
# Your parameters
) -> dict:
# Make HTTP request to your service
async with self._http_session.post(
f"{self._api_url}/v1/session",
json={
"livekit_url": livekit_url,
"livekit_token": livekit_token,
# Your service-specific config
}
) as response:
return await response.json()
Key Implementation Details
Token Generation
All avatar services use the ATTRIBUTE_PUBLISH_ON_BEHALF attribute to allow the avatar participant to publish tracks on behalf of the agent avatar.py:88-99 .
Audio Output Routing
Two main patterns exist for audio routing:
• `DataStreamAudioOutput`: Streams audio directly to the avatar participant avatar.py:116-121
• `QueueAudioOutput`: Buffers audio for synchronized playback avatar.py:127-131
Sample Rate Configuration
Different services use different sample rates:
• LiveAvatar: 24000 Hz avatar.py:30
• Anam: 24000 Hz avatar.py:25
• AvatarTalk: 16000 Hz avatar.py:16
TypeScript Implementation
For TypeScript/JavaScript implementations, follow the same pattern
Best Practices
1. Error Handling: Implement proper error handling with custom exceptions __init__.py:6-7
2. Logging: Add structured logging for debugging avatar.py
3. Retry Logic: Use APIConnectOptions for configurable retry behavior avatar.py:112-142
4. Cleanup: Implement proper session cleanup on shutdown avatar.py:85-90
Notes
• All avatar services create a separate participant in the LiveKit room
• The publish_on_behalf attribute is crucial for allowing the avatar to publish tracks
• Audio routing is handled through specialized audio output classes
• Each service may have unique configuration parameters and API endpoints
• Consider both Python and TypeScript implementations for broader compatibilityquaint-ambulance-32873
12/11/2025, 2:26 PMmost-match-32106
12/14/2025, 7:13 AMquaint-ambulance-32873
12/14/2025, 9:15 AMquaint-ambulance-32873
12/14/2025, 9:16 AMmost-match-32106
12/15/2025, 6:28 AMquaint-ambulance-32873
12/15/2025, 8:46 AMmost-match-32106
12/15/2025, 3:19 PM