feat: add scalability mode for AV1/VP9. (#1076)

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: cloudwebrtc

.changeset/feat_add_scalability_mode_for_av1_vp9.md

@@ -0,0 +1,7 @@
+---
+libwebrtc: patch
+livekit: patch
+livekit-ffi: patch
+---
+
+feat: add scalability mode for AV1/VP9. - #1076 (@cloudwebrtc)

libwebrtc/src/native/rtp_parameters.rs

@@ -72,6 +72,7 @@ impl From<sys_rp::ffi::RtpEncodingParameters> for RtpEncodingParameters {
             scale_resolution_down_by: value
                 .has_scale_resolution_down_by
                 .then_some(value.scale_resolution_down_by),
+            scalability_mode: value.has_scalability_mode.then_some(value.scalability_mode),
         }
     }
 }
@@ -203,8 +204,8 @@ impl From<RtpEncodingParameters> for sys_rp::ffi::RtpEncodingParameters {
             min_bitrate_bps: 0,
             has_num_temporal_layers: false,
             num_temporal_layers: 0,
-            has_scalability_mode: false,
-            scalability_mode: "".to_string(),
+            has_scalability_mode: value.scalability_mode.is_some(),
+            scalability_mode: value.scalability_mode.unwrap_or_default(),
             has_ssrc: false,
             ssrc: 0,
         }

libwebrtc/src/rtp_parameters.rs

@@ -58,6 +58,9 @@ pub struct RtpEncodingParameters {
     pub priority: Priority,
     pub rid: String,
     pub scale_resolution_down_by: Option<f64>,
+    /// RTP scalability mode (e.g. "L3T3_KEY"). Required to enable true
+    /// SVC for codecs that support it (VP9, AV1).
+    pub scalability_mode: Option<String>,
 }
 
 #[derive(Debug, Clone)]
@@ -89,6 +92,7 @@ impl Default for RtpEncodingParameters {
             priority: Priority::Low,
             rid: String::default(),
             scale_resolution_down_by: None,
+            scalability_mode: None,
         }
     }
 }

livekit-ffi-node-bindings/proto/room_pb.d.ts

@@ -1770,6 +1770,15 @@ export declare class TrackPublishOptions extends Message<TrackPublishOptions> {
    */
   packetTrailerFeatures: PacketTrailerFeature[];
 
+  /**
+   * RTP scalability mode (e.g. "L3T3_KEY"). When set, a single RTP
+   * encoding is produced with this mode, enabling true SVC for codecs
+   * that support it (VP9, AV1). Has no effect for VP8/H264.
+   *
+   * @generated from field: optional string scalability_mode = 11;
+   */
+  scalabilityMode?: string;
+
   constructor(data?: PartialMessage<TrackPublishOptions>);
 
   static readonly runtime: typeof proto2;

livekit-ffi-node-bindings/proto/room_pb.js

@@ -697,6 +697,7 @@ const TrackPublishOptions = /*@__PURE__*/ proto2.makeMessageType(
     { no: 8, name: "stream", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
     { no: 9, name: "preconnect_buffer", kind: "scalar", T: 8 /* ScalarType.BOOL */, opt: true },
     { no: 10, name: "packet_trailer_features", kind: "enum", T: proto2.getEnumType(PacketTrailerFeature), repeated: true },
+    { no: 11, name: "scalability_mode", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
   ],
 );
 

livekit-ffi/protocol/room.proto

@@ -308,6 +308,10 @@ message TrackPublishOptions {
   optional string stream = 8;
   optional bool preconnect_buffer = 9;
   repeated PacketTrailerFeature packet_trailer_features = 10;
+  // RTP scalability mode (e.g. "L3T3_KEY"). When set, a single RTP
+  // encoding is produced with this mode, enabling true SVC for codecs
+  // that support it (VP9, AV1). Has no effect for VP8/H264.
+  optional string scalability_mode = 11;
 }
 
 enum IceTransportType {

livekit-ffi/src/conversion/room.rs

@@ -316,6 +316,7 @@ impl From<proto::TrackPublishOptions> for TrackPublishOptions {
             packet_trailer_features: packet_trailer_features_from_proto(
                 opts.packet_trailer_features,
             ),
+            scalability_mode: opts.scalability_mode,
         }
     }
 }

livekit/src/room/options.rs

@@ -119,6 +119,10 @@ pub struct TrackPublishOptions {
     pub stream: String,
     pub preconnect_buffer: bool,
     pub packet_trailer_features: PacketTrailerFeatures,
+    /// RTP scalability mode (e.g. "L3T3_KEY"). When set, a single RTP
+    /// encoding is produced and that mode is forwarded to libwebrtc to
+    /// enable true SVC for VP9/AV1. Has no effect for VP8/H264.
+    pub scalability_mode: Option<String>,
 }
 
 impl Default for TrackPublishOptions {
@@ -135,6 +139,7 @@ impl Default for TrackPublishOptions {
             stream: "".to_string(),
             preconnect_buffer: false,
             packet_trailer_features: PacketTrailerFeatures::default(),
+            scalability_mode: None,
         }
     }
 }
