Adaptive Bitrate (ABR)

Overview

The playback quality during play-out of a THEOlive stream is determined by the ABR algorithm. On starting play-out, the ABR strategy determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on the THEOplayer website and demo page.

ABR Configuration

The ABR configuration is accessible through player.abr. It allows you to control the ABR strategy, target buffer, and preferred peak bitrate.

Setting the ABR Strategy

The strategy determines which quality the player initially selects when starting playback:

Strategy	Description
performance	Prefer the lowest quality for faster startup and lower bandwidth usage.
quality	Prefer the highest quality for the best visual experience.
bandwidth	Estimate available bandwidth and select the best matching quality.

The default strategy is bandwidth.

// Set the ABR strategy to "quality" (prefer highest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.quality),
);

// Set the ABR strategy to "performance" (prefer lowest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.performance),
);

// Read the current strategy
final config = await player.abr.strategy;
print("Current ABR strategy: ${config.type}");

Setting an Initial Bitrate Cap

You can pass optional metadata with a bitrate value (in bits per second) to cap the initial quality selection:

player.abr.setStrategy(
  AbrStrategyConfiguration(
    type: AbrStrategyType.bandwidth,
    metadata: AbrStrategyMetadata(bitrate: 1200000), // 1.2 Mbps
  ),
);

This is useful when you have an estimate of the user's available bandwidth and want to avoid buffering on startup.

Target Buffer

The target buffer controls how many seconds of video the player should buffer ahead of the current playback position. This only applies to HLS (non-THEOlive) streams.

// Get the current target buffer (default: 20 seconds)
final buffer = await player.abr.targetBuffer;

// Set the target buffer to 10 seconds
player.abr.setTargetBuffer(10.0);

Preferred Peak Bitrate (iOS only)

On iOS you can set the desired limit for network bandwidth consumption. This only applies to HLS (non-THEOlive) streams and is a no-op on other platforms.

// Cap bandwidth to 2 Mbps
player.abr.setPreferredPeakBitRate(2000000);

// Remove the cap (default: 0 = no limit)
player.abr.setPreferredPeakBitRate(0);

Setting Target Video Quality

By default, the ABR algorithm will choose from all the video qualities available in the stream. You can pin the player to a specific quality or a subset of qualities using the targetQuality / targetQualities properties on a video track:

final videoTrack = player.videoTracks.first;

// Pin to a single quality (disables ABR)
videoTrack.targetQuality = videoTrack.qualities.first;

// Pin to a subset of qualities (ABR selects among these)
videoTrack.targetQualities = [
  videoTrack.qualities[0],
  videoTrack.qualities[1],
];

// Reset to automatic (let ABR choose freely)
videoTrack.targetQuality = null;

Subscribing to Quality Change Events

You can listen for quality changes on video and audio tracks:

// Listen for new video tracks
player.videoTracks.addEventListener(VideoTracksEventTypes.ADDTRACK, (event) {
  final track = (event as AddVideoTrackEvent).track;
  print("Video track added: ${track.uid}");

  // Print all available qualities
  for (final quality in track.qualities) {
    print("  quality: ${quality.width}x${quality.height}, "
        "bandwidth: ${quality.bandwidth}");
  }

  // Listen for active quality changes on this track
  track.addEventListener(
    VideoTrackEventTypes.ACTIVEQUALITYCHANGED,
    (event) {
      final q = (event as VideoActiveQualityChangedEvent).quality;
      print("Active quality changed: ${q.width}x${q.height}, "
          "bandwidth: ${q.bandwidth}");
    },
  );
});

Supported Platforms

Property	Android	iOS	Web
strategy	✅	✅	✅
targetBuffer	✅	✅	✅
preferredPeakBitRate	❌	✅	❌
targetQuality	✅	✅	✅
Quality change events	✅	✅	✅

Notes: On iOS, the ABR strategy configuration only affects THEOlive (HESP) streams. For other stream types, the player uses the platform-native ABR algorithm that cannot be configured through this API.

On Android and Web, the ABR strategy is applied to all adaptive streams.