Network quality

import { ChannelEventType } from '@seastart/srtc-web-sdk';
import type { ConnectionQualityEventData } from '@seastart/srtc-web-sdk';

srtc.onNotifyChannelEvent = (evt) => {
  switch (evt.type) {
    case ChannelEventType.CONNECTION_QUALITY_CHANGED: {
      // Fired when the network level changes (excellent/good/poor/lost/unknown)
      const { evaluation, previous } = evt.data as ConnectionQualityEventData;
      console.log(`Network quality: ${previous} -> ${evaluation.overall}`);
      console.log(`Reasons:`, evaluation.reasons);
      console.log(`MOS:`, evaluation.mos);
      break;
    }
    case ChannelEventType.CPU_CONSTRAINED:
      // The sender is persistently CPU-limited; consider lowering quality/resolution
      toast('CPU overloaded, consider lowering video quality');
      break;
    case ChannelEventType.BANDWIDTH_CONSTRAINED:
      // The sender is persistently bandwidth-limited
      toast('Insufficient uplink bandwidth');
      break;
  }
};

const q = srtc.getConnectionQuality();
// => QualityEvaluation

/** Connection quality level (aligned with the industry-standard 5 levels) */
export enum ConnectionQuality {
  /** Initial placeholder, used when there aren't enough samples, to avoid false alarms */
  Unknown = 'unknown',
  /** Excellent */
  Excellent = 'excellent',
  /** Good */
  Good = 'good',
  /** Poor */
  Poor = 'poor',
  /** Connection lost, media can't be transmitted; should trigger reconnection */
  Lost = 'lost',
}

export interface QualityEvaluation {
  /** Uplink quality */
  uplink: ConnectionQuality;
  /** Downlink quality */
  downlink: ConnectionQuality;
  /** Overall quality, the worse of uplink and downlink */
  overall: ConnectionQuality;
  /** Estimated audio/video MOS, 1.0 to 4.5 */
  mos: number;
  /** Main reasons for the current level, for troubleshooting */
  reasons: string[];
  /** Sample timestamp */
  timestamp: number;
}

const net = srtc.getNetworkStats();
// => NetworkStats

/** Overall network statistics */
export interface NetworkStats {
  /** Downlink bitrate, kb/s */
  bitrate_down: number;
  /** Uplink bitrate, kb/s */
  bitrate_up: number;
  /** Downlink packet loss rate, % */
  lossrate_down: number;
  /** Uplink packet loss rate, % */
  lossrate_up: number;
  /** Uplink packet count */
  pkt_up: number;
  /** Downlink packet count */
  pkt_down: number;
  /** Uplink lost packet count */
  pkt_loss_up: number;
  /** Downlink lost packet count */
  pkt_loss_down: number;
  /** Available uplink bandwidth estimated by BWE, kb/s (from candidate-pair) */
  available_outgoing_bitrate?: number;
  /** Available downlink bandwidth estimated by SFU/BWE, kb/s (from candidate-pair) */
  available_incoming_bitrate?: number;
  /** RTT observed on the publish connection, in ms */
  rtt_up?: number;
  /** RTT observed on the subscribe connection, in ms */
  rtt_down?: number;
}

const metric = srtc.getStreamMetric();
// => StreamMetric

/** Metric snapshot output periodically by the media streaming engine */
export interface StreamMetric {
  /** Overall network statistics */
  network: NetworkStats;
  /** Locally published audio tracks */
  local_audios: TrackMetric[];
  /** Locally published video tracks */
  local_videos: TrackMetric[];
  /** Subscribed remote audio tracks */
  remote_audios: TrackMetric[];
  /** Subscribed remote video tracks */
  remote_videos: TrackMetric[];
}

/** Real-time metric snapshot of a single track */
export interface TrackMetric {
  /** Real-time bitrate, kb/s */
  bitrate?: number;
  /** Audio level, dBFS */
  db?: number;
  /** Video width */
  width?: number;
  /** Video height */
  height?: number;
  /** Real-time frame rate */
  fps?: number;
  /** Raw sender/receiver stats */
  stats?: AudioSenderStats | VideoSenderStats | AudioReceiverStats | VideoReceiverStats;
  /** uid of the user who owns the track (subscriber side) */
  uid?: string;
  /** Other fields expanded from track.getInfo() */
  [key: string]: any;
}

