@streaming-cdn/rtc-web 1.3.24 → 1.3.25

package/README.md

@@ -1,4 +1,4 @@
-# RTC Web SDK 1.3.24
+# RTC Web SDK 1.3.25
 
 The customer package contains compiled ESM/UMD JavaScript and TypeScript declarations. It intentionally excludes implementation source and source maps. Example source remains available under `examples/`.
 
@@ -357,6 +357,16 @@ operational diagnostics. Tokens, SDP, media, and chat content are never part of
 that report. Set `reportSignalingDiagnostics: false` only when replacing this
 with an application-owned diagnostics pipeline.
 
+## 1.3.25 notes
+
+- **B21 — per-peer quality no longer ratchets down on bandwidth-pinned
+  links.** The step-up gate required `qualityLimitationReason` to clear; on
+  links that pin it at `bandwidth`, upgrades were mathematically impossible.
+  Both directions now share `bandwidthSustainRatio` (default 0.7): down
+  judges the current tier's target, up judges the next tier's, so promotions
+  cannot flap. `bandwidthHeadroomRatio` is retired and ignored, and
+  `goodSamplesToStepUp` is effective again in this state.
+
 ## 1.3.24 notes
 
 - `callupdated` now carries `actorExternalId`, matching the React Native SDK.

package/dist/avatar-library.d.ts

@@ -0,0 +1,82 @@
+import { type ZipEntry } from "./zip-reader";
+/**
+ * Custom avatar model library.
+ *
+ * A browser cannot look inside the user's Downloads folder — no web API
+ * enumerates the file system. So a model obtained from a third-party site is
+ * handed over once, explicitly (file picker or drag-and-drop), and kept here so
+ * every later call finds it already imported.
+ *
+ * Models never leave the device: the avatar is rendered locally into the
+ * outgoing video track, so remote participants receive video, never the model
+ * file. Nothing here uploads, and nothing here depends on three.js — reading a
+ * VRM's own metadata only needs its glTF JSON chunk.
+ */
+export interface AvatarModelLicense {
+    /** Character name declared by the model, when present. */
+    title: string | null;
+    author: string | null;
+    /** Who the model may be used by, verbatim from the file. */
+    allowedUser: string | null;
+    /** Whether the author permits commercial use, verbatim from the file. */
+    commercialUse: string | null;
+    licenseName: string | null;
+    licenseUrl: string | null;
+}
+export interface AvatarModelEntry {
+    id: string;
+    /** Display name: the model's own title when it declares one, else the file name. */
+    name: string;
+    bytes: number;
+    importedAt: string;
+    /** The author's terms as declared inside the file; null when it declares none. */
+    license: AvatarModelLicense | null;
+}
+export interface AvatarModelImportOptions {
+    /** Overrides the name taken from the model metadata or file name. */
+    name?: string;
+    /** Rejects models above this size. Defaults to AVATAR_MODEL_MAX_BYTES. */
+    maxBytes?: number;
+    /**
+     * Which character to take when the source is an archive holding several.
+     * Comes from AvatarModelError.choices on a previous "archive_many_models".
+     */
+    entryPath?: string;
+}
+/**
+ * Lists the characters inside a downloaded pack, so a caller can offer a
+ * choice before importing. Returns an empty list for a bare .vrm.
+ */
+export declare function listArchiveModels(source: File | ArrayBuffer): Promise<string[]>;
+/** Well past any sensible VRM character, far below anything that would wedge a tab. */
+export declare const AVATAR_MODEL_MAX_BYTES: number;
+export type AvatarModelErrorCode = "model_too_large" | "model_not_glb" | "model_not_vrm" | "model_unreadable" | "storage_unavailable" | "archive_no_model" | "archive_many_models" | "archive_unreadable" | "archive_encrypted" | "archive_unsupported";
+export declare class AvatarModelError extends Error {
+    readonly code: AvatarModelErrorCode;
+    /**
+     * The characters found inside an archive. Set only for
+     * "archive_many_models", so the caller can ask which one to import and pass
+     * it back as importAvatarModel's entryPath.
+     */
+    readonly choices: string[];
+    constructor(code: AvatarModelErrorCode, message: string, choices?: string[]);
+}
+/** Entries a character pack holds that are actually characters. */
+export declare function findArchiveModels(entries: ZipEntry[]): ZipEntry[];
+/**
+ * Reads the VRM metadata a model declares about itself. Supports VRM 0.x
+ * (extensions.VRM.meta) and VRM 1.0 (extensions.VRMC_vrm.meta), whose field
+ * names differ. Returns null for a glTF that carries neither.
+ */
+export declare function readAvatarModelMetadata(buffer: ArrayBuffer): AvatarModelLicense | null;
+/**
+ * Validates a model the user supplied and keeps it for later calls. The bytes
+ * are checked before anything renders them: an oversized or non-VRM file is
+ * rejected with a code the UI can explain, never handed to the renderer.
+ */
+export declare function importAvatarModel(source: File | ArrayBuffer, options?: AvatarModelImportOptions): Promise<AvatarModelEntry>;
+/** Every model this device has imported, newest first. */
+export declare function listAvatarModels(): Promise<AvatarModelEntry[]>;
+/** The stored bytes for a model, or null when it is no longer present. */
+export declare function readAvatarModel(id: string): Promise<ArrayBuffer | null>;
+export declare function removeAvatarModel(id: string): Promise<void>;

