examples/user_timestamped_video

stephen-derosa · stephen-derosa · commit 314ed944da94 · 2026-03-30T13:47:58.000-06:00
diff --git a/examples/user_timestamped_video/README.md b/examples/user_timestamped_video/README.md
@@ -1,16 +1,44 @@
 # UserTimestampedVideo
 
-This example is split into two executables:
+This example is split into two executables and can demonstrate all four
+producer/consumer combinations:
 
 - `UserTimestampedVideoProducer` publishes a synthetic camera track and stamps
   each frame with `VideoCaptureOptions::metadata.user_timestamp_us`.
 - `UserTimestampedVideoConsumer` subscribes to remote camera frames with
-  `Room::setOnVideoFrameEventCallback` and logs the received user timestamp
-  metadata.
+  either the rich or legacy callback path.
 
 Run them in the same room with different participant identities:
 
 ```sh
 LIVEKIT_URL=ws://localhost:7880 LIVEKIT_TOKEN=<producer-token> ./UserTimestampedVideoProducer
 LIVEKIT_URL=ws://localhost:7880 LIVEKIT_TOKEN=<consumer-token> ./UserTimestampedVideoConsumer
 ```
+
+Flags:
+
+- Producer default: sends user timestamps
+- Producer `--without-user-timestamp`: does not send user timestamps
+- Consumer default: reads user timestamps through `setOnVideoFrameEventCallback`
+- Consumer `--ignore-user-timestamp`: ignores metadata through the legacy
+  `setOnVideoFrameCallback`
+
+Matrix:
+
+```sh
+# 1. Producer sends, consumer reads
+./UserTimestampedVideoProducer
+./UserTimestampedVideoConsumer
+
+# 2. Producer sends, consumer ignores
+./UserTimestampedVideoProducer
+./UserTimestampedVideoConsumer --ignore-user-timestamp
+
+# 3. Producer does not send, consumer ignores
+./UserTimestampedVideoProducer --without-user-timestamp
+./UserTimestampedVideoConsumer --ignore-user-timestamp
+
+# 4. Producer does not send, consumer reads
+./UserTimestampedVideoProducer --without-user-timestamp
+./UserTimestampedVideoConsumer
+```
diff --git a/examples/user_timestamped_video/consumer.cpp b/examples/user_timestamped_video/consumer.cpp
@@ -30,6 +30,7 @@
 #include <string>
 #include <thread>
 #include <unordered_set>
+#include <vector>
 
 #include "livekit/livekit.h"
 