/** Sending statistics */
interface SenderStats {
  /** Packets sent */
  packetsSent?: number;
  /** Bytes sent */
  bytesSent?: number;
  /** Network jitter perceived by the remote side, in ms */
  jitter?: number;
  /** Packets lost as reported by the remote side */
  packetsLost?: number;
  /** Round-trip time reported by the remote side, in ms */
  roundTripTime?: number;
  /** Outbound stream ID */
  streamId?: string;
  /** Timestamp */
  timestamp: number;
}

export interface AudioSenderStats extends SenderStats {
  type: 'audio';
  /** Audio level */
  audioLevel?: number;
}

export interface VideoSenderStats extends SenderStats {
  type: 'video';
  /** Number of FIR requests received */
  firCount: number;
  /** Number of PLI requests received */
  pliCount: number;
  /** Number of NACK requests received */
  nackCount: number;
  /** RTP stream ID */
  rid: string;
  /** Frame width */
  frameWidth: number;
  /** Frame height */
  frameHeight: number;
  /** Frame rate */
  framesPerSecond: number;
  /** Frames sent */
  framesSent: number;
  /** Quality limitation reason (bandwidth/cpu/other/none) */
  qualityLimitationReason?: string;
  /** Quality limitation durations */
  qualityLimitationDurations?: Record<string, number>;
  /** Number of resolution changes caused by quality limitation */
  qualityLimitationResolutionChanges?: number;
  /** Retransmitted packets */
  retransmittedPacketsSent?: number;
  /** Target bitrate */
  targetBitrate: number;
}

/** Receiving statistics */
interface ReceiverStats {
  /** Cumulative receiver jitter buffer delay (sum of delays of all frames emitted from the buffer since playback started), in ms */
  jitterBufferDelay?: number;
  /** Cumulative number of frames/samples emitted from the jitter buffer; used to convert the cumulative jitterBufferDelay into an average */
  jitterBufferEmittedCount?: number;
  /** Average per-frame jitter buffer delay within the period (since the previous stats sample), in ms; use this for perceived latency */
  jitterBufferAvgDelay?: number;
  /** Cumulative packets lost (based on RTP sequence number gaps) */
  packetsLost?: number;
  /** Cumulative RTP packets received */
  packetsReceived?: number;
  /** Cumulative bytes received (including RTP headers) */
  bytesReceived?: number;
  /** Media stream identifier (usually corresponds to the remote SSRC) */
  streamId?: string;
  /** Network-layer RTP jitter (as defined in RFC 3550), in ms */
  jitter?: number;
  /** Collection timestamp of this set of stats, in ms */
  timestamp: number;
}

export interface AudioReceiverStats extends ReceiverStats {
  type: 'audio';
  /** Audio level */
  audioLevel?: number;
  /** Concealed samples */
  concealedSamples?: number;
  /** Concealment events */
  concealmentEvents?: number;
  /** Silent concealed samples */
  silentConcealedSamples?: number;
  /** Silent concealment events */
  silentConcealmentEvents?: number;
  /** Total audio energy */
  totalAudioEnergy?: number;
  /** Total samples duration */
  totalSamplesDuration?: number;
}

export interface VideoReceiverStats extends ReceiverStats {
  type: 'video';
  /** Frames decoded */
  framesDecoded: number;
  /** Frames dropped */
  framesDropped: number;
  /** Frames received */
  framesReceived: number;
  /** Frame rate */
  framesPerSecond?: number;
  /** Frame width */
  frameWidth?: number;
  /** Frame height */
  frameHeight?: number;
  /** Number of FIR requests sent */
  firCount?: number;
  /** Number of PLI requests sent */
  pliCount?: number;
  /** Number of NACK requests sent */
  nackCount?: number;
  /** Decoder implementation */
  decoderImplementation?: string;
  /** MIME type */
  mimeType?: string;
  /** Video freeze count (a single freeze > 1 s or > 3x the average frame interval, per the W3C definition) */
  freezeCount?: number;
  /** Cumulative video freeze duration (s) */
  totalFreezesDuration?: number;
  /** Video pause count (remote side paused sending) */
  pauseCount?: number;
  /** Cumulative video pause duration (s) */
  totalPausesDuration?: number;
  /** Frames assembled from multiple RTP packets */
  framesAssembledFromMultiplePackets?: number;
  /** Cumulative assembly time of all frames (s) */
  totalAssemblyTime?: number;
}

