tirtc-devtools-cli 0.0.11 → 0.0.13

package/vendor/app-server/bin/runtime/linux-x64/manifest.txt

@@ -1,4 +1,4 @@
 platform=linux-x64
 profile=credential
-staged_at_utc=2026-04-21T05:02:38Z
+staged_at_utc=2026-04-23T07:10:15Z
 source_sdk=/workspace/.build/sdk/linux-x64

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

@@ -11,429 +11,152 @@
 extern "C" {
 #endif
 
-/**
- * @file tirtc/audio.h
- * @brief Audio facade layer built on top of `tirtc/trp.h`.
- *
- * This header adds media-object owned audio producer and consumer contracts to
- * the base transport facade.
- *
- * Typical uplink flow:
- * 1. Create a ::TirtcAudioInput.
- * 2. Bind a concrete capture backend with ::tirtc_audio_input_set_ain.
- * 3. Optionally configure processing options and an observer.
- * 4. Start or stop the local producer lifecycle with
- *    ::tirtc_audio_input_start and ::tirtc_audio_input_stop.
- * 5. Attach or detach the input to individual connections with
- *    ::tirtc_audio_input_attach and ::tirtc_audio_input_detach.
- * 6. Destroy the input when the object is no longer needed.
- *
- * Typical downlink flow:
- * 1. Create a ::TirtcAudioOutput.
- * 2. Bind a concrete playback backend with ::tirtc_audio_output_set_aout.
- * 3. Optionally configure playback options and 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 audio input and output handles.
- * - Input and output attach relationships are non-owning binds.
- * - 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 its own
- *   attach-state, observer state, and internal pipeline state.
- */
-
-/** @brief Opaque audio uplink handle. */
 typedef struct TirtcAudioInput TirtcAudioInput;
 
-/** @brief Opaque audio downlink handle. */
 typedef struct TirtcAudioOutput TirtcAudioOutput;
 
-/**
- * @brief Generic input lifecycle state used by audio and video inputs.
- */
 typedef enum TirtcInputState {
-  /** Input exists but has not started running yet. */
+
   TIRTC_INPUT_STATE_IDLE = 0,
 
-  /** Input is actively capturing or producing data. */
   TIRTC_INPUT_STATE_RUNNING = 1,
 
-  /** Input has been explicitly stopped. */
   TIRTC_INPUT_STATE_STOPPED = 2,
 
-  /** Input encountered a producer-side failure. */
   TIRTC_INPUT_STATE_FAILED = 3,
 } TirtcInputState;
 
-/**
- * @brief Audio output state reported through ::TirtcAudioOutputObserver.
- */
 typedef enum TirtcAudioOutputState {
-  /** Output currently is not consuming or rendering a remote route. */
+
   TIRTC_AUDIO_OUTPUT_STATE_IDLE = 0,
 
-  /** Output is waiting for enough decoded audio to continue playback. */
   TIRTC_AUDIO_OUTPUT_STATE_BUFFERING = 1,
 
-  /** Output is actively playing remote audio. */
   TIRTC_AUDIO_OUTPUT_STATE_PLAYING = 2,
 
-  /** Output encountered repeated playback failures. */
   TIRTC_AUDIO_OUTPUT_STATE_FAILED = 3,
 } TirtcAudioOutputState;
 
-/**
- * @brief Audio input processing options.
- *
- * These options are consumed when the internal uplink pipeline is created or
- * restarted. Configure them before the next ::tirtc_audio_input_start when
- * predictable start behavior matters.
- */
 typedef struct TirtcAudioInputOptions {
-  /**
-   * @brief Capture sample rate.
-   *
-   * The current implementation defaults to 16 kHz when this field is
-   * ::TIRTC_AUDIO_SAMPLE_RATE_NONE.
-   */
   TirtcAudioSampleRate sample_rate;
 
-  /** @brief Acoustic echo cancellation mode. */
   TirtcAudioAecMode aec_mode;
 
-  /** @brief Automatic gain control level. */
   TirtcAudioAgcLevel agc_level;
 
-  /** @brief Acoustic noise suppression level. */
   TirtcAudioAnsLevel ans_level;
 } TirtcAudioInputOptions;
 
-/**
- * @brief Audio output playback options.
- *
- * Configure these options before attaching the output to a connection. The
- * current API does not support updating them while the output remains bound.
- */
 typedef struct TirtcAudioOutputOptions {
-  /**
-   * @brief Playback volume in percent.
-   *
-   * The current implementation treats `0` as the default `100` percent.
-   */
   uint32_t volume_percent;
 
-  /** @brief Additional gain level forwarded to the downlink pipeline. */
   int gain_level;
 
-  /** @brief Additional noise-reduction level forwarded to the downlink pipeline. */
   int noise_reduction_level;
 } TirtcAudioOutputOptions;
 
+typedef struct TirtcOutputStutterMetrics {
+  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;
+} TirtcOutputStutterMetrics;
+
+typedef struct TirtcPendingDurationMetrics {
+  uint64_t undecoded_duration_ms;
+  uint64_t decoded_duration_ms;
+} TirtcPendingDurationMetrics;
+
+typedef struct TirtcAudioOutputMetricsSnapshot {
+  TirtcOutputStutterMetrics stutter;
+  TirtcPendingDurationMetrics pending;
+} TirtcAudioOutputMetricsSnapshot;
+
 /**
- * @brief Optional observer for an audio input object.
- *
- * The implementation stores a copy of this structure. Installing or replacing
- * an observer does not replay prior state; callbacks describe subsequent input
- * lifecycle transitions and failures.
+ * Audio input observer.
  *
- * 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 TirtcAudioInputObserver {
-  /**
-   * @brief Called when the input lifecycle state changes.
-   */
   void (*on_state_changed)(TirtcAudioInput* input, TirtcInputState state, void* user_data);
 
-  /**
-   * @brief Called when the input encounters an error.
-   */
-  void (*on_error)(TirtcAudioInput* input, TirtcError error, const char* message, void* user_data);
+  void (*on_error)(TirtcAudioInput* input, TirtcError error, TirtcOwnedString* owned_message,
+                   void* user_data);
 } TirtcAudioInputObserver;
 
 /**
- * @brief Optional observer for an audio output object.
- *
- * The implementation stores a copy of this structure. Installing or replacing
- * an observer does not replay the current output state.
+ * Audio output observer.
  *
- * Callback delivery is not guaranteed to be on a fixed thread. State changes
- * may be reported synchronously by attach or detach 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 TirtcAudioOutputObserver {
-  /**
-   * @brief Called when the output state changes.
-   */
   void (*on_state_changed)(TirtcAudioOutput* output, TirtcAudioOutputState state, void* user_data);
 
