@charivo/core 0.34.0 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -200,10 +200,7 @@ interface LLMToolResponse {
200
200
  toolCalls?: LLMToolCall[];
201
201
  }
202
202
  interface LLMProvider {
203
- generateResponse(messages: Array<{
204
- role: string;
205
- content: string;
206
- }>): Promise<string>;
203
+ generateResponse(messages: LLMMessage[]): Promise<string>;
207
204
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
208
205
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
209
206
  }
@@ -215,10 +212,7 @@ interface LLMCallOptions {
215
212
  signal?: AbortSignal;
216
213
  }
217
214
  interface LLMClient {
218
- call(messages: Array<{
219
- role: string;
220
- content: string;
221
- }>, options?: LLMCallOptions): Promise<string>;
215
+ call(messages: LLMMessage[], options?: LLMCallOptions): Promise<string>;
222
216
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
223
217
  callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
224
218
  }
@@ -352,6 +346,26 @@ interface TTSOptions {
352
346
  voice?: string;
353
347
  }
354
348
  type TTSPlaybackMode = "audio" | "web-speech";
349
+ /**
350
+ * Raw PCM carries no container, so the sample layout can't be sniffed from
351
+ * the bytes the way a WAV/MP3 buffer can — it has to ride along with the
352
+ * stream itself.
353
+ */
354
+ interface TTSPcmFormat {
355
+ encoding: "pcm-s16le";
356
+ sampleRate: number;
357
+ /** Mono only — the TTS manager rejects a stream declaring any other count. */
358
+ channels: number;
359
+ }
360
+ /**
361
+ * A streamed TTS result. `format` always describes `pcm-s16le`, regardless
362
+ * of any vendor label on the request, since every streaming provider decodes
363
+ * to that layout before handing the stream back.
364
+ */
365
+ interface TTSPcmStream {
366
+ body: ReadableStream<Uint8Array>;
367
+ format: TTSPcmFormat;
368
+ }
355
369
  interface TTSPlayer {
356
370
  /**
357
371
  * Explicit playback mode for the manager. Prefer setting this on concrete
@@ -367,22 +381,41 @@ interface TTSPlayer {
367
381
  setVoice(voice: string): void;
368
382
  isSupported(): boolean;
369
383
  /**
370
- * Stateless audio generation. Required for the `"audio"` playback mode: the
371
- * manager creates the audio element itself so it can analyze playback for
372
- * lip-sync. Players that can only `speak()` must use `"web-speech"` mode.
384
+ * Stateless audio generation. The `"audio"` playback mode requires this or
385
+ * `generateAudioStream`: the manager plays the finished buffer through an
386
+ * audio element it creates itself, so it can analyze playback for lip-sync.
387
+ * Players that can only `speak()` must use `"web-speech"` mode.
373
388
  */
374
389
  generateAudio?(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
390
+ /**
391
+ * Streaming counterpart to `generateAudio`, for players that can deliver PCM
392
+ * as it is synthesized instead of one finished buffer; the manager schedules
393
+ * it into Web Audio as it arrives. Takes precedence: the manager streams
394
+ * whenever this method exists, so a player implementing both never has
395
+ * `generateAudio` called. Aborting `signal`, or cancelling the returned
396
+ * stream's `body`, must cancel the upstream request.
397
+ */
398
+ generateAudioStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
375
399
  }
376
400
  interface TTSProvider {
377
401
  generateSpeech(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
378
402
  setVoice(voice: string): void;
403
+ /** Streaming counterpart to `generateSpeech`, called by a route handler (or a player delegating to it); `generateSpeech` remains for callers that want a whole buffer. Aborting `signal`, or cancelling the returned stream's `body`, must cancel the upstream request. */
404
+ generateSpeechStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
379
405
  }
380
406
  interface TTSManager {
381
407
  speak(text: string, options?: TTSOptions): Promise<void>;
382
408
  stop(): Promise<void>;
383
409
  setVoice(voice: string): void;
384
410
  isSupported(): boolean;
385
- /** Creates the audio analysis context up front; call from a user gesture handler so browsers allow playback later. */
411
+ /**
412
+ * Creates the audio analysis context up front, and, for a player that
413
+ * streams, warms the streamed playback context too; call from a user
414
+ * gesture handler so browsers allow playback later. On a browser without
415
+ * sticky activation (e.g. Safari), skipping this before a streaming
416
+ * `speak()` fails that call with `CharivoStateError` rather than merely
417
+ * degrading lip-sync.
418
+ */
386
419
  prepareAudio?(): Promise<void>;
387
420
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
388
421
  /** Final resource release; call stop() first - dispose() does not stop playback. */
@@ -1023,4 +1056,4 @@ interface CharivoOptions {
1023
1056
  */
1024
1057
  declare function createCharivo(options?: CharivoOptions): Charivo;
1025
1058
 
1026
- export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type BuiltInRealtimeManager, type BuiltInSTTManager, type BuiltInTTSManager, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, GEMINI_LIVE_ADAPTER, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, readResponseErrorMessage, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
1059
+ export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type BuiltInRealtimeManager, type BuiltInSTTManager, type BuiltInTTSManager, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, GEMINI_LIVE_ADAPTER, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPcmFormat, type TTSPcmStream, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, readResponseErrorMessage, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
package/dist/index.d.ts CHANGED
@@ -200,10 +200,7 @@ interface LLMToolResponse {
200
200
  toolCalls?: LLMToolCall[];
201
201
  }
202
202
  interface LLMProvider {
203
- generateResponse(messages: Array<{
204
- role: string;
205
- content: string;
206
- }>): Promise<string>;
203
+ generateResponse(messages: LLMMessage[]): Promise<string>;
207
204
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
208
205
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
209
206
  }
@@ -215,10 +212,7 @@ interface LLMCallOptions {
215
212
  signal?: AbortSignal;
216
213
  }
217
214
  interface LLMClient {
218
- call(messages: Array<{
219
- role: string;
220
- content: string;
221
- }>, options?: LLMCallOptions): Promise<string>;
215
+ call(messages: LLMMessage[], options?: LLMCallOptions): Promise<string>;
222
216
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
223
217
  callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
224
218
  }
@@ -352,6 +346,26 @@ interface TTSOptions {
352
346
  voice?: string;
353
347
  }
354
348
  type TTSPlaybackMode = "audio" | "web-speech";
349
+ /**
350
+ * Raw PCM carries no container, so the sample layout can't be sniffed from
351
+ * the bytes the way a WAV/MP3 buffer can — it has to ride along with the
352
+ * stream itself.
353
+ */
354
+ interface TTSPcmFormat {
355
+ encoding: "pcm-s16le";
356
+ sampleRate: number;
357
+ /** Mono only — the TTS manager rejects a stream declaring any other count. */
358
+ channels: number;
359
+ }
360
+ /**
361
+ * A streamed TTS result. `format` always describes `pcm-s16le`, regardless
362
+ * of any vendor label on the request, since every streaming provider decodes
363
+ * to that layout before handing the stream back.
364
+ */
365
+ interface TTSPcmStream {
366
+ body: ReadableStream<Uint8Array>;
367
+ format: TTSPcmFormat;
368
+ }
355
369
  interface TTSPlayer {
356
370
  /**
357
371
  * Explicit playback mode for the manager. Prefer setting this on concrete
@@ -367,22 +381,41 @@ interface TTSPlayer {
367
381
  setVoice(voice: string): void;
368
382
  isSupported(): boolean;
369
383
  /**
370
- * Stateless audio generation. Required for the `"audio"` playback mode: the
371
- * manager creates the audio element itself so it can analyze playback for
372
- * lip-sync. Players that can only `speak()` must use `"web-speech"` mode.
384
+ * Stateless audio generation. The `"audio"` playback mode requires this or
385
+ * `generateAudioStream`: the manager plays the finished buffer through an
386
+ * audio element it creates itself, so it can analyze playback for lip-sync.
387
+ * Players that can only `speak()` must use `"web-speech"` mode.
373
388
  */
374
389
  generateAudio?(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
390
+ /**
391
+ * Streaming counterpart to `generateAudio`, for players that can deliver PCM
392
+ * as it is synthesized instead of one finished buffer; the manager schedules
393
+ * it into Web Audio as it arrives. Takes precedence: the manager streams
394
+ * whenever this method exists, so a player implementing both never has
395
+ * `generateAudio` called. Aborting `signal`, or cancelling the returned
396
+ * stream's `body`, must cancel the upstream request.
397
+ */
398
+ generateAudioStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
375
399
  }
376
400
  interface TTSProvider {
377
401
  generateSpeech(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
378
402
  setVoice(voice: string): void;
403
+ /** Streaming counterpart to `generateSpeech`, called by a route handler (or a player delegating to it); `generateSpeech` remains for callers that want a whole buffer. Aborting `signal`, or cancelling the returned stream's `body`, must cancel the upstream request. */
404
+ generateSpeechStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
379
405
  }
380
406
  interface TTSManager {
381
407
  speak(text: string, options?: TTSOptions): Promise<void>;
382
408
  stop(): Promise<void>;
383
409
  setVoice(voice: string): void;
384
410
  isSupported(): boolean;
385
- /** Creates the audio analysis context up front; call from a user gesture handler so browsers allow playback later. */
411
+ /**
412
+ * Creates the audio analysis context up front, and, for a player that
413
+ * streams, warms the streamed playback context too; call from a user
414
+ * gesture handler so browsers allow playback later. On a browser without
415
+ * sticky activation (e.g. Safari), skipping this before a streaming
416
+ * `speak()` fails that call with `CharivoStateError` rather than merely
417
+ * degrading lip-sync.
418
+ */
386
419
  prepareAudio?(): Promise<void>;
387
420
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
388
421
  /** Final resource release; call stop() first - dispose() does not stop playback. */
@@ -1023,4 +1056,4 @@ interface CharivoOptions {
1023
1056
  */
1024
1057
  declare function createCharivo(options?: CharivoOptions): Charivo;
1025
1058
 
1026
- export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type BuiltInRealtimeManager, type BuiltInSTTManager, type BuiltInTTSManager, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, GEMINI_LIVE_ADAPTER, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, readResponseErrorMessage, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
1059
+ export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type BuiltInRealtimeManager, type BuiltInSTTManager, type BuiltInTTSManager, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, GEMINI_LIVE_ADAPTER, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPcmFormat, type TTSPcmStream, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, readResponseErrorMessage, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };