@reactor-team/js-sdk 3.0.2 → 3.1.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.cjs CHANGED
@@ -379,14 +379,185 @@ function toPublicClip(clip) {
379
379
  }
380
380
 
381
381
  // src/internal/stats.ts
382
- var STATS_INTERVAL_MS = 2e3;
383
- function createRTCStatsExtractor() {
382
+ var LOCAL_STATS_INTERVAL_MS = 2e3;
383
+ var RUNTIME_REPORT_INTERVAL_MS = 5e3;
384
+ function pollPeerStats(client, intervalMs, onReport) {
385
+ let stopped = false;
386
+ let reading = false;
387
+ const handle = setInterval(() => {
388
+ if (reading) {
389
+ return;
390
+ }
391
+ const peerConnection = client.getPeerConnection();
392
+ if (!peerConnection) {
393
+ return;
394
+ }
395
+ reading = true;
396
+ void peerConnection.getStats().then(
397
+ (report) => {
398
+ if (stopped) {
399
+ return;
400
+ }
401
+ try {
402
+ onReport(report);
403
+ } catch (error) {
404
+ console.error("[Reactor] stats report handler threw:", error);
405
+ }
406
+ },
407
+ () => {
408
+ }
409
+ ).finally(() => {
410
+ reading = false;
411
+ });
412
+ }, intervalMs);
413
+ return () => {
414
+ stopped = true;
415
+ clearInterval(handle);
416
+ };
417
+ }
418
+ function roundMs(ms) {
419
+ return Math.round(ms * 1e3) / 1e3;
420
+ }
421
+ function secondsToMs(seconds) {
422
+ return roundMs(seconds * 1e3);
423
+ }
424
+ var WIRE_CODECS = {
425
+ video: /* @__PURE__ */ new Set(["vp8", "vp9", "av1", "h264", "h265"]),
426
+ audio: /* @__PURE__ */ new Set(["opus"])
427
+ };
428
+ function createTrackStatsExtractor() {
429
+ const lastBytes = /* @__PURE__ */ new Map();
430
+ return (report, tracks, pausedTracks) => {
431
+ const reportWithLookup = report;
432
+ const stats = [];
433
+ const seenStreams = /* @__PURE__ */ new Set();
434
+ const remoteInbound = /* @__PURE__ */ new Map();
435
+ report.forEach((stat) => {
436
+ if (stat.type === "remote-inbound-rtp" && stat.localId !== void 0) {
437
+ remoteInbound.set(stat.localId, stat);
438
+ }
439
+ });
440
+ report.forEach((stat) => {
441
+ const inbound = stat.type === "inbound-rtp";
442
+ if (!inbound && stat.type !== "outbound-rtp" || stat.mid === void 0) {
443
+ return;
444
+ }
445
+ const direction = inbound ? "recvonly" : "sendonly";
446
+ const streamKey = `${direction}:${stat.mid}`;
447
+ if (seenStreams.has(streamKey)) {
448
+ return;
449
+ }
450
+ const track = tracks.find((entry) => entry.mid === stat.mid && entry.direction === direction);
451
+ const codecStat = stat.codecId !== void 0 ? reportWithLookup.get(stat.codecId) : void 0;
452
+ const codec = codecStat?.mimeType?.split("/")[1]?.toLowerCase();
453
+ if (track === void 0 || codec === void 0 || !WIRE_CODECS[track.kind].has(codec)) {
454
+ return;
455
+ }
456
+ seenStreams.add(streamKey);
457
+ const metrics = {};
458
+ const put = (key, value) => {
459
+ if (value !== void 0) {
460
+ metrics[key] = value;
461
+ }
462
+ };
463
+ const bytes = inbound ? stat.bytesReceived : stat.bytesSent;
464
+ if (bytes !== void 0) {
465
+ const previous = lastBytes.get(stat.id);
466
+ if (previous !== void 0 && stat.timestamp > previous.timestamp && bytes >= previous.bytes) {
467
+ put("bitrate_bps", Math.round((bytes - previous.bytes) * 8 * 1e3 / (stat.timestamp - previous.timestamp)));
468
+ }
469
+ lastBytes.set(stat.id, { bytes, timestamp: stat.timestamp });
470
+ }
471
+ const keyframeRequests = stat.firCount !== void 0 || stat.pliCount !== void 0 ? (stat.firCount ?? 0) + (stat.pliCount ?? 0) : void 0;
472
+ if (inbound) {
473
+ put("packets_received", stat.packetsReceived);
474
+ put("packets_lost", stat.packetsLost);
475
+ put("jitter_ms", stat.jitter !== void 0 ? secondsToMs(stat.jitter) : void 0);
476
+ put("nack_count", stat.nackCount);
477
+ if (track.kind === "video") {
478
+ put("frames_per_second", stat.framesPerSecond);
479
+ put("frames_decoded", stat.framesDecoded);
480
+ put("frames_dropped", stat.framesDropped);
481
+ put("frame_width", stat.frameWidth);
482
+ put("frame_height", stat.frameHeight);
483
+ put("keyframe_requests", keyframeRequests);
484
+ } else {
485
+ put("concealed_samples", stat.concealedSamples);
486
+ put("total_samples_received", stat.totalSamplesReceived);
487
+ }
488
+ } else {
489
+ const remote = remoteInbound.get(stat.id);
490
+ put("packets_sent", stat.packetsSent);
491
+ put("retransmitted_packets_sent", stat.retransmittedPacketsSent);
492
+ put("nack_count", stat.nackCount);
493
+ put("packets_lost", remote?.packetsLost);
494
+ put("jitter_ms", remote?.jitter !== void 0 ? secondsToMs(remote.jitter) : void 0);
495
+ put("round_trip_time_ms", remote?.roundTripTime !== void 0 ? secondsToMs(remote.roundTripTime) : void 0);
496
+ if (track.kind === "video") {
497
+ put("frames_per_second", stat.framesPerSecond);
498
+ put("frames_encoded", stat.framesEncoded);
499
+ put("frame_width", stat.frameWidth);
500
+ put("frame_height", stat.frameHeight);
501
+ put("keyframe_requests", keyframeRequests);
502
+ }
503
+ }
504
+ stats.push({
505
+ timestamp: Date.now(),
506
+ trackName: track.name,
507
+ kind: track.kind,
508
+ direction,
509
+ codec,
510
+ paused: pausedTracks.includes(track.name),
511
+ metrics
512
+ });
513
+ });
514
+ return stats;
515
+ };
516
+ }
517
+ function toClientConnectionStat(report, timeToConnectMs) {
518
+ const pair = activeCandidatePair(report);
519
+ const metrics = {};
520
+ if (pair?.availableOutgoingBitrate !== void 0) {
521
+ metrics.available_outgoing_bitrate_bps = pair.availableOutgoingBitrate;
522
+ }
523
+ if (pair?.availableIncomingBitrate !== void 0) {
524
+ metrics.available_incoming_bitrate_bps = pair.availableIncomingBitrate;
525
+ }
526
+ if (pair?.currentRoundTripTime !== void 0) {
527
+ metrics.connection_rtt_ms = secondsToMs(pair.currentRoundTripTime);
528
+ }
529
+ if (timeToConnectMs !== void 0) {
530
+ metrics.time_to_connect_ms = roundMs(timeToConnectMs);
531
+ }
532
+ return { timestamp: Date.now(), metrics };
533
+ }
534
+ function activeCandidatePair(report) {
535
+ let namedByTransport;
536
+ let flaggedSelected;
537
+ let firstNominated;
538
+ report.forEach((stat) => {
539
+ if (stat.type === "transport" && stat.selectedCandidatePairId) {
540
+ namedByTransport ??= stat.selectedCandidatePairId;
541
+ }
542
+ if (stat.type === "candidate-pair" && stat.state === "succeeded") {
543
+ if (stat.selected) {
544
+ flaggedSelected ??= stat;
545
+ }
546
+ if (stat.nominated) {
547
+ firstNominated ??= stat;
548
+ }
549
+ }
550
+ });
551
+ const named = namedByTransport !== void 0 ? report.get(namedByTransport) : void 0;
552
+ const namedSucceeded = named?.state === "succeeded" ? named : void 0;
553
+ return namedSucceeded ?? flaggedSelected ?? firstNominated;
554
+ }
555
+ function createConnectionStatsExtractor() {
384
556
  let lastBytesReceived;
385
557
  let lastBytesSent;
386
558
  let lastCandPairTimestamp;
387
559
  let lastCandPairId;
388
560
  return (report) => {
389
- let candPairId;
390
561
  let rtt;
391
562
  let availableOutgoingBitrate;
392
563
  let availableIncomingBitrate;
@@ -397,40 +568,35 @@ function createRTCStatsExtractor() {
397
568
  let jitter;
398
569
  let packetLossRatio;
399
570
  let candidateType;
400
- const reportWithLookup = report;
401
- report.forEach((stat) => {
402
- if (candPairId === void 0 && stat.type === "candidate-pair" && stat.state === "succeeded" && stat.nominated) {
403
- candPairId = stat.id;
404
- if (stat.currentRoundTripTime !== void 0) {
405
- rtt = stat.currentRoundTripTime * 1e3;
406
- }
407
- if (stat.availableOutgoingBitrate !== void 0) {
408
- availableOutgoingBitrate = stat.availableOutgoingBitrate;
409
- }
410
- if (stat.availableIncomingBitrate !== void 0) {
411
- availableIncomingBitrate = stat.availableIncomingBitrate;
412
- }
413
- const localCandidate = stat.localCandidateId !== void 0 ? reportWithLookup.get(stat.localCandidateId) : void 0;
414
- if (localCandidate?.candidateType) {
415
- candidateType = localCandidate.candidateType;
416
- }
417
- const samePair = lastCandPairId === candPairId;
418
- const timeDiff = samePair && lastCandPairTimestamp !== void 0 ? stat.timestamp - lastCandPairTimestamp : 0;
419
- if (stat.bytesReceived !== void 0) {
420
- if (samePair && lastBytesReceived !== void 0 && timeDiff > 0) {
421
- incomingBitrate = (stat.bytesReceived - lastBytesReceived) * 8 / timeDiff * 1e3;
422
- }
423
- lastBytesReceived = stat.bytesReceived;
571
+ const pair = activeCandidatePair(report);
572
+ if (pair !== void 0) {
573
+ if (pair.currentRoundTripTime !== void 0) {
574
+ rtt = pair.currentRoundTripTime * 1e3;
575
+ }
576
+ availableOutgoingBitrate = pair.availableOutgoingBitrate;
577
+ availableIncomingBitrate = pair.availableIncomingBitrate;
578
+ const localCandidate = pair.localCandidateId !== void 0 ? report.get(pair.localCandidateId) : void 0;
579
+ if (localCandidate?.candidateType) {
580
+ candidateType = localCandidate.candidateType;
581
+ }
582
+ const samePair = lastCandPairId === pair.id;
583
+ const timeDiff = samePair && lastCandPairTimestamp !== void 0 ? pair.timestamp - lastCandPairTimestamp : 0;
584
+ if (pair.bytesReceived !== void 0) {
585
+ if (samePair && lastBytesReceived !== void 0 && timeDiff > 0) {
586
+ incomingBitrate = (pair.bytesReceived - lastBytesReceived) * 8 / timeDiff * 1e3;
424
587
  }
425
- if (stat.bytesSent !== void 0) {
426
- if (samePair && lastBytesSent !== void 0 && timeDiff > 0) {
427
- outgoingBitrate = (stat.bytesSent - lastBytesSent) * 8 / timeDiff * 1e3;
428
- }
429
- lastBytesSent = stat.bytesSent;
588
+ lastBytesReceived = pair.bytesReceived;
589
+ }
590
+ if (pair.bytesSent !== void 0) {
591
+ if (samePair && lastBytesSent !== void 0 && timeDiff > 0) {
592
+ outgoingBitrate = (pair.bytesSent - lastBytesSent) * 8 / timeDiff * 1e3;
430
593
  }
431
- lastCandPairTimestamp = stat.timestamp;
432
- lastCandPairId = candPairId;
594
+ lastBytesSent = pair.bytesSent;
433
595
  }
596
+ lastCandPairTimestamp = pair.timestamp;
597
+ lastCandPairId = pair.id;
598
+ }
599
+ report.forEach((stat) => {
434
600
  if (videoInboundRtpId === void 0 && stat.type === "inbound-rtp" && stat.kind === "video") {
435
601
  videoInboundRtpId = stat.id;
436
602
  if (stat.framesPerSecond !== void 0) {
@@ -485,7 +651,7 @@ async function importWasmModule() {
485
651
  // package.json
486
652
  var package_default = {
487
653
  name: "@reactor-team/js-sdk",
488
- version: "3.0.2",
654
+ version: "3.1.0",
489
655
  description: "Connect your JavaScript/TypeScript app to a live Reactor model in the browser.",
490
656
  license: "Apache-2.0",
491
657
  repository: {
@@ -961,11 +1127,14 @@ var Reactor = class {
961
1127
  capabilities;
962
1128
  stats;
963
1129
  connectionTimings;
964
- statsPollHandle;
965
- /** Bumped on every `startStatsPolling()`/`stopStatsPolling()` call — lets an
966
- * in-flight `getStats()` recognize it's stale once it resolves, even if
967
- * `this.client` hasn't changed in the meantime. */
968
- statsPollGeneration = 0;
1130
+ /** The stop functions of the running stats pollers — see `pollPeerStats()`. */
1131
+ stopStatsPollers = [];
1132
+ /** Whether this connection has already reported its time to connect —
1133
+ * a one-time fact, sent on the first client-stats report that carries it
1134
+ * and omitted on every one after. Set only once a batch actually went out
1135
+ * with it, so a batch sent before the timings exist doesn't use it up.
1136
+ * Reset per `startStatsPolling()` call, i.e. per connect()/reconnect(). */
1137
+ hasSentConnectTime = false;
969
1138
  /** Set on the "connecting" status transition, cleared once `connectionTimings`
970
1139
  * is finalized on "ready" — see `handleStatusChanged()`. */
971
1140
  connectStartTime;
@@ -1494,7 +1663,7 @@ var Reactor = class {
1494
1663
  getLastError() {
1495
1664
  return this._lastError;
1496
1665
  }
1497
- /** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
1666
+ /** The most recent WebRTC connection stats, polled every `LOCAL_STATS_INTERVAL_MS`
1498
1667
  * while "ready" — see `statsUpdate`. `undefined` before the first sample. */
1499
1668
  getStats() {
1500
1669
  return this.stats;
@@ -1644,31 +1813,57 @@ var Reactor = class {
1644
1813
  this.stopStatsPolling();
1645
1814
  }
1646
1815
  }
1816
+ /** Starts both stats pollers: the local one updates `getStats()` and emits
1817
+ * `statsUpdate`, the runtime one sends a client-stats batch. Each owns the
1818
+ * extractor it computes bitrates with, so a bitrate covers its own
1819
+ * poller's interval. */
1647
1820
  startStatsPolling(client) {
1648
1821
  this.stopStatsPolling();
1649
- const generation = ++this.statsPollGeneration;
1650
- const extractStats = createRTCStatsExtractor();
1651
- this.statsPollHandle = setInterval(() => {
1652
- const peerConnection = client.getPeerConnection();
1653
- if (!peerConnection) {
1654
- return;
1655
- }
1656
- peerConnection.getStats().then((report) => {
1657
- if (generation !== this.statsPollGeneration) {
1658
- return;
1659
- }
1660
- this.stats = { ...extractStats(report), connectionTimings: this.connectionTimings };
1822
+ const extractConnectionStats = createConnectionStatsExtractor();
1823
+ const extractTrackStats = createTrackStatsExtractor();
1824
+ this.hasSentConnectTime = false;
1825
+ this.stopStatsPollers = [
1826
+ pollPeerStats(client, LOCAL_STATS_INTERVAL_MS, (report) => {
1827
+ this.stats = { ...extractConnectionStats(report), connectionTimings: this.connectionTimings };
1661
1828
  this.emitter.emit("statsUpdate", this.stats);
1662
- }).catch(() => {
1663
- });
1664
- }, STATS_INTERVAL_MS);
1829
+ }),
1830
+ pollPeerStats(client, RUNTIME_REPORT_INTERVAL_MS, (report) => {
1831
+ this.reportClientStats(client, report, extractTrackStats);
1832
+ })
1833
+ ];
1834
+ }
1835
+ /** Report one quality batch to the runtime: a reading per negotiated
1836
+ * track — audio and video, sent and received — see
1837
+ * `createTrackStatsExtractor`, and the connection-wide reading — see
1838
+ * `toClientConnectionStat`. The connection reading goes even while no
1839
+ * track has one yet (none negotiated onto a named track, or no codec
1840
+ * reported yet), so the runtime gets the bandwidth estimate, the
1841
+ * round-trip time and the time to connect without waiting on the tracks.
1842
+ * Skipped only when there is nothing at all to say; one is due again in
1843
+ * `RUNTIME_REPORT_INTERVAL_MS`. The time to connect goes on the first batch
1844
+ * actually sent for this connection — see `hasSentConnectTime`.
1845
+ * `sendClientStats` throws synchronously on a closing connection; caught
1846
+ * here for the same reason `getStats()`'s rejection is above. */
1847
+ reportClientStats(client, report, extractTrackStats) {
1848
+ const trackStats = extractTrackStats(report, this.trackMapping(), this.pausedTracks());
1849
+ const timeToConnectMs = this.hasSentConnectTime ? void 0 : this.connectionTimings?.totalMs;
1850
+ const connectionStat = toClientConnectionStat(report, timeToConnectMs);
1851
+ if (trackStats.length === 0 && Object.keys(connectionStat.metrics).length === 0) {
1852
+ return;
1853
+ }
1854
+ try {
1855
+ client.sendClientStats(trackStats, connectionStat);
1856
+ if (timeToConnectMs !== void 0) {
1857
+ this.hasSentConnectTime = true;
1858
+ }
1859
+ } catch {
1860
+ }
1665
1861
  }
1666
1862
  stopStatsPolling() {
1667
- this.statsPollGeneration += 1;
1668
- if (this.statsPollHandle !== void 0) {
1669
- clearInterval(this.statsPollHandle);
1670
- this.statsPollHandle = void 0;
1863
+ for (const stop of this.stopStatsPollers) {
1864
+ stop();
1671
1865
  }
1866
+ this.stopStatsPollers = [];
1672
1867
  this.stats = void 0;
1673
1868
  }
1674
1869
  /** Called on every `disconnect()` and on `[Symbol.dispose]`. Leaves