@keyframelabs/sdk 0.1.0 → 0.1.1

package/dist/PersonaSession.d.ts

@@ -0,0 +1,89 @@
+/**
+ * PersonaSession - Core SDK class for connecting to Persona avatars.
+ *
+ * Handles:
+ * - Creating sessions via Central API
+ * - Connecting to LiveKit room as "user" participant
+ * - Sending audio to "persona" via DataStream
+ * - Receiving video from "persona"
+ * - Interrupt signaling
+ */
+import type { PersonaSessionOptions, SessionState } from './types.js';
+/**
+ * PersonaSession manages the connection between your app and a Persona avatar.
+ *
+ * @example
+ * ```typescript
+ * const session = new PersonaSession({
+ *   // WebRTC URL, access token, and agent identity returned from KeyframeLab API (called from your server code)
+ *   serverUrl: websocket-url,
+ *   participantToken: webrtc-participant-token,
+ *   agentIdentity: agent_identity,
+ *   onVideoTrack: (track) => {
+ *     videoElement.srcObject = new MediaStream([track]);
+ *   },
+ * });
+ *
+ * await session.connect();
+ * session.sendAudio(audioBytes);
+ * await session.close();
+ * ```
+ */
+export declare class PersonaSession {
+    private options;
+    private room;
+    private _state;
+    private byteStreamWriter;
+    private writeQueue;
+    private autoFlushTimer;
+    constructor(options: PersonaSessionOptions);
+    /** Current session state */
+    get state(): SessionState;
+    private setState;
+    /**
+     * Connect to a Persona avatar session.
+     *
+     * Creates a session via Central API and connects to the LiveKit room.
+     */
+    connect(): Promise<void>;
+    private setupRoomListeners;
+    /**
+     * Send audio data to the persona for video synthesis.
+     *
+     * @param pcmData - 16-bit PCM audio at 24kHz
+     */
+    sendAudio(pcmData: Uint8Array): void;
+    /**
+     * Schedule auto-flush after a timeout.
+     * Called on each sendAudio() to reset the timer.
+     */
+    private scheduleAutoFlush;
+    /**
+     * Flush all pending audio writes.
+     * Call before close to ensure all audio is sent.
+     */
+    flush(): Promise<void>;
+    /**
+     * End the current audio turn and flush any buffered data.
+     *
+     * This is called automatically 300ms after the last sendAudio() call.
+     * You typically don't need to call this manually, but it's available
+     * if you need immediate flushing.
+     */
+    endAudioTurn(): Promise<void>;
+    /**
+     * Signal an interruption to the avatar.
+     *
+     * Clears any pending frames in the GPU node's publish queue,
+     * allowing the avatar to quickly respond to new audio.
+     *
+     * Call this when the user interrupts the agent (e.g., starts speaking
+     * while the agent is still talking).
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Close the session and clean up resources.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=PersonaSession.d.ts.map

package/dist/PersonaSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonaSession.d.ts","sourceRoot":"","sources":["../src/PersonaSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,OAAO,KAAK,EAEV,qBAAqB,EACrB,YAAY,EACb,MAAM,YAAY,CAAC;AA2BpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CACS;IACxB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,gBAAgB,CAAiC;IAGzD,OAAO,CAAC,UAAU,CAAoC;IAGtD,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,EAAE,qBAAqB;IAI1C,4BAA4B;IAC5B,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,OAAO,CAAC,QAAQ;IAOhB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B9B,OAAO,CAAC,kBAAkB;IAiC1B;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IA2BpC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBnC;;;;;;;;OAQG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBhC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4B7B"}

package/dist/PersonaSession.js

@@ -0,0 +1,277 @@
+/**
+ * PersonaSession - Core SDK class for connecting to Persona avatars.
+ *
+ * Handles:
+ * - Creating sessions via Central API
+ * - Connecting to LiveKit room as "user" participant
+ * - Sending audio to "persona" via DataStream
+ * - Receiving video from "persona"
+ * - Interrupt signaling
+ */
+import { Room, RoomEvent, Track, DisconnectReason, } from 'livekit-client';
+/** Map LiveKit DisconnectReason to our CloseReason */
+function mapDisconnectReason(reason) {
+    switch (reason) {
+        case DisconnectReason.CLIENT_INITIATED:
+            return 'client_initiated';
+        case DisconnectReason.ROOM_DELETED:
+            return 'room_deleted';
+        case DisconnectReason.SERVER_SHUTDOWN:
+            return 'server_shutdown';
+        case DisconnectReason.PARTICIPANT_REMOVED:
+            return 'participant_removed';
+        default:
+            return 'unknown';
+    }
+}
+/** DataStream topic for audio (must match GPU node) */
+const AUDIO_STREAM_TOPIC = 'lk.audio_stream';
+/** DataStream topic for control messages (interrupt, etc.) */
+const CONTROL_STREAM_TOPIC = 'lk.control';
+/** Auto-flush timeout in ms after last audio chunk */
+const AUTO_FLUSH_TIMEOUT_MS = 300;
+/**
+ * PersonaSession manages the connection between your app and a Persona avatar.
+ *
+ * @example
+ * ```typescript
+ * const session = new PersonaSession({
+ *   // WebRTC URL, access token, and agent identity returned from KeyframeLab API (called from your server code)
+ *   serverUrl: websocket-url,
+ *   participantToken: webrtc-participant-token,
+ *   agentIdentity: agent_identity,
+ *   onVideoTrack: (track) => {
+ *     videoElement.srcObject = new MediaStream([track]);
+ *   },
+ * });
+ *
+ * await session.connect();
+ * session.sendAudio(audioBytes);
+ * await session.close();
+ * ```
+ */
+export class PersonaSession {
+    options;
+    room = null;
+    _state = 'disconnected';
+    byteStreamWriter = null;
+    // Write queue for proper ordering and completion tracking
+    writeQueue = Promise.resolve();
+    // Auto-flush timer for turn end detection
+    autoFlushTimer = null;
+    constructor(options) {
+        this.options = { ...options };
+    }
+    /** Current session state */
+    get state() {
+        return this._state;
+    }
+    setState(state) {
+        if (this._state !== state) {
+            this._state = state;
+            this.options.onStateChange?.(state);
+        }
+    }
+    /**
+     * Connect to a Persona avatar session.
+     *
+     * Creates a session via Central API and connects to the LiveKit room.
+     */
+    async connect() {
+        if (this._state !== 'disconnected') {
+            throw new Error('Session already connected or connecting');
+        }
+        this.setState('connecting');
+        try {
+            // 1. Connect to LiveKit room
+            this.room = new Room();
+            this.setupRoomListeners();
+            await this.room.connect(this.options.serverUrl, this.options.participantToken);
+            // Open ByteStream for audio
+            this.byteStreamWriter = await this.room.localParticipant.streamBytes({
+                topic: AUDIO_STREAM_TOPIC,
+                destinationIdentities: [this.options.agentIdentity],
+            });
+            console.log('[PersonaSession] Opened audio stream');
+            this.setState('connected');
+            console.log('[PersonaSession] Connected to room');
+        }
+        catch (error) {
+            this.setState('error');
+            this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    setupRoomListeners() {
+        if (!this.room)
+            return;
+        // Handle tracks from persona
+        this.room.on(RoomEvent.TrackSubscribed, (track, _pub, participant) => {
+            if (participant.identity !== this.options.agentIdentity)
+                return;
+            const mediaTrack = track.mediaStreamTrack;
+            if (track.kind === Track.Kind.Video) {
+                console.log('[PersonaSession] Got video track from persona');
+                this.options.onVideoTrack?.(mediaTrack);
+            }
+            else if (track.kind === Track.Kind.Audio) {
+                console.log('[PersonaSession] Got audio track from persona');
+                this.options.onAudioTrack?.(mediaTrack);
+            }
+        });
+        // Handle disconnection
+        this.room.on(RoomEvent.Disconnected, (reason) => {
+            const closeReason = mapDisconnectReason(reason);
+            console.log('[PersonaSession] Disconnected from room:', closeReason);
+            this.setState('disconnected');
+            this.options.onClose?.(closeReason);
+        });
+        // Handle errors
+        this.room.on(RoomEvent.MediaDevicesError, (error) => {
+            console.error('[PersonaSession] Media devices error:', error);
+            this.options.onError?.(error);
+        });
+    }
+    /**
+     * Send audio data to the persona for video synthesis.
+     *
+     * @param pcmData - 16-bit PCM audio at 24kHz
+     */
+    sendAudio(pcmData) {
+        if (!this.room || this._state !== 'connected') {
+            console.warn('[PersonaSession] sendAudio dropped - not connected');
+            return;
+        }
+        // Chain writes to ensure ordering and track completion
+        // Lazily create ByteStreamWriter if needed (e.g., after endAudioTurn closed it)
+        console.log(`[PersonaSession] Writing ${pcmData.length} bytes to ByteStream`);
+        this.writeQueue = this.writeQueue
+            .then(async () => {
+            if (!this.byteStreamWriter && this.room) {
+                this.byteStreamWriter = await this.room.localParticipant.streamBytes({
+                    topic: AUDIO_STREAM_TOPIC,
+                    destinationIdentities: [this.options.agentIdentity],
+                });
+            }
+            await this.byteStreamWriter?.write(pcmData);
+        })
+            .catch((err) => {
+            console.warn('[PersonaSession] Failed to write audio:', err);
+        });
+        // Schedule auto-flush after timeout (reset on each audio chunk)
+        this.scheduleAutoFlush();
+    }
+    /**
+     * Schedule auto-flush after a timeout.
+     * Called on each sendAudio() to reset the timer.
+     */
+    scheduleAutoFlush() {
+        if (this.autoFlushTimer) {
+            clearTimeout(this.autoFlushTimer);
+        }
+        this.autoFlushTimer = setTimeout(() => {
+            if (this.byteStreamWriter) {
+                console.log('[PersonaSession] Auto-flush: no audio for', AUTO_FLUSH_TIMEOUT_MS, 'ms');
+                this.endAudioTurn();
+            }
+        }, AUTO_FLUSH_TIMEOUT_MS);
+    }
+    /**
+     * Flush all pending audio writes.
+     * Call before close to ensure all audio is sent.
+     */
+    async flush() {
+        await this.writeQueue;
+    }
+    /**
+     * End the current audio turn and flush any buffered data.
+     *
+     * This is called automatically 300ms after the last sendAudio() call.
+     * You typically don't need to call this manually, but it's available
+     * if you need immediate flushing.
+     */
+    async endAudioTurn() {
+        // Clear auto-flush timer to prevent double-flush
+        if (this.autoFlushTimer) {
+            clearTimeout(this.autoFlushTimer);
+            this.autoFlushTimer = null;
+        }
+        console.debug('[PersonaSession] endAudioTurn() called, awaiting writeQueue...');
+        await this.writeQueue;
+        console.debug('[PersonaSession] writeQueue complete, closing stream...');
+        if (this.byteStreamWriter) {
+            try {
+                await this.byteStreamWriter.close();
+                console.debug('[PersonaSession] stream closed successfully');
+            }
+            catch (err) {
+                console.warn('[PersonaSession] stream close error:', err);
+            }
+            this.byteStreamWriter = null;
+        }
+        else {
+            console.debug('[PersonaSession] no stream to close');
+        }
+    }
+    /**
+     * Signal an interruption to the avatar.
+     *
+     * Clears any pending frames in the GPU node's publish queue,
+     * allowing the avatar to quickly respond to new audio.
+     *
+     * Call this when the user interrupts the agent (e.g., starts speaking
+     * while the agent is still talking).
+     */
+    async interrupt() {
+        // Clear auto-flush timer - we're interrupting, don't need to flush
+        if (this.autoFlushTimer) {
+            clearTimeout(this.autoFlushTimer);
+            this.autoFlushTimer = null;
+        }
+        if (!this.room || this._state !== 'connected') {
+            console.warn('[PersonaSession] interrupt() called but not connected');
+            return;
+        }
+        try {
+            console.debug('[PersonaSession] Sending interrupt');
+            const writer = await this.room.localParticipant.streamBytes({
+                topic: CONTROL_STREAM_TOPIC,
+                destinationIdentities: [this.options.agentIdentity],
+            });
+            await writer.write(new TextEncoder().encode('interrupt'));
+            await writer.close();
+        }
+        catch (error) {
+            console.warn('[PersonaSession] Failed to send interrupt:', error);
+        }
+    }
+    /**
+     * Close the session and clean up resources.
+     */
+    async close() {
+        // Clear auto-flush timer
+        if (this.autoFlushTimer) {
+            clearTimeout(this.autoFlushTimer);
+            this.autoFlushTimer = null;
+        }
+        // Wait for pending writes to complete before closing
+        await this.flush();
+        // Close byte stream
+        if (this.byteStreamWriter) {
+            try {
+                await this.byteStreamWriter.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.byteStreamWriter = null;
+        }
+        // Disconnect from room
+        if (this.room) {
+            this.room.disconnect();
+            this.room = null;
+        }
+        this.setState('disconnected');
+    }
+}
+//# sourceMappingURL=PersonaSession.js.map

package/dist/PersonaSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonaSession.js","sourceRoot":"","sources":["../src/PersonaSession.ts"],"names":[],"mappings":"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"}

package/dist/audio-utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Audio utilities for PCM processing and silence generation.
+ */
+/** Sample rate for audio sent to Persona */
+export declare const SAMPLE_RATE = 24000;
+/** Bytes per sample (16-bit PCM) */
+export declare const BYTES_PER_SAMPLE = 2;
+/** Number of channels (mono) */
+export declare const CHANNELS = 1;
+/**
+ * Convert base64-encoded audio to Uint8Array.
+ *
+ * @param base64 - Base64 encoded audio data
+ * @returns Uint8Array of audio bytes
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Convert Uint8Array to base64 string.
+ *
+ * @param bytes - Audio bytes
+ * @returns Base64 encoded string
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Resample PCM audio from one sample rate to another.
+ * Simple linear interpolation - not high quality but sufficient for real-time.
+ *
+ * @param input - Input PCM bytes (16-bit signed)
+ * @param fromRate - Source sample rate
+ * @param toRate - Target sample rate
+ * @returns Resampled PCM bytes
+ */
+export declare function resamplePcm(input: Uint8Array, fromRate: number, toRate: number): Uint8Array;
+/**
+ * Create a simple typed event emitter.
+ */
+export declare function createEventEmitter<T extends Record<string, any>>(): {
+    on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+    off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+    emit<K extends keyof T>(event: K, data: T[K]): void;
+    removeAllListeners(): void;
+};
+//# sourceMappingURL=audio-utils.d.ts.map

package/dist/audio-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-utils.d.ts","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,WAAW,QAAQ,CAAC;AAEjC,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gCAAgC;AAChC,eAAO,MAAM,QAAQ,IAAI,CAAC;AAE1B;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAuBZ;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;OAKzD,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;QAQhE,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;SAKhE,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;0BAI7B,IAAI;EAI7B"}

package/dist/audio-utils.js

@@ -0,0 +1,91 @@
+/**
+ * Audio utilities for PCM processing and silence generation.
+ */
+/** Sample rate for audio sent to Persona */
+export const SAMPLE_RATE = 24000;
+/** Bytes per sample (16-bit PCM) */
+export const BYTES_PER_SAMPLE = 2;
+/** Number of channels (mono) */
+export const CHANNELS = 1;
+/**
+ * Convert base64-encoded audio to Uint8Array.
+ *
+ * @param base64 - Base64 encoded audio data
+ * @returns Uint8Array of audio bytes
+ */
+export function base64ToBytes(base64) {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Convert Uint8Array to base64 string.
+ *
+ * @param bytes - Audio bytes
+ * @returns Base64 encoded string
+ */
+export function bytesToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Resample PCM audio from one sample rate to another.
+ * Simple linear interpolation - not high quality but sufficient for real-time.
+ *
+ * @param input - Input PCM bytes (16-bit signed)
+ * @param fromRate - Source sample rate
+ * @param toRate - Target sample rate
+ * @returns Resampled PCM bytes
+ */
+export function resamplePcm(input, fromRate, toRate) {
+    if (fromRate === toRate) {
+        return input;
+    }
+    const inputView = new Int16Array(input.buffer, input.byteOffset, input.length / 2);
+    const ratio = fromRate / toRate;
+    const outputLength = Math.floor(inputView.length / ratio);
+    const output = new Int16Array(outputLength);
+    for (let i = 0; i < outputLength; i++) {
+        const srcIndex = i * ratio;
+        const srcIndexFloor = Math.floor(srcIndex);
+        const srcIndexCeil = Math.min(srcIndexFloor + 1, inputView.length - 1);
+        const fraction = srcIndex - srcIndexFloor;
+        // Linear interpolation
+        output[i] = Math.round(inputView[srcIndexFloor] * (1 - fraction) + inputView[srcIndexCeil] * fraction);
+    }
+    return new Uint8Array(output.buffer);
+}
+/**
+ * Create a simple typed event emitter.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createEventEmitter() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const listeners = new Map();
+    return {
+        on(event, handler) {
+            if (!listeners.has(event)) {
+                listeners.set(event, new Set());
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            listeners.get(event).add(handler);
+        },
+        off(event, handler) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            listeners.get(event)?.delete(handler);
+        },
+        emit(event, data) {
+            listeners.get(event)?.forEach((handler) => handler(data));
+        },
+        removeAllListeners() {
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=audio-utils.js.map

package/dist/audio-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-utils.js","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"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"}

package/{src/index.ts → dist/index.d.ts}

@@ -1,10 +1,10 @@
 /**
  * @keyframelabs/sdk - Browser SDK for KeyframeLab's Persona avatar sessions.
- * 
+ *
  * @example
  * ```typescript
  * import { createClient } from '@keyframelabs/sdk';
- * 
+ *
  * const client = createClient({
  *   personaId: 'luna',
  *   // WebRTC URL and access token returned from KeyframeLab API (called from your server code)
@@ -14,41 +14,22 @@
  *     videoElement.srcObject = new MediaStream([track]);
  *   },
  * });
- * 
+ *
  * await client.connect();
  * client.sendAudio(audioBytes);
  * await client.close();
  * ```
  */
-
 import { PersonaSession } from './PersonaSession.js';
 import type { PersonaSessionOptions } from './types.js';
-
 /**
  * Create a new Persona client.
- * 
+ *
  * @param options - Session configuration options
  * @returns A new PersonaSession instance
  */
-const createClient = (options: PersonaSessionOptions): PersonaSession => {
-  return new PersonaSession(options);
-};
-
-// Core
+declare const createClient: (options: PersonaSessionOptions) => PersonaSession;
 export { createClient, PersonaSession };
-
-// Types
-export type {
-  CloseReason,
-  PersonaSessionOptions,
-  SessionState,
-} from './types.js';
-
-// Utilities
-export {
-  SAMPLE_RATE,
-  base64ToBytes,
-  bytesToBase64,
-  createEventEmitter,
-  resamplePcm,
-} from './audio-utils.js';
+export type { CloseReason, PersonaSessionOptions, SessionState, } from './types.js';
+export { SAMPLE_RATE, base64ToBytes, bytesToBase64, createEventEmitter, resamplePcm, } from './audio-utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;GAKG;AACH,QAAA,MAAM,YAAY,GAAI,SAAS,qBAAqB,KAAG,cAEtD,CAAC;AAGF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAGxC,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,WAAW,EACX,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,WAAW,GACZ,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * @keyframelabs/sdk - Browser SDK for KeyframeLab's Persona avatar sessions.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@keyframelabs/sdk';
+ *
+ * const client = createClient({
+ *   personaId: 'luna',
+ *   // WebRTC URL and access token returned from KeyframeLab API (called from your server code)
+ *   serverUrl: 'wss://webrtc-server-url.com',
+ *   participantToken: 'webrtc-participant-token',
+ *   onVideoTrack: (track) => {
+ *     videoElement.srcObject = new MediaStream([track]);
+ *   },
+ * });
+ *
+ * await client.connect();
+ * client.sendAudio(audioBytes);
+ * await client.close();
+ * ```
+ */
+import { PersonaSession } from './PersonaSession.js';
+/**
+ * Create a new Persona client.
+ *
+ * @param options - Session configuration options
+ * @returns A new PersonaSession instance
+ */
+const createClient = (options) => {
+    return new PersonaSession(options);
+};
+// Core
+export { createClient, PersonaSession };
+// Utilities
+export { SAMPLE_RATE, base64ToBytes, bytesToBase64, createEventEmitter, resamplePcm, } from './audio-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;GAKG;AACH,MAAM,YAAY,GAAG,CAAC,OAA8B,EAAkB,EAAE;IACtE,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF,OAAO;AACP,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AASxC,YAAY;AACZ,OAAO,EACL,WAAW,EACX,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,WAAW,GACZ,MAAM,kBAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types for Persona SDK.
+ */
+/** Session state machine */
+export type SessionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** Reason for session close */
+export type CloseReason = 'client_initiated' | 'room_deleted' | 'server_shutdown' | 'participant_removed' | 'unknown';
+/** Options for creating a PersonaSession */
+export interface PersonaSessionOptions {
+    /** WebRTC URL (returned from KeyframeLab API) */
+    serverUrl: string;
+    /** WebRTC access token (returned from KeyframeLab API) */
+    participantToken: string;
+    /** Identity of the agent participant */
+    agentIdentity: string;
+    /** Called when video track is available */
+    onVideoTrack?: (track: MediaStreamTrack) => void;
+    /** Called when audio track is available */
+    onAudioTrack?: (track: MediaStreamTrack) => void;
+    /** Called when session state changes */
+    onStateChange?: (state: SessionState) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when session is closed (by server or client) */
+    onClose?: (reason: CloseReason) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4BAA4B;AAC5B,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,OAAO,CAAC;AAEZ,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,qBAAqB,GACrB,SAAS,CAAC;AAEd,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAEjD,2CAA2C;IAC3C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAEjD,wCAAwC;IACxC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAE9C,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEjC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACzC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for Persona SDK.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyframelabs/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Browser SDK for KeyframeLab's Persona avatar sessions",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,8 +12,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"

package/src/PersonaSession.ts

@@ -1,324 +0,0 @@
-/**
- * PersonaSession - Core SDK class for connecting to Persona avatars.
- * 
- * Handles:
- * - Creating sessions via Central API
- * - Connecting to LiveKit room as "user" participant
- * - Sending audio to "persona" via DataStream
- * - Receiving video from "persona"
- * - Interrupt signaling
- */
-
-import {
-  Room,
-  RoomEvent,
-  Track,
-  RemoteTrack,
-  RemoteParticipant,
-  DisconnectReason,
-} from 'livekit-client';
-
-// ByteStreamWriter type from livekit-client (not exported directly)
-type ByteStreamWriter = Awaited<ReturnType<Room['localParticipant']['streamBytes']>>;
-import type {
-  CloseReason,
-  PersonaSessionOptions,
-  SessionState
-} from './types.js';
-
-/** Map LiveKit DisconnectReason to our CloseReason */
-function mapDisconnectReason(reason?: DisconnectReason): CloseReason {
-  switch (reason) {
-    case DisconnectReason.CLIENT_INITIATED:
-      return 'client_initiated';
-    case DisconnectReason.ROOM_DELETED:
-      return 'room_deleted';
-    case DisconnectReason.SERVER_SHUTDOWN:
-      return 'server_shutdown';
-    case DisconnectReason.PARTICIPANT_REMOVED:
-      return 'participant_removed';
-    default:
-      return 'unknown';
-  }
-}
-
-/** DataStream topic for audio (must match GPU node) */
-const AUDIO_STREAM_TOPIC = 'lk.audio_stream';
-
-/** DataStream topic for control messages (interrupt, etc.) */
-const CONTROL_STREAM_TOPIC = 'lk.control';
-
-/** Auto-flush timeout in ms after last audio chunk */
-const AUTO_FLUSH_TIMEOUT_MS = 300;
-
-/**
- * PersonaSession manages the connection between your app and a Persona avatar.
- * 
- * @example
- * ```typescript
- * const session = new PersonaSession({
- *   // WebRTC URL, access token, and agent identity returned from KeyframeLab API (called from your server code)
- *   serverUrl: websocket-url,
- *   participantToken: webrtc-participant-token,
- *   agentIdentity: agent_identity,
- *   onVideoTrack: (track) => {
- *     videoElement.srcObject = new MediaStream([track]);
- *   },
- * });
- * 
- * await session.connect();
- * session.sendAudio(audioBytes);
- * await session.close();
- * ```
- */
-export class PersonaSession {
-  private options: Required<Pick<PersonaSessionOptions, 'serverUrl' | 'participantToken' | 'agentIdentity'>> &
-    PersonaSessionOptions;
-  private room: Room | null = null;
-  private _state: SessionState = 'disconnected';
-  private byteStreamWriter: ByteStreamWriter | null = null;
-  
-  // Write queue for proper ordering and completion tracking
-  private writeQueue: Promise<void> = Promise.resolve();
-  
-  // Auto-flush timer for turn end detection
-  private autoFlushTimer: ReturnType<typeof setTimeout> | null = null;
-  
-  constructor(options: PersonaSessionOptions) {
-    this.options = { ...options };
-  }
-  
-  /** Current session state */
-  get state(): SessionState {
-    return this._state;
-  }
-  
-  private setState(state: SessionState): void {
-    if (this._state !== state) {
-      this._state = state;
-      this.options.onStateChange?.(state);
-    }
-  }
-  
-  /**
-   * Connect to a Persona avatar session.
-   * 
-   * Creates a session via Central API and connects to the LiveKit room.
-   */
-  async connect(): Promise<void> {
-    if (this._state !== 'disconnected') {
-      throw new Error('Session already connected or connecting');
-    }
-    
-    this.setState('connecting');
-    
-    try {
-      // 1. Connect to LiveKit room
-      this.room = new Room();
-      this.setupRoomListeners();
-      
-      await this.room.connect(this.options.serverUrl, this.options.participantToken);
-      
-      // Open ByteStream for audio
-      this.byteStreamWriter = await this.room.localParticipant.streamBytes({
-        topic: AUDIO_STREAM_TOPIC,
-        destinationIdentities: [this.options.agentIdentity],
-      });
-      console.log('[PersonaSession] Opened audio stream');
-      
-      this.setState('connected');
-      console.log('[PersonaSession] Connected to room');
-    } catch (error) {
-      this.setState('error');
-      this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
-      throw error;
-    }
-  }
-  
-  private setupRoomListeners(): void {
-    if (!this.room) return;
-    
-    // Handle tracks from persona
-    this.room.on(RoomEvent.TrackSubscribed, (track: RemoteTrack, _pub, participant: RemoteParticipant) => {
-      if (participant.identity !== this.options.agentIdentity) return;
-      
-      const mediaTrack = track.mediaStreamTrack;
-      
-      if (track.kind === Track.Kind.Video) {
-        console.log('[PersonaSession] Got video track from persona');
-        this.options.onVideoTrack?.(mediaTrack);
-      } else if (track.kind === Track.Kind.Audio) {
-        console.log('[PersonaSession] Got audio track from persona');
-        this.options.onAudioTrack?.(mediaTrack);
-      }
-    });
-    
-    // Handle disconnection
-    this.room.on(RoomEvent.Disconnected, (reason?: DisconnectReason) => {
-      const closeReason = mapDisconnectReason(reason);
-      console.log('[PersonaSession] Disconnected from room:', closeReason);
-      this.setState('disconnected');
-      this.options.onClose?.(closeReason);
-    });
-    
-    // Handle errors
-    this.room.on(RoomEvent.MediaDevicesError, (error: Error) => {
-      console.error('[PersonaSession] Media devices error:', error);
-      this.options.onError?.(error);
-    });
-  }
-  
-  /**
-   * Send audio data to the persona for video synthesis.
-   * 
-   * @param pcmData - 16-bit PCM audio at 24kHz
-   */
-  sendAudio(pcmData: Uint8Array): void {
-    if (!this.room || this._state !== 'connected') {
-      console.warn('[PersonaSession] sendAudio dropped - not connected');
-      return;
-    }
-    
-    // Chain writes to ensure ordering and track completion
-    // Lazily create ByteStreamWriter if needed (e.g., after endAudioTurn closed it)
-    console.log(`[PersonaSession] Writing ${pcmData.length} bytes to ByteStream`);
-    this.writeQueue = this.writeQueue
-      .then(async () => {
-        if (!this.byteStreamWriter && this.room) {
-          this.byteStreamWriter = await this.room.localParticipant.streamBytes({
-            topic: AUDIO_STREAM_TOPIC,
-            destinationIdentities: [this.options.agentIdentity],
-          });
-        }
-        await this.byteStreamWriter?.write(pcmData);
-      })
-      .catch((err) => {
-        console.warn('[PersonaSession] Failed to write audio:', err);
-      });
-    
-    // Schedule auto-flush after timeout (reset on each audio chunk)
-    this.scheduleAutoFlush();
-  }
-  
-  /**
-   * Schedule auto-flush after a timeout.
-   * Called on each sendAudio() to reset the timer.
-   */
-  private scheduleAutoFlush(): void {
-    if (this.autoFlushTimer) {
-      clearTimeout(this.autoFlushTimer);
-    }
-    
-    this.autoFlushTimer = setTimeout(() => {
-      if (this.byteStreamWriter) {
-        console.log('[PersonaSession] Auto-flush: no audio for', AUTO_FLUSH_TIMEOUT_MS, 'ms');
-        this.endAudioTurn();
-      }
-    }, AUTO_FLUSH_TIMEOUT_MS);
-  }
-  
-  /**
-   * Flush all pending audio writes.
-   * Call before close to ensure all audio is sent.
-   */
-  async flush(): Promise<void> {
-    await this.writeQueue;
-  }
-  
-  /**
-   * End the current audio turn and flush any buffered data.
-   * 
-   * This is called automatically 300ms after the last sendAudio() call.
-   * You typically don't need to call this manually, but it's available
-   * if you need immediate flushing.
-   */
-  async endAudioTurn(): Promise<void> {
-    // Clear auto-flush timer to prevent double-flush
-    if (this.autoFlushTimer) {
-      clearTimeout(this.autoFlushTimer);
-      this.autoFlushTimer = null;
-    }
-    
-    console.debug('[PersonaSession] endAudioTurn() called, awaiting writeQueue...');
-    await this.writeQueue;
-    console.debug('[PersonaSession] writeQueue complete, closing stream...');
-    if (this.byteStreamWriter) {
-      try {
-        await this.byteStreamWriter.close();
-        console.debug('[PersonaSession] stream closed successfully');
-      } catch (err) {
-        console.warn('[PersonaSession] stream close error:', err);
-      }
-      this.byteStreamWriter = null;
-    } else {
-      console.debug('[PersonaSession] no stream to close');
-    }
-  }
-  
-  /**
-   * Signal an interruption to the avatar.
-   * 
-   * Clears any pending frames in the GPU node's publish queue,
-   * allowing the avatar to quickly respond to new audio.
-   * 
-   * Call this when the user interrupts the agent (e.g., starts speaking
-   * while the agent is still talking).
-   */
-  async interrupt(): Promise<void> {
-    // Clear auto-flush timer - we're interrupting, don't need to flush
-    if (this.autoFlushTimer) {
-      clearTimeout(this.autoFlushTimer);
-      this.autoFlushTimer = null;
-    }
-    
-    if (!this.room || this._state !== 'connected') {
-      console.warn('[PersonaSession] interrupt() called but not connected');
-      return;
-    }
-    
-    try {
-      console.debug('[PersonaSession] Sending interrupt');
-      const writer = await this.room.localParticipant.streamBytes({
-        topic: CONTROL_STREAM_TOPIC,
-        destinationIdentities: [this.options.agentIdentity],
-      });
-      await writer.write(new TextEncoder().encode('interrupt'));
-      await writer.close();
-    } catch (error) {
-      console.warn('[PersonaSession] Failed to send interrupt:', error);
-    }
-  }
-  
-  /**
-   * Close the session and clean up resources.
-   */
-  async close(): Promise<void> {
-    // Clear auto-flush timer
-    if (this.autoFlushTimer) {
-      clearTimeout(this.autoFlushTimer);
-      this.autoFlushTimer = null;
-    }
-    
-    // Wait for pending writes to complete before closing
-    await this.flush();
-    
-    // Close byte stream
-    if (this.byteStreamWriter) {
-      try {
-        await this.byteStreamWriter.close();
-      } catch {
-        // Ignore close errors
-      }
-      this.byteStreamWriter = null;
-    }
-    
-    // Disconnect from room
-    if (this.room) {
-      this.room.disconnect();
-      this.room = null;
-    }
-    
-    this.setState('disconnected');
-  }
-}
-

package/src/audio-utils.ts

@@ -1,112 +0,0 @@
-/**
- * Audio utilities for PCM processing and silence generation.
- */
-
-/** Sample rate for audio sent to Persona */
-export const SAMPLE_RATE = 24000;
-
-/** Bytes per sample (16-bit PCM) */
-export const BYTES_PER_SAMPLE = 2;
-
-/** Number of channels (mono) */
-export const CHANNELS = 1;
-
-/**
- * Convert base64-encoded audio to Uint8Array.
- * 
- * @param base64 - Base64 encoded audio data
- * @returns Uint8Array of audio bytes
- */
-export function base64ToBytes(base64: string): Uint8Array {
-  const binaryString = atob(base64);
-  const bytes = new Uint8Array(binaryString.length);
-  for (let i = 0; i < binaryString.length; i++) {
-    bytes[i] = binaryString.charCodeAt(i);
-  }
-  return bytes;
-}
-
-/**
- * Convert Uint8Array to base64 string.
- * 
- * @param bytes - Audio bytes
- * @returns Base64 encoded string
- */
-export function bytesToBase64(bytes: Uint8Array): string {
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-}
-
-/**
- * Resample PCM audio from one sample rate to another.
- * Simple linear interpolation - not high quality but sufficient for real-time.
- * 
- * @param input - Input PCM bytes (16-bit signed)
- * @param fromRate - Source sample rate
- * @param toRate - Target sample rate
- * @returns Resampled PCM bytes
- */
-export function resamplePcm(
-  input: Uint8Array,
-  fromRate: number,
-  toRate: number
-): Uint8Array {
-  if (fromRate === toRate) {
-    return input;
-  }
-  
-  const inputView = new Int16Array(input.buffer, input.byteOffset, input.length / 2);
-  const ratio = fromRate / toRate;
-  const outputLength = Math.floor(inputView.length / ratio);
-  const output = new Int16Array(outputLength);
-  
-  for (let i = 0; i < outputLength; i++) {
-    const srcIndex = i * ratio;
-    const srcIndexFloor = Math.floor(srcIndex);
-    const srcIndexCeil = Math.min(srcIndexFloor + 1, inputView.length - 1);
-    const fraction = srcIndex - srcIndexFloor;
-    
-    // Linear interpolation
-    output[i] = Math.round(
-      inputView[srcIndexFloor] * (1 - fraction) + inputView[srcIndexCeil] * fraction
-    );
-  }
-  
-  return new Uint8Array(output.buffer);
-}
-
-/**
- * Create a simple typed event emitter.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function createEventEmitter<T extends Record<string, any>>() {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const listeners = new Map<keyof T, Set<(data: any) => void>>();
-  
-  return {
-    on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
-      if (!listeners.has(event)) {
-        listeners.set(event, new Set());
-      }
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      listeners.get(event)!.add(handler as (data: any) => void);
-    },
-    
-    off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      listeners.get(event)?.delete(handler as (data: any) => void);
-    },
-    
-    emit<K extends keyof T>(event: K, data: T[K]): void {
-      listeners.get(event)?.forEach((handler) => handler(data));
-    },
-    
-    removeAllListeners(): void {
-      listeners.clear();
-    },
-  };
-}
-

package/src/types.ts

@@ -1,43 +0,0 @@
-/**
- * Shared types for Persona SDK.
- */
-
-/** Session state machine */
-export type SessionState =
-  | 'disconnected'
-  | 'connecting'
-  | 'connected'
-  | 'error';
-
-/** Reason for session close */
-export type CloseReason = 
-  | 'client_initiated'      // User called close()
-  | 'room_deleted'          // Backend deleted the room (max duration, etc.)
-  | 'server_shutdown'       // Server is shutting down
-  | 'participant_removed'   // Participant was kicked
-  | 'unknown';              // Unknown reason
-
-/** Options for creating a PersonaSession */
-export interface PersonaSessionOptions {
-  /** WebRTC URL (returned from KeyframeLab API) */
-  serverUrl: string;
-  /** WebRTC access token (returned from KeyframeLab API) */
-  participantToken: string;
-  /** Identity of the agent participant */
-  agentIdentity: string;
-
-  /** Called when video track is available */
-  onVideoTrack?: (track: MediaStreamTrack) => void;
-  
-  /** Called when audio track is available */
-  onAudioTrack?: (track: MediaStreamTrack) => void;
-  
-  /** Called when session state changes */
-  onStateChange?: (state: SessionState) => void;
-  
-  /** Called on error */
-  onError?: (error: Error) => void;
-  
-  /** Called when session is closed (by server or client) */
-  onClose?: (reason: CloseReason) => void;
-}