docs(millicast): document resolution caps for Millicast playback (OPTI-1349)

millicast/playback/players-sdks/android/player/index.mdx

@@ -92,6 +92,22 @@ theoplayerView.player.source = SourceDescription.Builder(
 ).build()
 ```
 
+### Limit the maximum resolution
+
+Since THEOplayer 11.5.0, you can cap the resolution of a Millicast stream through [`abr.preferredMaximumResolution`](<pathname:///theoplayer/v11/api-reference/android/com/theoplayer/android/api/abr/Abr.html#setPreferredMaximumResolution(android.util.Size)>). You can set it before playback starts, or change it during playback, for example when the device rotates between portrait and landscape. Changes are applied without reconnecting to the stream, and the media server keeps switching between the layers within that limit when network conditions change.
+
+```kotlin
+import android.util.Size
+
+// Limit playback to layers of at most 1280x720
+theoplayerView.player.abr.preferredMaximumResolution = Size(1280, 720)
+
+// Remove the limit and use the full ABR range again
+theoplayerView.player.abr.preferredMaximumResolution = null
+```
+
+Selecting a specific video quality through `targetQuality` pins playback to that layer and turns off ABR. While a quality is pinned, `preferredMaximumResolution` is ignored.
+
 ### Background playback
 
 :::info[Known issue on Android Millicast background playback]

millicast/playback/players-sdks/ios/player/index.mdx

@@ -106,6 +106,18 @@ connectOptions.disableAudio = true
 MillicastSource(src: ..., streamAccountId: ..., connectOptions: connectOptions)
 ```
 
+### Limit the maximum resolution
+
+Since THEOplayer 11.5.0, you can cap the resolution of a Millicast stream through [`abr.preferredMaximumResolution`](pathname:///theoplayer/v11/api-reference/ios/Protocols/ABRConfiguration.html#/s:13THEOplayerSDK16ABRConfigurationP26preferredMaximumResolutionSo6CGSizeVvp). You can set it before playback starts, or change it during playback, for example when the device rotates between portrait and landscape. Changes are applied without reconnecting to the stream, and the media server keeps switching between the layers within that limit when network conditions change.
+
+```swift
+// Limit playback to layers of at most 1280x720
+theoplayer.abr.preferredMaximumResolution = CGSize(width: 1280, height: 720)
+
+// Remove the limit and use the full ABR range again
+theoplayer.abr.preferredMaximumResolution = .zero
+```
+
 ### Background playback
 
 In order to play Millicast sources in the background, ensure you've configured a `backgroundPlaybackDelegate` on the player. A simple example for always allowing background playback is shown below:

millicast/playback/players-sdks/web/player/index.mdx

@@ -101,6 +101,45 @@ connectOptions: {
 
 Setting a `maxHeight` of `0` will use the full ABR range available. Setting the `maxHeight` to an arbitrarily low value, such as `20`, will force the user onto the layer with the lowest resolution.
 
+These values are applied when the player connects to the stream. To change the maximum resolution during playback without reconnecting, use [`player.abr.preferredMaximumResolution`](#change-the-maximum-resolution-during-playback) instead.
+
+#### Change the maximum resolution during playback
+
+Since THEOplayer 11.13.0, you can cap the resolution of a Millicast stream at any time through [`player.abr.preferredMaximumResolution`](pathname:///theoplayer/v11/api-reference/web/interfaces/ABRConfiguration.html#preferredMaximumResolution), for example when the player is shown in a smaller view or the viewport is rotated between portrait and landscape. The new limit is applied without reconnecting to the stream, and the media server keeps switching between the layers within that limit when network conditions change.
+
+```javascript
+// Limit playback to layers of at most 1280x720
+player.abr.preferredMaximumResolution = { width: 1280, height: 720 };
+
+// Remove the limit and use the full ABR range again
+player.abr.preferredMaximumResolution = undefined;
+```
+
+#### Restrict the resolution to the player size
+
+Since THEOplayer 11.13.0, you can also let the player limit the resolution to the size at which it is displayed, by setting [`abr.restrictToPlayerSize`](pathname:///theoplayer/v11/api-reference/web/interfaces/SourceAbrConfiguration.html#restrictToPlayerSize) to `true` on the source description. The player then caps the stream to the smallest available layer that still covers the player's rendered size, and updates that cap when the player is resized.
+
+```javascript
+player.source = {
+  sources: {
+    type: 'millicast',
+    src: 'multiview',
+    streamAccountId: 'k9Mwad',
+  },
+  abr: {
+    restrictToPlayerSize: true,
+  },
+};
+```
+
+For Millicast sources, this restriction is only applied when `restrictToPlayerSize` is explicitly set to `true`.
+
+When `restrictToPlayerSize` is combined with `preferredMaximumResolution`, the most restrictive limit wins: the player uses the smallest width and the smallest height of both limits.
+
+:::note
+While `preferredMaximumResolution` or `restrictToPlayerSize` limits the resolution, that limit replaces the `maxWidth` and `maxHeight` values of `connectOptions.layer`. When the limit is removed, the player goes back to the full ABR range, not to the `connectOptions.layer` values. Avoid combining both approaches.
+:::
+
 #### Playout Delay
 
 Because of the complexities of last-mile delivery, some packets for video playback may arrive late. In higher-latency streaming protocols such as HESP or HLS, a client buffer helps smooth out playback so that these minor fluctuations are unnoticeable. Dolby's real-time streaming solution supports adding a playout buffer, which can similarly assist with these fluctuations. The `forcePlayoutDelay` buffer uses a `min` and a `max` value measured in milliseconds (ms) to specify the range the playout buffer should occupy. The player buffer will then dynamically shift between the `min` and `max` values depending on client conditions.