@voltkit-rtc/client 0.4.0 → 0.5.0

package/src/quality.ts

@@ -1,12 +1,4 @@
-/**
- * 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 for the first project during its free trial; the join result says which
- * (`video.maxQuality`), and the server caps each publisher's incoming bitrate
- * to match.
- */
+/** All video qualities are available on every plan; per-project safety restrictions still apply. */
 
 export type VideoQuality = '1080p' | '720p' | '480p';
 
@@ -17,13 +9,14 @@ export type LayerCount = 1 | 2 | 3;
 
 /** What the server allows this project to publish, from the join result. */
 export interface VideoPolicy {
-  maxQuality: '1080p' | '720p';
+  maxQuality: VideoQuality;
+  maxFrameRate?: 30 | 60;
   /** 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' };
+export const DEFAULT_VIDEO_POLICY: VideoPolicy = { maxQuality: '1080p', maxFrameRate: 60 };
 
 /** Each tier's 16:9 frame. */
 const TIER_SIZE: Record<VideoQuality, { width: number; height: number }> = {
@@ -36,27 +29,18 @@ 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 max = policy.maxQuality in RANK ? policy.maxQuality : '1080p';
   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 4 Mbps, 720p 2.5 Mbps, 540p 1.5 Mbps, 480p 1 Mbps,
- * 360p 700 kbps, 240p 400 kbps, smaller 200 kbps.
- *
- * Measured on a 720p camera picture: 2.5 Mbps brought VP8's quantiser down
- * from about 64 (at 1.8 Mbps) to about 55, which is finer detail, most of all
- * in motion. The server's per-project caps (4 Mbps up to 720p, 7 Mbps with
- * 1080p) carry these ladders with their audio.
- */
+/** The authoritative 30 fps bitrate for a layer of this many pixels. */
 export function layerBitrate(pixels: number): number {
-  if (pixels >= 1_800_000) return 4_000_000;
-  if (pixels >= 800_000) return 2_500_000;
-  if (pixels >= 450_000) return 1_500_000;
-  if (pixels >= 360_000) return 1_000_000;
-  if (pixels >= 200_000) return 700_000;
+  if (pixels >= 1_800_000) return 6_000_000;
+  if (pixels >= 800_000) return 3_000_000;
+  if (pixels >= 450_000) return 2_000_000;
+  if (pixels >= 360_000) return 1_200_000;
+  if (pixels >= 200_000) return 800_000;
   if (pixels >= 100_000) return 400_000;
   return 200_000;
 }
@@ -66,6 +50,7 @@ export interface VideoEncoding {
   scaleResolutionDownBy: number;
   maxBitrate: number;
   scalabilityMode: 'L1T3';
+  maxFramerate: number;
 }
 
 /**
@@ -98,7 +83,7 @@ export function topLayerSize(width: number, height: number, quality: VideoQualit
  * browser shrinks the picture and then sends fewer layers: from two it keeps
  * the full one, from three it lost it.
  */
-export function videoEncodings(width: number, height: number, quality: VideoQuality, maxLayers: LayerCount = 3): VideoEncoding[] {
+export function videoEncodings(width: number, height: number, quality: VideoQuality, maxLayers: LayerCount = 3, frameRate: 30 | 60 = 30): VideoEncoding[] {
   const { width: w, height: h, scale } = topLayerSize(width, height, quality);
   const top = w * h;
   const possible = top >= 960 * 540 ? 3 : top >= 480 * 270 ? 2 : 1;
@@ -108,7 +93,8 @@ export function videoEncodings(width: number, height: number, quality: VideoQual
   const layer = (divisor: number, rid?: string): VideoEncoding => ({
     ...(rid ? { rid } : {}),
     scaleResolutionDownBy: round(scale * divisor),
-    maxBitrate: layerBitrate(top / (divisor * divisor)),
+    maxBitrate: layerBitrate(top / (divisor * divisor)) * (divisor === 1 && frameRate === 60 ? 1.5 : 1),
+    maxFramerate: divisor === 1 ? frameRate : 30,
     scalabilityMode: 'L1T3',
   });
   if (layers === 3) return [layer(4, 'q'), layer(2, 'h'), layer(1, 'f')];
@@ -124,3 +110,46 @@ export function videoEncodings(width: number, height: number, quality: VideoQual
 export function sameLayout(a: readonly VideoEncoding[], b: readonly VideoEncoding[]): boolean {
   return a.length === b.length && a.every((encoding, i) => encoding.scaleResolutionDownBy === b[i].scaleResolutionDownBy);
 }
+
+/** Actual producer layer dimensions, smallest first; includes portrait and screen video. */
+export interface VideoLayer {
+  spatialLayer: number;
+  width: number;
+  height: number;
+}
+
+export type ReceiveQuality = 'auto' | VideoQuality;
+export type ScreenMode = 'detail' | 'motion';
+
+/** Never invent layers when an older producer does not describe them. */
+export function receiveSpatialLayer(layers: readonly VideoLayer[], quality: VideoQuality): number {
+  const valid = layers.filter((l) => Number.isInteger(l.spatialLayer) && l.spatialLayer >= 0 &&
+    Number.isFinite(l.width) && l.width > 0 && Number.isFinite(l.height) && l.height > 0)
+    .sort((a, b) => a.width * a.height - b.width * b.height);
+  if (!valid.length) throw new Error('producer has no video layer metadata');
+  const tier = TIER_SIZE[quality];
+  const fitting = valid.filter((l) => Math.max(l.width, l.height) <= tier.width + 1 && Math.min(l.width, l.height) <= tier.height + 1);
+  return (fitting.at(-1) ?? valid[0]).spatialLayer;
+}
+
+export function describeVideoLayers(width: number, height: number, encodings: readonly VideoEncoding[], quality: VideoQuality = '1080p'): VideoLayer[] {
+  const fallback = TIER_SIZE[quality];
+  const w = width > 0 ? width : fallback.width;
+  const h = height > 0 ? height : fallback.height;
+  return encodings.map((encoding, spatialLayer) => ({ spatialLayer, width: Math.round(w / encoding.scaleResolutionDownBy), height: Math.round(h / encoding.scaleResolutionDownBy) }));
+}
+
+/** Screen frames are capped to native 1080p, never enlarged, with two adaptive copies. */
+export function screenEncodings(width: number, height: number, mode: ScreenMode = 'detail'): VideoEncoding[] {
+  const nativeWidth = width > 0 ? width : 1920;
+  const nativeHeight = height > 0 ? height : 1080;
+  const scale = Math.max(1, Math.max(nativeWidth, nativeHeight) / 1920, Math.min(nativeWidth, nativeHeight) / 1080);
+  const w = nativeWidth / scale;
+  const h = nativeHeight / scale;
+  const layer = (divisor: number, rid?: string): VideoEncoding => ({
+    ...(rid ? { rid } : {}), scaleResolutionDownBy: scale * divisor,
+    maxBitrate: divisor === 1 ? (mode === 'motion' ? 6_000_000 : 2_500_000) : 600_000,
+    maxFramerate: mode === 'motion' ? 30 : 15, scalabilityMode: 'L1T3',
+  });
+  return w * h >= 480 * 270 ? [layer(2, 'h'), layer(1, 'f')] : [layer(1)];
+}