sonora-ffi 0.2.0

#ifndef WAP_AUDIO_PROCESSING_H
#define WAP_AUDIO_PROCESSING_H

/* Warning: this file is auto-generated by cbindgen. Do not edit. */

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

/**
 * Downmix method for multi-channel capture.
 */
enum WapDownmixMethod
#if defined(__cplusplus) || __STDC_VERSION__ >= 202311L
  : int32_t
#endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L
 {
  AverageChannels = 0,
  UseFirstChannel = 1,
};
#ifndef __cplusplus
#if __STDC_VERSION__ >= 202311L
typedef enum WapDownmixMethod WapDownmixMethod;
#else
typedef int32_t WapDownmixMethod;
#endif // __STDC_VERSION__ >= 202311L
#endif // __cplusplus

/**
 * Noise suppression aggressiveness level.
 */
enum WapNoiseSuppressionLevel
#if defined(__cplusplus) || __STDC_VERSION__ >= 202311L
  : int32_t
#endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L
 {
  Low = 0,
  Moderate = 1,
  High = 2,
  VeryHigh = 3,
};
#ifndef __cplusplus
#if __STDC_VERSION__ >= 202311L
typedef enum WapNoiseSuppressionLevel WapNoiseSuppressionLevel;
#else
typedef int32_t WapNoiseSuppressionLevel;
#endif // __STDC_VERSION__ >= 202311L
#endif // __cplusplus

/**
 * Error codes returned by C API functions.
 *
 * `0` = success, negative = error.
 */
enum WapError
#if defined(__cplusplus) || __STDC_VERSION__ >= 202311L
  : int32_t
#endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L
 {
  /**
   * Operation succeeded.
   */
  None = 0,
  /**
   * Null pointer passed to a function that requires non-null.
   */
  NullPointer = -1,
  /**
   * Internal error (panic caught at FFI boundary).
   */
  Internal = -2,
  /**
   * Bad sample rate.
   */
  BadSampleRate = -3,
  /**
   * Bad number of channels.
   */
  BadNumberChannels = -4,
  /**
   * A stream parameter was out of range and was clamped.
   */
  BadStreamParameter = -5,
  /**
   * Invalid data length.
   */
  BadDataLength = -6,
};
#ifndef __cplusplus
#if __STDC_VERSION__ >= 202311L
typedef enum WapError WapError;
#else
typedef int32_t WapError;
#endif // __STDC_VERSION__ >= 202311L
#endif // __cplusplus

/**
 * Opaque handle to the audio processing engine.
 *
 * Created via `wap_create()` or `wap_create_with_config()`.
 * Destroyed via `wap_destroy()`.
 *
 * **NOT thread-safe**: all calls on the same handle must be serialized.
 */
typedef struct WapAudioProcessing WapAudioProcessing;

/**
 * Flat configuration struct for the audio processing pipeline.
 *
 * Obtain a default-initialized instance via `wap_config_default()`.
 */
typedef struct WapConfig {
  int32_t pipeline_maximum_internal_processing_rate;
  bool pipeline_multi_channel_render;
  bool pipeline_multi_channel_capture;
  WapDownmixMethod pipeline_capture_downmix_method;
  bool pre_amplifier_enabled;
  float pre_amplifier_fixed_gain_factor;
  bool capture_level_adjustment_enabled;
  float capture_level_adjustment_pre_gain_factor;
  float capture_level_adjustment_post_gain_factor;
  bool analog_mic_gain_emulation_enabled;
  int32_t analog_mic_gain_emulation_initial_level;
  bool high_pass_filter_enabled;
  bool high_pass_filter_apply_in_full_band;
  bool echo_canceller_enabled;
  bool echo_canceller_enforce_high_pass_filtering;
  bool noise_suppression_enabled;
  WapNoiseSuppressionLevel noise_suppression_level;
  bool noise_suppression_analyze_linear_aec_output_when_available;
  bool gain_controller2_enabled;
  float gain_controller2_fixed_digital_gain_db;
  bool gain_controller2_adaptive_digital_enabled;
  float gain_controller2_adaptive_digital_headroom_db;
  float gain_controller2_adaptive_digital_max_gain_db;
  float gain_controller2_adaptive_digital_initial_gain_db;
  float gain_controller2_adaptive_digital_max_gain_change_db_per_second;
  float gain_controller2_adaptive_digital_max_output_noise_level_dbfs;
  bool gain_controller2_input_volume_controller_enabled;
} WapConfig;