package/dist/avatar-vrm.d.ts

@@ -0,0 +1,30 @@
+import type { AvatarRig } from "./avatar-rig";
+import type { AvatarRenderer } from "./avatar";
+export interface VrmRenderOptions {
+    /** Multiplier on head joint rotation; 1 mirrors the person exactly. */
+    headGain?: number;
+}
+export interface VrmStage {
+    canvas: HTMLCanvasElement;
+    applyAndRender(rig: AvatarRig, options?: VrmRenderOptions): void;
+    dispose(): void;
+}
+/**
+ * Adapts a VrmStage to the SDK's pluggable `AvatarRenderer`, so
+ * `createAvatarPipeline` can publish a VRM character instead of the built-in
+ * stylized avatar. In overlay mode the bust is framed around the head, so it
+ * spans a few head radii over the tracked anchor.
+ */
+export declare function vrmAvatarRenderer(stage: VrmStage, options?: {
+    headGain?: number;
+}): AvatarRenderer;
+export declare function createVrmStage(buffer: ArrayBuffer, size?: number): Promise<VrmStage>;
+/**
+ * One-call helper: bytes in, pipeline renderer out. Pair it with
+ * readAvatarModel() from the model library to render a character the user
+ * imported from a third-party site.
+ */
+export declare function createVrmAvatarRenderer(buffer: ArrayBuffer, options?: {
+    size?: number;
+    headGain?: number;
+}): Promise<AvatarRenderer>;

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { BackgroundPreset, OverlayEffect, Segmenter, VideoEffectsOptions, V
 export { AVATAR_TUNING_DEFAULTS, createAvatarPipeline, stylizedAvatarRenderer } from "./avatar";
 export type { AvatarMode, AvatarPipeline, AvatarPipelineOptions, AvatarRenderer, AvatarTuning, FaceTracker, FaceTrackerResult } from "./avatar";
 export { drawAvatar, headPoseFromMatrix, neutralRig, rigFromBlendshapes, smoothRig } from "./avatar-rig";
+export { AVATAR_MODEL_MAX_BYTES, AvatarModelError, importAvatarModel, listArchiveModels, listAvatarModels, readAvatarModel, readAvatarModelMetadata, removeAvatarModel } from "./avatar-library";
+export type { AvatarModelEntry, AvatarModelErrorCode, AvatarModelImportOptions, AvatarModelLicense } from "./avatar-library";
 export type { AvatarAnchor, AvatarRig, BlendshapeCategory } from "./avatar-rig";
 export type RtcMode = "voice" | "video" | "meeting";
 /**
@@ -393,4 +395,4 @@ export declare class RtcIncomingClient extends EventTarget {
     private emit;
 }
 export declare function createRtcIncomingClient(options: RtcIncomingClientOptions): RtcIncomingClient;
-export declare const version = "1.3.24";
+export declare const version = "1.3.25";

package/dist/peer-quality.d.ts

@@ -37,8 +37,20 @@ export interface PeerQualityThresholds {
     goodLossPct: number;
     goodRttMs: number;
     sustainRatio: number;
-    /** "bandwidth" counts only when the uplink estimate is below this multiple of the tier target. */
-    bandwidthHeadroomRatio: number;
+    /**
+     * One ratio governs both directions of the bandwidth-limited path (B21).
+     * Down: "bandwidth" counts as congestion only below this fraction of the
+     * CURRENT tier's target. Up: a bandwidth-limited but otherwise clean sample
+     * counts as good once the uplink covers this fraction of the NEXT tier's
+     * target — a capped encoder never lets estimation probe much past its send
+     * rate, so demanding the full next-tier target keeps the gate shut exactly
+     * when the cap is what throttles discovery. The default (0.7) exceeds every
+     * adjacent-tier cap ratio, so a promotion never yields fewer usable bits
+     * than the tier being left was allowed at full cap.
+     */
+    bandwidthSustainRatio: number;
+    /** @deprecated No longer used; superseded by bandwidthSustainRatio (B21). */
+    bandwidthHeadroomRatio?: number;
 }
 export declare const defaultPeerQualityThresholds: PeerQualityThresholds;
 export interface PeerQualitySample {

package/dist/rtc-web-avatar-vrm.es.js

@@ -0,0 +1,61 @@
+import * as l from "three";
+import { GLTFLoader as L } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { VRMLoaderPlugin as A, VRMUtils as k } from "@pixiv/three-vrm";
+function M(t, c) {
+  return {
+    render(n, p, s, m, o) {
+      if (t.applyAndRender(p, c), o) {
+        const a = o.radius * 5.2;
+        n.drawImage(t.canvas, o.x - a / 2, o.y - a * 0.42, a, a);
+      } else {
+        const a = Math.min(s, m);
+        n.drawImage(t.canvas, (s - a) / 2, (m - a) / 2, a, a);
+      }
+    },
+    dispose() {
+      t.dispose();
+    }
+  };
+}
+async function g(t, c = 512) {
+  const n = document.createElement("canvas");
+  n.width = c, n.height = c;
+  const p = new l.WebGLRenderer({ canvas: n, alpha: !0, antialias: !0 });
+  p.setClearColor(0, 0);
+  const s = new l.Scene();
+  s.add(new l.AmbientLight(16777215, 1.1));
+  const m = new l.DirectionalLight(16777215, 1.4);
+  m.position.set(0.5, 1.2, 1.5), s.add(m);
+  const o = new l.PerspectiveCamera(28, 1, 0.1, 20), a = new L();
+  a.register((e) => new A(e));
+  const w = await a.parseAsync(t, ""), i = w.userData.vrm;
+  k.removeUnnecessaryVertices(w.scene), k.combineSkeletons(w.scene), k.rotateVRM0(i), s.add(i.scene);
+  const u = i.humanoid?.getNormalizedBoneNode("head"), h = new l.Vector3(0, 1.35, 0);
+  u && u.getWorldPosition(h), o.position.set(0, h.y + 0.03, 0.85), o.lookAt(0, h.y + 0.01, 0);
+  const f = new l.Object3D();
+  f.position.set(0, h.y, 2), s.add(f), i.lookAt && (i.lookAt.target = f);
+  const b = new l.Clock();
+  return {
+    canvas: n,
+    applyAndRender(e, R) {
+      const y = R?.headGain ?? 0.9, r = i.expressionManager;
+      if (r) {
+        const V = r.expressionMap ?? {}, d = (v) => !!V[v];
+        d("blinkLeft") || d("blinkRight") ? (r.setValue("blinkLeft", e.blinkLeft), r.setValue("blinkRight", e.blinkRight)) : d("blink") && r.setValue("blink", (e.blinkLeft + e.blinkRight) / 2), d("aa") && r.setValue("aa", Math.max(0, e.jawOpen)), d("happy") && r.setValue("happy", Math.max(0, e.smile)), d("angry") && r.setValue("angry", Math.max(0, -e.smile) * 0.6);
+      }
+      u && u.rotation.set(-e.headPitch * y, e.headYaw * y, -e.headRoll * y), f.position.set(e.pupilX * 1.2, h.y - e.pupilY * 0.8, 2), i.update(b.getDelta()), p.render(s, o);
+    },
+    dispose() {
+      k.deepDispose(i.scene), p.dispose();
+    }
+  };
+}
+async function D(t, c = {}) {
+  const n = await g(t, c.size ?? 640);
+  return M(n, { headGain: c.headGain });
+}
+export {
+  D as createVrmAvatarRenderer,
+  g as createVrmStage,
+  M as vrmAvatarRenderer
+};

package/dist/rtc-web-avatar-vrm.umd.js

@@ -0,0 +1 @@
+(function(s,f){typeof exports=="object"&&typeof module<"u"?f(exports,require("three"),require("three/examples/jsm/loaders/GLTFLoader.js"),require("@pixiv/three-vrm")):typeof define=="function"&&define.amd?define(["exports","three","three/examples/jsm/loaders/GLTFLoader.js","@pixiv/three-vrm"],f):(s=typeof globalThis<"u"?globalThis:s||self,f(s.StreamingCdnRtcAvatarVrm={},s.THREE,s.THREE,s.THREE_VRM))})(this,(function(s,f,M,m){"use strict";function L(e){const i=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const t in e)if(t!=="default"){const r=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(i,t,r.get?r:{enumerable:!0,get:()=>e[t]})}}return i.default=e,Object.freeze(i)}const o=L(f);function w(e,i){return{render(t,r,d,h,c){if(e.applyAndRender(r,i),c){const a=c.radius*5.2;t.drawImage(e.canvas,c.x-a/2,c.y-a*.42,a,a)}else{const a=Math.min(d,h);t.drawImage(e.canvas,(d-a)/2,(h-a)/2,a,a)}},dispose(){e.dispose()}}}async function V(e,i=512){const t=document.createElement("canvas");t.width=i,t.height=i;const r=new o.WebGLRenderer({canvas:t,alpha:!0,antialias:!0});r.setClearColor(0,0);const d=new o.Scene;d.add(new o.AmbientLight(16777215,1.1));const h=new o.DirectionalLight(16777215,1.4);h.position.set(.5,1.2,1.5),d.add(h);const c=new o.PerspectiveCamera(28,1,.1,20),a=new M.GLTFLoader;a.register(n=>new m.VRMLoaderPlugin(n));const b=await a.parseAsync(e,""),l=b.userData.vrm;m.VRMUtils.removeUnnecessaryVertices(b.scene),m.VRMUtils.combineSkeletons(b.scene),m.VRMUtils.rotateVRM0(l),d.add(l.scene);const y=l.humanoid?.getNormalizedBoneNode("head"),R=new o.Vector3(0,1.35,0);y&&y.getWorldPosition(R),c.position.set(0,R.y+.03,.85),c.lookAt(0,R.y+.01,0);const v=new o.Object3D;v.position.set(0,R.y,2),d.add(v),l.lookAt&&(l.lookAt.target=v);const j=new o.Clock;return{canvas:t,applyAndRender(n,A){const k=A?.headGain??.9,p=l.expressionManager;if(p){const T=p.expressionMap??{},u=x=>!!T[x];u("blinkLeft")||u("blinkRight")?(p.setValue("blinkLeft",n.blinkLeft),p.setValue("blinkRight",n.blinkRight)):u("blink")&&p.setValue("blink",(n.blinkLeft+n.blinkRight)/2),u("aa")&&p.setValue("aa",Math.max(0,n.jawOpen)),u("happy")&&p.setValue("happy",Math.max(0,n.smile)),u("angry")&&p.setValue("angry",Math.max(0,-n.smile)*.6)}y&&y.rotation.set(-n.headPitch*k,n.headYaw*k,-n.headRoll*k),v.position.set(n.pupilX*1.2,R.y-n.pupilY*.8,2),l.update(j.getDelta()),r.render(d,c)},dispose(){m.VRMUtils.deepDispose(l.scene),r.dispose()}}}async function g(e,i={}){const t=await V(e,i.size??640);return w(t,{headGain:i.headGain})}s.createVrmAvatarRenderer=g,s.createVrmStage=V,s.vrmAvatarRenderer=w,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));