tirtc-devtools-cli 0.0.11 → 0.0.13

package/vendor/app-server/bin/runtime/macos-arm64/include/tirtc/av.h

@@ -11,485 +11,146 @@
 extern "C" {
 #endif
 
-/**
- * @file tirtc/av.h
- * @brief Audio-video facade layer built on top of `tirtc/audio.h`.
- *
- * This header adds media-object owned video producer, preview, view, and
- * remote-consumer contracts to the transport-plus-audio facade.
- *
- * Typical uplink flow:
- * 1. Create a ::TirtcVideoInput.
- * 2. Bind a concrete capture backend with ::tirtc_video_input_set_vin.
- * 3. Optionally configure encoding options and observers.
- * 4. Optionally bind a preview output with ::tirtc_video_input_attach_preview.
- * 5. Start or stop the local producer lifecycle with
- *    ::tirtc_video_input_start and ::tirtc_video_input_stop.
- * 6. Attach or detach the input to individual connections with
- *    ::tirtc_video_input_attach and ::tirtc_video_input_detach.
- * 7. Destroy the input when the object is no longer needed.
- *
- * Typical downlink flow:
- * 1. Create a ::TirtcVideoOutput.
- * 2. Bind a local render backend with ::tirtc_video_output_attach_view.
- * 3. Optionally install an observer.
- * 4. Attach or detach the output to select which remote stream it consumes.
- * 5. Destroy the output when the object is no longer needed.
- *
- * Ownership model:
- * - The caller owns all video input and output handles.
- * - Remote attach relationships and preview/view relationships are non-owning.
- * - Destroying a connection clears the binds that reference that connection but
- *   does not destroy media objects.
- * - Destroying a media object is strong cleanup: it releases attach-state,
- *   preview-state, view-state, observer state, and internal pipeline state.
- */
-
-/** @brief Opaque video uplink handle. */
 typedef struct TirtcVideoInput TirtcVideoInput;
 
-/** @brief Opaque video downlink or preview output handle. */
 typedef struct TirtcVideoOutput TirtcVideoOutput;
 
-/**
- * @brief Video output state reported through ::TirtcVideoOutputObserver.
- */
 typedef enum TirtcVideoOutputState {
-  /** Output currently is not consuming or rendering a remote route. */
+
   TIRTC_VIDEO_OUTPUT_STATE_IDLE = 0,
 
-  /** Output is waiting for frames or sink readiness. */
   TIRTC_VIDEO_OUTPUT_STATE_BUFFERING = 1,
 
-  /** Output is actively rendering frames. */
   TIRTC_VIDEO_OUTPUT_STATE_RENDERING = 2,
 
-  /** Output encountered repeated rendering failures. */
   TIRTC_VIDEO_OUTPUT_STATE_FAILED = 3,
 } TirtcVideoOutputState;
 
-/**
- * @brief Video input encoding options.
- *
- * These options are consumed when the internal video uplink pipeline is
- * created or restarted. Configure them before the next
- * ::tirtc_video_input_start when predictable start behavior matters.
- */
+typedef struct TirtcVideoOutputStartupMetrics {
+  int has_connect_start;
+  int has_connected;
+  int has_first_video_input;
+  int has_first_video_decoded;
+  int has_first_video_rendered;
+  uint64_t connect_start_monotonic_ms;
+  uint64_t connected_monotonic_ms;
+  uint64_t first_video_input_monotonic_ms;
+  uint64_t first_video_decoded_monotonic_ms;
+  uint64_t first_video_rendered_monotonic_ms;
+} TirtcVideoOutputStartupMetrics;
+
+typedef struct TirtcVideoOutputMetricsSnapshot {
+  TirtcVideoOutputStartupMetrics startup;
+  TirtcOutputStutterMetrics stutter;
+  TirtcPendingDurationMetrics pending;
+} TirtcVideoOutputMetricsSnapshot;
+
 typedef struct TirtcVideoInputOptions {
-  /**
-   * @brief Encoded video codec.
-   *
-   * The current implementation defaults to ::TIRTC_MEDIA_CODEC_VIDEO_H264 when
-   * this field is ::TIRTC_MEDIA_CODEC_NONE.
-   */
   TirtcMediaCodec codec;
 
-  /**
-   * @brief Target encoded width in pixels.
-   *
-   * The current implementation defaults to 320 when this field is zero.
-   */
   uint32_t width;
 
-  /**
-   * @brief Target encoded height in pixels.
-   *
-   * The current implementation defaults to 180 when this field is zero.
-   */
   uint32_t height;
 
-  /**
-   * @brief Target frame rate.
-   *
-   * The current implementation defaults to 15 when this field is zero.
-   */
   uint32_t fps;
 
-  /**
-   * @brief Target encoded bitrate in kilobits per second.
-   *
-   * The current implementation passes zero through to the underlying encoder,
-   * allowing the codec backend to choose its default rate-control behavior.
-   */
   uint32_t bitrate_kbps;
 } TirtcVideoInputOptions;
 
 /**
- * @brief Optional observer for a video input object.
+ * Video input observer.
  *
- * The implementation stores a copy of this structure. Installing or replacing
- * an observer does not replay prior state; callbacks describe subsequent input
- * lifecycle transitions, output-size changes, and failures.
- *
- * Callback delivery is not guaranteed to be on a fixed thread. Callers must
- * therefore make callback logic safe for reentrant delivery and perform their
- * own thread handoff when thread affinity is required.
+ * `owned_message` is allocated by facade for this callback dispatch. Consumers must release it
+ * with `tirtc_owned_string_release()` after copying or converting the string they need.
  */
 typedef struct TirtcVideoInputObserver {
-  /**
-   * @brief Called when the input lifecycle state changes.
-   */
   void (*on_state_changed)(TirtcVideoInput* input, TirtcInputState state, void* user_data);
 
-  /**
-   * @brief Called when the effective encoded output size changes.
-   */
   void (*on_output_size_changed)(TirtcVideoInput* input, uint32_t width, uint32_t height,
                                  void* user_data);
 
-  /**
-   * @brief Called when the input encounters an error.
-   */
-  void (*on_error)(TirtcVideoInput* input, TirtcError error, const char* message, void* user_data);
+  void (*on_error)(TirtcVideoInput* input, TirtcError error, TirtcOwnedString* owned_message,
+                   void* user_data);
 } TirtcVideoInputObserver;
 
 /**
- * @brief Optional observer for a video output object.
+ * Video output observer.
  *
- * The implementation stores a copy of this structure. Installing or replacing
- * an observer does not replay the current output state.
- *
- * Callback delivery is not guaranteed to be on a fixed thread. State changes,
- * output-size changes, and failures may be reported synchronously by local API
- * paths or asynchronously from the internal downlink pipeline. Callers must
- * therefore make callback logic safe for reentrant delivery and perform their
- * own thread handoff when thread affinity is required.
+ * `owned_message` is allocated by facade for this callback dispatch. Consumers must release it
+ * with `tirtc_owned_string_release()` after copying or converting the string they need.
  */
 typedef struct TirtcVideoOutputObserver {
-  /**
-   * @brief Called when the output state changes.
-   */
   void (*on_state_changed)(TirtcVideoOutput* output, TirtcVideoOutputState state, void* user_data);
 
-  /**
-   * @brief Called when the effective rendered output size changes.
-   */
   void (*on_output_size_changed)(TirtcVideoOutput* output, uint32_t width, uint32_t height,
                                  void* user_data);
 
-  /**
-   * @brief Called when the output encounters an error.
-   */
-  void (*on_error)(TirtcVideoOutput* output, TirtcError error, const char* message,
+  void (*on_error)(TirtcVideoOutput* output, TirtcError error, TirtcOwnedString* owned_message,
                    void* user_data);
 } TirtcVideoOutputObserver;
 
-/**
- * @brief Enable or disable runtime media-trace logging.
- *
- * This is a process-wide runtime switch, not a per-connection setting.
- *
- * @param enabled Non-zero to enable tracing; zero to disable it.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_set_media_trace_enabled(int enabled);
 
-/**
- * @brief Query whether runtime media tracing is enabled.
- *
- * @param out_enabled Receives `1` when enabled or `0` when disabled.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_get_media_trace_enabled(int* out_enabled);
 
-/**
- * @brief Request the remote sender to start sending a video stream.
- *
- * @param connection Target connection.
- * @param stream_id Remote video stream identifier.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_subscribe_video(TirtcConn* connection, uint8_t stream_id);
 
-/**
- * @brief Request the remote sender to stop sending a video stream.
- *
- * @param connection Target connection.
- * @param stream_id Remote video stream identifier.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_unsubscribe_video(TirtcConn* connection, uint8_t stream_id);
 
-/**
- * @brief Request a key frame from the remote sender for a video stream.
- *
- * This is typically used by a receiver after join, decoder recovery, or severe
- * packet loss when waiting for the next natural key frame would be too slow.
- *
- * @param connection Target connection.
- * @param stream_id Video stream identifier.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_request_key_frame(TirtcConn* connection, uint8_t stream_id);
 
-/**
- * @brief Create a video input object.
- *
- * The runtime must already be initialized.
- *
- * @param out_input Receives the created input handle on success.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_create(TirtcVideoInput** out_input);
 
-/**
- * @brief Bind a concrete video capture backend to an input object.
- *
- * This must be done before the backend is needed by the producer pipeline. The
- * backend pointer is non-owning and should remain valid while the input may
- * still use it.
- *
- * @param input Target video input.
- * @param vin Capture backend to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_set_vin(TirtcVideoInput* input, TirtcVideoVin* vin);
 
-/**
- * @brief Store video encoding options.
- *
- * Best practice is to call this before the next ::tirtc_video_input_start.
- * Updating options after the internal uplink pipeline has already been created
- * does not retroactively rebuild that running pipeline.
- *
- * @param input Target video input.
- * @param options Options to copy into the facade object.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_set_options(TirtcVideoInput* input,
                                          const TirtcVideoInputOptions* options);
 
-/**
- * @brief Install, replace, or clear the video input observer.
- *
- * Passing NULL for ::observer clears the current observer. The implementation
- * stores a copy of the observer structure and does not require it to outlive
- * this call.
- *
- * @param input Target video input.
- * @param observer Observer to install, or NULL to clear.
- * @param user_data Opaque pointer returned to observer callbacks.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_set_observer(TirtcVideoInput* input,
                                           const TirtcVideoInputObserver* observer, void* user_data);
 
-/**
- * @brief Start the local video producer lifecycle.
- *
- * This only manages the producer pipeline. It does not create, remove, or
- * replace any connection binding relationship.
- *
- * Calling start on an already-running input is idempotent.
- *
- * @param input Target video input.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_start(TirtcVideoInput* input);
 
-/**
- * @brief Stop the local video producer lifecycle.
- *
- * This stops capture, processing, and encoding for the input but keeps all
- * existing attach relationships intact. Future ::tirtc_video_input_start calls
- * may resume the same attach set.
- *
- * Calling stop on an already-stopped input is idempotent.
- *
- * @param input Target video input.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_stop(TirtcVideoInput* input);
 
-/**
- * @brief Attach a video input to a connection stream.
- *
- * This bind is non-owning. The same input may be attached to multiple
- * connections at the same time, but only one stream id per connection is kept.
- * Re-attaching the same input to the same connection replaces the prior stream
- * id without requiring an explicit detach first.
- *
- * Attach only manages the binding relationship. It does not implicitly start
- * the producer lifecycle.
- *
- * @param input Video input to bind.
- * @param connection Target connection.
- * @param stream_id Stream identifier that will carry this video route.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_attach(TirtcVideoInput* input, TirtcConn* connection,
                                     uint8_t stream_id);
 
-/**
- * @brief Detach a video input from one connection.
- *
- * This call is idempotent. It only removes the binding for the specified
- * connection and does not implicitly stop the input lifecycle.
- *
- * @param input Video input to unbind.
- * @param connection Connection whose video route should be removed.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_detach(TirtcVideoInput* input, TirtcConn* connection);
 
-/**
- * @brief Bind a preview output to a video input.
- *
- * Use this when local camera frames should also be rendered locally, for
- * example in a self-preview view.
- *
- * The supplied output must not currently be attached to a remote connection
- * stream or owned by another preview input. This preview relationship is
- * non-owning and may be established before or after ::tirtc_video_input_start.
- * Rebinding to a different output automatically releases the previous preview
- * relationship held by this input.
- *
- * @param input Target video input.
- * @param preview_output Video output to use for preview.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_attach_preview(TirtcVideoInput* input,
                                             TirtcVideoOutput* preview_output);
 
-/**
- * @brief Clear the preview output currently associated with a video input.
- *
- * This call is idempotent. Clearing the preview relationship does not destroy
- * the output object and does not affect remote connection binds owned by the
- * input.
- *
- * @param input Target video input.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_input_detach_preview(TirtcVideoInput* input);
 
-/**
- * @brief Destroy a video input object.
- *
- * Destroy is strong cleanup. The runtime stops the input lifecycle, clears
- * every connection bind and preview relationship owned by this input, and then
- * releases the object.
- *
- * @param input Input handle to destroy.
- */
 void tirtc_video_input_destroy(TirtcVideoInput* input);
 
-/**
- * @brief Create a video output object.
- *
- * The runtime must already be initialized.
- *
- * @param out_output Receives the created output handle on success.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_create(TirtcVideoOutput** out_output);
 
-/**
- * @brief Install, replace, or clear the video output observer.
- *
- * Passing NULL for ::observer clears the current observer. The implementation
- * stores a copy of the observer structure and does not require it to outlive
- * this call.
- *
- * @param output Target video output.
- * @param observer Observer to install, or NULL to clear.
- * @param user_data Opaque pointer returned to observer callbacks.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_set_observer(TirtcVideoOutput* output,
                                            const TirtcVideoOutputObserver* observer,
                                            void* user_data);
 
-/**
- * @brief Attach a local render backend to a video output.
- *
- * This establishes the local view/render sink relationship. It is independent
- * from the remote route relationship managed by ::tirtc_video_output_attach.
- * Re-attaching replaces the current local view relationship.
- *
- * @param output Target video output.
- * @param view_sink Render backend to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_attach_view(TirtcVideoOutput* output, TirtcVideoVout* view_sink);
 
-/**
- * @brief Detach the local render backend from a video output.
- *
- * This call is idempotent and does not implicitly detach the current remote
- * route.
- *
- * @param output Target video output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_detach_view(TirtcVideoOutput* output);
 
-/**
- * @brief Attach a video output to a remote connection stream.
- *
- * This bind is non-owning. The same output can consume only one remote route at
- * a time. Re-attaching replaces the prior route without requiring an explicit
- * detach first.
- *
- * Attach only manages the remote consume route. It does not change local view
- * ownership.
- *
- * @param output Video output to bind.
- * @param connection Target connection.
- * @param stream_id Remote video stream identifier to render.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_attach(TirtcVideoOutput* output, TirtcConn* connection,
                                      uint8_t stream_id);
 
-/**
- * @brief Detach the current remote route from a video output.
- *
- * This call is idempotent. Detach only stops consuming the current remote
- * route. It does not clear the current local view relationship.
- *
- * @param output Target video output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_detach(TirtcVideoOutput* output);
 
-/**
- * @brief Destroy a video output object.
- *
- * Destroy is strong cleanup. The runtime detaches the current remote route,
- * clears the local view relationship, clears observer state, and releases
- * internal render pipeline state before the object is destroyed.
- *
- * @param output Output handle to destroy.
- */
 void tirtc_video_output_destroy(TirtcVideoOutput* output);
 
-/**
- * @brief Start encoded raw dump for the media downlink currently owned by this output.
- *
- * The output must already be attached to a connection stream and have an active
- * media downlink. The runtime records received encoded payload into the fixed
- * logging-owned media raw dump directory and derives the dump prefix from the
- * bound route as `<peer_id>-<stream_id>`.
- *
- * @param output Target video output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_start_raw_dump(TirtcVideoOutput* output);
 
-/**
- * @brief Stop encoded raw dump for the media downlink currently owned by this output.
- *
- * This call is idempotent. Stopping seals the current dump directory and keeps
- * collected raw data on disk.
- *
- * @param output Target video output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_video_output_stop_raw_dump(TirtcVideoOutput* output);
 
+TirtcError tirtc_metrics_video_output_get_snapshot(TirtcVideoOutput* output,
+                                                   TirtcVideoOutputMetricsSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif  // TIRTC_FACADE_AV_H_
+#endif

package/vendor/app-server/bin/runtime/macos-arm64/include/tirtc/error.h

@@ -7,25 +7,44 @@ extern "C" {
 
 typedef enum TirtcError {
   TIRTC_ERROR_OK = 0,
-  TIRTC_ERROR_INVALID_ARGUMENT = 1,
-  TIRTC_ERROR_NOT_INITIALIZED = 2,
-  TIRTC_ERROR_INTERNAL = 3,
-  TIRTC_ERROR_NOT_READY = 4,
-  TIRTC_ERROR_UNSUPPORTED_LOOP_POLICY = 5,
-  TIRTC_ERROR_SOURCE_HASH_MISMATCH = 6,
-  TIRTC_ERROR_STOPPED = 7,
-  TIRTC_ERROR_DESTROYED = 8,
-  TIRTC_ERROR_TRANSPORT_INVALID_LICENSE = 9,
-  TIRTC_ERROR_TRANSPORT_TIMEOUT = 10,
-  TIRTC_ERROR_TRANSPORT_BUSY = 11,
-  TIRTC_ERROR_TRANSPORT_CONNECTION_TIMEOUT_CLOSED = 12,
-  TIRTC_ERROR_TRANSPORT_REMOTE_CLOSED = 13,
-  TIRTC_ERROR_TRANSPORT_CONNECTION_OTHER_ERROR = 14,
-  TIRTC_ERROR_TRANSPORT_TOKEN_EXPIRED = 15,
-  TIRTC_ERROR_DUMP_ROOT_UNAVAILABLE = 16,
-  TIRTC_ERROR_DUMP_ALREADY_ACTIVE = 17,
+  TIRTC_ERROR_INVALID_ARGUMENT = 6000,
+  TIRTC_ERROR_NOT_INITIALIZED = 6001,
+  TIRTC_ERROR_INTERNAL = 6002,
+  TIRTC_ERROR_NOT_READY = 6003,
+  TIRTC_ERROR_UNSUPPORTED_LOOP_POLICY = 6004,
+  TIRTC_ERROR_SOURCE_HASH_MISMATCH = 6005,
+  TIRTC_ERROR_ALREADY_STOPPED = 6006,
+  TIRTC_ERROR_STOPPED = TIRTC_ERROR_ALREADY_STOPPED,
+  TIRTC_ERROR_ALREADY_DESTROYED = 6007,
+  TIRTC_ERROR_DESTROYED = TIRTC_ERROR_ALREADY_DESTROYED,
+  TIRTC_ERROR_TRANSPORT_INVALID_LICENSE = 6008,
+  TIRTC_ERROR_TRANSPORT_TIMEOUT = 6009,
+  TIRTC_ERROR_TRANSPORT_BUSY = 6010,
+  TIRTC_ERROR_TRANSPORT_CONNECTION_TIMEOUT_CLOSED = 6011,
+  TIRTC_ERROR_TRANSPORT_REMOTE_CLOSED = 6012,
+  TIRTC_ERROR_TRANSPORT_CONNECTION_OTHER_ERROR = 6013,
+  TIRTC_ERROR_TRANSPORT_TOKEN_EXPIRED = 6014,
+  TIRTC_ERROR_DUMP_ROOT_UNAVAILABLE = 6015,
+  TIRTC_ERROR_DUMP_ALREADY_ACTIVE = 6016,
+  TIRTC_ERROR_TRANSPORT_RESOURCE_EXHAUSTED = 6017,
+  TIRTC_ERROR_TRANSPORT_SERVER_ERROR = 6018,
+  TIRTC_ERROR_TRANSPORT_BACKEND_INTERNAL_ERROR = 6019,
+  TIRTC_ERROR_TRANSPORT_NO_SECRET_KEY = 6020,
+  TIRTC_ERROR_TRANSPORT_UNEXPECTED_RESPONSE = 6021,
+  TIRTC_ERROR_ALREADY_INITIALIZED = 6022,
+  TIRTC_ERROR_INVALID_THREAD = 6023,
+  TIRTC_ERROR_PERMISSION_DENIED = 6024,
+  TIRTC_ERROR_ALREADY_BOUND = 6025,
+  TIRTC_ERROR_IN_USE = 6026,
+  TIRTC_ERROR_NOT_STARTED = 6027,
+  TIRTC_ERROR_NOT_CONNECTED = 6028,
+  TIRTC_ERROR_NOT_BOUND = 6029,
+  TIRTC_ERROR_NOT_CONFIGURED = 6030,
+  TIRTC_ERROR_NOT_OPEN = 6031,
 } TirtcError;
 
+const char* tirtc_error_to_string(TirtcError error);
+
 #ifdef __cplusplus
 }
 #endif

package/vendor/app-server/bin/runtime/macos-arm64/include/tirtc/media_downlink.h

@@ -43,6 +43,45 @@ typedef struct TirtcMediaDownlinkVideoObserver {
                                  void* user_data);
 } TirtcMediaDownlinkVideoObserver;
 
+typedef struct TirtcMediaDownlinkStutterMetricsSnapshot {
+  int session_started;
+  uint64_t session_duration_ms;
+  uint64_t session_stutter_total_ms;
+  uint32_t session_stutter_count;
+  uint64_t session_stutter_peak_ms;
+  double session_stutter_ratio;
+  uint32_t recent_window_duration_ms;
+  uint64_t recent_window_stutter_total_ms;
+  uint32_t recent_window_stutter_count;
+  uint64_t recent_window_stutter_peak_ms;
+  double recent_window_stutter_ratio;
+} TirtcMediaDownlinkStutterMetricsSnapshot;
+
+typedef struct TirtcMediaDownlinkPendingMetricsSnapshot {
+  uint64_t undecoded_pending_duration_ms;
+  uint64_t decoded_pending_duration_ms;
+} TirtcMediaDownlinkPendingMetricsSnapshot;
+
+typedef struct TirtcMediaDownlinkAudioMetricsSnapshot {
+  TirtcMediaDownlinkStutterMetricsSnapshot stutter;
+  TirtcMediaDownlinkPendingMetricsSnapshot pending;
+} TirtcMediaDownlinkAudioMetricsSnapshot;
+
+typedef struct TirtcMediaDownlinkVideoStartupMetricsSnapshot {
+  int has_first_video_input;
+  int has_first_video_decoded;
+  int has_first_video_rendered;
+  uint64_t first_video_input_monotonic_ms;
+  uint64_t first_video_decoded_monotonic_ms;
+  uint64_t first_video_rendered_monotonic_ms;
+} TirtcMediaDownlinkVideoStartupMetricsSnapshot;
+
+typedef struct TirtcMediaDownlinkVideoMetricsSnapshot {
+  TirtcMediaDownlinkVideoStartupMetricsSnapshot startup;
+  TirtcMediaDownlinkStutterMetricsSnapshot stutter;
+  TirtcMediaDownlinkPendingMetricsSnapshot pending;
+} TirtcMediaDownlinkVideoMetricsSnapshot;
+
 TirtcError tirtc_media_downlink_audio_create(TirtcMediaDownlinkAudio** out_downlink);
 void tirtc_media_downlink_audio_retain(TirtcMediaDownlinkAudio* downlink);
 void tirtc_media_downlink_audio_release(TirtcMediaDownlinkAudio* downlink);
@@ -94,6 +133,14 @@ TirtcError tirtc_media_downlink_video_start_raw_dump(TirtcMediaDownlinkVideo* do
                                                      const char* prefix);
 TirtcError tirtc_media_downlink_video_stop_raw_dump(TirtcMediaDownlinkVideo* downlink);
 
+TirtcError tirtc_media_downlink_audio_get_metrics_snapshot(
+    TirtcMediaDownlinkAudio* downlink, TirtcMediaDownlinkAudioMetricsSnapshot* out_snapshot);
+void tirtc_media_downlink_audio_reset_metrics_session(TirtcMediaDownlinkAudio* downlink);
+
+TirtcError tirtc_media_downlink_video_get_metrics_snapshot(
+    TirtcMediaDownlinkVideo* downlink, TirtcMediaDownlinkVideoMetricsSnapshot* out_snapshot);
+void tirtc_media_downlink_video_reset_metrics_session(TirtcMediaDownlinkVideo* downlink);
+
 #ifdef __cplusplus
 }
 #endif