/**
 * Audio stream configuration (sample rate and channel count).
 */
typedef struct WapStreamConfig {
  int32_t sample_rate_hz;
  int32_t num_channels;
} WapStreamConfig;

/**
 * Audio processing statistics.
 *
 * Each statistic has a `has_*` boolean. When `false`, the corresponding
 * value field is meaningless.
 */
typedef struct WapStats {
  bool has_echo_return_loss;
  double echo_return_loss;
  bool has_echo_return_loss_enhancement;
  double echo_return_loss_enhancement;
  bool has_divergent_filter_fraction;
  double divergent_filter_fraction;
  bool has_delay_median_ms;
  int32_t delay_median_ms;
  bool has_delay_standard_deviation_ms;
  int32_t delay_standard_deviation_ms;
  bool has_residual_echo_likelihood;
  double residual_echo_likelihood;
  bool has_residual_echo_likelihood_recent_max;
  double residual_echo_likelihood_recent_max;
  bool has_delay_ms;
  int32_t delay_ms;
} WapStats;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Returns a pointer to a static null-terminated version string.
 *
 * The returned pointer is valid for the lifetime of the process.
 */
 const char *wap_version(void);

/**
 * Returns a default-initialized configuration.
 */
 struct WapConfig wap_config_default(void);

/**
 * Creates a new audio processing instance with default configuration.
 *
 * Returns `NULL` on allocation failure or internal error.
 * The caller owns the returned pointer and must free it with
 * [`wap_destroy()`].
 */
 struct WapAudioProcessing *wap_create(void);

/**
 * Creates a new audio processing instance with the given configuration.
 *
 * Returns `NULL` on allocation failure or internal error.
 * The caller owns the returned pointer and must free it with
 * [`wap_destroy()`].
 */
 struct WapAudioProcessing *wap_create_with_config(struct WapConfig config);

/**
 * Destroys an audio processing instance and frees its memory.
 *
 * Passing `NULL` is a safe no-op. After this call the pointer is invalid.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * After this call the pointer is invalid and must not be used again.
 */
 void wap_destroy(struct WapAudioProcessing *apm);

/**
 * Applies a new configuration to the audio processing instance.
 *
 * Returns `WapError::NullPointer` if `apm` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_apply_config(struct WapAudioProcessing *apm, struct WapConfig config);

/**
 * Retrieves the current configuration.
 *
 * Returns `WapError::NullPointer` if `apm` or `config_out` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * All pointer arguments must be valid and properly aligned.
 */
 WapError wap_get_config(const struct WapAudioProcessing *apm, struct WapConfig *config_out);

/**
 * Initializes the processing pipeline with explicit stream configurations.
 *
 * Sets sample rates and channel counts for all four audio paths (capture
 * input, capture output, reverse input, reverse output) atomically,
 * triggering a full reinitialisation of internal buffers and submodules.
 *
 * Returns `WapError::NullPointer` if `apm` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */

WapError wap_initialize(struct WapAudioProcessing *apm,
                        struct WapStreamConfig input_config,
                        struct WapStreamConfig output_config,
                        struct WapStreamConfig reverse_input_config,
                        struct WapStreamConfig reverse_output_config);

/**
 * Processes a capture audio frame (float, deinterleaved).
 *
 * - `src`: array of `input_config.num_channels` pointers, each pointing
 *   to `input_config.sample_rate_hz / 100` samples.
 * - `dest`: array of `output_config.num_channels` pointers (output buffers).
 *
 * Returns `WapError::None` on success.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * `src` and `dest` channel pointer arrays must have the correct number
 * of channels and each channel pointer must point to at least the
 * required number of frames.
 */

WapError wap_process_stream_f32(struct WapAudioProcessing *apm,
                                const float *const *src,
                                struct WapStreamConfig input_config,
                                struct WapStreamConfig output_config,
                                float *const *dest);

