Skip to main content

​
Lifecycle

​
init()

Initializes the session and connects to the avatar room. Returns a Promise that resolves when the avatar’s video track is ready, or rejects on failure. If immediatelyJoin is true (default), init() calls join() automatically. 
try {
  await avatar.init();
} catch (e) {
  console.error("Avatar init failed:", e);
}

​
join()

Connects to the avatar room. Called automatically by init() unless immediatelyJoin: false. Use this when you want manual control over the moment of connection.
​
opts.startAudioOff
boolean
Start with microphone muted. Defaults to the SDK config’s startAudioOff.
const root = document.querySelector<HTMLDivElement>("#avaturn-video")!;
const avatar = new AvaturnHead(root, { sessionToken, immediatelyJoin: false });
await avatar.init();
// ...user interaction...
await avatar.join({ startAudioOff: false });

​
dispose()

Terminates local SDK state — destroys the Daily call object and aborts pending requests. Does not close the backend session directly; the backend session ends via user_absent_timeout (default 60s) or an explicit DELETE /api/v1/sessions/{id}. Call this on unmount. 
await avatar.dispose();

​
attachDOMNode(node)

Moves the avatar video into a different DOM element without re-initializing. Also use this when you constructed AvaturnHead without a DOM element and now want to render it. Takes effect after init() has resolved.
​
node
HTMLElement
required
New container for the avatar video.
avatar.attachDOMNode(document.getElementById("avatar-container")!);

​
Events

​
on(event, callback) / off(event, callback)

Subscribe to or unsubscribe from SDK events. See Events for the full list.
​
event
string
required
Event name.
​
callback
function
required
Handler invoked when the event fires.
function onInit() { console.log("avatar ready"); }

avatar.on("init", onInit);
avatar.off("init", onInit);

​
Media devices

​
requestMediaDevices()

Returns the list of available media devices (microphones, speakers, cameras). 
const { devices } = await avatar.requestMediaDevices();
const microphones = devices.filter(d => d.kind === "audioinput");

​
setInputDevices({ audioDeviceId?, videoDeviceId? })

Selects input devices for the session. Pass only the keys you want to change — both fields are optional at runtime. Use false or null to disable a device.
​
audioDeviceId
string | false | null
Microphone device id from requestMediaDevices().
​
videoDeviceId
string | false | null
Camera device id. Most integrations leave this unset — the avatar’s video comes from the server, not the user’s camera.
await avatar.setInputDevices({ audioDeviceId: "microphone-id-123" });
Returns DailyDeviceInfos from the underlying transport.

​
setOutputDevice({ outputDeviceId })

Selects the speaker for avatar audio output. Always pass outputDeviceId.
​
outputDeviceId
string
required
Device id from requestMediaDevices().
await avatar.setOutputDevice({ outputDeviceId: "speaker-id-123" });
If outputDeviceId is omitted, the SDK silently returns the list of input devices instead of switching output. Always pass outputDeviceId explicitly.
Returns DailyDeviceInfos.

​
toggleLocalAudio(value?)

Mutes or unmutes the user’s microphone. With no argument, toggles the current state.
​
value
boolean
true = unmute, false = mute.
avatar.toggleLocalAudio();      // toggle
avatar.toggleLocalAudio(false); // mute

​
Legacy: text-echo

Legacy. These methods belong to the text-echo flow. New integrations should drive speech through a conversation engine instead.

​
task(text)

Sends text for the avatar to speak. If the avatar is already speaking, the fragment is queued. Returns { task_id: string }.
​
text
string
required
The text to speak.
const { task_id } = await avatar.task("Hello, world!");

​
cancelAllTasks()

Stops the current utterance and clears the queue. 
await avatar.cancelAllTasks();

​
changeVoice(config)

Switches the text-echo TTS voice for subsequent task() calls. Patches the session’s conversation engine config to a new text-echo config with the supplied TTS.
​
config
TTSConfig
required
{ engine: "elevenlabs", voice_id: string }. Only elevenlabs is currently accepted by the backend.
await avatar.changeVoice({ engine: "elevenlabs", voice_id: "voice_id_123" });