@voltkit-rtc/client 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltkit-rtc/client",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Browser SDK for VoltKit RTC: realtime audio/video rooms, chat and live broadcast publishing.",
   "keywords": [
     "voltkit",

package/src/adaptive.ts

@@ -4,7 +4,7 @@
  *
  * The app attaches the element that shows a video (`attachVideo`). From that
  * element's size on screen (CSS pixels × devicePixelRatio, at most 2) the
- * smallest simulcast layer that fills it sharply is chosen; while no attached
+ * smallest simulcast layer that fills it without being stretched is chosen; while no attached
  * element is visible (scrolled away, `display: none`, the tab in the
  * background) the video is paused at the media server, so it costs no
  * bandwidth and no decoding. This is what LiveKit calls adaptiveStream and
@@ -27,12 +27,16 @@ export interface ViewBox {
 
 /** Never ask for more than twice the CSS size: a 3× phone screen gains nothing visible from it. */
 export const MAX_PIXEL_RATIO = 2;
-/** A layer shown at most this much bigger than it is still looks sharp: avoids a whole layer for a few pixels. */
-export const MAX_UPSCALE = 1.15;
+/**
+ * A layer is never stretched on screen: a box bigger than a layer gets the next one up. Up to 0.9.1 a layer could be
+ * shown 15% bigger than it is, which looks soft on a face (owner, 2026-10-20: "quality should look good"). The 2% is
+ * for rounding only, so a box a pixel or two bigger than a layer keeps it.
+ */
+export const MAX_UPSCALE = 1.02;
 
 /**
- * The smallest layer that fills `box` sharply, or null when the layers are
- * not known (an older publisher): then the server chooses, as before.
+ * The smallest layer that fills `box` without being stretched, or null when
+ * the layers are not known (an older publisher): then the server chooses, as before.
  *
  * With `cover` the picture is scaled until it fills the box (a part is
  * cropped), with `contain` until it fits. Either way the scale is measured
@@ -46,7 +50,7 @@ export function layerForBox(layers: readonly VideoLayer[], box: ViewBox, pixelRa
   const h = box.height * ratio;
   for (const layer of usable) {
     const scale = box.fit === 'cover' ? Math.max(w / layer.width, h / layer.height) : Math.min(w / layer.width, h / layer.height);
-    // The layer is at most slightly upscaled on screen.
+    // The layer is not stretched on screen (see MAX_UPSCALE).
     if (scale <= MAX_UPSCALE) return layer.spatialLayer;
   }
   return usable[usable.length - 1]!.spatialLayer;

package/src/diagnostics.ts

@@ -7,7 +7,7 @@
  */
 
 /** This package's version; kept equal to package.json by a test. */
-export const SDK_VERSION = '0.9.1';
+export const SDK_VERSION = '0.9.2';
 
 /** How many recent events the log keeps. */
 export const DIAGNOSTICS_LOG_SIZE = 200;

package/src/index.ts

@@ -2337,7 +2337,14 @@ export class StreamClient {
     return parseSendStats(report.values(), { quality: this.videoQuality, baseline, keyPrefix: prefix });
   }
 
-  /** Friendly receive ceiling using this producer's real layer sizes; auto restores adaptation. */
+  /**
+   * The quality this viewer gets of one remote video. '1080p', '720p' and '480p' pick the publisher's biggest layer
+   * at or below that size (a 720p camera cannot give 1080p), and the viewer gets it while the video is shown, however
+   * big it is on screen: someone who picks 1080p expects 1080p, not the smaller copy that fits the tile. A connection
+   * that cannot carry it still gets less until it recovers, and a video shown through attachVideo is still paused
+   * while nobody can see it. 'auto' (the default) goes back to the size it is shown at, or the server's choice.
+   * Kept across reconnects.
+   */
   async setReceiveQuality(producerId: string, quality: ReceiveQuality): Promise<void> {
     if (!['auto', '1080p', '720p', '480p'].includes(quality)) throw new RangeError('setReceiveQuality: unsupported quality');
     const consumer = this.consumers.get(producerId);
@@ -3089,26 +3096,31 @@ export class StreamClient {
    * Adaptive stream (like LiveKit's adaptiveStream and Tencent TRTC's small
    * stream with receiveWhenViewVisible): tell the SDK which element shows a
    * remote video. It then receives the smallest layer that fills that element
-   * sharply (its size on screen × devicePixelRatio, at most 2) and pauses the
+   * without stretching it (its size on screen × devicePixelRatio, at most 2) and pauses the
    * video at the server while the element is not visible (scrolled away,
    * `display: none`, or the tab in the background), so a grid of small tiles
    * stops decoding full-size video. Attach the same video to several elements
    * and the largest visible one decides. Returns the function that detaches
-   * it; detach when the element goes away. A ceiling set with
-   * `setReceiveQuality` or `setPreferredLayers` still applies. Works with any
-   * server; one without `pauseConsumer` gets the smallest layer instead of a
-   * pause.
+   * it; detach when the element goes away. A quality chosen with
+   * `setReceiveQuality` replaces the size it is shown at (the video is still
+   * paused while hidden), and a ceiling set with `setPreferredLayers` still
+   * applies. Works with any server; one without `pauseConsumer` gets the
+   * smallest layer instead of a pause.
    */
   attachVideo(producerId: string, element: Element): () => void {
     return this.adaptive.attach(producerId, element);
   }
 
-  /** The layers to ask for: the app's ceiling (setReceiveQuality / setPreferredLayers) and adaptive stream's, the lower. */
+  /**
+   * The layers to ask for. A quality chosen with setReceiveQuality is the layer, whatever the size on screen (owner,
+   * 2026-10-20: viewers who picked 1080p got 540p, because it was only a ceiling). A ceiling set with
+   * setPreferredLayers and adaptive stream's size: the lower of the two.
+   */
   private effectiveLayers(producerId: string, want: AdaptiveWant | null): PreferredLayers {
     let manual: PreferredLayers | undefined = this.preferredLayers.get(producerId);
     const quality = this.receiveQualities.get(producerId);
     if (quality && quality !== 'auto') {
-      try { manual = { spatialLayer: receiveSpatialLayer(this.remoteVideoLayers.get(producerId) ?? [], quality) }; } catch { manual = undefined; }
+      try { return { spatialLayer: receiveSpatialLayer(this.remoteVideoLayers.get(producerId) ?? [], quality) }; } catch { manual = undefined; }
     }
     const adaptive = want?.visible ? want.spatialLayer : null;
     if (adaptive === null || adaptive === undefined) return manual ?? { spatialLayer: -1, temporalLayer: -1 };