​
Documentation for StreamingAvatar Class

This document provides a detailed explanation of the StreamingAvatar class and its usage, including the parameters, methods, events, and examples.

​
StreamingAvatar Class Documentation

​
Constructor

​
new StreamingAvatar(params?: { token: string, openapiHost?: string })

Creates an instance of StreamingAvatar.

​
Parameters:

  • params.token (string) - Required. Open API authentication token.
  • params.openapiHost (string) - Optional. API host URL.

​
Example Usage:

const avatar = new StreamingAvatar({ token: "your-api-token" });

​
Public Methods

​
async startSession(videoContainer?: string, params?: InitParams): Promise<void>

Starts a new avatar session.

​
Parameters:

  • videoContainer (string) - The ID of the HTML container where the avatar video will be displayed.
  • params (InitParams) - Configuration options for the avatar session.

​
Example Usage:

await avatar.startSession("avatarContainer", {
  avatarId: "dvp_Tristan_cloth2_1080P",
  voiceId: "iP95p4xoKVk53GoZ742B",
  language: "en",
  modeType: "Dialogue",
  background: "https://example.com/background.jpg",
  duration: 120,
});

​
async startSessionWithCredentials(videoContainer?: string, params?: CredentialParams): Promise<void>

Starts a session using predefined credentials.

​
Parameters:

  • videoContainer (string) - The ID of the HTML container for the avatar video.
  • params (CredentialParams) - Credential details for joining an Agora session.

​
Example Usage:

await avatar.startSessionWithCredentials("avatarContainer", {
  _id: "session-id",
  credentials: {
    agora_uid: 12345,
    agora_app_id: "your-agora-app-id",
    agora_channel: "your-channel-name",
    agora_token: "your-agora-token",
  },
});

​
async closeStreaming(): Promise<void>

Closes the current streaming session.

​
Example Usage:

await avatar.closeStreaming();

​
async sendMessage(message: string): Promise<void>

Sends a text message to the avatar.

​
Parameters:

  • message (string) - The message to send.

​
Example Usage:

await avatar.sendMessage("Hello, how are you?");

​
async toggleMic(): Promise<void>

Toggles the microphone on or off.

​
Example Usage:

await avatar.toggleMic();

​
initDom(containerId: string, params?: InitParams): void

Initializes the user interface for the avatar.

​
Parameters:

  • containerId (string) - The ID of the HTML element to contain the avatar UI.
  • params (InitParams) - Optional parameters for session configuration.

​
Example Usage:

avatar.initDom("avatarContainer", {
  avatarId: "dvp_Tristan_cloth2_1080P",
  voiceId: "iP95p4xoKVk53GoZ742B",
  language: "en",
  modeType: "Dialogue",
  background: "https://example.com/background.jpg",
  duration: 120,
});

​
Event Handling

​
on(event: StreamEvents, handler: (event: CustomEvent) => void): void

Registers an event listener.

​
Parameters:

  • event (StreamEvents) - The event name.
  • handler (function) - The callback function to execute when the event occurs.

​
Example Usage:

avatar.on(StreamEvents.ONMESSAGE, (event) => {
  console.log("Message received:", event.detail);
});

​
off(event: StreamEvents, handler: (event: CustomEvent) => void): void

Removes an event listener.

​
Example Usage:

avatar.off(StreamEvents.ONMESSAGE, messageHandler);

​
emit(event: StreamEvents, params?: any): void

Manually triggers an event.

​
Example Usage:

avatar.emit(StreamEvents.READY, { ready: true });

​
Properties

​
micStatus: boolean

Returns the current microphone status.

​
Example Usage:

console.log(avatar.micStatus); // true or false

​
classStatus: object

Returns the current state of the StreamingAvatar instance.

​
Example Usage:

console.log(avatar.classStatus);

​
Enums

​
StreamEvents

Defines event types emitted by the class.
Event NameDescription
READYFired when the session is ready.
ONMESSAGEFired when a message is received.
ERRORFired when an error occurs.
WILLEXPIREFired when the session is about to expire.
EXPIREDFired when the session expires.
CLOSEDFired when the session is closed.

​
Example Usage:

avatar.on(StreamEvents.ERROR, (event) => {
  console.error("Error:", event.detail);
});

​
Interfaces

​
InitParams

Defines parameters for initializing a session.
PropertyTypeDescription
avatarIdstringAvatar ID.
voiceIdstringVoice ID.
languagestringLanguage code (e.g., ‘en’).
modeTypestringInteraction mode (‘Repeat’ or ‘Dialogue’).
backgroundstringBackground image URL.
voice_interaction_onbooleanEnable voice interaction.
durationnumberSession duration in seconds.

​
CredentialParams

Defines credentials for joining an existing session.
PropertyTypeDescription
voiceIdstringVoice ID.
languagestringLanguage code.
modeTypestringInteraction mode.
backgroundstringBackground image URL.
_idstringSession ID.
credentialsobjectAgora credentials.

​
Example Usage

const avatar = new StreamingAvatar({ token: "your-api-token" });

avatar.initDom("avatarContainer", {
  avatarId: "dvp_Tristan_cloth2_1080P",
  voiceId: "iP95p4xoKVk53GoZ742B",
  language: "en",
  modeType: "Dialogue",
  background: "https://example.com/background.jpg",
  duration: 120,
});

avatar.on(StreamEvents.ONMESSAGE, (event) => {
  console.log("Received message:", event.detail.text);
});

await avatar.startSession();
await avatar.sendMessage("Hello!");