move the subscriber user timestamp handler to internal to clean up API

Author: chenosaurus

examples/local_video/src/subscriber.rs

@@ -292,11 +292,9 @@ async fn handle_track_subscribed(
     }
     let simulcast2 = simulcast.clone();
     std::thread::spawn(move || {
+        // The user timestamp handler is automatically wired from the RtcVideoTrack,
+        // so frame.user_timestamp_us is populated without manual setup.
         let mut sink = NativeVideoStream::new(video_track.rtc_track());
-        // Wire up user timestamp extraction so frame.user_timestamp_us is populated
-        if let Some(handler) = video_track.user_timestamp_handler() {
-            sink.set_user_timestamp_handler(handler);
-        }
         let mut frames: u64 = 0;
         let mut last_log = Instant::now();
         let mut logged_first = false;

libwebrtc/src/native/media_stream.rs

@@ -43,7 +43,7 @@ impl MediaStream {
         self.sys_handle
             .get_video_tracks()
             .into_iter()
-            .map(|t| video_track::RtcVideoTrack { handle: RtcVideoTrack { sys_handle: t.ptr } })
+            .map(|t| video_track::RtcVideoTrack { handle: RtcVideoTrack::new(t.ptr) })
             .collect()
     }
 }

libwebrtc/src/native/media_stream_track.rs

@@ -44,7 +44,7 @@ pub fn new_media_stream_track(
         })
     } else if sys_handle.kind() == MEDIA_TYPE_VIDEO {
         MediaStreamTrack::Video(video_track::RtcVideoTrack {
-            handle: RtcVideoTrack { sys_handle: unsafe { media_to_video(sys_handle) } },
+            handle: RtcVideoTrack::new(unsafe { media_to_video(sys_handle) }),
         })
     } else {
         panic!("unknown track kind")

libwebrtc/src/native/peer_connection_factory.rs

@@ -82,11 +82,10 @@ impl PeerConnectionFactory {
 
     pub fn create_video_track(&self, label: &str, source: NativeVideoSource) -> RtcVideoTrack {
         RtcVideoTrack {
-            handle: imp_vt::RtcVideoTrack {
-                sys_handle: self
-                    .sys_handle
+            handle: imp_vt::RtcVideoTrack::new(
+                self.sys_handle
                     .create_video_track(label.to_string(), source.handle.sys_handle()),
-            },
+            ),
         }
     }
 

libwebrtc/src/native/video_stream.rs

@@ -40,9 +40,13 @@ pub struct NativeVideoStream {
 impl NativeVideoStream {
     pub fn new(video_track: RtcVideoTrack) -> Self {
         let (frame_tx, frame_rx) = mpsc::unbounded_channel();
+
+        // Auto-wire the user timestamp handler from the track if one is set.
+        let handler = video_track.handle.user_timestamp_handler();
+
         let observer = Arc::new(VideoTrackObserver {
             frame_tx,
-            user_timestamp_handler: parking_lot::Mutex::new(None),
+            user_timestamp_handler: parking_lot::Mutex::new(handler),
         });
         let native_sink = sys_vt::ffi::new_native_video_sink(Box::new(
             sys_vt::VideoSinkWrapper::new(observer.clone()),
@@ -57,8 +61,13 @@ impl NativeVideoStream {
     /// Set the user timestamp handler for this stream.
     ///
     /// When set, each frame produced by this stream will have its
-    /// `user_timestamp_us` field populated from the handler's last
-    /// received timestamp (if available).
+    /// `user_timestamp_us` field populated from the handler's receive
+    /// map (looked up by RTP timestamp).
+    ///
+    /// Note: If the handler was already set on the `RtcVideoTrack` before
+    /// creating this stream, it is automatically wired up. This method is
+    /// only needed if you want to override or set the handler after
+    /// construction.
     pub fn set_user_timestamp_handler(&self, handler: UserTimestampHandler) {
         *self.observer.user_timestamp_handler.lock() = Some(handler);
     }

libwebrtc/src/native/video_track.rs

@@ -12,22 +12,48 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use std::sync::Arc;
+
 use cxx::SharedPtr;
+use parking_lot::Mutex;
 use sys_vt::ffi::video_to_media;
 use webrtc_sys::video_track as sys_vt;
 
 use super::media_stream_track::impl_media_stream_track;
+use super::user_timestamp::UserTimestampHandler;
 use crate::media_stream_track::RtcTrackState;
 
 #[derive(Clone)]
 pub struct RtcVideoTrack {
     pub(crate) sys_handle: SharedPtr<sys_vt::ffi::VideoTrack>,
+    user_timestamp_handler: Arc<Mutex<Option<UserTimestampHandler>>>,
 }
 
 impl RtcVideoTrack {
     impl_media_stream_track!(video_to_media);
 
+    pub(crate) fn new(sys_handle: SharedPtr<sys_vt::ffi::VideoTrack>) -> Self {
+        Self {
+            sys_handle,
+            user_timestamp_handler: Arc::new(Mutex::new(None)),
+        }
+    }
+
     pub fn sys_handle(&self) -> SharedPtr<sys_vt::ffi::MediaStreamTrack> {
         video_to_media(self.sys_handle.clone())
     }
+
+    /// Set the user timestamp handler for this track.
+    ///
+    /// When set, any `NativeVideoStream` created from this track will
+    /// automatically use this handler to populate `user_timestamp_us`
+    /// on each decoded frame.
+    pub fn set_user_timestamp_handler(&self, handler: UserTimestampHandler) {
+        self.user_timestamp_handler.lock().replace(handler);
+    }
+
+    /// Get the user timestamp handler, if one has been set.
+    pub fn user_timestamp_handler(&self) -> Option<UserTimestampHandler> {
+        self.user_timestamp_handler.lock().clone()
+    }
 }

libwebrtc/src/video_stream.rs

@@ -50,8 +50,13 @@ pub mod native {
         /// Set the user timestamp handler for this stream.
         ///
         /// When set, each frame produced by this stream will have its
-        /// `user_timestamp_us` field populated from the handler's last
-        /// received timestamp (if available).
+        /// `user_timestamp_us` field populated by looking up the user
+        /// timestamp for each frame's RTP timestamp.
+        ///
+        /// Note: If the handler was already set on the `RtcVideoTrack`
+        /// before creating this stream, it is automatically wired up.
+        /// This method is only needed to override or set the handler
+        /// after construction.
         pub fn set_user_timestamp_handler(&self, handler: UserTimestampHandler) {
             self.handle.set_user_timestamp_handler(handler);
         }

libwebrtc/src/video_track.rs

@@ -19,13 +19,32 @@ use crate::{
     media_stream_track::{media_stream_track, RtcTrackState},
 };
 
+#[cfg(not(target_arch = "wasm32"))]
+use crate::native::user_timestamp::UserTimestampHandler;
+
 #[derive(Clone)]
 pub struct RtcVideoTrack {
     pub(crate) handle: imp_vt::RtcVideoTrack,
 }
 
 impl RtcVideoTrack {
     media_stream_track!();
+
+    /// Set the user timestamp handler for this track.
+    ///
+    /// When set, any `NativeVideoStream` created from this track will
+    /// automatically use this handler to populate `user_timestamp_us`
+    /// on each decoded frame.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn set_user_timestamp_handler(&self, handler: UserTimestampHandler) {
+        self.handle.set_user_timestamp_handler(handler);
+    }
+
+    /// Get the user timestamp handler, if one has been set.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn user_timestamp_handler(&self) -> Option<UserTimestampHandler> {
+        self.handle.user_timestamp_handler()
+    }
 }
 
 impl Debug for RtcVideoTrack {

livekit/src/room/track/remote_video_track.rs

@@ -16,15 +16,13 @@ use std::{fmt::Debug, sync::Arc};
 
 use libwebrtc::{native::user_timestamp::UserTimestampHandler, prelude::*, stats::RtcStats};
 use livekit_protocol as proto;
-use parking_lot::Mutex;
 
 use super::{remote_track, TrackInner};
 use crate::prelude::*;
 
 #[derive(Clone)]
 pub struct RemoteVideoTrack {
     inner: Arc<TrackInner>,
-    user_timestamp_handler: Arc<Mutex<Option<UserTimestampHandler>>>,
 }
 
 impl Debug for RemoteVideoTrack {
@@ -46,7 +44,6 @@ impl RemoteVideoTrack {
                 TrackKind::Video,
                 MediaStreamTrack::Video(rtc_track),
             )),
-            user_timestamp_handler: Arc::new(Mutex::new(None)),
         }
     }
 
@@ -101,24 +98,23 @@ impl RemoteVideoTrack {
     /// remote video track, if the user timestamp transformer is enabled and
     /// a timestamp has been received.
     pub fn last_user_timestamp(&self) -> Option<i64> {
-        self.user_timestamp_handler
-            .lock()
-            .as_ref()
+        self.rtc_track()
+            .user_timestamp_handler()
             .and_then(|h| h.last_user_timestamp())
     }
 
     /// Returns a clone of the user timestamp handler, if one has been set.
-    ///
-    /// This can be passed to a `NativeVideoStream` via
-    /// `set_user_timestamp_handler` so that each frame's
-    /// `user_timestamp_us` field is populated automatically.
     pub fn user_timestamp_handler(&self) -> Option<UserTimestampHandler> {
-        self.user_timestamp_handler.lock().clone()
+        self.rtc_track().user_timestamp_handler()
     }
 
     /// Internal: set the handler that extracts user timestamps for this track.
+    ///
+    /// The handler is stored on the underlying `RtcVideoTrack`, so any
+    /// `NativeVideoStream` created from this track will automatically
+    /// pick it up — no manual wiring required.
     pub(crate) fn set_user_timestamp_handler(&self, handler: UserTimestampHandler) {
-        self.user_timestamp_handler.lock().replace(handler);
+        self.rtc_track().set_user_timestamp_handler(handler);
     }
 
     pub async fn get_stats(&self) -> RoomResult<Vec<RtcStats>> {