@furious.luke/argus-js 0.5.6 → 0.5.7

package/dist/index.d.cts

@@ -79,6 +79,11 @@ type SignalMessage = {
     track: TrackType;
     track_id?: string;
     reason?: string;
+} | {
+    type: "speech_slow";
+    realtime_factor: number;
+} | {
+    type: "speech_recovered";
 } | {
     type: "recovery_event";
     event: "recovery_started" | "recovery_retry" | "recovery_failed";
@@ -131,6 +136,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called when server-side text-to-speech generation crosses the realtime
+     * boundary: `degraded: true` when the TTS provider drops below realtime
+     * (`realtimeFactor` < 1.0), synthesizing audio slower than it plays and starving
+     * playout regardless of the network, and `degraded: false` when a later utterance
+     * climbs comfortably back above realtime. The degraded transition is raised live
+     * during synthesis — a long, slow utterance is reported while it is happening, not
+     * once it finishes. Edge-triggered — fires only on the transition, not per
+     * utterance, and a factor hovering at the boundary does not flap it. This is a
+     * distinct axis from {@link onConnectionQualityChange} (which is network health);
+     * react by, e.g., warning the user or offering a text fallback.
+     */
+    onSpeechQualityChange?: (event: SpeechQualityEvent) => void;
     /**
      * Called for every periodic connection-stats sample while connected — the raw
      * feed behind {@link onConnectionQualityChange}. Fires at
@@ -157,6 +175,17 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A change in server-side text-to-speech generation health, delivered to
+ * {@link PublisherCallbacks.onSpeechQualityChange}. `degraded` is `true` on the
+ * transition into below-realtime synthesis (`realtimeFactor` < 1.0) and `false`
+ * once synthesis climbs comfortably back above realtime. `realtimeFactor` (audio
+ * produced ÷ wall-clock to produce it) accompanies a degraded transition.
+ */
+interface SpeechQualityEvent {
+    degraded: boolean;
+    realtimeFactor?: number;
+}
 /**
  * A coarse assessment of the uplink to the media server, derived from periodic
  * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
@@ -811,4 +840,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type SpeechQualityEvent, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };

package/dist/index.d.ts

@@ -79,6 +79,11 @@ type SignalMessage = {
     track: TrackType;
     track_id?: string;
     reason?: string;
+} | {
+    type: "speech_slow";
+    realtime_factor: number;
+} | {
+    type: "speech_recovered";
 } | {
     type: "recovery_event";
     event: "recovery_started" | "recovery_retry" | "recovery_failed";
@@ -131,6 +136,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called when server-side text-to-speech generation crosses the realtime
+     * boundary: `degraded: true` when the TTS provider drops below realtime
+     * (`realtimeFactor` < 1.0), synthesizing audio slower than it plays and starving
+     * playout regardless of the network, and `degraded: false` when a later utterance
+     * climbs comfortably back above realtime. The degraded transition is raised live
+     * during synthesis — a long, slow utterance is reported while it is happening, not
+     * once it finishes. Edge-triggered — fires only on the transition, not per
+     * utterance, and a factor hovering at the boundary does not flap it. This is a
+     * distinct axis from {@link onConnectionQualityChange} (which is network health);
+     * react by, e.g., warning the user or offering a text fallback.
+     */
+    onSpeechQualityChange?: (event: SpeechQualityEvent) => void;
     /**
      * Called for every periodic connection-stats sample while connected — the raw
      * feed behind {@link onConnectionQualityChange}. Fires at
@@ -157,6 +175,17 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A change in server-side text-to-speech generation health, delivered to
+ * {@link PublisherCallbacks.onSpeechQualityChange}. `degraded` is `true` on the
+ * transition into below-realtime synthesis (`realtimeFactor` < 1.0) and `false`
+ * once synthesis climbs comfortably back above realtime. `realtimeFactor` (audio
+ * produced ÷ wall-clock to produce it) accompanies a degraded transition.
+ */
+interface SpeechQualityEvent {
+    degraded: boolean;
+    realtimeFactor?: number;
+}
 /**
  * A coarse assessment of the uplink to the media server, derived from periodic
  * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
@@ -811,4 +840,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type SpeechQualityEvent, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };

package/dist/index.js

@@ -1092,6 +1092,17 @@ var Publisher = class {
         this.completeMediaRecovery(msg.track);
         break;
       }
+      case "speech_slow": {
+        this.opts.callbacks?.onSpeechQualityChange?.({
+          degraded: true,
+          realtimeFactor: msg.realtime_factor
+        });
+        break;
+      }
+      case "speech_recovered": {
+        this.opts.callbacks?.onSpeechQualityChange?.({ degraded: false });
+        break;
+      }
       case "error": {
         const err = new ReportedPublisherError(msg.error, msg.fatal === true);
         const pending = this.pendingAnswer;