-  /**
-   * @brief Called when the output encounters an error.
-   */
-  void (*on_error)(TirtcAudioOutput* output, TirtcError error, const char* message,
+  void (*on_error)(TirtcAudioOutput* output, TirtcError error, TirtcOwnedString* owned_message,
                    void* user_data);
 } TirtcAudioOutputObserver;
 
-/**
- * @brief Request the remote sender to start sending an audio stream.
- *
- * @param connection Target connection.
- * @param stream_id Remote audio stream identifier.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_subscribe_audio(TirtcConn* connection, uint8_t stream_id);
 
-/**
- * @brief Request the remote sender to stop sending an audio stream.
- *
- * @param connection Target connection.
- * @param stream_id Remote audio stream identifier.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_unsubscribe_audio(TirtcConn* connection, uint8_t stream_id);
 
-/**
- * @brief Create an audio 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_audio_input_create(TirtcAudioInput** out_input);
 
-/**
- * @brief Bind a concrete audio 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 must remain valid while the input may still
- * use it.
- *
- * @param input Target audio input.
- * @param ain Capture backend to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_set_ain(TirtcAudioInput* input, TirtcAudioAin* ain);
 
-/**
- * @brief Store audio input processing options.
- *
- * Best practice is to call this before the next ::tirtc_audio_input_start.
- * Updating options after the internal uplink pipeline has already been created
- * does not retroactively rebuild that running pipeline.
- *
- * @param input Target audio input.
- * @param options Options to copy into the facade object.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_set_options(TirtcAudioInput* input,
                                          const TirtcAudioInputOptions* options);
 
-/**
- * @brief Install, replace, or clear the audio 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 audio 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_audio_input_set_observer(TirtcAudioInput* input,
                                           const TirtcAudioInputObserver* observer, void* user_data);
 
-/**
- * @brief Start the local audio 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 audio input.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_start(TirtcAudioInput* input);
 
-/**
- * @brief Stop the local audio producer lifecycle.
- *
- * This stops capture, processing, and encoding for the input but keeps all
- * existing attach relationships intact. Future ::tirtc_audio_input_start calls
- * may resume the same attach set.
- *
- * Calling stop on an already-stopped input is idempotent.
- *
- * @param input Target audio input.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_stop(TirtcAudioInput* input);
 
-/**
- * @brief Attach an audio 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 Audio input to bind.
- * @param connection Target connection.
- * @param stream_id Stream identifier that will carry this audio route.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_attach(TirtcAudioInput* input, TirtcConn* connection,
                                     uint8_t stream_id);
 
-/**
- * @brief Detach an audio 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 Audio input to unbind.
- * @param connection Connection whose audio route should be removed.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_input_detach(TirtcAudioInput* input, TirtcConn* connection);
 
-/**
- * @brief Destroy an audio input object.
- *
- * Destroy is strong cleanup. The runtime stops the input lifecycle and clears
- * every attach relationship owned by this input before releasing the object.
- *
- * @param input Input handle to destroy.
- */
 void tirtc_audio_input_destroy(TirtcAudioInput* input);
 
