feat: account for display pixel density in adaptive stream

The adaptive-stream visibility observer fed each view's logical (DIP) size
straight to the server, so on retina/HiDPI displays it under-requested by the
device pixel ratio and the server returned an upscaled/soft layer. Server
layers are sized in physical pixels.

- Add AdaptiveStreamPixelDensity (auto | fixed(double)) mirroring the JS SDK's
  pixelDensity option, plus RoomOptions.adaptiveStreamPixelDensity (default:
  auto). Fractional densities are supported and the resolved value is capped at
  3x to bound bandwidth.
- In auto mode the view's real devicePixelRatio is read per-view via
  MediaQuery; fixed modes use a constant multiplier.
- _computeVideoViewVisibility now scales each view's logical size by the
  resolved density before computing the largest requested dimensions.

Author: hiroshihorie

.changes/adaptive-stream-pixel-density

@@ -0,0 +1 @@
+patch type="improved" "Account for display pixel density (retina) in adaptive stream dimensions"

lib/src/options.dart

@@ -69,6 +69,48 @@ class ConnectOptions {
   });
 }
 
+/// Controls how a subscribed video view's logical size is scaled to physical
+/// pixels when computing adaptive-stream dimensions. Mirrors the JS SDK's
+/// `pixelDensity` option (`number | 'screen'`).
+///
+/// Layers on the server are sized in physical pixels, so on high-density
+/// (retina) displays the logical view size under-represents the pixels needed.
+class AdaptiveStreamPixelDensity {
+  /// Upper bound applied to the resolved density to keep bandwidth in check.
+  static const maxDensity = 3.0;
+
+  /// Fixed multiplier, or `null` to use the view's device pixel ratio ([auto]).
+  final double? value;
+
+  const AdaptiveStreamPixelDensity._(this.value);
+
+  /// Use the view's actual device pixel ratio, read via `MediaQuery`.
+  /// Equivalent to the JS SDK's `'screen'` setting. Capped at [maxDensity].
+  static const auto = AdaptiveStreamPixelDensity._(null);
+
+  /// A fixed pixel-density multiplier (fractional allowed, e.g. `1.5`, `2.0`,
+  /// `2.75`). The effective value is capped at [maxDensity] (3x) when resolved.
+  const AdaptiveStreamPixelDensity.fixed(double density) : value = density;
+
+  /// Resolves the effective multiplier, capped at [maxDensity]. For [auto],
+  /// falls back to the supplied [devicePixelRatio].
+  double resolve(double devicePixelRatio) {
+    final density = value ?? devicePixelRatio;
+    return density > maxDensity ? maxDensity : density;
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) || (other is AdaptiveStreamPixelDensity && other.value == value);
+
+  @override
+  int get hashCode => value.hashCode;
+
+  @override
+  String toString() =>
+      value == null ? 'AdaptiveStreamPixelDensity.auto' : 'AdaptiveStreamPixelDensity.fixed($value)';
+}
+
 /// Options used to modify the behavior of the [Room].
 /// {@category Room}
 class RoomOptions {
@@ -98,6 +140,12 @@ class RoomOptions {
   /// the data flow until they are visible again.
   final bool adaptiveStream;
 
+  /// Pixel density used to scale a video view's logical size when computing
+  /// adaptive-stream dimensions. Defaults to [AdaptiveStreamPixelDensity.auto]
+  /// (the view's real device pixel ratio), so retina displays request
+  /// appropriately sized layers. Only used when [adaptiveStream] is enabled.
+  final AdaptiveStreamPixelDensity adaptiveStreamPixelDensity;
+
   /// enable Dynacast, off by default. With Dynacast dynamically pauses
   /// video layers that are not being consumed by any subscribers, significantly
   /// reducing publishing CPU and bandwidth usage.
@@ -134,6 +182,7 @@ class RoomOptions {
     this.defaultAudioPublishOptions = const AudioPublishOptions(),
     this.defaultAudioOutputOptions = const AudioOutputOptions(),
     this.adaptiveStream = false,
+    this.adaptiveStreamPixelDensity = AdaptiveStreamPixelDensity.auto,
     this.dynacast = false,
     this.stopLocalTrackOnUnpublish = true,
     this.e2eeOptions,
@@ -150,6 +199,7 @@ class RoomOptions {
     AudioPublishOptions? defaultAudioPublishOptions,
     AudioOutputOptions? defaultAudioOutputOptions,
     bool? adaptiveStream,
+    AdaptiveStreamPixelDensity? adaptiveStreamPixelDensity,
     bool? dynacast,
     bool? stopLocalTrackOnUnpublish,
     E2EEOptions? e2eeOptions,
@@ -164,6 +214,7 @@ class RoomOptions {
       defaultAudioPublishOptions: defaultAudioPublishOptions ?? this.defaultAudioPublishOptions,
       defaultAudioOutputOptions: defaultAudioOutputOptions ?? this.defaultAudioOutputOptions,
       adaptiveStream: adaptiveStream ?? this.adaptiveStream,
+      adaptiveStreamPixelDensity: adaptiveStreamPixelDensity ?? this.adaptiveStreamPixelDensity,
       dynacast: dynacast ?? this.dynacast,
       stopLocalTrackOnUnpublish: stopLocalTrackOnUnpublish ?? this.stopLocalTrackOnUnpublish,
       // ignore: deprecated_member_use_from_same_package

lib/src/publication/remote.dart

@@ -157,15 +157,24 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
         );
 
     final videoTrack = track as VideoTrack;
+    final pixelDensity = participant.room.roomOptions.adaptiveStreamPixelDensity;
 
-    // filter visible build contexts
+    // Filter visible build contexts and scale each view's logical size by its
+    // pixel density, so the server is asked for physical-pixel dimensions
+    // (retina-aware). With AdaptiveStreamPixelDensity.auto the actual device
+    // pixel ratio is read per-view via MediaQuery.
     final viewSizes = videoTrack.viewKeys
         .map((e) => e.currentContext)
         .nonNulls
-        .map((e) => e.findRenderObject() as RenderBox?)
-        .nonNulls
-        .where((e) => e.hasSize)
-        .map((e) => e.size);
+        .map((context) {
+          final renderBox = context.findRenderObject() as RenderBox?;
+          if (renderBox == null || !renderBox.hasSize) return null;
+          final density = pixelDensity.resolve(
+            MediaQuery.maybeOf(context)?.devicePixelRatio ?? 1.0,
+          );
+          return renderBox.size * density;
+        })
+        .nonNulls;
 
     logger.finer('[Visibility] ${track?.sid} watching ${viewSizes.length} views...');
 

test/options/adaptive_stream_pixel_density_test.dart

@@ -0,0 +1,75 @@
+// Copyright 2025 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:livekit_client/src/options.dart';
+
+void main() {
+  group('AdaptiveStreamPixelDensity.resolve', () {
+    test('fixed densities ignore the device pixel ratio', () {
+      expect(const AdaptiveStreamPixelDensity.fixed(1.0).resolve(3.0), 1.0);
+      expect(const AdaptiveStreamPixelDensity.fixed(2.0).resolve(1.0), 2.0);
+    });
+
+    test('fractional fixed densities are supported', () {
+      expect(const AdaptiveStreamPixelDensity.fixed(1.5).resolve(3.0), 1.5);
+      expect(const AdaptiveStreamPixelDensity.fixed(2.75).resolve(1.0), 2.75);
+    });
+
+    test('auto falls back to the supplied device pixel ratio', () {
+      expect(AdaptiveStreamPixelDensity.auto.resolve(1.0), 1.0);
+      expect(AdaptiveStreamPixelDensity.auto.resolve(2.0), 2.0);
+      expect(AdaptiveStreamPixelDensity.auto.resolve(2.625), 2.625);
+    });
+
+    test('caps at 3x for both fixed and auto', () {
+      expect(const AdaptiveStreamPixelDensity.fixed(4.0).resolve(1.0), 3.0);
+      expect(AdaptiveStreamPixelDensity.auto.resolve(4.0), 3.0);
+      expect(AdaptiveStreamPixelDensity.maxDensity, 3.0);
+    });
+
+    test('value is null only for auto', () {
+      expect(AdaptiveStreamPixelDensity.auto.value, isNull);
+      expect(const AdaptiveStreamPixelDensity.fixed(1.5).value, 1.5);
+    });
+
+    test('equality is by value', () {
+      expect(
+        const AdaptiveStreamPixelDensity.fixed(2.0),
+        const AdaptiveStreamPixelDensity.fixed(2.0),
+      );
+      expect(
+        const AdaptiveStreamPixelDensity.fixed(2.0) == AdaptiveStreamPixelDensity.auto,
+        isFalse,
+      );
+    });
+  });
+
+  group('RoomOptions.adaptiveStreamPixelDensity', () {
+    test('defaults to auto', () {
+      expect(
+        const RoomOptions().adaptiveStreamPixelDensity,
+        AdaptiveStreamPixelDensity.auto,
+      );
+    });
+
+    test('copyWith overrides the density', () {
+      final opts = const RoomOptions().copyWith(
+        adaptiveStreamPixelDensity: const AdaptiveStreamPixelDensity.fixed(1.5),
+      );
+      expect(opts.adaptiveStreamPixelDensity, const AdaptiveStreamPixelDensity.fixed(1.5));
+    });
+  });
+}