tirtc-devtools-cli 0.0.9 → 0.0.11

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

@@ -1,6 +1,8 @@
 #ifndef TIRTC_FACADE_AUDIO_H_
 #define TIRTC_FACADE_AUDIO_H_
 
+#include <stdint.h>
+
 #include "tirtc/audio_io.h"
 #include "tirtc/audio_processing.h"
 #include "tirtc/trp.h"
@@ -13,28 +15,33 @@ extern "C" {
  * @file tirtc/audio.h
  * @brief Audio facade layer built on top of `tirtc/trp.h`.
  *
- * This header adds local audio capture and remote audio playback objects to the
- * transport-facing facade.
+ * 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 the input and attach it to a connection stream.
- * 5. Detach, stop, and destroy the input during shutdown.
+ * 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 the output to a connected ::TirtcConn.
- * 5. Detach and destroy the output during shutdown.
+ * 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.
- * - Attaching an object to a connection is a non-owning bind.
- * - Destroying a connection detaches bound audio objects but does not destroy
- *   them.
+ * - 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. */
@@ -44,10 +51,7 @@ typedef struct TirtcAudioInput TirtcAudioInput;
 typedef struct TirtcAudioOutput TirtcAudioOutput;
 
 /**
- * @brief Generic input state used by audio and video input observers.
- *
- * The current facade implementation primarily reports RUNNING and STOPPED.
- * Callers should still handle the full enum for forward compatibility.
+ * @brief Generic input lifecycle state used by audio and video inputs.
  */
 typedef enum TirtcInputState {
   /** Input exists but has not started running yet. */
@@ -56,50 +60,42 @@ typedef enum TirtcInputState {
   /** Input is actively capturing or producing data. */
   TIRTC_INPUT_STATE_RUNNING = 1,
 
-  /** Reserved paused state. */
-  TIRTC_INPUT_STATE_PAUSED = 2,
+  /** Input has been explicitly stopped. */
+  TIRTC_INPUT_STATE_STOPPED = 2,
 
-  /** Input is stopped. */
-  TIRTC_INPUT_STATE_STOPPED = 3,
-
-  /** Reserved terminal failure state. */
-  TIRTC_INPUT_STATE_FAILED = 4,
+  /** Input encountered a producer-side failure. */
+  TIRTC_INPUT_STATE_FAILED = 3,
 } TirtcInputState;
 
 /**
  * @brief Audio output state reported through ::TirtcAudioOutputObserver.
  */
 typedef enum TirtcAudioOutputState {
-  /** Output is attached but not currently rendering audio. */
+  /** Output currently is not consuming or rendering a remote route. */
   TIRTC_AUDIO_OUTPUT_STATE_IDLE = 0,
 
-  /** Output is actively playing remote audio. */
-  TIRTC_AUDIO_OUTPUT_STATE_PLAYING = 1,
-
   /** Output is waiting for enough decoded audio to continue playback. */
-  TIRTC_AUDIO_OUTPUT_STATE_BUFFERING = 2,
-
-  /** Reserved paused state. */
-  TIRTC_AUDIO_OUTPUT_STATE_PAUSED = 3,
+  TIRTC_AUDIO_OUTPUT_STATE_BUFFERING = 1,
 
-  /** Reserved completed state. */
-  TIRTC_AUDIO_OUTPUT_STATE_COMPLETED = 4,
+  /** Output is actively playing remote audio. */
+  TIRTC_AUDIO_OUTPUT_STATE_PLAYING = 2,
 
   /** Output encountered repeated playback failures. */
-  TIRTC_AUDIO_OUTPUT_STATE_FAILED = 5,
+  TIRTC_AUDIO_OUTPUT_STATE_FAILED = 3,
 } TirtcAudioOutputState;
 
 /**
  * @brief Audio input processing options.
  *
- * These options are consumed when the internal uplink pipeline is created.
- * Configure them before the first successful start for predictable behavior.
+ * 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 set to
+   * The current implementation defaults to 16 kHz when this field is
    * ::TIRTC_AUDIO_SAMPLE_RATE_NONE.
    */
   TirtcAudioSampleRate sample_rate;
@@ -139,23 +135,23 @@ typedef struct TirtcAudioOutputOptions {
  * @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 local
- * start and stop transitions.
+ * an observer does not replay prior state; callbacks describe subsequent input
+ * lifecycle transitions and failures.
  *
- * Callback delivery is not guaranteed to be on a fixed thread. In the current
- * implementation, input state notifications may be dispatched synchronously by
- * API calls such as ::tirtc_audio_input_start and ::tirtc_audio_input_stop.
- * Callers must therefore make callback logic safe for reentrant delivery.
+ * 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.
  */
 typedef struct TirtcAudioInputObserver {
   /**
-   * @brief Called when the input starts or stops.
-   *
-   * In the current implementation, a start failure is reported as STOPPED with
-   * a non-OK ::error value.
+   * @brief Called when the input lifecycle state changes.
    */
-  void (*on_state_changed)(TirtcAudioInput* input, TirtcInputState state, TirtcError error,
-                           void* user_data);
+  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);
 } TirtcAudioInputObserver;
 
 /**
@@ -173,74 +169,33 @@ typedef struct TirtcAudioInputObserver {
 typedef struct TirtcAudioOutputObserver {
   /**
    * @brief Called when the output state changes.
-   *
-   * A common sequence is IDLE after attach, then BUFFERING, then PLAYING, and
-   * IDLE again after detach.
-   * Repeated downlink failures may eventually promote the output to FAILED.
    */
-  void (*on_state_changed)(TirtcAudioOutput* output, TirtcAudioOutputState state, TirtcError error,
-                           void* user_data);
-} TirtcAudioOutputObserver;
-
-/**
- * @brief Attach an audio input to a connection stream.
- *
- * This bind is non-owning. The same input cannot be attached to more than one
- * connection at a time. The selected ::stream_id must be unique across all
- * audio inputs, video inputs, and video outputs currently attached to the same
- * connection.
- *
- * The input may be attached before or after ::tirtc_audio_input_start. Audio
- * is actually sent only while the input is both attached and running.
- *
- * @param connection Target connection.
- * @param stream_id Stream identifier that will carry this audio route.
- * @param input Audio input to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
-TirtcError tirtc_conn_attach_audio_input(TirtcConn* connection, uint8_t stream_id,
-                                         TirtcAudioInput* input);
+  void (*on_state_changed)(TirtcAudioOutput* output, TirtcAudioOutputState state, void* user_data);
 
-/**
- * @brief Attach a remote audio output to a connection stream.
- *
- * This bind is non-owning. The same output cannot be attached to more than
- * one connection stream at a time. Configure the output with
- * ::tirtc_audio_output_set_aout and any desired options before attaching it.
- *
- * If an observer is already installed, a successful attach typically reports an
- * initial IDLE state before playback begins.
- *
- * @param connection Target connection.
- * @param stream_id Remote audio stream identifier to render.
- * @param output Audio output to bind.
- * @return ::TIRTC_ERROR_OK on success.
- */
-TirtcError tirtc_conn_attach_audio_output(TirtcConn* connection, uint8_t stream_id,
-                                          TirtcAudioOutput* output);
+  /**
+   * @brief Called when the output encounters an error.
+   */
+  void (*on_error)(TirtcAudioOutput* output, TirtcError error, const char* message,
+                   void* user_data);
+} TirtcAudioOutputObserver;
 
 /**
- * @brief Detach an audio input from a connection stream.
- *
- * This call is idempotent. If the stream is attached, the internal uplink path
- * for that bind is stopped and the input returns to an unbound state.
+ * @brief Request the remote sender to start sending an audio stream.
  *
  * @param connection Target connection.
- * @param stream_id Stream identifier to detach.
+ * @param stream_id Remote audio stream identifier.
  * @return ::TIRTC_ERROR_OK on success.
  */
