@charivo/core 0.34.0 → 0.35.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
@@ -352,6 +352,26 @@ interface TTSOptions {
352
352
  voice?: string;
353
353
  }
354
354
  type TTSPlaybackMode = "audio" | "web-speech";
355
+ /**
356
+ * Raw PCM carries no container, so the sample layout can't be sniffed from
357
+ * the bytes the way a WAV/MP3 buffer can — it has to ride along with the
358
+ * stream itself.
359
+ */
360
+ interface TTSPcmFormat {
361
+ encoding: "pcm-s16le";
362
+ sampleRate: number;
363
+ /** Mono only — the TTS manager rejects a stream declaring any other count. */
364
+ channels: number;
365
+ }
366
+ /**
367
+ * A streamed TTS result. `format` always describes `pcm-s16le`, regardless
368
+ * of any vendor label on the request, since every streaming provider decodes
369
+ * to that layout before handing the stream back.
370
+ */
371
+ interface TTSPcmStream {
372
+ body: ReadableStream<Uint8Array>;
373
+ format: TTSPcmFormat;
374
+ }
355
375
  interface TTSPlayer {
356
376
  /**
357
377
  * Explicit playback mode for the manager. Prefer setting this on concrete
@@ -367,22 +387,41 @@ interface TTSPlayer {
367
387
  setVoice(voice: string): void;
368
388
  isSupported(): boolean;
369
389
  /**
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.
390
+ * Stateless audio generation. The `"audio"` playback mode requires this or
391
+ * `generateAudioStream`: the manager plays the finished buffer through an
392
+ * audio element it creates itself, so it can analyze playback for lip-sync.
393
+ * Players that can only `speak()` must use `"web-speech"` mode.
373
394
  */
374
395
  generateAudio?(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
396
+ /**
397
+ * Streaming counterpart to `generateAudio`, for players that can deliver PCM
398
+ * as it is synthesized instead of one finished buffer; the manager schedules
399
+ * it into Web Audio as it arrives. Takes precedence: the manager streams
400
+ * whenever this method exists, so a player implementing both never has
401
+ * `generateAudio` called. Aborting `signal`, or cancelling the returned
402
+ * stream's `body`, must cancel the upstream request.
403
+ */
404
+ generateAudioStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
375
405
  }
376
406
  interface TTSProvider {
377
407
  generateSpeech(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
378
408
  setVoice(voice: string): void;
409
+ /** 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. */
410
+ generateSpeechStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
379
411
  }
380
412
  interface TTSManager {
381
413
  speak(text: string, options?: TTSOptions): Promise<void>;
382
414
  stop(): Promise<void>;
383
415
  setVoice(voice: string): void;
384
416
  isSupported(): boolean;
385
- /** Creates the audio analysis context up front; call from a user gesture handler so browsers allow playback later. */
417
+ /**
418
+ * Creates the audio analysis context up front, and, for a player that
419
+ * streams, warms the streamed playback context too; call from a user
420
+ * gesture handler so browsers allow playback later. On a browser without
421
+ * sticky activation (e.g. Safari), skipping this before a streaming
422
+ * `speak()` fails that call with `CharivoStateError` rather than merely
423
+ * degrading lip-sync.
424
+ */
386
425
  prepareAudio?(): Promise<void>;
387
426
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
388
427
  /** Final resource release; call stop() first - dispose() does not stop playback. */
@@ -1023,4 +1062,4 @@ interface CharivoOptions {
1023
1062
  */
1024
1063
  declare function createCharivo(options?: CharivoOptions): Charivo;
1025
1064
 
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 };
1065
+ 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
@@ -352,6 +352,26 @@ interface TTSOptions {
352
352
  voice?: string;
353
353
  }
354
354
  type TTSPlaybackMode = "audio" | "web-speech";
355
+ /**
356
+ * Raw PCM carries no container, so the sample layout can't be sniffed from
357
+ * the bytes the way a WAV/MP3 buffer can — it has to ride along with the
358
+ * stream itself.
359
+ */
360
+ interface TTSPcmFormat {
361
+ encoding: "pcm-s16le";
362
+ sampleRate: number;
363
+ /** Mono only — the TTS manager rejects a stream declaring any other count. */
364
+ channels: number;
365
+ }
366
+ /**
367
+ * A streamed TTS result. `format` always describes `pcm-s16le`, regardless
368
+ * of any vendor label on the request, since every streaming provider decodes
369
+ * to that layout before handing the stream back.
370
+ */
371
+ interface TTSPcmStream {
372
+ body: ReadableStream<Uint8Array>;
373
+ format: TTSPcmFormat;
374
+ }
355
375
  interface TTSPlayer {
356
376
  /**
357
377
  * Explicit playback mode for the manager. Prefer setting this on concrete
@@ -367,22 +387,41 @@ interface TTSPlayer {
367
387
  setVoice(voice: string): void;
368
388
  isSupported(): boolean;
369
389
  /**
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.
390
+ * Stateless audio generation. The `"audio"` playback mode requires this or
391
+ * `generateAudioStream`: the manager plays the finished buffer through an
392
+ * audio element it creates itself, so it can analyze playback for lip-sync.
393
+ * Players that can only `speak()` must use `"web-speech"` mode.
373
394
  */
374
395
  generateAudio?(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
396
+ /**
397
+ * Streaming counterpart to `generateAudio`, for players that can deliver PCM
398
+ * as it is synthesized instead of one finished buffer; the manager schedules
399
+ * it into Web Audio as it arrives. Takes precedence: the manager streams
400
+ * whenever this method exists, so a player implementing both never has
401
+ * `generateAudio` called. Aborting `signal`, or cancelling the returned
402
+ * stream's `body`, must cancel the upstream request.
403
+ */
404
+ generateAudioStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
375
405
  }
376
406
  interface TTSProvider {
377
407
  generateSpeech(text: string, options?: TTSOptions): Promise<ArrayBuffer>;
378
408
  setVoice(voice: string): void;
409
+ /** 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. */
410
+ generateSpeechStream?(text: string, options?: TTSOptions, signal?: AbortSignal): Promise<TTSPcmStream>;
379
411
  }
380
412
  interface TTSManager {
381
413
  speak(text: string, options?: TTSOptions): Promise<void>;
382
414
  stop(): Promise<void>;
383
415
  setVoice(voice: string): void;
384
416
  isSupported(): boolean;
385
- /** Creates the audio analysis context up front; call from a user gesture handler so browsers allow playback later. */
417
+ /**
418
+ * Creates the audio analysis context up front, and, for a player that
419
+ * streams, warms the streamed playback context too; call from a user
420
+ * gesture handler so browsers allow playback later. On a browser without
421
+ * sticky activation (e.g. Safari), skipping this before a streaming
422
+ * `speak()` fails that call with `CharivoStateError` rather than merely
423
+ * degrading lip-sync.
424
+ */
386
425
  prepareAudio?(): Promise<void>;
387
426
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
388
427
  /** Final resource release; call stop() first - dispose() does not stop playback. */
@@ -1023,4 +1062,4 @@ interface CharivoOptions {
1023
1062
  */
1024
1063
  declare function createCharivo(options?: CharivoOptions): Charivo;
1025
1064
 
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 };
1065
+ 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 };