@@ -57,14 +58,49 @@ formatUserTimestamp(const std::optional<VideoFrameMetadata> &metadata) {
 
 void printUsage(const char *program) {
   std::cerr << "Usage:\n"
-            << "  " << program << " <ws-url> <token>\n"
+            << "  " << program << " <ws-url> <token> [--ignore-user-timestamp]\n"
             << "or:\n"
-            << "  LIVEKIT_URL=... LIVEKIT_TOKEN=... " << program << "\n";
+            << "  LIVEKIT_URL=... LIVEKIT_TOKEN=... " << program
+            << " [--ignore-user-timestamp]\n";
+}
+
+bool parseArgs(int argc, char *argv[], std::string &url, std::string &token,
+               bool &read_user_timestamp) {
+  read_user_timestamp = true;
+  std::vector<std::string> positional;
+
+  for (int i = 1; i < argc; ++i) {
+    const std::string arg = argv[i];
+    if (arg == "-h" || arg == "--help") {
+      return false;
+    }
+    if (arg == "--ignore-user-timestamp") {
+      read_user_timestamp = false;
+      continue;
+    }
+    if (arg == "--read-user-timestamp") {
+      read_user_timestamp = true;
+      continue;
+    }
+
+    positional.push_back(arg);
+  }
+
+  url = getenvOrEmpty("LIVEKIT_URL");
+  token = getenvOrEmpty("LIVEKIT_TOKEN");
+
+  if (positional.size() >= 2) {
+    url = positional[0];
+    token = positional[1];
+  }
+
+  return !(url.empty() || token.empty());
 }
 
 class UserTimestampedVideoConsumerDelegate : public RoomDelegate {
 public:
-  explicit UserTimestampedVideoConsumerDelegate(Room &room) : room_(room) {}
+  UserTimestampedVideoConsumerDelegate(Room &room, bool read_user_timestamp)
+      : room_(room), read_user_timestamp_(read_user_timestamp) {}
 
   void registerExistingParticipants() {
     for (const auto &participant : room_.remoteParticipants()) {
@@ -114,39 +150,50 @@ class UserTimestampedVideoConsumerDelegate : public RoomDelegate {
     VideoStream::Options stream_options;
     stream_options.format = VideoBufferType::RGBA;
 
-    room_.setOnVideoFrameEventCallback(
-        identity, TrackSource::SOURCE_CAMERA,
-        [identity](const VideoFrameEvent &event) {
-          std::cout << "[consumer] from=" << identity
-                    << " size=" << event.frame.width() << "x"
-                    << event.frame.height()
-                    << " capture_ts_us=" << event.timestamp_us
-                    << " user_ts_us=" << formatUserTimestamp(event.metadata)
-                    << " rotation=" << static_cast<int>(event.rotation) << "\n";
-        },
-        stream_options);
+    if (read_user_timestamp_) {
+      room_.setOnVideoFrameEventCallback(
+          identity, TrackSource::SOURCE_CAMERA,
+          [identity](const VideoFrameEvent &event) {
+            std::cout << "[consumer] from=" << identity
+                      << " size=" << event.frame.width() << "x"
+                      << event.frame.height()
+                      << " capture_ts_us=" << event.timestamp_us
+                      << " user_ts_us=" << formatUserTimestamp(event.metadata)
+                      << " rotation=" << static_cast<int>(event.rotation)
+                      << "\n";
+          },
+          stream_options);
+    } else {
+      room_.setOnVideoFrameCallback(
+          identity, TrackSource::SOURCE_CAMERA,
+          [identity](const VideoFrame &frame, std::int64_t timestamp_us) {
+            std::cout << "[consumer] from=" << identity
+                      << " size=" << frame.width() << "x" << frame.height()
+                      << " capture_ts_us=" << timestamp_us
+                      << " user_ts_us=ignored\n";
+          },
+          stream_options);
+    }
 
     std::cout << "[consumer] listening for camera frames from " << identity
-              << "\n";
+              << " with user timestamp "
+              << (read_user_timestamp_ ? "enabled" : "ignored") << "\n";
   }
 
   Room &room_;
+  bool read_user_timestamp_;
   std::mutex mutex_;
   std::unordered_set<std::string> registered_identities_;
 };
 
 } // namespace
 
 int main(int argc, char *argv[]) {
-  std::string url = getenvOrEmpty("LIVEKIT_URL");
-  std::string token = getenvOrEmpty("LIVEKIT_TOKEN");
-
-  if (argc >= 3) {
-    url = argv[1];
-    token = argv[2];
-  }
+  std::string url;
+  std::string token;
+  bool read_user_timestamp = true;
 
-  if (url.empty() || token.empty()) {
+  if (!parseArgs(argc, argv, url, token, read_user_timestamp)) {
     printUsage(argv[0]);
     return 1;
   }
@@ -165,7 +212,7 @@ int main(int argc, char *argv[]) {
     options.auto_subscribe = true;
     options.dynacast = false;
 
-    UserTimestampedVideoConsumerDelegate delegate(room);
+    UserTimestampedVideoConsumerDelegate delegate(room, read_user_timestamp);
     room.setDelegate(&delegate);
 
     std::cout << "[consumer] connecting to " << url << "\n";
@@ -175,7 +222,8 @@ int main(int argc, char *argv[]) {
     } else {
       std::cout << "[consumer] connected as "
                 << room.localParticipant()->identity() << " to room '"
-                << room.room_info().name << "'\n";
+                << room.room_info().name << "' with user timestamp "
+                << (read_user_timestamp ? "enabled" : "ignored") << "\n";
 
       delegate.registerExistingParticipants();
 
diff --git a/examples/user_timestamped_video/producer.cpp b/examples/user_timestamped_video/producer.cpp
@@ -30,6 +30,7 @@
 #include <memory>
 #include <string>
 #include <thread>
+#include <vector>
 
 #include "livekit/livekit.h"
 
@@ -74,23 +75,54 @@ void fillFrame(VideoFrame &frame, std::uint32_t frame_index) {
 
 void printUsage(const char *program) {
   std::cerr << "Usage:\n"
-            << "  " << program << " <ws-url> <token>\n"
+            << "  " << program
+            << " <ws-url> <token> [--without-user-timestamp]\n"
             << "or:\n"
-            << "  LIVEKIT_URL=... LIVEKIT_TOKEN=... " << program << "\n";
+            << "  LIVEKIT_URL=... LIVEKIT_TOKEN=... " << program
+            << " [--without-user-timestamp]\n";
 }
 
-} // namespace
+bool parseArgs(int argc, char *argv[], std::string &url, std::string &token,
+               bool &send_user_timestamp) {
+  send_user_timestamp = true;
+  std::vector<std::string> positional;
 
-int main(int argc, char *argv[]) {
-  std::string url = getenvOrEmpty("LIVEKIT_URL");
-  std::string token = getenvOrEmpty("LIVEKIT_TOKEN");
+  for (int i = 1; i < argc; ++i) {
+    const std::string arg = argv[i];
+    if (arg == "-h" || arg == "--help") {
+      return false;
+    }
+    if (arg == "--without-user-timestamp") {
+      send_user_timestamp = false;
+      continue;
+    }
+    if (arg == "--with-user-timestamp") {
+      send_user_timestamp = true;
+      continue;
+    }
+
+    positional.push_back(arg);
+  }
+
+  url = getenvOrEmpty("LIVEKIT_URL");
+  token = getenvOrEmpty("LIVEKIT_TOKEN");
 
-  if (argc >= 3) {
-    url = argv[1];
-    token = argv[2];
+  if (positional.size() >= 2) {
+    url = positional[0];
+    token = positional[1];
   }
 
-  if (url.empty() || token.empty()) {
+  return !(url.empty() || token.empty());
+}
+
+} // namespace
+
+int main(int argc, char *argv[]) {
+  std::string url;
+  std::string token;
+  bool send_user_timestamp = true;
+
+  if (!parseArgs(argc, argv, url, token, send_user_timestamp)) {
     printUsage(argv[0]);
     return 1;
   }
@@ -125,11 +157,12 @@ int main(int argc, char *argv[]) {
       try {
         TrackPublishOptions publish_options;
         publish_options.source = TrackSource::SOURCE_CAMERA;
-        publish_options.packet_trailer_features.user_timestamp = true;
+        publish_options.packet_trailer_features.user_timestamp =
+            send_user_timestamp;
 
         room.localParticipant()->publishTrack(track, publish_options);
-        std::cout << "[producer] published camera track with "
-                     "packet_trailer_features.user_timestamp enabled\n";
+        std::cout << "[producer] published camera track with user timestamp "
+                  << (send_user_timestamp ? "enabled" : "disabled") << "\n";
 
         VideoFrame frame = VideoFrame::create(kFrameWidth, kFrameHeight,
                                               VideoBufferType::BGRA);
@@ -146,16 +179,22 @@ int main(int argc, char *argv[]) {
                   std::chrono::steady_clock::now() - capture_start)
                   .count());
           capture_options.rotation = VideoRotation::VIDEO_ROTATION_0;
-          capture_options.metadata = VideoFrameMetadata{};
-          capture_options.metadata->user_timestamp_us = nowEpochUs();
+          if (send_user_timestamp) {
+            capture_options.metadata = VideoFrameMetadata{};
+            capture_options.metadata->user_timestamp_us = nowEpochUs();
+          }
 
           source->captureFrame(frame, capture_options);
 
           if (frame_index % 5 == 0) {
             std::cout << "[producer] frame=" << frame_index
                       << " capture_ts_us=" << capture_options.timestamp_us
                       << " user_ts_us="
-                      << *capture_options.metadata->user_timestamp_us << "\n";
+                      << (send_user_timestamp
+                              ? std::to_string(
+                                    *capture_options.metadata->user_timestamp_us)
+                              : std::string("disabled"))
+                      << "\n";
           }
 
           ++frame_index;
diff --git a/src/tests/integration/test_subscription_thread_dispatcher.cpp b/src/tests/integration/test_subscription_thread_dispatcher.cpp
