@voltkit-rtc/client 0.2.0 → 0.3.0

package/src/quality.ts

@@ -0,0 +1,91 @@
+/**
+ * Video quality tiers and the simulcast layers sent for each.
+ *
+ * A project can publish at 720p or 480p on any plan. 1080p uses more
+ * bandwidth, so the server allows it only for projects that have it enabled,
+ * and during the free trial; the join result says which (`video.maxQuality`),
+ * and the server caps each publisher's incoming bitrate to match.
+ */
+
+export type VideoQuality = '1080p' | '720p' | '480p';
+
+export const VIDEO_QUALITIES: readonly VideoQuality[] = ['1080p', '720p', '480p'];
+
+/** What the server allows this project to publish, from the join result. */
+export interface VideoPolicy {
+  maxQuality: '1080p' | '720p';
+  /** The server's cap on one publisher's incoming bitrate, in bits per second. */
+  maxBitrate?: number;
+}
+
+/** Servers from before quality tiers send no policy; they get the default tier. */
+export const DEFAULT_VIDEO_POLICY: VideoPolicy = { maxQuality: '720p' };
+
+/** Each tier's 16:9 frame. */
+const TIER_SIZE: Record<VideoQuality, { width: number; height: number }> = {
+  '1080p': { width: 1920, height: 1080 },
+  '720p': { width: 1280, height: 720 },
+  '480p': { width: 854, height: 480 },
+};
+
+const RANK: Record<VideoQuality, number> = { '480p': 0, '720p': 1, '1080p': 2 };
+
+/** The lower of what was asked for and what the project may use. */
+export function allowedQuality(requested: VideoQuality | undefined, policy: VideoPolicy = DEFAULT_VIDEO_POLICY): VideoQuality {
+  const max = policy.maxQuality === '1080p' ? '1080p' : '720p';
+  const wanted = requested && requested in RANK ? requested : max;
+  return RANK[wanted] <= RANK[max] ? wanted : max;
+}
+
+/**
+ * The bitrate a layer of this many pixels gets, at up to 30 fps.
+ * About 1080p 2.5 Mbps, 720p 1.8 Mbps, 540p 1.2 Mbps, 480p 750 kbps,
+ * 360p 600 kbps, 240p 250 kbps, smaller 200 kbps.
+ */
+export function layerBitrate(pixels: number): number {
+  if (pixels >= 1_800_000) return 2_500_000;
+  if (pixels >= 800_000) return 1_800_000;
+  if (pixels >= 450_000) return 1_200_000;
+  if (pixels >= 360_000) return 750_000;
+  if (pixels >= 200_000) return 600_000;
+  if (pixels >= 100_000) return 250_000;
+  return 200_000;
+}
+
+export interface VideoEncoding {
+  rid?: string;
+  scaleResolutionDownBy: number;
+  maxBitrate: number;
+  scalabilityMode: 'L1T3';
+}
+
+/**
+ * The simulcast layers for a camera picture of `width` × `height` at
+ * `quality`.
+ *
+ * The top layer is the picture scaled down to the tier (never up). The number
+ * of layers follows what browsers really send for a picture that size: Chrome
+ * sends three layers from 960×540 up, two from 480×270, one below that, and
+ * when a picture is too small for the layers asked for it drops the TOP ones,
+ * which would leave viewers with half or a quarter of the resolution. Asking
+ * for exactly as many layers as will be sent keeps the full picture.
+ */
+export function videoEncodings(width: number, height: number, quality: VideoQuality): VideoEncoding[] {
+  const tier = TIER_SIZE[quality] ?? TIER_SIZE['720p'];
+  // Size unknown (some tracks don't report it): assume the tier's own frame.
+  const w = width > 0 && height > 0 ? width : tier.width;
+  const h = width > 0 && height > 0 ? height : tier.height;
+  const scale = Math.max(1, Math.max(w, h) / tier.width);
+  const top = (w / scale) * (h / scale);
+  const layers = top >= 960 * 540 ? 3 : top >= 480 * 270 ? 2 : 1;
+  const round = (value: number) => Math.round(value * 1000) / 1000;
+  const layer = (divisor: number, rid?: string): VideoEncoding => ({
+    ...(rid ? { rid } : {}),
+    scaleResolutionDownBy: round(scale * divisor),
+    maxBitrate: layerBitrate(top / (divisor * divisor)),
+    scalabilityMode: 'L1T3',
+  });
+  if (layers === 3) return [layer(4, 'q'), layer(2, 'h'), layer(1, 'f')];
+  if (layers === 2) return [layer(2, 'h'), layer(1, 'f')];
+  return [layer(1)];
+}