@charivo/core 0.29.0 → 0.31.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;
@@ -132,18 +141,17 @@ interface RealtimeState {
132
141
  text: string;
133
142
  };
134
143
  /**
135
- * Whether the character's audio is still coming out of the speakers.
136
- *
137
- * Not the same question as `response.status`, and the difference is the one
138
- * that bites: a response completes when the provider finishes SENDING audio,
139
- * and playback runs on past that. Anything that asks "is the character still
140
- * talking" — a barge-in, a mouth animation, a UI affordance — has to read
141
- * this, not the response status.
142
- *
143
- * Derived from the normalized `audio.output.started` / `audio.output.ended`
144
- * transport events, so it means the same thing for every provider.
144
+ * Whether the character is still audible. Outlasts `response.status`, which
145
+ * completes when the provider stops sending while playback runs on.
145
146
  */
146
147
  audioPlaying: boolean;
148
+ /**
149
+ * Whether a reply is still expected. Wider than
150
+ * `response.status === "responding"` — it also covers the gap before the
151
+ * reply starts streaming. Only the response-in-progress refusal; an inactive
152
+ * or reconnecting session is rejected separately.
153
+ */
154
+ awaitingResponse: boolean;
147
155
  lastError: Error | null;
148
156
  }
149
157
  interface RealtimeUsageEvent {
@@ -309,7 +317,10 @@ interface Renderer {
309
317
  playExpression?(expressionId: string): void;
310
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. */
311
319
  stopExpression?(): void;
312
- 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;
313
324
  lookAt?(coords: GazeCoordinates): void;
314
325
  getAvailableExpressions?(): string[];
315
326
  getAvailableMotionGroups?(): Record<string, number>;
@@ -545,9 +556,15 @@ interface EventMap {
545
556
  "avatar:expression": {
546
557
  expressionId: string;
547
558
  };
559
+ /**
560
+ * `muteSound` is a rendering request — play the motion without its baked-in
561
+ * sample clip — not a provenance tag. Absent means audible, so every existing
562
+ * emitter keeps today's behavior.
563
+ */
548
564
  "avatar:motion": {
549
565
  group: string;
550
566
  index: number;
567
+ muteSound?: boolean;
551
568
  };
552
569
  "avatar:gaze": GazeCoordinates;
553
570
  "realtime:error": {
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;
@@ -132,18 +141,17 @@ interface RealtimeState {
132
141
  text: string;
133
142
  };
134
143
  /**
135
- * Whether the character's audio is still coming out of the speakers.
136
- *
137
- * Not the same question as `response.status`, and the difference is the one
138
- * that bites: a response completes when the provider finishes SENDING audio,
139
- * and playback runs on past that. Anything that asks "is the character still
140
- * talking" — a barge-in, a mouth animation, a UI affordance — has to read
141
- * this, not the response status.
142
- *
143
- * Derived from the normalized `audio.output.started` / `audio.output.ended`
144
- * transport events, so it means the same thing for every provider.
144
+ * Whether the character is still audible. Outlasts `response.status`, which
145
+ * completes when the provider stops sending while playback runs on.
145
146
  */
146
147
  audioPlaying: boolean;
148
+ /**
149
+ * Whether a reply is still expected. Wider than
150
+ * `response.status === "responding"` — it also covers the gap before the
151
+ * reply starts streaming. Only the response-in-progress refusal; an inactive
152
+ * or reconnecting session is rejected separately.
153
+ */
154
+ awaitingResponse: boolean;
147
155
  lastError: Error | null;
148
156
  }
149
157
  interface RealtimeUsageEvent {
@@ -309,7 +317,10 @@ interface Renderer {
309
317
  playExpression?(expressionId: string): void;
310
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. */
311
319
  stopExpression?(): void;
312
- 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;
313
324
  lookAt?(coords: GazeCoordinates): void;
314
325
  getAvailableExpressions?(): string[];
315
326
  getAvailableMotionGroups?(): Record<string, number>;
@@ -545,9 +556,15 @@ interface EventMap {
545
556
  "avatar:expression": {
546
557
  expressionId: string;
547
558
  };
559
+ /**
560
+ * `muteSound` is a rendering request — play the motion without its baked-in
561
+ * sample clip — not a provenance tag. Absent means audible, so every existing
562
+ * emitter keeps today's behavior.
563
+ */
548
564
  "avatar:motion": {
549
565
  group: string;
550
566
  index: number;
567
+ muteSound?: boolean;
551
568
  };
552
569
  "avatar:gaze": GazeCoordinates;
553
570
  "realtime:error": {