Community-maintained integration. This service is built and maintained by Akapulu Labs. Pipecat does not test or officially support it. Please report issues and request changes on the source repository. Learn more about community integrations.
Overview
AkapuluAvatar is a Pipecat processor that sits after your speech model. It
sends assistant audio to the Akapulu Labs worker. The
worker joins the Daily room for that call and publishes the avatar video and
audio. Your voice bot itself does not publish camera or microphone.
On InterruptionFrame, the processor tells the worker to cut the in-flight
reply so the avatar can stop speaking when the caller barges in.
Source Repository
Source code, examples, and issues for the Akapulu Labs integration
PyPI Package
The
pipecat-akapulu package on PyPIAkapulu Labs Docs
Create the Daily room, start a live session, and wire
AkapuluAvatarAkapulu Labs
Create an account and get an API key
Installation
This is a community-maintained package distributed separately frompipecat-ai:
Prerequisites
Akapulu Labs account setup
Before using the Akapulu Labs video avatar, you need:- Akapulu Labs API key: Create an account at Akapulu Labs
- Avatar ID: UUID of a public or private avatar. See our catalog for public avatars. Private avatars are available on our enterprise plan.
- Daily API key: Daily is used to create the
room when you call
create_akapulu_call
Required environment variables
AKAPULU_API_KEY: Your Akapulu Labs API keyDAILY_API_KEY: Your Daily API key (create_akapulu_callreads this)
Configuration
create_akapulu_call
Run this on your server before the voice bot starts. It creates a private Daily
room for three participants and mints the browser, voice-bot, and avatar worker
tokens. It uses your AKAPULU_API_KEY to POST /api/live-sessions/ to
Akapulu Labs. It returns room_url, bot_token,
browser_token, and session_id. The worker token is sent to Akapulu Labs and
is not returned.
UUID of a public or private avatar. See our
catalog for public avatars. Private avatars are
available on our enterprise plan.
HTTP client for creating the Daily room and for the Akapulu Labs live-session
request.
Daily room lifetime in seconds. Defaults to two hours. Daily removes everyone
when the room expires.
create_akapulu_call spawns an avatar worker. That worker can take 5 to 10
seconds to start up.While that worker starts up, AkapuluAvatar pushes
RTVI server messages:type:statuscall_is_ready: true when the first video frame is publishedcompletion_percentlatest_update_text
call_is_ready is true.create_akapulu_call.
We recommend these room settings:
privacy:privatemax_participants:3(the end user joins asYou, your voice bot joins as the name you pass toDailyTransport,Assistantin the example below, and the avatar worker joins asAvatar)enable_chat: offenable_prejoin_ui: offeject_at_room_exp: on, so Daily removes everyone whenexpis reached
/api/live-sessions/ to Akapulu Labs
with avatar_id, show_ai_label, room_url, and avatar_token. The response
is session_id.
The avatar worker joins the room as
Avatar and publishes audio and video.
Its token needs permission to send audio and video.Daily shows the end user and the avatar. The voice bot is in the room and
does not get its own tile.create_akapulu_call already does this.AkapuluAvatar
Constructor parameters for AkapuluAvatar:
Seconds to wait after
TTSStoppedFrame before the audio counts as stopped, so
the avatar can transition from speaking back to idle. We recommend 0. Custom
engineered pipelines with voice bots that trickle in audio more slowly might
need different values. See our enterprise
plan.See the source repository for
the authoritative, up-to-date list of parameters, loading-status RTVI
messages, and the complete example.
Usage
When you construct your voice bot and create your transport processor, leave audio out and video out off. Your voice bot will not publish audio or video into the Daily room. The Akapulu Labs avatar worker publishes the audio and video. AddAkapuluAvatar after your TTS processor so it forwards that audio
to the avatar worker.
browser_token as You and stays subscribed to the
Avatar microphone. That track is the voice the person on the call hears.
Pipecat subscribes the voice bot to every remote microphone. When Avatar
joins, turn that microphone off so the voice bot only hears the caller. Call
this once. Do not set subscriptions again on a participant update.
The avatar worker needs about 800 ms of assistant audio before it starts
rendering the video. The render itself, given the audio, only takes around
150ms.You might see added latency in your bot’s response even if your TTS
provider’s TTFA is low, due to this buffer accumulation.A TTS that trickles audio in slowly fills that buffer late, so the response
is slower and the avatar gestures less.We recommend a TTS that sends audio in waves.Cartesia has been the best in
our testing.