@streaming-cdn/rtc-web 1.3.24 → 1.3.26

package/README.md

@@ -1,4 +1,4 @@
-# RTC Web SDK 1.3.24
+# RTC Web SDK 1.3.26
 
 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,30 @@ 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.26 notes
+
+- **VRM avatars are framed from the model's own measurements.** The bust
+  camera in `avatar-vrm` was fixed at a 0.42 m window aimed at the head
+  joint — which sits at the *bottom* of the skull — so characters with tall
+  hair or accessories had their crowns cropped, and big-headed models filled
+  the whole canvas and rendered far larger than the built-in avatar when
+  overlaid. `createVrmStage` now measures each model (head joint from the
+  humanoid, crown from the scene bounds, hair included) and frames the bust
+  so the skull spans ~38% of the canvas with its centre at 42% from the top —
+  the exact contract `vrmAvatarRenderer`'s overlay math expects. Every
+  character now appears the same size as the built-in stylized avatar,
+  whatever its proportions. The framing rule is exported as `frameVrmBust()`.
+
+## 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,53 @@
+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;
+}
+/**
+ * Bust framing computed from the model's own measurements.
+ *
+ * Characters do not share proportions: the head joint sits at the bottom of
+ * the skull, and between a chibi and a tall model the joint-to-crown distance
+ * (hair and accessories included) spans several fold. A fixed camera cropped
+ * tall hair off and let big heads fill the whole canvas, which the overlay
+ * then multiplied into an avatar larger than the screen.
+ *
+ * The contract with `vrmAvatarRenderer` is proportional: the skull spans
+ * roughly 38% of the canvas (2 of the 5.2 head radii the overlay paints) with
+ * its centre at 42% from the top — the same size and seat as the built-in
+ * stylized head, so switching characters never changes how big the avatar
+ * appears over the person.
+ */
+export declare function frameVrmBust(measure: {
+    headY: number;
+    crownY: number;
+}): {
+    windowHeight: number;
+    lookY: number;
+    distance: number;
+};
+/**
+ * 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,68 @@
+import * as d from "three";
+import { GLTFLoader as L } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { VRMLoaderPlugin as g, VRMUtils as w } from "@pixiv/three-vrm";
+function A(n) {
+  const o = n.crownY - n.headY, t = o > 0.05 && o < 1.5 ? o : 0.25, r = t * 2.1, p = n.headY + t * 0.45 - r * 0.08, s = r / 2 / Math.tan(28 / 2 * (Math.PI / 180));
+  return { windowHeight: r, lookY: p, distance: s };
+}
+function C(n, o) {
+  return {
+    render(t, r, c, p, s) {
+      if (n.applyAndRender(r, o), s) {
+        const a = s.radius * 5.2;
+        t.drawImage(n.canvas, s.x - a / 2, s.y - a * 0.42, a, a);
+      } else {
+        const a = Math.min(c, p);
+        t.drawImage(n.canvas, (c - a) / 2, (p - a) / 2, a, a);
+      }
+    },
+    dispose() {
+      n.dispose();
+    }
+  };
+}
+async function G(n, o = 512) {
+  const t = document.createElement("canvas");
+  t.width = o, t.height = o;
+  const r = new d.WebGLRenderer({ canvas: t, alpha: !0, antialias: !0 });
+  r.setClearColor(0, 0);
+  const c = new d.Scene();
+  c.add(new d.AmbientLight(16777215, 1.1));
+  const p = new d.DirectionalLight(16777215, 1.4);
+  p.position.set(0.5, 1.2, 1.5), c.add(p);
+  const s = new d.PerspectiveCamera(28, 1, 0.1, 20), a = new L();
+  a.register((e) => new g(e));
+  const k = await a.parseAsync(n, ""), i = k.userData.vrm;
+  w.removeUnnecessaryVertices(k.scene), w.combineSkeletons(k.scene), w.rotateVRM0(i), c.add(i.scene);
+  const u = i.humanoid?.getNormalizedBoneNode("head"), h = new d.Vector3(0, 1.35, 0);
+  u && u.getWorldPosition(h), i.scene.updateWorldMatrix(!0, !0);
+  const R = new d.Box3().setFromObject(i.scene), V = Number.isFinite(R.max.y) ? R.max.y : h.y + 0.25, y = A({ headY: h.y, crownY: V });
+  s.position.set(0, y.lookY, y.distance), s.lookAt(0, y.lookY, 0);
+  const f = new d.Object3D();
+  f.position.set(0, h.y, 2), c.add(f), i.lookAt && (i.lookAt.target = f);
+  const M = new d.Clock();
+  return {
+    canvas: t,
+    applyAndRender(e, Y) {
+      const b = Y?.headGain ?? 0.9, l = i.expressionManager;
+      if (l) {
+        const v = l.expressionMap ?? {}, m = (x) => !!v[x];
+        m("blinkLeft") || m("blinkRight") ? (l.setValue("blinkLeft", e.blinkLeft), l.setValue("blinkRight", e.blinkRight)) : m("blink") && l.setValue("blink", (e.blinkLeft + e.blinkRight) / 2), m("aa") && l.setValue("aa", Math.max(0, e.jawOpen)), m("happy") && l.setValue("happy", Math.max(0, e.smile)), m("angry") && l.setValue("angry", Math.max(0, -e.smile) * 0.6);
+      }
+      u && u.rotation.set(-e.headPitch * b, e.headYaw * b, -e.headRoll * b), f.position.set(e.pupilX * 1.2, h.y - e.pupilY * 0.8, 2), i.update(M.getDelta()), r.render(c, s);
+    },
+    dispose() {
+      w.deepDispose(i.scene), r.dispose();
+    }
+  };
+}
+async function B(n, o = {}) {
+  const t = await G(n, o.size ?? 640);
+  return C(t, { headGain: o.headGain });
+}
+export {
+  B as createVrmAvatarRenderer,
+  G as createVrmStage,
+  A as frameVrmBust,
+  C 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,j,h){"use strict";function x(e){const n=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const t in e)if(t!=="default"){const o=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(n,t,o.get?o:{enumerable:!0,get:()=>e[t]})}}return n.default=e,Object.freeze(n)}const d=x(f);function M(e){const n=e.crownY-e.headY,t=n>.05&&n<1.5?n:.25,o=t*2.1,p=e.headY+t*.45-o*.08,i=o/2/Math.tan(28/2*(Math.PI/180));return{windowHeight:o,lookY:p,distance:i}}function V(e,n){return{render(t,o,l,p,i){if(e.applyAndRender(o,n),i){const r=i.radius*5.2;t.drawImage(e.canvas,i.x-r/2,i.y-r*.42,r,r)}else{const r=Math.min(l,p);t.drawImage(e.canvas,(l-r)/2,(p-r)/2,r,r)}},dispose(){e.dispose()}}}async function g(e,n=512){const t=document.createElement("canvas");t.width=n,t.height=n;const o=new d.WebGLRenderer({canvas:t,alpha:!0,antialias:!0});o.setClearColor(0,0);const l=new d.Scene;l.add(new d.AmbientLight(16777215,1.1));const p=new d.DirectionalLight(16777215,1.4);p.position.set(.5,1.2,1.5),l.add(p);const i=new d.PerspectiveCamera(28,1,.1,20),r=new j.GLTFLoader;r.register(a=>new h.VRMLoaderPlugin(a));const w=await r.parseAsync(e,""),c=w.userData.vrm;h.VRMUtils.removeUnnecessaryVertices(w.scene),h.VRMUtils.combineSkeletons(w.scene),h.VRMUtils.rotateVRM0(c),l.add(c.scene);const R=c.humanoid?.getNormalizedBoneNode("head"),y=new d.Vector3(0,1.35,0);R&&R.getWorldPosition(y),c.scene.updateWorldMatrix(!0,!0);const L=new d.Box3().setFromObject(c.scene),T=Number.isFinite(L.max.y)?L.max.y:y.y+.25,k=M({headY:y.y,crownY:T});i.position.set(0,k.lookY,k.distance),i.lookAt(0,k.lookY,0);const b=new d.Object3D;b.position.set(0,y.y,2),l.add(b),c.lookAt&&(c.lookAt.target=b);const Y=new d.Clock;return{canvas:t,applyAndRender(a,S){const v=S?.headGain??.9,u=c.expressionManager;if(u){const E=u.expressionMap??{},m=O=>!!E[O];m("blinkLeft")||m("blinkRight")?(u.setValue("blinkLeft",a.blinkLeft),u.setValue("blinkRight",a.blinkRight)):m("blink")&&u.setValue("blink",(a.blinkLeft+a.blinkRight)/2),m("aa")&&u.setValue("aa",Math.max(0,a.jawOpen)),m("happy")&&u.setValue("happy",Math.max(0,a.smile)),m("angry")&&u.setValue("angry",Math.max(0,-a.smile)*.6)}R&&R.rotation.set(-a.headPitch*v,a.headYaw*v,-a.headRoll*v),b.position.set(a.pupilX*1.2,y.y-a.pupilY*.8,2),c.update(Y.getDelta()),o.render(l,i)},dispose(){h.VRMUtils.deepDispose(c.scene),o.dispose()}}}async function A(e,n={}){const t=await g(e,n.size??640);return V(t,{headGain:n.headGain})}s.createVrmAvatarRenderer=A,s.createVrmStage=g,s.frameVrmBust=M,s.vrmAvatarRenderer=V,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));