@charivo/core 0.30.0 → 0.32.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
@@ -16,6 +16,15 @@ interface AvatarControlCatalog {
16
16
  * When omitted or empty, no semantic hints are provided (preserving today's behavior).
17
17
  */
18
18
  expressionDescriptions?: Record<string, string>;
19
+ /**
20
+ * Optional semantic descriptions for each motion.
21
+ * Keys should correspond to group names in `motions`; a group's array is
22
+ * positional, so index 0 describes motion index 0.
23
+ * Groups not present in `motions`, and indices at or beyond a group's count,
24
+ * are ignored by consumers.
25
+ * When omitted or empty, no semantic hints are provided (preserving today's behavior).
26
+ */
27
+ motionDescriptions?: Record<string, string[]>;
19
28
  }
20
29
  interface Character {
21
30
  id: string;
@@ -308,7 +317,10 @@ interface Renderer {
308
317
  playExpression?(expressionId: string): void;
309
318
  /** Releases the active expression so the model returns to its base face — implementations may fade it out rather than snapping; renderers without expression state omit it. */
310
319
  stopExpression?(): void;
311
- playMotionByGroup?(group: string, index: number): void;
320
+ /** `options.muteSound` asks for the motion without its baked-in sample clip; renderers with no motion audio may ignore it, and omitting it keeps the clip audible. */
321
+ playMotionByGroup?(group: string, index: number, options?: {
322
+ muteSound?: boolean;
323
+ }): void;
312
324
  lookAt?(coords: GazeCoordinates): void;
313
325
  getAvailableExpressions?(): string[];
314
326
  getAvailableMotionGroups?(): Record<string, number>;
@@ -369,6 +381,17 @@ interface TTSManager {
369
381
  /** Final resource release; call stop() first - dispose() does not stop playback. */
370
382
  dispose?(): Promise<void>;
371
383
  }
384
+ /**
385
+ * `TTSManager` with the members the built-in manager always provides required
386
+ * instead of optional. A third-party `TTSManager` may omit audio preparation,
387
+ * event wiring, or disposal; the manager returned by `createTTSManager` never
388
+ * does, so callers of the factory should not have to narrow them.
389
+ */
390
+ interface BuiltInTTSManager extends TTSManager {
391
+ prepareAudio(): Promise<void>;
392
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
393
+ dispose(): Promise<void>;
394
+ }
372
395
  interface STTOptions {
373
396
  language?: string;
374
397
  }
@@ -388,6 +411,13 @@ interface STTManager {
388
411
  isRecording(): boolean;
389
412
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
390
413
  }
414
+ /**
415
+ * `STTManager` with event wiring required instead of optional — the manager
416
+ * returned by `createSTTManager` always provides it.
417
+ */
418
+ interface BuiltInSTTManager extends STTManager {
419
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
420
+ }
391
421
  interface RealtimeManager {
392
422
  setCharacter(character: Character): void;
393
423
  getState(): RealtimeState;
@@ -403,6 +433,14 @@ interface RealtimeManager {
403
433
  getRegisteredTools(): ToolDefinition[];
404
434
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
405
435
  }
436
+ /**
437
+ * `RealtimeManager` with the members the built-in manager always provides
438
+ * required instead of optional — `createRealtimeManager` implements both.
439
+ */
440
+ interface BuiltInRealtimeManager extends RealtimeManager {
441
+ prepareAudio(config?: RealtimeSessionConfig): Promise<void>;
442
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
443
+ }
406
444
  /**
407
445
  * An interface (not a type alias) so third-party packages can extend it via
408
446
  * declaration merging — a custom renderer or manager declares its own events
@@ -544,9 +582,15 @@ interface EventMap {
544
582
  "avatar:expression": {
545
583
  expressionId: string;
546
584
  };
585
+ /**
586
+ * `muteSound` is a rendering request — play the motion without its baked-in
587
+ * sample clip — not a provenance tag. Absent means audible, so every existing
588
+ * emitter keeps today's behavior.
589
+ */
547
590
  "avatar:motion": {
548
591
  group: string;
549
592
  index: number;
593
+ muteSound?: boolean;
550
594
  };
551
595
  "avatar:gaze": GazeCoordinates;
552
596
  "realtime:error": {
@@ -956,4 +1000,4 @@ interface CharivoOptions {
956
1000
  */
957
1001
  declare function createCharivo(options?: CharivoOptions): Charivo;
958
1002
 
959
- export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, 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, 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 };
1003
+ 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, 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 };
package/dist/index.d.ts CHANGED
@@ -16,6 +16,15 @@ interface AvatarControlCatalog {
16
16
  * When omitted or empty, no semantic hints are provided (preserving today's behavior).
17
17
  */
18
18
  expressionDescriptions?: Record<string, string>;
19
+ /**
20
+ * Optional semantic descriptions for each motion.
21
+ * Keys should correspond to group names in `motions`; a group's array is
22
+ * positional, so index 0 describes motion index 0.
23
+ * Groups not present in `motions`, and indices at or beyond a group's count,
24
+ * are ignored by consumers.
25
+ * When omitted or empty, no semantic hints are provided (preserving today's behavior).
26
+ */
27
+ motionDescriptions?: Record<string, string[]>;
19
28
  }
20
29
  interface Character {
21
30
  id: string;
@@ -308,7 +317,10 @@ interface Renderer {
308
317
  playExpression?(expressionId: string): void;
309
318
  /** Releases the active expression so the model returns to its base face — implementations may fade it out rather than snapping; renderers without expression state omit it. */
310
319
  stopExpression?(): void;
311
- playMotionByGroup?(group: string, index: number): void;
320
+ /** `options.muteSound` asks for the motion without its baked-in sample clip; renderers with no motion audio may ignore it, and omitting it keeps the clip audible. */
321
+ playMotionByGroup?(group: string, index: number, options?: {
322
+ muteSound?: boolean;
323
+ }): void;
312
324
  lookAt?(coords: GazeCoordinates): void;
313
325
  getAvailableExpressions?(): string[];
314
326
  getAvailableMotionGroups?(): Record<string, number>;
@@ -369,6 +381,17 @@ interface TTSManager {
369
381
  /** Final resource release; call stop() first - dispose() does not stop playback. */
370
382
  dispose?(): Promise<void>;
371
383
  }
384
+ /**
385
+ * `TTSManager` with the members the built-in manager always provides required
386
+ * instead of optional. A third-party `TTSManager` may omit audio preparation,
387
+ * event wiring, or disposal; the manager returned by `createTTSManager` never
388
+ * does, so callers of the factory should not have to narrow them.
389
+ */
390
+ interface BuiltInTTSManager extends TTSManager {
391
+ prepareAudio(): Promise<void>;
392
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
393
+ dispose(): Promise<void>;
394
+ }
372
395
  interface STTOptions {
373
396
  language?: string;
374
397
  }
@@ -388,6 +411,13 @@ interface STTManager {
388
411
  isRecording(): boolean;
389
412
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
390
413
  }
414
+ /**
415
+ * `STTManager` with event wiring required instead of optional — the manager
416
+ * returned by `createSTTManager` always provides it.
417
+ */
418
+ interface BuiltInSTTManager extends STTManager {
419
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
420
+ }
391
421
  interface RealtimeManager {
392
422
  setCharacter(character: Character): void;
393
423
  getState(): RealtimeState;
@@ -403,6 +433,14 @@ interface RealtimeManager {
403
433
  getRegisteredTools(): ToolDefinition[];
404
434
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
405
435
  }
436
+ /**
437
+ * `RealtimeManager` with the members the built-in manager always provides
438
+ * required instead of optional — `createRealtimeManager` implements both.
439
+ */
440
+ interface BuiltInRealtimeManager extends RealtimeManager {
441
+ prepareAudio(config?: RealtimeSessionConfig): Promise<void>;
442
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
443
+ }
406
444
  /**
407
445
  * An interface (not a type alias) so third-party packages can extend it via
408
446
  * declaration merging — a custom renderer or manager declares its own events
@@ -544,9 +582,15 @@ interface EventMap {
544
582
  "avatar:expression": {
545
583
  expressionId: string;
546
584
  };
585
+ /**
586
+ * `muteSound` is a rendering request — play the motion without its baked-in
587
+ * sample clip — not a provenance tag. Absent means audible, so every existing
588
+ * emitter keeps today's behavior.
589
+ */
547
590
  "avatar:motion": {
548
591
  group: string;
549
592
  index: number;
593
+ muteSound?: boolean;
550
594
  };
551
595
  "avatar:gaze": GazeCoordinates;
552
596
  "realtime:error": {
@@ -956,4 +1000,4 @@ interface CharivoOptions {
956
1000
  */
957
1001
  declare function createCharivo(options?: CharivoOptions): Charivo;
958
1002
 
959
- export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, 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, 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 };
1003
+ 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, 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 };