@charivo/core 0.33.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. */
@@ -785,6 +824,22 @@ interface FetchWithTimeoutOptions {
785
824
  declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
786
825
  signal?: never;
787
826
  }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
827
+ /**
828
+ * Reads the most specific failure message a non-ok response carries.
829
+ *
830
+ * Remote clients talk to a caller-supplied route, and a route that took the
831
+ * trouble to explain itself is the only place the real cause lives -- a
832
+ * provider rate limit or an upstream outage reaches the browser as a bare
833
+ * status line otherwise. Routes in this repo answer with `{ error, details? }`,
834
+ * where `details` carries the vendor's own text; both are read here, most
835
+ * specific first, falling back to the status line.
836
+ *
837
+ * A body that is not JSON is not an error in itself, so it falls back. Any
838
+ * other read failure -- an abort or timeout part-way through the body --
839
+ * propagates, so `fetchWithTimeout` can classify it instead of it being masked
840
+ * as a provider error.
841
+ */
842
+ declare function readResponseErrorMessage(response: Response): Promise<string>;
788
843
 
789
844
  declare class Charivo {
790
845
  private eventBus;
@@ -1007,4 +1062,4 @@ interface CharivoOptions {
1007
1062
  */
1008
1063
  declare function createCharivo(options?: CharivoOptions): Charivo;
1009
1064
 
1010
- 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, 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. */
@@ -785,6 +824,22 @@ interface FetchWithTimeoutOptions {
785
824
  declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
786
825
  signal?: never;
787
826
  }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
827
+ /**
828
+ * Reads the most specific failure message a non-ok response carries.
829
+ *
830
+ * Remote clients talk to a caller-supplied route, and a route that took the
831
+ * trouble to explain itself is the only place the real cause lives -- a
832
+ * provider rate limit or an upstream outage reaches the browser as a bare
833
+ * status line otherwise. Routes in this repo answer with `{ error, details? }`,
834
+ * where `details` carries the vendor's own text; both are read here, most
835
+ * specific first, falling back to the status line.
836
+ *
837
+ * A body that is not JSON is not an error in itself, so it falls back. Any
838
+ * other read failure -- an abort or timeout part-way through the body --
839
+ * propagates, so `fetchWithTimeout` can classify it instead of it being masked
840
+ * as a provider error.
841
+ */
842
+ declare function readResponseErrorMessage(response: Response): Promise<string>;
788
843
 
789
844
  declare class Charivo {
790
845
  private eventBus;
@@ -1007,4 +1062,4 @@ interface CharivoOptions {
1007
1062
  */
1008
1063
  declare function createCharivo(options?: CharivoOptions): Charivo;
1009
1064
 
1010
- 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, 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.js CHANGED
@@ -607,6 +607,20 @@ function fetchWithTimeout(input, init, options, consumeBody) {
607
607
  }
608
608
  );
609
609
  }
610
+ async function readResponseErrorMessage(response) {
611
+ let body;
612
+ try {
613
+ body = await response.json();
614
+ } catch (error) {
615
+ if (!(error instanceof SyntaxError)) {
616
+ throw error;
617
+ }
618
+ }
619
+ const fields = typeof body === "object" && body !== null ? body : {};
620
+ const detail = typeof fields.details === "string" ? fields.details : void 0;
621
+ const summary = typeof fields.error === "string" ? fields.error : void 0;
622
+ return detail ?? summary ?? response.statusText;
623
+ }
610
624
 
611
625
  // src/index.ts
612
626
  var Charivo = class {
@@ -1227,6 +1241,6 @@ function createCharivo(options = {}) {
1227
1241
  return charivo;
1228
1242
  }
1229
1243
 
1230
- export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, GEMINI_LIVE_ADAPTER, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
1244
+ export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, GEMINI_LIVE_ADAPTER, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, readResponseErrorMessage, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
1231
1245
  //# sourceMappingURL=index.js.map
1232
1246
  //# sourceMappingURL=index.js.map