-/**
- * @brief Create an audio 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_audio_output_create(TirtcAudioOutput** out_output);
 
-/**
- * @brief Bind a concrete audio playback backend to an output object.
- *
- * The backend pointer is non-owning and should remain valid until the output
- * has been detached and destroyed. Passing NULL is not supported by this API.
- *
- * @param output Target audio output.
- * @param aout Playback backend to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_set_aout(TirtcAudioOutput* output, TirtcAudioAout* aout);
 
-/**
- * @brief Store audio output playback options.
- *
- * This call is intended for the pre-attach configuration phase. The current
- * implementation rejects option changes while the output is attached.
- *
- * @param output Target audio output.
- * @param options Options to copy into the facade object.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_set_options(TirtcAudioOutput* output,
                                           const TirtcAudioOutputOptions* options);
 
-/**
- * @brief Install, replace, or clear the audio 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 audio 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_audio_output_set_observer(TirtcAudioOutput* output,
                                            const TirtcAudioOutputObserver* observer,
                                            void* user_data);
 
-/**
- * @brief Attach an audio 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 connection
- * lifecycle or local sink ownership.
- *
- * @param output Audio output to bind.
- * @param connection Target connection.
- * @param stream_id Remote audio stream identifier to render.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_attach(TirtcAudioOutput* output, TirtcConn* connection,
                                      uint8_t stream_id);
 
-/**
- * @brief Detach the current remote route from an audio output.
- *
- * This call is idempotent. Detach only stops consuming the current remote
- * route. It does not destroy the output object or its local sink.
- *
- * @param output Target audio output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_detach(TirtcAudioOutput* output);
 
-/**
- * @brief Destroy an audio output object.
- *
- * Destroy is strong cleanup. The runtime detaches the current route, clears
- * observer state, and releases internal playback pipeline state before the
- * object is destroyed.
- *
- * @param output Output handle to destroy.
- */
 void tirtc_audio_output_destroy(TirtcAudioOutput* 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 audio output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_start_raw_dump(TirtcAudioOutput* 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 audio output.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_audio_output_stop_raw_dump(TirtcAudioOutput* output);
 
+TirtcError tirtc_metrics_audio_output_get_snapshot(TirtcAudioOutput* output,
+                                                   TirtcAudioOutputMetricsSnapshot* out_snapshot);
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif  // TIRTC_FACADE_AUDIO_H_
+#endif