rename Packet Trailer to Frame Metadata

.changeset/frame-metadata-user-data.md

@@ -0,0 +1,7 @@
+---
+livekit: minor
+livekit-ffi: minor
+livekit-protocol: minor
+---
+
+Rename user facing APIs for Packet Trailer to Frame Metadata.  

examples/local_video/src/publisher.rs

@@ -2,7 +2,7 @@ use anyhow::Result;
 use clap::{Parser, ValueEnum};
 use livekit::e2ee::{key_provider::*, E2eeOptions, EncryptionType};
 use livekit::options::{
-    self, video as video_presets, PacketTrailerFeatures, TrackPublishOptions, VideoCodec,
+    self, video as video_presets, FrameMetadataFeatures, TrackPublishOptions, VideoCodec,
     VideoEncoderBackend, VideoEncoding, VideoPreset,
 };
 use livekit::prelude::*;
@@ -1178,16 +1178,16 @@ async fn run(args: Args, ctrl_c_received: Arc<AtomicBool>) -> Result<()> {
         );
     }
 
-    let mut packet_trailer_features = PacketTrailerFeatures::default();
-    packet_trailer_features.user_timestamp = args.attach_timestamp;
-    packet_trailer_features.frame_id = args.attach_frame_id;
+    let mut frame_metadata_features = FrameMetadataFeatures::default();
+    frame_metadata_features.user_timestamp = args.attach_timestamp;
+    frame_metadata_features.frame_id = args.attach_frame_id;
 
     let publish_opts = |codec: VideoCodec| TrackPublishOptions {
         source: TrackSource::Camera,
         simulcast: args.simulcast,
         video_codec: codec,
         video_encoder: requested_encoder,
-        packet_trailer_features,
+        frame_metadata_features,
         video_encoding: Some(main_encoding.clone()),
         simulcast_layers: args.simulcast.then(|| simulcast_presets.clone()),
         ..Default::default()

examples/local_video/src/subscriber.rs

@@ -881,15 +881,15 @@ async fn handle_track_subscribed(
     }
 
     info!(
-        "Subscribed to video track: {} (sid {}) from {} - codec: {}, simulcast: {}, dimension: {}x{}, packet_trailer_features: {:?}",
+        "Subscribed to video track: {} (sid {}) from {} - codec: {}, simulcast: {}, dimension: {}x{}, frame_metadata_features: {:?}",
         publication.name(),
         publication.sid(),
         participant.identity(),
         codec,
         publication.simulcasted(),
         publication.dimension().0,
         publication.dimension().1,
-        publication.packet_trailer_features(),
+        publication.frame_metadata_features(),
     );
 
     {

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

@@ -20,7 +20,7 @@
 import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf";
 import { Message, proto2 } from "@bufbuild/protobuf";
 import type { DisconnectReason, OwnedParticipant, ParticipantInfo, ParticipantPermission } from "./participant_pb.js";
-import type { OwnedTrack, OwnedTrackPublication, PacketTrailerFeature, TrackPublicationInfo, TrackSource } from "./track_pb.js";
+import type { FrameMetadataFeature, OwnedTrack, OwnedTrackPublication, TrackPublicationInfo, TrackSource } from "./track_pb.js";
 import type { RtcStats } from "./stats_pb.js";
 import type { VideoCodec } from "./video_frame_pb.js";
 import type { E2eeOptions, EncryptionState } from "./e2ee_pb.js";
@@ -1844,9 +1844,9 @@ export declare class TrackPublishOptions extends Message<TrackPublishOptions> {
   preconnectBuffer?: boolean;
 
   /**
-   * @generated from field: repeated livekit.proto.PacketTrailerFeature packet_trailer_features = 10;
+   * @generated from field: repeated livekit.proto.FrameMetadataFeature frame_metadata_features = 10;
    */
-  packetTrailerFeatures: PacketTrailerFeature[];
+  frameMetadataFeatures: FrameMetadataFeature[];
 
   /**
    * RTP scalability mode (e.g. "L3T3_KEY"). When set, a single RTP

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

@@ -22,7 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 
 const { proto2 } = require("@bufbuild/protobuf");
 const { DisconnectReason, OwnedParticipant, ParticipantInfo, ParticipantPermission } = require("./participant_pb.js");
-const { OwnedTrack, OwnedTrackPublication, PacketTrailerFeature, TrackPublicationInfo, TrackSource } = require("./track_pb.js");
+const { FrameMetadataFeature, OwnedTrack, OwnedTrackPublication, TrackPublicationInfo, TrackSource } = require("./track_pb.js");
 const { RtcStats } = require("./stats_pb.js");
 const { VideoCodec } = require("./video_frame_pb.js");
 const { E2eeOptions, EncryptionState } = require("./e2ee_pb.js");
@@ -729,7 +729,7 @@ const TrackPublishOptions = /*@__PURE__*/ proto2.makeMessageType(
     { no: 7, name: "source", kind: "enum", T: proto2.getEnumType(TrackSource), opt: true },
     { 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: 10, name: "frame_metadata_features", kind: "enum", T: proto2.getEnumType(FrameMetadataFeature), repeated: true },
     { no: 11, name: "scalability_mode", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
     { no: 12, name: "video_encoder", kind: "enum", T: proto2.getEnumType(VideoEncoderBackend), opt: true },
   ],

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

@@ -136,18 +136,18 @@ export declare enum AudioTrackFeature {
 }
 
 /**
- * @generated from enum livekit.proto.PacketTrailerFeature
+ * @generated from enum livekit.proto.FrameMetadataFeature
  */
-export declare enum PacketTrailerFeature {
+export declare enum FrameMetadataFeature {
   /**
-   * @generated from enum value: PTF_USER_TIMESTAMP = 0;
+   * @generated from enum value: FMF_USER_TIMESTAMP = 0;
    */
-  PTF_USER_TIMESTAMP = 0,
+  FMF_USER_TIMESTAMP = 0,
 
   /**
-   * @generated from enum value: PTF_FRAME_ID = 1;
+   * @generated from enum value: FMF_FRAME_ID = 1;
    */
-  PTF_FRAME_ID = 1,
+  FMF_FRAME_ID = 1,
 }
 
 /**
@@ -431,9 +431,9 @@ export declare class TrackPublicationInfo extends Message<TrackPublicationInfo>
   audioFeatures: AudioTrackFeature[];
 
   /**
-   * @generated from field: repeated livekit.proto.PacketTrailerFeature packet_trailer_features = 13;
+   * @generated from field: repeated livekit.proto.FrameMetadataFeature frame_metadata_features = 13;
    */
-  packetTrailerFeatures: PacketTrailerFeature[];
+  frameMetadataFeatures: FrameMetadataFeature[];
 
   constructor(data?: PartialMessage<TrackPublicationInfo>);
 

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

@@ -80,13 +80,13 @@ const AudioTrackFeature = /*@__PURE__*/ proto2.makeEnum(
 );
 
 /**
- * @generated from enum livekit.proto.PacketTrailerFeature
+ * @generated from enum livekit.proto.FrameMetadataFeature
  */
-const PacketTrailerFeature = /*@__PURE__*/ proto2.makeEnum(
-  "livekit.proto.PacketTrailerFeature",
+const FrameMetadataFeature = /*@__PURE__*/ proto2.makeEnum(
+  "livekit.proto.FrameMetadataFeature",
   [
-    {no: 0, name: "PTF_USER_TIMESTAMP"},
-    {no: 1, name: "PTF_FRAME_ID"},
+    {no: 0, name: "FMF_USER_TIMESTAMP"},
+    {no: 1, name: "FMF_FRAME_ID"},
   ],
 );
 
@@ -195,7 +195,7 @@ const TrackPublicationInfo = /*@__PURE__*/ proto2.makeMessageType(
     { no: 10, name: "remote", kind: "scalar", T: 8 /* ScalarType.BOOL */, req: true },
     { no: 11, name: "encryption_type", kind: "enum", T: proto2.getEnumType(EncryptionType), req: true },
     { no: 12, name: "audio_features", kind: "enum", T: proto2.getEnumType(AudioTrackFeature), repeated: true },
-    { no: 13, name: "packet_trailer_features", kind: "enum", T: proto2.getEnumType(PacketTrailerFeature), repeated: true },
+    { no: 13, name: "frame_metadata_features", kind: "enum", T: proto2.getEnumType(FrameMetadataFeature), repeated: true },
   ],
 );
 
@@ -319,7 +319,7 @@ exports.TrackKind = TrackKind;
 exports.TrackSource = TrackSource;
 exports.StreamState = StreamState;
 exports.AudioTrackFeature = AudioTrackFeature;
-exports.PacketTrailerFeature = PacketTrailerFeature;
+exports.FrameMetadataFeature = FrameMetadataFeature;
 exports.CreateVideoTrackRequest = CreateVideoTrackRequest;
 exports.CreateVideoTrackResponse = CreateVideoTrackResponse;
 exports.CreateAudioTrackRequest = CreateAudioTrackRequest;

livekit-ffi/protocol/room.proto

@@ -312,7 +312,7 @@ message TrackPublishOptions {
   optional TrackSource source = 7;
   optional string stream = 8;
   optional bool preconnect_buffer = 9;
-  repeated PacketTrailerFeature packet_trailer_features = 10;
+  repeated FrameMetadataFeature frame_metadata_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.

livekit-ffi/protocol/track.proto

@@ -91,7 +91,7 @@ message TrackPublicationInfo {
   required bool remote = 10;
   required EncryptionType encryption_type = 11;
   repeated AudioTrackFeature audio_features = 12;
-  repeated PacketTrailerFeature packet_trailer_features = 13;
+  repeated FrameMetadataFeature frame_metadata_features = 13;
 }
 
 message OwnedTrackPublication {
@@ -161,7 +161,7 @@ enum AudioTrackFeature {
   TF_PRECONNECT_BUFFER = 6; // client will buffer audio once available and send it to the server via bytes stream once connected
 }
 
-enum PacketTrailerFeature {
-  PTF_USER_TIMESTAMP = 0;
-  PTF_FRAME_ID = 1;
+enum FrameMetadataFeature {
+  FMF_USER_TIMESTAMP = 0;
+  FMF_FRAME_ID = 1;
 }

livekit-ffi/src/conversion/room.rs

@@ -19,7 +19,7 @@ use livekit::{
         E2eeOptions, EncryptionType,
     },
     options::{
-        AudioEncoding, PacketTrailerFeatures, TrackPublishOptions, VideoEncoderBackend,
+        AudioEncoding, FrameMetadataFeatures, TrackPublishOptions, VideoEncoderBackend,
         VideoEncoding,
     },
     prelude::*,
@@ -31,23 +31,23 @@ use livekit::{
 };
 use std::time::Duration;
 
-fn packet_trailer_features_from_proto(features: Vec<i32>) -> PacketTrailerFeatures {
-    let mut packet_trailer_features = PacketTrailerFeatures::default();
+fn frame_metadata_features_from_proto(features: Vec<i32>) -> FrameMetadataFeatures {
+    let mut frame_metadata_features = FrameMetadataFeatures::default();
 
     for feature in
-        features.into_iter().filter_map(|value| proto::PacketTrailerFeature::try_from(value).ok())
+        features.into_iter().filter_map(|value| proto::FrameMetadataFeature::try_from(value).ok())
     {
         match feature {
-            proto::PacketTrailerFeature::PtfUserTimestamp => {
-                packet_trailer_features.user_timestamp = true;
+            proto::FrameMetadataFeature::FmfUserTimestamp => {
+                frame_metadata_features.user_timestamp = true;
             }
-            proto::PacketTrailerFeature::PtfFrameId => {
-                packet_trailer_features.frame_id = true;
+            proto::FrameMetadataFeature::FmfFrameId => {
+                frame_metadata_features.frame_id = true;
             }
         }
     }
 
-    packet_trailer_features
+    frame_metadata_features
 }
 
 fn video_encoder_from_proto(backend: Option<i32>) -> Option<VideoEncoderBackend> {
@@ -329,8 +329,8 @@ impl From<proto::TrackPublishOptions> for TrackPublishOptions {
             preconnect_buffer: opts
                 .preconnect_buffer
                 .unwrap_or(default_publish_options.preconnect_buffer),
-            packet_trailer_features: packet_trailer_features_from_proto(
-                opts.packet_trailer_features,
+            frame_metadata_features: frame_metadata_features_from_proto(
+                opts.frame_metadata_features,
             ),
             video_encoder: video_encoder_from_proto(opts.video_encoder)
                 .unwrap_or(default_publish_options.video_encoder),
@@ -355,22 +355,22 @@ impl From<proto::AudioEncoding> for AudioEncoding {
 mod tests {
     use livekit::options::{TrackPublishOptions, VideoEncoderBackend};
 
-    use super::{packet_trailer_features_from_proto, video_encoder_from_proto};
+    use super::{frame_metadata_features_from_proto, video_encoder_from_proto};
     use crate::proto;
 
     #[test]
-    fn packet_trailer_features_default_to_empty() {
-        let features = packet_trailer_features_from_proto(Vec::new());
+    fn frame_metadata_features_default_to_empty() {
+        let features = frame_metadata_features_from_proto(Vec::new());
 
         assert!(!features.user_timestamp);
         assert!(!features.frame_id);
     }
 
     #[test]
-    fn packet_trailer_features_enable_known_flags() {
-        let features = packet_trailer_features_from_proto(vec![
-            proto::PacketTrailerFeature::PtfUserTimestamp.into(),
-            proto::PacketTrailerFeature::PtfFrameId.into(),
+    fn frame_metadata_features_enable_known_flags() {
+        let features = frame_metadata_features_from_proto(vec![
+            proto::FrameMetadataFeature::FmfUserTimestamp.into(),
+            proto::FrameMetadataFeature::FmfFrameId.into(),
         ]);
 
         assert!(features.user_timestamp);

livekit-ffi/src/conversion/track.rs

@@ -39,10 +39,10 @@ impl From<&FfiPublication> for proto::TrackPublicationInfo {
                 .into_iter()
                 .map(|i| proto::AudioTrackFeature::from(i).into())
                 .collect(),
-            packet_trailer_features: publication
-                .packet_trailer_features()
+            frame_metadata_features: publication
+                .frame_metadata_features()
                 .into_iter()
-                .map(|i| proto::PacketTrailerFeature::from(i).into())
+                .map(|i| proto::FrameMetadataFeature::from(i).into())
                 .collect(),
         }
     }
@@ -164,14 +164,14 @@ impl From<AudioTrackFeature> for proto::AudioTrackFeature {
     }
 }
 
-impl From<livekit_protocol::PacketTrailerFeature> for proto::PacketTrailerFeature {
+impl From<livekit_protocol::PacketTrailerFeature> for proto::FrameMetadataFeature {
     fn from(value: livekit_protocol::PacketTrailerFeature) -> Self {
         match value {
             livekit_protocol::PacketTrailerFeature::PtfUserTimestamp => {
-                proto::PacketTrailerFeature::PtfUserTimestamp
+                proto::FrameMetadataFeature::FmfUserTimestamp
             }
             livekit_protocol::PacketTrailerFeature::PtfFrameId => {
-                proto::PacketTrailerFeature::PtfFrameId
+                proto::FrameMetadataFeature::FmfFrameId
             }
         }
     }

livekit/src/room/options.rs

@@ -74,12 +74,12 @@ pub struct AudioPreset {
 
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 #[non_exhaustive]
-pub struct PacketTrailerFeatures {
+pub struct FrameMetadataFeatures {
     pub user_timestamp: bool,
     pub frame_id: bool,
 }
 
-impl PacketTrailerFeatures {
+impl FrameMetadataFeatures {
     pub(crate) fn is_empty(&self) -> bool {
         !self.user_timestamp && !self.frame_id
     }
@@ -121,7 +121,7 @@ pub struct TrackPublishOptions {
     pub source: TrackSource,
     pub stream: String,
     pub preconnect_buffer: bool,
-    pub packet_trailer_features: PacketTrailerFeatures,
+    pub frame_metadata_features: FrameMetadataFeatures,
     /// Preferred encoder backend for video tracks published with these options.
     ///
     /// If the requested backend is unavailable, the SDK logs a warning and
@@ -146,7 +146,7 @@ impl Default for TrackPublishOptions {
             source: TrackSource::Unknown,
             stream: "".to_string(),
             preconnect_buffer: false,
-            packet_trailer_features: PacketTrailerFeatures::default(),
+            frame_metadata_features: FrameMetadataFeatures::default(),
             video_encoder: VideoEncoderBackend::Auto,
             scalability_mode: None,
         }