@opentok/client 2.35.0-alpha.27 → 2.35.0-alpha.28

package/dist/js/opentok.js

@@ -1,11 +1,11 @@
 /**
- * @license OpenTok.js 2.35.0 87f6a8fb6
+ * @license OpenTok.js 2.35.0 6d82efef1
  *
  * Copyright (c) 2010-2026 TokBox, Inc.
  * Subject to the applicable Software Development Kit (SDK) License Agreement:
  * https://www.vonage.com/legal/communications-apis/terms-of-use/
  *
- * Date: Fri, 22 May 2026 18:11:26 GMT
+ * Date: Sat, 23 May 2026 07:05:36 GMT
  */
 
 (function webpackUniversalModuleDefinition(root, factory) {
@@ -26176,7 +26176,9 @@ function SubscriberFactory(_ref2) {
     *   <li>Total audio and video packets lost</li>
     *   <li>Total audio and video packets received</li>
     *   <li>Total audio and video bytes received</li>
-    *   <li>Current average video frame rate</li>
+    *   <li>Actual received video resolution (via <a href="#videoWidth">videoWidth()</a> and
+    *     <a href="#videoHeight">videoHeight()</a>)</li>
+    *   <li>Actual decoded video frame rate (via <code>video.decodedFrameRate</code>)</li>
     *
     * </ul>
     *
@@ -26860,11 +26862,20 @@ function SubscriberFactory(_ref2) {
     };
 
     /**
-    * Returns the width, in pixels, of the Subscriber video.
+    * Returns the actual received width, in pixels, of the Subscriber video. This reflects
+    * the decoded resolution of the incoming video stream, which may differ from the
+    * publisher's capture resolution due to network/CPU adaptation or scalable video layer
+    * selection. Use this method to observe the real resolution being rendered for this
+    * subscriber.
+    * <p>
+    * For more information on monitoring stream quality, see the
+    * <a href="https://tokbox.com/developer/guides/client-observability/">Client Observability</a>
+    * developer guide.
     *
+    * @see <a href="#getStats">Subscriber.getStats()</a>
     * @method #videoWidth
     * @memberOf Subscriber
-    * @return {Number} the width, in pixels, of the Subscriber video.
+    * @return {Number} The actual received width, in pixels, of the Subscriber video.
     */
     this.videoWidth = () => {
       const video = _widgetView && _widgetView.video();
@@ -26872,11 +26883,20 @@ function SubscriberFactory(_ref2) {
     };
 
     /**
-    * Returns the height, in pixels, of the Subscriber video.
+    * Returns the actual received height, in pixels, of the Subscriber video. This reflects
+    * the decoded resolution of the incoming video stream, which may differ from the
+    * publisher's capture resolution due to network or cpu adaptation or scalable video layer
+    * selection. Use this method to observe the real resolution being rendered for this
+    * subscriber.
+    * <p>
+    * For more information on monitoring stream quality, see the
+    * <a href="https://tokbox.com/developer/guides/client-observability/">Client Observability</a>
+    * developer guide.
     *
+    * @see <a href="#getStats">Subscriber.getStats()</a>
     * @method #videoHeight
     * @memberOf Subscriber
-    * @return {Number} the width, in pixels, of the Subscriber video.
+    * @return {Number} The actual received height, in pixels, of the Subscriber video.
     */
     this.videoHeight = () => {
       const video = _widgetView && _widgetView.video();
@@ -28326,14 +28346,26 @@ function SubscriberFactory(_ref2) {
     */
 
     /**
-    * Dispatched when the video dimensions of the video change. This can occur when the
-    * <code>stream.videoType</code> property is set to <code>"screen"</code> (for a screen-sharing
-    * video stream), when the user resizes the window being captured. It can also occur if the video
-    * is being published by a mobile device and the user rotates the device (causing the camera
-    * orientation to change). This event object has a <code>newValue</code> property and an
-    * <code>oldValue</code> property, representing the new and old dimensions of the video.
-    * Each of these has a <code>height</code> property and a <code>width</code> property,
-    * representing the height and width, in pixels.
+    * Dispatched when the <code>stream.videoDimensions</code> property is updated by the
+    * publisher. This occurs when the publisher's local video element detects a dimension change
+    * and signals the update to all session participants. Examples of what can cause this:
+    * <ul>
+    *   <li>When <code>stream.videoType</code> is set to <code>"screen"</code> (screen-sharing)
+    *       and the user resizes the captured window.</li>
+    *   <li>When the video is being published by a mobile device and the user rotates the device,
+    *       causing the camera orientation to change.</li>
+    *   <li>When the publisher calls {@link Publisher#setPreferredResolution}, changing the
+    *       target capture resolution.</li>
+    * </ul>
+    * This event object has a <code>newValue</code> property and an <code>oldValue</code> property,
+    * representing the new and old dimensions of the video. Each of these has a <code>height</code>
+    * property and a <code>width</code> property, representing the height and width, in pixels.
+    * <p>
+    * Note: these dimensions reflect the publisher's <em>capture</em> resolution (what the
+    * publisher is encoding and sending), not the resolution actually decoded by this subscriber.
+    * The decoded resolution may differ due to network adaptation or scalable video coding.
+    * Use {@link Subscriber#videoWidth} and {@link Subscriber#videoHeight} for the actual
+    * received resolution.
     * @name videoDimensionsChanged
     * @event
     * @memberof Subscriber
@@ -41891,7 +41923,7 @@ function staticConfigFactory(_temp) {
     _ref$axios = _ref.axios,
     axios = _ref$axios === void 0 ? _axios.default : _ref$axios,
     _ref$properties = _ref.properties,
-    properties = _ref$properties === void 0 ? {"version":"v2.35.0","buildHash":"87f6a8fb6","minimumVersion":{"firefox":52,"chrome":49},"debug":false,"websiteURL":"http://www.tokbox.com","configURL":"https://config.opentok.com","ipWhitelistConfigURL":"","cdnURL":"","loggingURL":"https://hlg.tokbox.com/prod","apiURL":"https://anvil.opentok.com","vonageApiURL":""} : _ref$properties;
+    properties = _ref$properties === void 0 ? {"version":"v2.35.0","buildHash":"6d82efef1","minimumVersion":{"firefox":52,"chrome":49},"debug":false,"websiteURL":"http://www.tokbox.com","configURL":"https://config.opentok.com","ipWhitelistConfigURL":"","cdnURL":"","loggingURL":"https://hlg.tokbox.com/prod","apiURL":"https://anvil.opentok.com","vonageApiURL":""} : _ref$properties;
   /** @type builtInConfig */
   const builtInConfig = (0, _cloneDeep.default)(properties);
   /**
@@ -48509,26 +48541,24 @@ function PublisherFactory(_ref) {
     };
 
     /**
-    * Returns the width, in pixels, of the Publisher video. This may differ from the
-    * <code>resolution</code> property passed in as the <code>properties</code> property
-    * the options passed into the <code>OT.initPublisher()</code> method, if the browser
-    * does not support the requested resolution.
+    * Returns the width, in pixels, of the publisher's local video, read from the
+    * local <code>&lt;video&gt;</code> element. This is the same value as
+    * <code>stream.videoDimensions.width</code>
     *
     * @method #videoWidth
     * @memberOf Publisher
-    * @return {Number} the width, in pixels, of the Publisher video.
+    * @return {Number} The width, in pixels, of the publisher's local video.
     */
     this.videoWidth = () => getVideoDimensions().width;
 
     /**
-    * Returns the height, in pixels, of the Publisher video. This may differ from the
-    * <code>resolution</code> property passed in as the <code>properties</code> property
-    * the options passed into the <code>OT.initPublisher()</code> method, if the browser
-    * does not support the requested resolution.
+    * Returns the height, in pixels, of the publisher's local video, read from the
+    * local <code>&lt;video&gt;</code> element. This is the same value as
+    * <code>stream.videoDimensions.height</code>.
     *
     * @method #videoHeight
     * @memberOf Publisher
-    * @return {Number} the height, in pixels, of the Publisher video.
+    * @return {Number} The height, in pixels, of the publisher's local video.
     */
     this.videoHeight = () => getVideoDimensions().height;
 
@@ -50347,12 +50377,21 @@ function PublisherFactory(_ref) {
   */
 
   /**
-  * Dispatched when the video dimensions of the video change. This can only occur in when the
-  * <code>stream.videoType</code> property is set to <code>"screen"</code> (for a screen-sharing
-  * video stream), when the user resizes the window being captured. This event object has a
-  * <code>newValue</code> property and an <code>oldValue</code> property, representing the new and
-  * old dimensions of the video. Each of these has a <code>height</code> property and a
-  * <code>width</code> property, representing the height and width, in pixels.
+  * Dispatched when the publisher's local <code>&lt;video&gt;</code> element detects a dimension
+  * change. When the publisher is actively publishing, this also updates the
+  * <code>stream.videoDimensions</code> property. Examples of what can cause the local video
+  * element to resize:
+  * <ul>
+  *   <li>When <code>stream.videoType</code> is set to <code>"screen"</code> (screen-sharing)
+  *       and the user resizes the captured window.</li>
+  *   <li>When the video is being published by a mobile device and the user rotates the device,
+  *       causing the camera orientation to change.</li>
+  *   <li>When the publisher calls {@link Publisher#setPreferredResolution}, changing the
+  *       target capture resolution.</li>
+  * </ul>
+  * This event object has a <code>newValue</code> property and an <code>oldValue</code> property,
+  * representing the new and old dimensions of the video. Each of these has a <code>height</code>
+  * property and a <code>width</code> property, representing the height and width, in pixels.
   * @name videoDimensionsChanged
   * @event
   * @memberof Publisher
@@ -80049,8 +80088,17 @@ function EventsFactory(deps) {
   };
 
   /**
-   * Dispatched when the video dimensions of the video change for a screen-sharing
-   * video stream (when the user resizes the window being captured).
+   * Dispatched when the video dimensions of a published stream change.
+   * <p>
+   * On the <strong>Publisher</strong>, this event fires when the publisher's local
+   * <code>&lt;video&gt;</code> element detects a dimension change. When the publisher is
+   * actively publishing, this also updates the <code>stream.videoDimensions</code> property.
+   * Examples of what can cause the local video element to resize: resizing a captured
+   * screen-sharing window, rotating a mobile device (changing camera orientation), or calling
+   * <code>Publisher.setPreferredResolution()</code>.
+   * <p>
+   * On the <strong>Subscriber</strong>, this event fires when the <code>stream.videoDimensions</code>
+   * property is updated by the publisher.
    *
    * @class VideoDimensionsChangedEvent
    * @property {Object} newValue The new video dimensions (after the change). This object has two
@@ -107462,9 +107510,19 @@ const validPropertyNames = ['name', 'archiving'];
  * Date object by calling <code>new Date(creationTime)</code>, where <code>creationTime</code> is
  * the <code>creationTime</code> property of the Stream object.
  *
- * @property {Number} frameRate The frame rate of the video stream. This property is only set if
- * the publisher of the stream specifies a frame rate when calling the
- * <code>OT.initPublisher()</code> method; otherwise, this property is undefined.
+ * @property {Number} frameRate The publisher's capture target frame rate.
+ * Initially derived from the <code>frameRate</code> property passed to
+ * <a href="OT.html#initPublisher">OT.initPublisher()</a>. This property is only set if the
+ * publisher explicitly specifies a frame rate; otherwise, it is undefined. This value is
+ * updated when the publisher calls
+ * <a href="Publisher.html#setPreferredFrameRate">Publisher.setPreferredFrameRate()</a>.
+ * <p>
+ * <b>Note:</b> This value represents the publisher's current target capture frame rate, not
+ * the frame rate actually encoded or received by a subscriber. The encoded frame rate may
+ * still be lower due to bandwidth or CPU constraints, and the received frame rate can vary
+ * further based on network conditions. To get the real decoded frame rate for a subscriber,
+ * use the <code>video.decodedFrameRate</code> property returned by
+ * <a href="Subscriber.html#getStats">Subscriber.getStats()</a>.
  *
  * @property {Boolean} hasCaptions Whether the stream has captions. This property can change if the
  * publisher turns captions on or off (by calling the
@@ -107496,13 +107554,26 @@ const validPropertyNames = ['name', 'archiving'];
  * @property {String} streamId The unique ID of the stream.
  *
  * @property {Object} videoDimensions This object has two properties: <code>width</code> and
- * <code>height</code>. Both are numbers. The <code>width</code> property is the width of the
- * encoded stream; the <code>height</code> property is the height of the encoded stream. (These
- * are independent of the actual width of Publisher and Subscriber objects corresponding to the
- * stream.) This property can change if a stream published from a mobile device resizes, based on
- * a change in the device orientation. When the video dimensions change,
- * the {@link Session} object dispatches a <code>streamPropertyChanged</code> event
- * (see {@link StreamPropertyChangedEvent}).
+ * <code>height</code> (both numbers). These represent the publisher's capture target resolution
+ * last signaled to the session. The value is broadcast to all participants via the
+ * signaling layer and is readable on both the publishing and subscribing clients.
+ * <p>
+ * The value is set initially from the <code>resolution</code> property passed to
+ * <a href="OT.html#initPublisher">OT.initPublisher()</a>. It is updated at runtime when the
+ * publisher's local <code>&lt;video&gt;</code> element detects a dimension change (for example,
+ * after a call to
+ * <a href="Publisher.html#setPreferredResolution">Publisher.setPreferredResolution()</a>,
+ * a screen-sharing window resize, or a mobile device rotation).
+ * <p>
+ * <b>Note:</b> These values represent the publisher's capture target resolution, not the resolution
+ * actually encoded or received by a subscriber. The publisher may encode at a lower resolution
+ * due to bandwidth or CPU constraints, and subscribers using scalable video may receive an even
+ * lower resolution layer. To get the actual decoded resolution on the subscribing client, use
+ * <a href="Subscriber.html#videoWidth">Subscriber.videoWidth()</a> and
+ * <a href="Subscriber.html#videoHeight">Subscriber.videoHeight()</a>.
+ * <p>
+ * When this property changes, the {@link Session} object dispatches a
+ * <code>streamPropertyChanged</code> event (see {@link StreamPropertyChangedEvent}).
  *
  * @property {String} videoType The type of video &mdash; either <code>"camera"</code>,
  * <code>"screen"</code>, or <code>"custom"</code>.