-TirtcError tirtc_conn_detach_audio_input(TirtcConn* connection, uint8_t stream_id);
+TirtcError tirtc_conn_subscribe_audio(TirtcConn* connection, uint8_t stream_id);
 
 /**
- * @brief Detach an audio output from a connection stream.
- *
- * This call is idempotent.
+ * @brief Request the remote sender to stop sending an audio stream.
  *
  * @param connection Target connection.
- * @param stream_id Stream identifier to detach.
+ * @param stream_id Remote audio stream identifier.
  * @return ::TIRTC_ERROR_OK on success.
  */
-TirtcError tirtc_conn_detach_audio_output(TirtcConn* connection, uint8_t stream_id);
+TirtcError tirtc_conn_unsubscribe_audio(TirtcConn* connection, uint8_t stream_id);
 
 /**
  * @brief Create an audio input object.
@@ -252,23 +207,12 @@ TirtcError tirtc_conn_detach_audio_output(TirtcConn* connection, uint8_t stream_
  */
 TirtcError tirtc_audio_input_create(TirtcAudioInput** out_input);
 
-/**
- * @brief Destroy an audio input object.
- *
- * The input must already be detached from any connection. If the input is
- * still bound, the current implementation keeps it alive and ignores the
- * destroy request.
- *
- * @param input Input handle to destroy.
- */
-void tirtc_audio_input_destroy(TirtcAudioInput* input);
-
 /**
  * @brief Bind a concrete audio capture backend to an input object.
  *
- * This must be done while the input is stopped and detached, before the next
- * successful start. The backend pointer is non-owning and must remain valid
- * while the input may still use it.
+ * 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.
@@ -279,9 +223,9 @@ TirtcError tirtc_audio_input_set_ain(TirtcAudioInput* input, TirtcAudioAin* ain)
 /**
  * @brief Store audio input processing options.
  *
- * Best practice is to call this before the first successful start. Updating
- * options after the internal uplink pipeline has already been created does not
- * retroactively rebuild that running pipeline.
+ * 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.
@@ -306,10 +250,12 @@ TirtcError tirtc_audio_input_set_observer(TirtcAudioInput* input,
                                           const TirtcAudioInputObserver* observer, void* user_data);
 
 /**
- * @brief Start local audio capture for an input object.
+ * @brief Start the local audio producer lifecycle.
+ *
+ * This only manages the producer pipeline. It does not create, remove, or
+ * replace any connection binding relationship.
  *
- * A capture backend must already be bound with ::tirtc_audio_input_set_ain.
- * Starting twice without an intervening stop is rejected.
+ * Calling start on an already-running input is idempotent.
  *
  * @param input Target audio input.
  * @return ::TIRTC_ERROR_OK on success.
@@ -317,10 +263,13 @@ TirtcError tirtc_audio_input_set_observer(TirtcAudioInput* input,
 TirtcError tirtc_audio_input_start(TirtcAudioInput* input);
 
 /**
- * @brief Stop local audio capture for an input object.
+ * @brief Stop the local audio producer lifecycle.
  *
- * This is the normal pairing call for ::tirtc_audio_input_start. The current
- * implementation also tolerates stopping an already stopped input.
+ * 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.
@@ -328,25 +277,55 @@ TirtcError tirtc_audio_input_start(TirtcAudioInput* input);
 TirtcError tirtc_audio_input_stop(TirtcAudioInput* input);
 
 /**
- * @brief Create an audio output object.
+ * @brief Attach an audio input to a connection stream.
  *
- * The runtime must already be initialized.
+ * 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.
  *
- * @param out_output Receives the created output handle on success.
+ * 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_output_create(TirtcAudioOutput** out_output);
+TirtcError tirtc_audio_input_attach(TirtcAudioInput* input, TirtcConn* connection,
+                                    uint8_t stream_id);
 
 /**
- * @brief Destroy an audio output object.
+ * @brief Detach an audio input from one connection.
  *
- * The output must already be detached from any connection. If it is still
- * bound, the current implementation keeps it alive and ignores the destroy
- * request.
+ * This call is idempotent. It only removes the binding for the specified
+ * connection and does not implicitly stop the input lifecycle.
  *
- * @param output Output handle to destroy.
+ * @param input Audio input to unbind.
+ * @param connection Connection whose audio route should be removed.
+ * @return ::TIRTC_ERROR_OK on success.
  */
-void tirtc_audio_output_destroy(TirtcAudioOutput* output);
+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.
@@ -389,6 +368,70 @@ 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);
+
 #ifdef __cplusplus
 }
 #endif