@kaltura-sdk/avatars

Core implementation of AvatarClientManager — the state machine-driven client for Kaltura's conversational avatar. Runs on xstate + @unisphere/core reactive stores; owns the whole connection lifecycle (RTC session, chat, captions, screen share, tap-to-talk, client tools, Kaltura context).

For a framework-free, CDN-loadable build, use @kaltura-sdk/avatars-esm — it re-exports this package.

Usage

import { AvatarClientManager } from '@kaltura-sdk/avatars';

const manager = new AvatarClientManager({
  actions: { showNotification }, // optional, defaults to a noop
  debugMode: true, // optional, default false
  logger, // optional — UnisphereLoggerType, defaults to an internal 'avatar-client' logger
  runtimeSettings, // AvatarRuntimeSettings
  kalturaAnalyticsService, // optional, no-ops if omitted
  pubSubService, // optional, no-ops if omitted
  registerDeveloperTools: (actor) => {}, // optional, e.g. xstate inspector
  videoContainerId: 'avatar-video', // optional — auto-joins STV once castMode is "webrtc"
});

manager.connectionStatus.onChanges((status) => console.log(status));
manager.connect({ dynamicVariables, kickOffPhrase });
manager.disconnect();
manager.stop(); // full teardown, unsubscribes everything

connect()/disconnect() are sync (fire-and-forget) — read outcomes off the reactive stores (connectionStatus, castMode, disconnectData, etc).

API surface

• Lifecycle: connect(), disconnect(), reconnect(), stop(), connectionStatus, playerUrl, sessionId, castMode, turnServerURL, disconnectData
• Pause/resume: pause(), resume(), pauseAfterSpeaking(), isPaused
• Chat & content: askViaText(), chatLog, content, setLocalContent(), clearContent(), agentData
• Screen share: startScreenShare(), stopScreenShare(), screenShareInfo
• Tap-to-talk: tapToTalkStart(), tapToTalkEnd(), toggleTapToTalkMode(), tapToTalkInfo
• Captions: captions (state + toggle/setReplacements/setFilter)
• Kaltura context: kalturaContext, toggleKalturaContext(), updateDynamicVariables()
• Client tools: registerClientTools(), unregisterClientTools(), registeredClientTools, clientToolCallLog
• Session metadata: threadId, setExternalThreadId(), isPreviewMode, contextSelectorVisible, features, agentPreviewUrl, agentPreviewImageUrl, serverUrl
• RTC/device passthrough: audioState, audioVolumeLevel, devicesList, joinSTV(), leaveSTV(), changeDevice(), toggleMuteAudio()
• Player events: onPlayerReady(), onPlayerError()

All getters return @unisphere/core reactive stores (.consumer, subscribe via .onChanges).

connection is a deprecated back-compat facade kept only for consumers not yet migrated to the manager's own getters/methods.