@@ -176,6 +181,16 @@ pub fn compute_video_encodings(
         },
     };
 
+    // SVC: when an explicit scalability_mode is set, emit a single encoding
+    // and let libwebrtc produce the spatial/temporal layers internally.
+    if let Some(mode) = options.scalability_mode.clone() {
+        let mut encodings = into_rtp_encodings(width, height, &[initial_preset]);
+        if let Some(first) = encodings.first_mut() {
+            first.scalability_mode = Some(mode);
+        }
+        return encodings;
+    }
+
     if !options.simulcast {
         return into_rtp_encodings(width, height, &[initial_preset]);
     }
@@ -310,6 +325,19 @@ pub fn video_quality_for_rid(rid: &str) -> Option<proto::VideoQuality> {
     }
 }
 
+/// Parse the number of spatial layers from an RTP scalability mode string.
+/// Standard modes start with `L<N>` where `<N>` is the spatial-layer count
+/// (e.g. "L3T3_KEY" -> 3, "L2T3" -> 2, "L1T3" -> 1).
+pub fn spatial_layers_from_scalability_mode(mode: &str) -> u32 {
+    if let Some(rest) = mode.strip_prefix('L') {
+        let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
+        if let Ok(n) = digits.parse::<u32>() {
+            return n.max(1);
+        }
+    }
+    1
+}
+
 pub fn video_layers_from_encodings(
     width: u32,
     height: u32,
@@ -326,6 +354,39 @@ pub fn video_layers_from_encodings(
         }];
     }
 
+    // SVC: a single RTP encoding carries multiple spatial layers internally.
+    // Synthesise one VideoLayer per spatial layer so the SFU knows the track
+    // has switchable quality tiers.
+    if encodings.len() == 1 {
+        if let Some(mode) = encodings[0].scalability_mode.as_ref() {
+            let spatial = spatial_layers_from_scalability_mode(mode);
+            if spatial > 1 {
+                let total_bitrate = encodings[0].max_bitrate.unwrap_or(0);
+                let mut layers = Vec::with_capacity(spatial as usize);
+                // Highest spatial layer is the source resolution; each lower
+                // layer is half on each axis (the libwebrtc default for
+                // L2/L3 scalability modes).
+                for i in 0..spatial {
+                    let scale = 1u32 << (spatial - 1 - i);
+                    let quality = match (spatial - 1 - i, spatial) {
+                        (0, _) => proto::VideoQuality::High,
+                        (1, _) => proto::VideoQuality::Medium,
+                        _ => proto::VideoQuality::Low,
+                    };
+                    layers.push(proto::VideoLayer {
+                        quality: quality as i32,
+                        width: width / scale,
+                        height: height / scale,
+                        bitrate: (total_bitrate / spatial as u64) as u32,
+                        ssrc: 0,
+                        ..Default::default()
+                    });
+                }
+                return layers;
+            }
+        }
+    }
+
     let mut layers = Vec::with_capacity(encodings.len());
     for encoding in encodings {
         let scale = encoding.scale_resolution_down_by.unwrap_or(1.0);

livekit/src/room/participant/local_participant.rs

@@ -336,8 +336,17 @@ impl LocalParticipant {
                 encodings = compute_video_encodings(req.width, req.height, &options);
                 req.layers = video_layers_from_encodings(req.width, req.height, &encodings);
 
-                // Populate simulcast_codecs so the server knows this track is simulcasted
-                if options.simulcast && encodings.len() > 1 {
+                // Populate simulcast_codecs so the server knows this track has
+                // multiple quality layers — either real simulcast (multiple
+                // RTP encodings) or SVC (one encoding with several spatial
+                // layers carried inside it).
+                let is_svc_multilayer = encodings.len() == 1
+                    && encodings
+                        .first()
+                        .and_then(|e| e.scalability_mode.as_ref())
+                        .map(|m| options::spatial_layers_from_scalability_mode(m) > 1)
+                        .unwrap_or(false);
+                if (options.simulcast && encodings.len() > 1) || is_svc_multilayer {
                     req.simulcast_codecs = vec![proto::SimulcastCodec {
                         codec: options.video_codec.as_str().to_string(),
                         cid: track.rtc_track().id(),