/**
 * Processes a reverse (render / far-end) audio frame (float, deinterleaved).
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * `src` and `dest` channel pointer arrays must have the correct number
 * of channels and each channel pointer must point to at least the
 * required number of frames.
 */

WapError wap_process_reverse_stream_f32(struct WapAudioProcessing *apm,
                                        const float *const *src,
                                        struct WapStreamConfig input_config,
                                        struct WapStreamConfig output_config,
                                        float *const *dest);

/**
 * Processes a capture audio frame (int16, interleaved).
 *
 * - `src`: pointer to `num_frames * num_channels` interleaved i16 samples.
 * - `dest`: pointer to output buffer of same size.
 * - Input and output configs must have native rates (8k/16k/32k/48k) and
 *   matching rates and channel counts.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * `src` and `dest` must point to at least the specified number of samples.
 */

WapError wap_process_stream_i16(struct WapAudioProcessing *apm,
                                const int16_t *src,
                                int32_t src_len,
                                struct WapStreamConfig input_config,
                                struct WapStreamConfig output_config,
                                int16_t *dest,
                                int32_t dest_len);

/**
 * Processes a reverse (render / far-end) audio frame (int16, interleaved).
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * `src` and `dest` must point to at least the specified number of samples.
 */

WapError wap_process_reverse_stream_i16(struct WapAudioProcessing *apm,
                                        const int16_t *src,
                                        int32_t src_len,
                                        struct WapStreamConfig input_config,
                                        struct WapStreamConfig output_config,
                                        int16_t *dest,
                                        int32_t dest_len);

/**
 * Sets the applied input volume (e.g. from the OS mixer).
 *
 * Must be called before [`wap_process_stream_f32()`] if the input volume
 * controller is enabled. Value should be in range `[0, 255]`.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_stream_analog_level(struct WapAudioProcessing *apm, int32_t level);

/**
 * Returns the recommended analog level from AGC.
 *
 * Should be called after [`wap_process_stream_f32()`] to obtain the
 * recommended new analog level. Returns 0 if `apm` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 int32_t wap_recommended_stream_analog_level(const struct WapAudioProcessing *apm);

/**
 * Sets the delay in ms between render and capture.
 *
 * The delay is clamped to `[0, 500]`. Returns `WapError::BadStreamParameter`
 * if clamping was necessary (processing still proceeds).
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_stream_delay_ms(struct WapAudioProcessing *apm, int32_t delay);

/**
 * Returns the current stream delay in ms. Returns 0 if `apm` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 int32_t wap_stream_delay_ms(const struct WapAudioProcessing *apm);

/**
 * Sets the capture pre-gain factor via runtime setting.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_capture_pre_gain(struct WapAudioProcessing *apm, float gain);

/**
 * Sets the capture post-gain factor via runtime setting.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_capture_post_gain(struct WapAudioProcessing *apm, float gain);

/**
 * Sets the fixed post-gain in dB via runtime setting (range: 0..=90).
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_capture_fixed_post_gain(struct WapAudioProcessing *apm, float gain_db);

/**
 * Notifies of a playout volume change via runtime setting.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_playout_volume(struct WapAudioProcessing *apm, int32_t volume);

/**
 * Notifies of a playout audio device change via runtime setting.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */

WapError wap_set_playout_audio_device(struct WapAudioProcessing *apm,
                                      int32_t device_id,
                                      int32_t max_volume);

/**
 * Sets whether the capture output is used via runtime setting.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 */
 WapError wap_set_capture_output_used(struct WapAudioProcessing *apm, bool used);

/**
 * Retrieves current processing statistics.
 *
 * Returns `WapError::NullPointer` if `apm` or `stats_out` is null.
 *
 * # Safety
 *
 * `apm` must be a valid pointer returned by [`wap_create`] or
 * [`wap_create_with_config`] and must not be concurrently accessed.
 * All pointer arguments must be valid and properly aligned.
 */
 WapError wap_get_statistics(const struct WapAudioProcessing *apm, struct WapStats *stats_out);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* WAP_AUDIO_PROCESSING_H */