tirtc-devtools-cli 0.0.12 → 0.0.14

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

@@ -5,6 +5,7 @@
 
 #include "tirtc/audio.h"
 #include "tirtc/media_codec.h"
+#include "tirtc/video_codec.h"
 #include "tirtc/video_io.h"
 
 #ifdef __cplusplus
@@ -13,6 +14,8 @@ extern "C" {
 
 typedef struct TirtcVideoInput TirtcVideoInput;
 
+typedef struct TirtcVideoEncodedInput TirtcVideoEncodedInput;
+
 typedef struct TirtcVideoOutput TirtcVideoOutput;
 
 typedef enum TirtcVideoOutputState {
@@ -26,6 +29,29 @@ typedef enum TirtcVideoOutputState {
   TIRTC_VIDEO_OUTPUT_STATE_FAILED = 3,
 } TirtcVideoOutputState;
 
+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 TirtcVideoOutputOptions {
+  TirtcVideoDecoderPreference decoder_preference;
+} TirtcVideoOutputOptions;
+
 typedef struct TirtcVideoInputOptions {
   TirtcMediaCodec codec;
 
@@ -36,6 +62,8 @@ typedef struct TirtcVideoInputOptions {
   uint32_t fps;
 
   uint32_t bitrate_kbps;
+
+  TirtcVideoEncoderPreference encoder_preference;
 } TirtcVideoInputOptions;
 
 /**
@@ -54,6 +82,23 @@ typedef struct TirtcVideoInputObserver {
                    void* user_data);
 } TirtcVideoInputObserver;
 
+typedef struct TirtcVideoEncodedInputOptions {
+  TirtcMediaCodec codec;
+  TirtcVideoBitstreamFormat bitstream_format;
+} TirtcVideoEncodedInputOptions;
+
+typedef struct TirtcVideoEncodedInputObserver {
+  void (*on_state_changed)(TirtcVideoEncodedInput* input, TirtcInputState state, void* user_data);
+
+  void (*on_output_size_changed)(TirtcVideoEncodedInput* input, uint32_t width, uint32_t height,
+                                 void* user_data);
+
+  void (*on_error)(TirtcVideoEncodedInput* input, TirtcError error, TirtcOwnedString* owned_message,
+                   void* user_data);
+
+  void (*on_key_frame_requested)(TirtcVideoEncodedInput* input, void* user_data);
+} TirtcVideoEncodedInputObserver;
+
 /**
  * Video output observer.
  *
@@ -106,8 +151,34 @@ TirtcError tirtc_video_input_detach_preview(TirtcVideoInput* input);
 
 void tirtc_video_input_destroy(TirtcVideoInput* input);
 
+TirtcError tirtc_video_encoded_input_create(TirtcVideoEncodedInput** out_input);
+
+TirtcError tirtc_video_encoded_input_set_options(TirtcVideoEncodedInput* input,
+                                                 const TirtcVideoEncodedInputOptions* options);
+
+TirtcError tirtc_video_encoded_input_set_observer(TirtcVideoEncodedInput* input,
+                                                  const TirtcVideoEncodedInputObserver* observer,
+                                                  void* user_data);
+
+TirtcError tirtc_video_encoded_input_start(TirtcVideoEncodedInput* input);
+
+TirtcError tirtc_video_encoded_input_stop(TirtcVideoEncodedInput* input);
+
+TirtcError tirtc_video_encoded_input_attach(TirtcVideoEncodedInput* input, TirtcConn* connection,
+                                            uint8_t stream_id);
+
+TirtcError tirtc_video_encoded_input_detach(TirtcVideoEncodedInput* input, TirtcConn* connection);
+
+TirtcError tirtc_video_encoded_input_submit_frame(TirtcVideoEncodedInput* input,
+                                                  const TirtcVideoEncodedFrame* frame);
+
+void tirtc_video_encoded_input_destroy(TirtcVideoEncodedInput* input);
+
 TirtcError tirtc_video_output_create(TirtcVideoOutput** out_output);
 
+TirtcError tirtc_video_output_set_options(TirtcVideoOutput* output,
+                                          const TirtcVideoOutputOptions* options);
+
 TirtcError tirtc_video_output_set_observer(TirtcVideoOutput* output,
                                            const TirtcVideoOutputObserver* observer,
                                            void* user_data);
@@ -127,6 +198,9 @@ TirtcError tirtc_video_output_start_raw_dump(TirtcVideoOutput* output);
 
 TirtcError tirtc_video_output_stop_raw_dump(TirtcVideoOutput* output);
 
+TirtcError tirtc_metrics_video_output_get_snapshot(TirtcVideoOutput* output,
+                                                   TirtcVideoOutputMetricsSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -0,0 +1,63 @@
+#ifndef TIRTC_FOUNDATION_ERROR_H_
+#define TIRTC_FOUNDATION_ERROR_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum TirtcError {
+  TIRTC_ERROR_OK = 0,
+  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,
+  TIRTC_ERROR_APP_ID_REQUIRED = 6032,
+  TIRTC_ERROR_VIDEO_ENCODER_BACKEND_UNAVAILABLE = 6033,
+  TIRTC_ERROR_VIDEO_ENCODER_CODEC_UNSUPPORTED = 6034,
+  TIRTC_ERROR_VIDEO_ENCODER_INITIALIZATION_FAILED = 6035,
+  TIRTC_ERROR_VIDEO_DECODER_CODEC_UNSUPPORTED = 6036,
+  TIRTC_ERROR_VIDEO_DECODER_BACKEND_UNAVAILABLE = 6037,
+  TIRTC_ERROR_VIDEO_DECODER_INITIALIZATION_FAILED = 6038,
+  TIRTC_ERROR_VIDEO_DECODER_CONFIGURATION_FAILED = 6039,
+  TIRTC_ERROR_VIDEO_DECODER_RUNTIME_FAILED = 6040,
+  TIRTC_ERROR_VIDEO_OUTPUT_TARGET_UNAVAILABLE = 6041,
+  TIRTC_ERROR_VIDEO_OUTPUT_RENDER_FAILED = 6042,
+} TirtcError;
+
+const char* tirtc_error_to_string(TirtcError error);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // TIRTC_FOUNDATION_ERROR_H_

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

@@ -5,7 +5,9 @@
 
 #include "tirtc/audio_frame.h"
 #include "tirtc/audio_io.h"
+#include "tirtc/audio_processing.h"
 #include "tirtc/error.h"
+#include "tirtc/video_codec.h"
 #include "tirtc/video_frame.h"
 #include "tirtc/video_io.h"
 
@@ -20,17 +22,19 @@ typedef enum TirtcMediaDownlinkState {
   TIRTC_MEDIA_DOWNLINK_STATE_IDLE = 0,
   TIRTC_MEDIA_DOWNLINK_STATE_RENDERING = 1,
   TIRTC_MEDIA_DOWNLINK_STATE_BUFFERING = 2,
-  TIRTC_MEDIA_DOWNLINK_STATE_PAUSED = 3,
-  TIRTC_MEDIA_DOWNLINK_STATE_COMPLETED = 4,
-  TIRTC_MEDIA_DOWNLINK_STATE_FAILED = 5,
+  TIRTC_MEDIA_DOWNLINK_STATE_FAILED = 3,
 } TirtcMediaDownlinkState;
 
 typedef struct TirtcMediaDownlinkAudioOptions {
   uint32_t volume_percent;
-  int gain_level;
-  int noise_reduction_level;
+  TirtcAudioAgcLevel agc_level;
+  TirtcAudioAnsLevel ans_level;
 } TirtcMediaDownlinkAudioOptions;
 
+typedef struct TirtcMediaDownlinkVideoOptions {
+  TirtcVideoDecoderPreference decoder_preference;
+} TirtcMediaDownlinkVideoOptions;
+
 typedef struct TirtcMediaDownlinkAudioObserver {
   void (*on_state_changed)(TirtcMediaDownlinkAudio* downlink, TirtcMediaDownlinkState state,
                            TirtcError error, void* user_data);
@@ -43,6 +47,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);
@@ -72,6 +115,8 @@ void tirtc_media_downlink_video_release(TirtcMediaDownlinkVideo* downlink);
 void tirtc_media_downlink_video_destroy(TirtcMediaDownlinkVideo* downlink);
 TirtcError tirtc_media_downlink_video_set_vout(TirtcMediaDownlinkVideo* downlink,
                                                TirtcVideoVout* vout);
+TirtcError tirtc_media_downlink_video_set_options(TirtcMediaDownlinkVideo* downlink,
+                                                  const TirtcMediaDownlinkVideoOptions* options);
 TirtcError tirtc_media_downlink_video_set_observer(TirtcMediaDownlinkVideo* downlink,
                                                    const TirtcMediaDownlinkVideoObserver* observer,
                                                    void* user_data);
@@ -94,6 +139,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

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/media_uplink.h

@@ -8,6 +8,7 @@
 #include "tirtc/audio_processing.h"
 #include "tirtc/error.h"
 #include "tirtc/media_codec.h"
+#include "tirtc/video_codec.h"
 #include "tirtc/video_frame.h"
 #include "tirtc/video_io.h"
 
@@ -40,6 +41,7 @@ typedef struct TirtcMediaUplinkVideoOptions {
   uint32_t height;
   uint32_t fps;
   uint32_t bitrate_kbps;
+  TirtcVideoEncoderPreference encoder_preference;
 } TirtcMediaUplinkVideoOptions;
 
 typedef struct TirtcMediaUplinkAudioSink {
@@ -108,6 +110,8 @@ TirtcError tirtc_media_uplink_video_get_output_size(TirtcMediaUplinkVideo* uplin
 TirtcError tirtc_media_uplink_video_request_key_frame(TirtcMediaUplinkVideo* uplink);
 TirtcError tirtc_media_uplink_video_start(TirtcMediaUplinkVideo* uplink);
 TirtcError tirtc_media_uplink_video_stop(TirtcMediaUplinkVideo* uplink);
+TirtcError tirtc_media_uplink_video_submit_encoded_frame(TirtcMediaUplinkVideo* uplink,
+                                                         const TirtcVideoEncodedFrame* frame);
 
 #ifdef __cplusplus
 }

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/transport.h

@@ -82,14 +82,42 @@ typedef enum TirtcTransportAudioSample {
 #define TIRTC_TRANSPORT_FRAME_FLAG_KEY_FRAME 0x01
 
 /**
- * @brief Opaque descriptor payload passed to transport backend.
- */
-typedef struct TirtcTransportDescriptor {
-  /** Pointer to descriptor bytes. */
-  const void* data;
-  /** Descriptor byte length. */
-  size_t length;
-} TirtcTransportDescriptor;
+ * @brief Network type hint passed to the transport backend.
+ */
+typedef enum TirtcTransportNetworkType {
+  /** Use the backend default network behavior. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_DEFAULT = 0,
+  /** Wi-Fi network path. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_WIFI = 1,
+  /** 4G cellular network path. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_4G = 2,
+} TirtcTransportNetworkType;
+
+/**
+ * @brief Transport runtime options shared by service and outgoing connection paths.
+ */
+typedef struct TirtcTransportRuntimeOptions {
+  /** Required service endpoint URL. */
+  const char* endpoint;
+  /** Optional network type hint. Zero-initialized options use the backend default. */
+  TirtcTransportNetworkType network_type;
+  /** Non-zero enables backend wakeup support. */
+  uint8_t wakeup_enabled;
+  /** Non-zero enables restricted-network mode. */
+  uint8_t restricted_network;
+} TirtcTransportRuntimeOptions;
+
+/**
+ * @brief Connect-parameter cache policy for outgoing connections.
+ */
+typedef enum TirtcTransportConnectCacheMode {
+  /** Use backend default cache policy. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_DEFAULT = 0,
+  /** Disable backend connection-parameter cache. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_DISABLED = 1,
+  /** Enable backend connection-parameter cache. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_ENABLED = 2,
+} TirtcTransportConnectCacheMode;
 
 typedef struct TirtcTransportConnService TirtcTransportConnService;
 typedef struct TirtcTransportConn TirtcTransportConn;
@@ -98,8 +126,11 @@ typedef struct TirtcTransportConn TirtcTransportConn;
  * @brief Options for starting service runtime.
  */
 typedef struct TirtcTransportConnServiceOptions {
-  /** Required transport descriptor for service runtime. */
-  const TirtcTransportDescriptor* descriptor;
+  /** Required service license. */
+  const char* license;
+
+  /** Required runtime options. */
+  TirtcTransportRuntimeOptions runtime_options;
 
   /**
    * @brief Maximum number of concurrently accepted connections for this
@@ -117,10 +148,16 @@ typedef struct TirtcTransportConnServiceOptions {
  * @brief Options for creating outgoing connection.
  */
 typedef struct TirtcTransportConnOptions {
-  /** Target peer identifier. */
-  const char* peer_id;
-  /** Required transport descriptor for client connection. */
-  const TirtcTransportDescriptor* descriptor;
+  /** Target remote identifier. */
+  const char* remote_id;
+  /** Required one-shot bootstrap token. */
+  const char* token;
+  /** Required runtime options. */
+  TirtcTransportRuntimeOptions runtime_options;
+  /** Backend connection-parameter cache policy. */
+  TirtcTransportConnectCacheMode connect_cache_mode;
+  /** Non-zero asks backend to try cached connect parameters before the explicit token. */
+  uint8_t prefer_cached_connect_params;
 } TirtcTransportConnOptions;
 
 /**
@@ -271,7 +308,7 @@ TirtcError tirtc_transport_enable_debug(uint8_t enabled);
 void tirtc_transport_uninit(void);
 
 /**
- * @brief Start service runtime with descriptor and service observer.
+ * @brief Start service runtime with typed options and service observer.
  */
 TirtcError tirtc_transport_conn_service_start(const TirtcTransportConnServiceOptions* options,
                                               const TirtcTransportConnServiceCallbacks* callbacks,

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/trp.h

@@ -14,14 +14,16 @@
 extern "C" {
 #endif
 
-typedef struct TirtcOptions {
+typedef struct TirtcInitOptions {
+  const char* app_id;
+
   const char* endpoint;
 
   const char* log_root_dir;
 
-  int enable_console_log;
+  int console_log_enabled;
 
-} TirtcOptions;
+} TirtcInitOptions;
 
 typedef enum TirtcMediaSendPolicy {
 
@@ -39,7 +41,7 @@ typedef struct TirtcConnServiceStartOptions {
 } TirtcConnServiceStartOptions;
 
 typedef struct TirtcConnConnectOptions {
-  const char* peer_id;
+  const char* remote_id;
 
   const char* token;
 } TirtcConnConnectOptions;
@@ -81,6 +83,13 @@ typedef struct TirtcConnCommand {
   size_t length;
 } TirtcConnCommand;
 
+typedef struct TirtcConnMetricsSnapshot {
+  int has_connect_start;
+  int has_connected;
+  uint64_t connect_start_monotonic_ms;
+  uint64_t connected_monotonic_ms;
+} TirtcConnMetricsSnapshot;
+
 /** Heap-owned byte payload allocated by facade callback dispatch. */
 typedef struct TirtcOwnedBytes {
   /** Payload buffer allocated by facade, or `NULL` for zero-length payloads. */
@@ -127,7 +136,7 @@ typedef struct TirtcConnCallbacks {
                             TirtcOwnedBytes* owned_payload, void* user_data);
 } TirtcConnCallbacks;
 
-TirtcError tirtc_init(const TirtcOptions* options);
+TirtcError tirtc_init(const TirtcInitOptions* options);
 
 void tirtc_uninit(void);
 
@@ -168,6 +177,9 @@ void tirtc_owned_string_release(TirtcOwnedString* owned);
 
 TirtcError tirtc_conn_send_command(TirtcConn* connection, const TirtcConnCommand* command);
 
+TirtcError tirtc_metrics_conn_get_snapshot(TirtcConn* connection,
+                                           TirtcConnMetricsSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/video_codec.h

@@ -14,6 +14,30 @@ extern "C" {
 typedef struct TirtcVideoEncoder TirtcVideoEncoder;
 typedef struct TirtcVideoDecoder TirtcVideoDecoder;
 
+typedef enum TirtcVideoEncoderPreference {
+  TIRTC_VIDEO_ENCODER_PREFERENCE_AUTO = 0,
+  TIRTC_VIDEO_ENCODER_PREFERENCE_SOFTWARE = 1,
+  TIRTC_VIDEO_ENCODER_PREFERENCE_HARDWARE = 2,
+} TirtcVideoEncoderPreference;
+
+typedef enum TirtcVideoDecoderPreference {
+  TIRTC_VIDEO_DECODER_PREFERENCE_AUTO = 0,
+  TIRTC_VIDEO_DECODER_PREFERENCE_SOFTWARE = 1,
+  TIRTC_VIDEO_DECODER_PREFERENCE_HARDWARE = 2,
+} TirtcVideoDecoderPreference;
+
+typedef enum TirtcVideoEncoderBackendKind {
+  TIRTC_VIDEO_ENCODER_BACKEND_KIND_SOFTWARE = 1,
+  TIRTC_VIDEO_ENCODER_BACKEND_KIND_HARDWARE = 2,
+} TirtcVideoEncoderBackendKind;
+
+typedef struct TirtcVideoEncoderRuntimeInfo {
+  TirtcVideoEncoderBackendKind actual_backend;
+  TirtcVideoEncoderPreference requested_encoder_preference;
+  int did_fallback;
+  TirtcVideoPixelFormat resolved_input_pixel_format;
+} TirtcVideoEncoderRuntimeInfo;
+
 typedef struct TirtcVideoEncoderConfig {
   TirtcMediaCodec codec;
   TirtcVideoBitstreamFormat bitstream_format;
@@ -22,6 +46,14 @@ typedef struct TirtcVideoEncoderConfig {
   uint32_t fps;
   uint32_t bitrate_kbps;
   TirtcVideoPixelFormat input_pixel_format;
+  /**
+   * Selects the encoder backend family before the encoder is created.
+   *
+   * Zero-initialized configs use `AUTO`, which currently preserves the software encoder path.
+   * `HARDWARE` is strict: if the requested hardware backend is unavailable or cannot initialize,
+   * create fails with a video encoder error instead of falling back to software.
+   */
+  TirtcVideoEncoderPreference encoder_preference;
 } TirtcVideoEncoderConfig;
 
 typedef struct TirtcVideoDecoderConfig {
@@ -35,6 +67,15 @@ TirtcError tirtc_video_encoder_create(const TirtcVideoEncoderConfig* config,
 void tirtc_video_encoder_destroy(TirtcVideoEncoder* encoder);
 TirtcError tirtc_video_encoder_reset(TirtcVideoEncoder* encoder);
 TirtcError tirtc_video_encoder_request_key_frame(TirtcVideoEncoder* encoder);
+/**
+ * Returns the backend decision made during encoder creation.
+ *
+ * `out_info` is caller-owned storage. The function writes a value copy and does not allocate or
+ * transfer ownership. It may be called after successful create and before destroy, including while
+ * another thread is using the encoder through the normal encode/control API.
+ */
+TirtcError tirtc_video_encoder_get_runtime_info(const TirtcVideoEncoder* encoder,
+                                                TirtcVideoEncoderRuntimeInfo* out_info);
 TirtcError tirtc_video_encoder_encode(TirtcVideoEncoder* encoder,
                                       const TirtcVideoPixelFrame* in_frame, void* out_buffer,
                                       size_t out_buffer_capacity,

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/video_io.h

@@ -21,6 +21,11 @@ typedef struct TirtcVideoIoConfig {
   TirtcVideoPixelFormat pixel_format;
 } TirtcVideoIoConfig;
 
+typedef struct TirtcVideoHeadlessVoutOptions {
+  const char* first_frame_json_path;
+  const char* first_frame_raw_path;
+} TirtcVideoHeadlessVoutOptions;
+
 typedef void (*TirtcVideoVinOnFrameFn)(TirtcVideoVin* vin, const TirtcVideoPixelFrame* frame,
                                        void* user_data);
 
@@ -33,6 +38,8 @@ TirtcError tirtc_video_vin_close(TirtcVideoVin* vin);
 void tirtc_video_vin_destroy(TirtcVideoVin* vin);
 
 TirtcError tirtc_video_vout_open(TirtcVideoVout* vout, const TirtcVideoIoConfig* config);
+TirtcError tirtc_video_vout_create_headless_capture(const TirtcVideoHeadlessVoutOptions* options,
+                                                    TirtcVideoVout** out_vout);
 TirtcError tirtc_video_vout_get_actual_config(TirtcVideoVout* vout, TirtcVideoIoConfig* out_config);
 TirtcError tirtc_video_vout_render_frame(TirtcVideoVout* vout, const TirtcVideoPixelFrame* frame);
 TirtcError tirtc_video_vout_flush(TirtcVideoVout* vout);

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/include/tirtc/video_io_android.h

@@ -18,6 +18,8 @@ typedef enum TirtcVideoAndroidVoutRenderer {
 typedef struct TirtcVideoAndroidSurfaceTextureVoutOptions {
   struct ANativeWindow* native_window;
   TirtcVideoAndroidVoutRenderer renderer;
+  const char* h264_decoder_name;
+  const char* h265_decoder_name;
 } TirtcVideoAndroidSurfaceTextureVoutOptions;
 
 TirtcError tirtc_video_android_create_surface_texture_vout(TirtcVideoVout** out_vout);

package/vendor/{app-server/bin/runtime → runtime}/macos-arm64/manifest.txt

@@ -1,36 +1,32 @@
 platform=macos-arm64
-profile=credential
-staged_at_utc=2026-04-21T13:44:23Z
+profile=full
+staged_at_utc=2026-04-30T07:05:30Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/macos-arm64
 
-bfea7c19fdc3f25680946a575db9b3e60e8cd2b3fe1ddde8c7c93b57a6a3902c  include/tirtc/audio.h
+e962631f85675937fd973797720466fd75717f74335c8102c664814d59179113  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
-84f1bbe67efa15ab3b2d995d661025aac43e2fe547a14a012a24d89cfe3cb859  include/tirtc/audio_io.h
+fb8ea35263167c33487bd3aa503c26ed2dfbf97877f7bda92c10065cd5c97c13  include/tirtc/audio_io.h
 c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/audio_io_android.h
 878bb18220ac62304ec95807f31e83e050c8dac14811f873454f9b045028694a  include/tirtc/audio_io_apple.h
 0569eb1d043ee7fa8d45ca43143eca1a22e4c4bf1507ca7e045e010a3ecbc288  include/tirtc/audio_io_harmony.h
 51cbc911fe9f9834046f0e0a1a7cdd814a8e194a615894a8b4d11f9e5f095610  include/tirtc/audio_io_windows.h
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
-339508d784d3114dd3cbf14ad90dd6345d633ec647ca0f9bb8942eb1b83533b2  include/tirtc/av.h
-4198c95c48ae579d1c782635b00fa5c9009d0c56ba466e6e3873e8298faae029  include/tirtc/credential.h
-d29f24fc665d01ab45f993c06c09fccca2bd5c844250ddbdc3c9d8d0c8548803  include/tirtc/error.h
+94f378da8bc728a1b9a44fbe74a0367b06ad2401ae55fa5bb6bee63b447ce511  include/tirtc/av.h
+70d0e950f78309e12c927b37a6f7184fe3724edc5391176a697f7d7c7f49ab5a  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
 7cf8b372a3d48d4de4a65a04c7f102281a7b42cebb9ec247853d3c53afb63b6a  include/tirtc/http.h
 70bbf93b84d9d1a85f376d9986de570c1f658319e1e5ab6d621f7a4d41033f5c  include/tirtc/logging.h
 7e2f7f81afe37e22f5414d9db32438edd948ff775230c3a0a17ff9ac1a0b560e  include/tirtc/media_codec.h
-3fa1d5fe3c3c2644d134e13678cbf5562440a2c5d4a652dc24bf9f124731509a  include/tirtc/media_downlink.h
-21ef53b4d120aab600168c4082e7622c791ab4929fb20b3fb31f73ed01eee02a  include/tirtc/media_fixture_av_sync.h
-037d9a581cef71afe9233456b1f4ef866c3739150532f3c30a67d361e8af9eef  include/tirtc/media_fixture_source.h
-a4f8ab44c1a20ad37f250363a403a9d4d007e61ddb2426c7966dbc05f6a04b4f  include/tirtc/media_live_source.h
-1b3be6954e547f91a047866438bff1820c8406afaf91cef68ddee29a6ac70234  include/tirtc/media_uplink.h
-26b831c7b8bd69b7699017427f3243cd22393c90c9518a820f5eb87eb3792483  include/tirtc/transport.h
-185183a736774cdf737504c091e4648d7f476c16abf18ee8c8ac0da2eb9a5c79  include/tirtc/trp.h
-dff5b0a0ac4a40ad17c93e1e56b3c416371c81ab365e287ea8cd6ce37ccbed3b  include/tirtc/video_codec.h
+0d1c3a8d1537a839cb6050fe5b35079087f094673dd9eb5b4d9acdcc9a2dd5fc  include/tirtc/media_downlink.h
+e64191a39004165cdcd11b2ca824af34d4bfe02f7ec3c3101fa9291f56488c30  include/tirtc/media_uplink.h
+489f6c9caa3e4094566b660ef0a002a39c66c1956ef0a1bdb6eacca3798c849a  include/tirtc/transport.h
+bb9c1bf46f2ab51a9f7adb211276c8563b09e7968031c0c6abeebc0eddd66acb  include/tirtc/trp.h
+118593dd6e57d1a982c4b861e7d26f066a4eb4b5f2e152dbf7b7205d87b467f2  include/tirtc/video_codec.h
 e51379666c199588cc33279ccf52248035d1cae3d1d468b1615ebf29f0b39c9c  include/tirtc/video_frame.h
-d920afad955b9f206b02b19ca152315190fa84ab6f24e895a5b24c3ab9ffd701  include/tirtc/video_io.h
-9294d144dbc56415ddbc06c68a26b4a662b51a3808f49ded81a37776ad243293  include/tirtc/video_io_android.h
+2a02645d82c58d433c7306a9f0bcd31d0f3e560b63822f7e80919761b81a6284  include/tirtc/video_io.h
+9930dce5e8e2b12a1ab28ee91f3fb46f6cf3487e515ea2b4ec0e00009bd5f070  include/tirtc/video_io_android.h
 005114b9213ec826e18d11eca4b9d65cce2ca0e7c781f03d85292365d9d5dfdd  include/tirtc/video_io_apple.h
 cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/video_io_harmony.h
 65b5d24fe3a6bc2a299a2220148a153ba4eb0955a49c1c3baabf1fdfed8aabdd  include/tirtc/video_io_windows.h
@@ -39,14 +35,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8db86d6714264047e8fd4086ddd7315722d675749719e6175f89eb5a636b48a1  lib/libTiRTC.a
 b39daee6a3d39bf0ca20c45084601133c4198de8dca848dcff6dd9c70ae99016  lib/libcrypto.a
 c052857ef315e3d61db9c862cad10709a3a6b2487dc41799cbe4d74a805de875  lib/libcrypto.dylib
-a3cbd2372889b96346fb211846de94edb5ec7f5d15af02a150c3c24efb999187  lib/libmatrix_runtime_audio.a
-012cf0bd9aaa49fe42a43de19edddb01b654df741a0f5782568c52f0d3c8dfbb  lib/libmatrix_runtime_credential.a
-75554a31b1c99be83d22f168de91584f19dc9ee69a13fe8b62d5dfdab6baf016  lib/libmatrix_runtime_facade.a
-a5235f14059d7807968353b32cefcddbebec2cc5808912898078a6c6cf9bdd50  lib/libmatrix_runtime_foundation_http.a
-dcb14497951c566352cf4b14a7b870872069824d6a2a067bfe5b421fc6500216  lib/libmatrix_runtime_foundation_logging.a
-1b1b7980f498b603132bf11dce7d24f60bdc8a11d6a0ac916c4454dde4ebbc3f  lib/libmatrix_runtime_media.a
-6d6bf7d07cc35df568582218193487235452ef47dd736f36d7de3c95ac1bde18  lib/libmatrix_runtime_transport.a
-0abee197077a906f6af3f5e05c72bcfe5b874478b65ad454b3013ab9df398af1  lib/libmatrix_runtime_video.a
+d8467c6dd8da2b9ecf55b4969703ecc2fee1bd696828db0dace96b8250ba59a2  lib/libmatrix_runtime_audio.a
+395dc1ad1f45de3922a924f1a2a6b292e05a66c8f91781f3daf608467ff85e83  lib/libmatrix_runtime_facade.a
+d7b60286d449e8e32ea2ba4b44d7c013d68df1892a731dd554a3715677faed48  lib/libmatrix_runtime_foundation_http.a
+1f17fcd4f27d12b04c94f3d2df89aeae4f691ade8a3c4da635c17859fb8e3ea4  lib/libmatrix_runtime_foundation_logging.a
+ff0accd2e53381e9f8a4174df0a5409ddf48052c8646a4af63c22517bf4e7a8c  lib/libmatrix_runtime_media.a
+31016e1e69ca8991f4d3862e6998f21c349e6578c8f47a8a9bc8b186f73d2cb3  lib/libmatrix_runtime_transport.a
+87aaeb7b243200f70312c21b715c235259782eb02a7c760d4c5f79fa43e0b3f8  lib/libmatrix_runtime_video.a
 c11c65d373a127028350c41fa58cd2d1223f2b5d70a84e13b115d90daaba25ca  lib/libssl.a
 ef1c1104bbdd2528ed7b958fb7252bd6249875f92300b0c9577d6c4bd6c0d88a  lib/libssl.dylib
 e14e846e43d64e240fa0e5745bf4e702b79d0f2442e7f768beb990610735c71b  lib/libtgrtc.dylib