// 1. Subscribe to level changes for UI hints
srtc.onNotifyChannelEvent = (evt) => {
  if (evt.type === ChannelEventType.CONNECTION_QUALITY_CHANGED) {
    const { evaluation } = evt.data as ConnectionQualityEventData;
    updateNetworkIndicator(evaluation.overall); // Your UI update function
  }
};

// 2. When you need a detailed data panel, call getStreamMetric on demand
setInterval(() => {
  const metric = srtc.getStreamMetric();
  if (metric) renderDashboard(metric);
}, 2000);

const q = srtc.getConnectionQuality();
if (q.uplink === ConnectionQuality.Poor) {
  showTip('Your network is poor; others may not see you clearly');
} else if (q.downlink === ConnectionQuality.Poor) {
  showTip('Poor network, optimizing video quality');
}

srtc.disableLocalTrack(localVideoTrack);  // Disable (lightweight, keeps the publishing path, can be restored at any time)
srtc.enableLocalTrack(localVideoTrack);   // Re-enable after the network recovers

await srtc.unsubscribeRemoteTrack(remoteVideoTrack);

await srtc.publishLocalTrack(localVideoTrack, {
  degradationPreference: 'maintain-resolution',
});

import { ChannelEventType, ConnectionQuality } from '@seastart/srtc-web-sdk';
import type { ConnectionQualityEventData, LocalVideoTrack } from '@seastart/srtc-web-sdk';

// Assume a local camera track has already been created and is held here
let cameraTrack: LocalVideoTrack;
// Marks whether the camera was turned off because of a poor network, so it can be turned back on automatically after recovery
let cameraOffByNetwork = false;

// Publish: enable simulcast (the remote side can drop to the low stream automatically on a poor network); if sharing documents/slides, use maintain-resolution to keep it sharp
await srtc.publishLocalTrack(cameraTrack, {
  degradationPreference: 'maintain-framerate', // Use this for general interaction; change to 'maintain-resolution' for document sharing
});

// Simple debounce: show the same kind of hint at most once every N seconds
const lastToast: Record<string, number> = {};
function toastOnce(key: string, msg: string, intervalMs = 8000) {
  const now = Date.now();
  if (now - (lastToast[key] ?? 0) < intervalMs) return;
  lastToast[key] = now;
  toast(msg); // Replace with your toast implementation
}

srtc.onNotifyChannelEvent = (evt) => {
  switch (evt.type) {
    // 1) Network level changed: update the indicator + direction-specific hints + reconnection + recovery
    case ChannelEventType.CONNECTION_QUALITY_CHANGED: {
      const { evaluation } = evt.data as ConnectionQualityEventData;
      updateNetworkIndicator(evaluation.overall); // Your status indicator

      if (evaluation.overall === ConnectionQuality.Lost) {
        showReconnecting(); // Show "Reconnecting"
      } else if (evaluation.uplink === ConnectionQuality.Poor) {
        toastOnce('uplink', 'Your network is poor; others may not see you clearly');
      } else if (evaluation.downlink === ConnectionQuality.Poor) {
        toastOnce('downlink', 'Poor network, optimizing video quality');
        // When the downlink is poor, the SFU automatically drops you to the low stream, which usually resolves it; generally no action is needed.
        // For an "audio only" fallback: if the downlink stays poor for a long time, ask the user to confirm first,
        // then call srtc.unsubscribeRemoteTrack(videoTrack) on the currently subscribed remote video tracks to unsubscribe, keeping only audio.
      }

      // Network recovered and the camera was turned off earlier because of the poor network → turn it back on automatically
      if (
        cameraOffByNetwork &&
        (evaluation.overall === ConnectionQuality.Good ||
          evaluation.overall === ConnectionQuality.Excellent)
      ) {
        srtc.enableLocalTrack(cameraTrack);
        cameraOffByNetwork = false;
      }
      break;
    }

    // 2) Insufficient uplink bandwidth: notify the user and offer a one-click "turn off camera, keep audio" action (not done silently)
    case ChannelEventType.BANDWIDTH_CONSTRAINED:
      toastOnce('bw', 'Insufficient uplink bandwidth; turn off the camera to keep the voice call');
      showDowngradeButton(() => {
        srtc.disableLocalTrack(cameraTrack); // Turn off the camera, keep audio
        cameraOffByNetwork = true;
      });
      break;

    // 3) The device's encoder can't keep up: suggest lowering quality / closing other apps
    case ChannelEventType.CPU_CONSTRAINED:
      toastOnce('cpu', 'Device busy; close other apps or lower video quality');
      break;
  }
};