@furious.luke/argus-js 0.5.5 → 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,32 @@ 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
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -144,6 +175,97 @@ 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
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -232,6 +354,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -277,6 +417,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -459,6 +604,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -688,4 +840,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, 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,32 @@ 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
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -144,6 +175,97 @@ 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
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -232,6 +354,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -277,6 +417,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -459,6 +604,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -688,4 +840,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, 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 };