# GMF-Audio

[中文]

gmf_audio is the audio processing component of ESP-GMF, providing 17 elements across five categories: codec, format conversion, audio effects, channel layout, and audio muxer. All elements inherit from `esp_gmf_audio_element_t`, exposing unified lifecycle functions, acquire-release data interfaces, and runtime method calls. The underlying algorithms are implemented by `esp_audio_codec`, `esp_audio_effects`, and `esp_muxer`. This document covers the purpose, configuration, and runtime control of each element by category. For the element base class and runtime method mechanism, see GMF Elements; for the data path, see Data Flow.

## Feature List

- aud_dec: multi-format audio decoding, supporting MP3, AAC, AMRNB, AMRWB, FLAC, WAV, M4A, TS, OPUS, SBC, LC3, ADPCM, ALAC, G711, VORBIS, OGG, G722; format can be reconfigured without rebuilding the element

- aud_enc: multi-format audio encoding, supporting AAC, AMRNB, AMRWB, ADPCM, OPUS, PCM, ALAC, SBC, LC3, G711, G722; bitrate can be adjusted at runtime

- aud_rate_cvt: sample rate conversion; the target sample rate can be switched at runtime via `set_dest_rate`

- aud_asrc: hardware-assisted sample rate conversion; `perf_type` supports AUTO / HW_ONLY / SW_MEMORY / SW_SPEED; `complexity` 0-3 controls precision; shares the same runtime method interface as `aud_rate_cvt`

- aud_ch_cvt: channel count conversion, supporting mapping and downmixing between mono, stereo, and multi-channel

- aud_bit_cvt: bit depth conversion, covering mutual conversion among 8 / 16 / 24 / 32 bit PCM

- aud_eq: multi-band equalizer; each band supports filter types such as peak, low-shelf, high-shelf, low-pass, and high-pass; bands can be toggled individually

- aud_alc: automatic level control, adjusting gain independently per channel

- aud_fade: fade-in/fade-out, supporting linear and curve transitions; progress can be reset at runtime

- aud_sonic: time-stretch / pitch-shift; speed and pitch range [0.5, 2.0]

- aud_mixer: multi-track mixer; each input track has an independent transition mode; audio info can be reset at runtime

- aud_drc: single-band dynamic range control; parameterized attack / release / hold / makeup / knee and breakpoint curve

- aud_mbc: multi-band dynamic range compression; each band has independent solo / bypass / crossover frequency

- aud_howl: howling suppression; FFT spectrum analysis combined with PAPR / PHPR / PNPR / IMSD multi-criteria; dynamically inserts notch filters per frame

- aud_intlv / aud_deintlv: multi-channel interleaving and de-interleaving; packs N independent mono streams into one multi-channel stream or splits in reverse

- aud_muxer: audio muxer that packages encoded audio data into container formats (TS, MP4, FLV, WAV, CAF, OGG, AVI); supports both streaming output and segmented file writing modes

- Common: automatic format detection, dynamic reconfiguration (`need_reopen`), bypass optimization, effects buffer in-place, per-element mutex thread safety

## Technical Details

### Element Hierarchy and Common Mechanisms

Each specific element is constructed by “wrapping an `esp_ae_*` algorithm handle”: the derived struct uses `esp_gmf_audio_element_t` as its first field, binds the algorithm handle, a configuration block, and an internal mutex; `open` creates the algorithm handle and fills back the element `ops`; `process` acquires a pair of input/output payloads at each scheduling interval and calls the algorithm’s `process` function; `close` destroys the handle.

            classDiagram
        direction TD

        class esp_gmf_audio_element_t
        class Codec {
            aud_dec
            aud_enc
        }
        class FormatConversion {
            aud_rate_cvt
            aud_asrc
            aud_ch_cvt
            aud_bit_cvt
        }
        class AudioEffects {
            aud_eq
            aud_alc
            aud_fade
            aud_sonic
            aud_mixer
            aud_drc
            aud_mbc
            aud_howl
        }
        class ChannelLayout {
            aud_intlv
            aud_deintlv
        }
        class Muxer {
            aud_muxer
        }

        esp_gmf_audio_element_t <|-- Codec
        esp_gmf_audio_element_t <|-- FormatConversion
        esp_gmf_audio_element_t <|-- AudioEffects
        esp_gmf_audio_element_t <|-- ChannelLayout
        esp_gmf_audio_element_t <|-- Muxer

All elements share three common mechanisms; understanding them avoids repeatedly consulting the source code:

- Effects buffer in-place: Effect elements (`eq` / `alc` / `fade`, etc.) check `in_port->is_shared` in `process`; if set, they directly let `out_load = in_load`, sharing the same payload buffer between input and output; the underlying `esp_ae_*` algorithm processes in-place, avoiding extra allocation.

- Bypass optimization: Conversion elements (`rate_cvt` / `ch_cvt` / `bit_cvt` / `asrc`) compare source and destination parameters at the `open` stage; if identical, they enter bypass mode. In bypass mode, if `in_port->is_shared` is set, `out_load = in_load` is used for zero-copy pass-through; otherwise a single memcpy is performed.

- Fine-grained mutex: All algorithm handle calls are wrapped in the element’s own mutex, allowing setters to be called from other threads during runtime (e.g., adjusting volume while running).

- Format notify-and-update: The upstream element notifies the downstream element after resolving the current sample format; the downstream element rebuilds the underlying algorithm handle accordingly. Detailed in the next section.

### Format Notify-and-Update Flow

Audio processing pipelines often encounter situations where downstream algorithms can only be configured correctly after the upstream decoder resolves the actual sample rate. gmf_audio divides this flow into two actions: notify and update:

Notify (upstream): After the upstream element (decoder, rate converter, channel converter, etc.) confirms the actual sample_rate / channel / bit_depth of the current frame in `open` or `process`, it calls the `GMF_AUDIO_UPDATE_SND_INFO(self, rate, bits, ch)` macro, which does two things: writes the new `esp_gmf_info_sound_t` to its own audio info field, and reports a `REPORT_INFO` event via `esp_gmf_element_notify_snd_info`; the pipeline receives this and delivers it to subsequent elements along the topology.

Update (downstream): The downstream element writes the new info to its own audio info field in the event callback and sets `need_reopen`. At the next `process` boundary, the element detects this flag, calls `close` to destroy the old handle, then `open` to rebuild with the new parameters. The framework completes the reopen automatically; application code only needs to ensure that downstream elements have an event subscription relationship with upstream elements (which pipelines created from a pool satisfy by default).

Setter calls (`set_dest_rate` / `set_para`, etc.) use the same update path: after a setter change, `need_reopen` is also set, and the algorithm handle is rebuilt at the next `process` boundary.

For format info events and dependency-type element startup flow, see the REPORT_INFO description in GMF Pipeline and Task Scheduling.

### Runtime Method Call Pattern

Each element exposes a set of macro-based method names via `esp_gmf_audio_methods_def.h`; the application layer assembles a string with `AMETHOD(MODULE, METHOD)` and calls `esp_gmf_element_exe_method`:

    /* Adjust ALC channel 0 gain to -6 dB */
    uint8_t buf[2] = { 0 /* idx */, (uint8_t)(-6) };
    esp_gmf_element_exe_method(alc_el, AMETHOD(ALC, SET_GAIN), buf, sizeof(buf));

You can also call the element’s own named setter directly (e.g., `esp_gmf_alc_set_gain()`), both paths use the same implementation; the only difference is the calling style. This component provides complete named APIs per element, and either can be chosen at runtime.

Another advantage of runtime methods is the decoupling of interface from implementation. Taking `aud_rate_cvt` as an example: when the application calls `AMETHOD(RATE_CVT, SET_DEST_RATE)`, it only depends on the method name, not the specific element. If switching to hardware ASRC (`aud_asrc`) is needed, simply replace `aud_rate_cvt` with `aud_asrc` in the pool; the latter implements the same `RATE_CVT::SET_DEST_RATE` interface, so no application code changes are required. Similarly, a custom resampling implementation can be registered as a custom element under the same runtime method name and connected directly to an existing pipeline without modifying the upper-level call logic.

### Audio Codec

aud_dec and aud_enc are the start or end elements of playback and recording pipelines; a typical assembly is as follows.

            flowchart LR
        subgraph play ["Playback Pipeline"]
            direction LR
            FileIn(("file/http")) --> Dec["aud_dec"]
            Dec --> Rate["aud_rate_cvt"]
            Rate --> EQ["aud_eq"]
            EQ --> Out(("codec_dev"))
        end
        subgraph rec ["Recording Pipeline"]
            direction LR
            CodecIn(("codec_dev")) --> Ch["aud_ch_cvt"]
            Ch --> AGC["aud_alc"]
            AGC --> Enc["aud_enc"]
            Enc --> FileOut(("file/http"))
        end

aud_dec: Decodes compressed streams to PCM. `esp_gmf_audio_dec_init()` accepts `esp_audio_simple_dec_cfg_t`; `dec_type` specifies the format; setting `use_frame_dec` to true uses frame-level decoding directly, bypassing the simple decoder’s container parsing layer. At runtime, reconfigure via `esp_gmf_audio_dec_reconfig()` or by `esp_gmf_info_sound_t`, which applies when the codec is configured after the IO returns the stream header. aud_dec has a built-in `audio_dec_detect_type` that automatically detects common container headers (`#!AMR`, `RIFF`, `fLaC`, `OggS`, `ID3`); when `dec_type` is unspecified, it can identify MP3 / AAC / FLAC / OGG, and other formats.

    esp_audio_simple_dec_cfg_t cfg = DEFAULT_ESP_GMF_AUDIO_DEC_CONFIG();
    cfg.dec_type = ESP_AUDIO_SIMPLE_DEC_TYPE_MP3;

    esp_gmf_element_handle_t dec = NULL;
    esp_gmf_audio_dec_init(&cfg, &dec);
    /* Switch to AAC after receiving stream header */
    esp_gmf_info_sound_t info = { .format_id = ESP_FOURCC_AAC, ... };
    esp_gmf_audio_dec_reconfig_by_sound_info(dec, &info);

aud_enc: Encodes PCM to a compressed format. `esp_gmf_audio_enc_init()` accepts `esp_audio_enc_config_t`; `type` specifies the output format (AAC, OPUS, SBC, LC3, G722, etc.). At runtime, call `esp_gmf_audio_enc_set_bitrate()` to change the bitrate; `esp_gmf_audio_enc_reconfig()` / `..._by_sound_info` switches format or parameters when the element is in `NONE` or `INITIALIZED` state.

aud_enc internally uses a byte cache to handle the case where input data is not necessarily aligned to a full frame; it cooperates with job return codes and task scheduling:

- When input is not enough for one frame, it accumulates in the byte cache and returns `ESP_GMF_JOB_ERR_CONTINUE`; the task feeds another block of data to the same element;

- When input is larger than one frame, only complete frames from the byte cache are consumed; the remaining tail stays in the byte cache and returns `ESP_GMF_JOB_ERR_TRUNCATE`; the task skips to the downstream element to consume the encoded output, then returns to this element to process the remaining bytes;

- After accumulating a complete frame, calls the underlying `esp_audio_enc_process` to produce output.

PTS is also maintained by the element at the byte cache level: when the accumulated duration in the byte cache exceeds the `pts` of the current origin, it is automatically clamped to 0 to avoid rollback. aud_dec uses the same `CONTINUE` / `TRUNCATE` pattern; application code does not need to care. Custom elements connected after a codec must also follow the same convention.

### Format Conversion

The format conversion section has four elements: `rate_cvt` / `ch_cvt` / `bit_cvt` wrap the corresponding algorithms in `esp_audio_effects`, exposing only one `set_dest_*` setter each; `asrc` uses the independent `esp_asrc` library, providing hardware-assisted or software-fallback processing paths.

aud_rate_cvt: Resamples input PCM to the target sample rate. `DEFAULT_ESP_GMF_RATE_CVT_CONFIG` defaults to 44100 → 48000, stereo, 16-bit; `complexity` ranges from 0-5, where higher values give better quality at greater cost; `perf_type` selects between `ESP_AE_RATE_CVT_PERF_TYPE_SPEED` and `QUALITY`. To switch target sample rate at runtime:

    esp_gmf_rate_cvt_set_dest_rate(rate_el, 16000);

The setter triggers `need_reopen`; the underlying handle is automatically rebuilt at the next `process` boundary.

aud_ch_cvt: Converts channel count, supporting arbitrary N → M mapping. If the source and destination channels are equal, bypass is set at open. Use `esp_gmf_ch_cvt_set_dest_ch()` to change the destination channel count at runtime.

aud_bit_cvt: Converts bit depth, covering mutual conversion among uint8 / int16 / int24 / int32 PCM. Use `esp_gmf_bit_cvt_set_dest_bits()` to change the destination bit depth at runtime.

aud_asrc: Uses the hardware ASRC peripheral (when supported by the SoC) or a software fallback for sample rate conversion; `perf_type` determines the backend selection:

- `ESP_ASRC_PERF_TYPE_AUTO`: Prefers hardware; automatically falls back to software when unavailable

- `ESP_ASRC_PERF_TYPE_HW_ONLY`: Hardware only; returns an error on unsupported SoCs

- `ESP_ASRC_PERF_TYPE_SW_MEMORY` / `ESP_ASRC_PERF_TYPE_SW_SPEED`: Pure software; optimizes memory usage or processing speed respectively

`complexity` ranges from 0-3 (only valid in software mode); higher values give better quality at greater cost. `timeout_ms` is the timeout threshold for waiting for hardware to complete one frame; ignored in software mode. `DEFAULT_ESP_GMF_ASRC_CONFIG` defaults to 44100 → 48000, stereo, 16-bit.

    esp_asrc_cfg_t cfg = DEFAULT_ESP_GMF_ASRC_CONFIG();
    esp_gmf_element_handle_t asrc_el = NULL;
    esp_gmf_asrc_init(&cfg, &asrc_el);
    /* Switch target sample rate at runtime */
    esp_gmf_asrc_set_dest_rate(asrc_el, 16000);

The setter triggers `need_reopen`, same behavior as `aud_rate_cvt`. `aud_asrc` registers the `RATE_CVT::SET_DEST_RATE` method with the same interface as `aud_rate_cvt`, and can be swapped in the pool without modifying application code.

All three conversion elements (`rate_cvt` / `ch_cvt` / `bit_cvt`) follow the same data flow: in `process`, acquire one block of input, compute the required output bytes by src/dest ratio, acquire output, call `esp_ae_*_process` to process one frame, then release both. In bypass mode, if `in_port->is_shared` is set, the output payload directly points to the input payload for zero-copy pass-through.

### Audio Effects

aud_eq: Multi-band equalizer. `DEFAULT_ESP_GMF_EQ_CONFIG` uses built-in 10-band default parameters (covering 31 Hz - 16 kHz) when `filter_num = 0`. Each band is configured independently:

    esp_ae_eq_filter_para_t para = {
        .filter_type = ESP_AE_EQ_FILTER_PEAK,
        .fc          = 1000,
        .q           = 1.0f,
        .gain        = 6.0f,
    };
    esp_gmf_eq_set_para(eq_el, 0, &para);
    esp_gmf_eq_enable_filter(eq_el, 0, true);

EQ decides which bands participate in processing based on the enable state at `open`; `process` calls `esp_ae_eq_process` to apply the overall frequency response adjustment to the current PCM.

aud_alc: Automatic level control; gain is set independently per channel, range [-64, 63] dB; values below `-64` are treated as mute.

    esp_gmf_alc_set_gain(alc_el, 0, -6);  /* Left -6 dB */
    esp_gmf_alc_set_gain(alc_el, 1, -6);  /* Right -6 dB */

aud_fade: Fade-in/fade-out; `mode` selects `FADE_IN` or `FADE_OUT`; `curve` selects `LINE` or `CURVE`; `transit_time` in ms. `esp_gmf_fade_reset()` resets the current fade progress to the initial weight, useful for “reusing the same fade element when switching tracks”.

aud_sonic: Time-stretch / pitch-shift. speed and pitch range [0.5, 2.0], where 1.0 means no change. Time-stretch changes the number of output samples; the element internally maintains a variable-length output buffer to handle this scaling relationship.

    esp_gmf_sonic_set_speed(sonic_el, 1.25f);  /* 1.25x speed */
    esp_gmf_sonic_set_pitch(sonic_el, 0.9f);   /* Slightly lower pitch */

aud_mixer: Multi-track mixer; the number of input ports is determined by `src_num`. Each track sets its transition mode independently via `esp_gmf_mixer_set_mode()` (`FADE_BY_SAMPLES` / `MUTE` / `NONE`, etc.); the shared sample rate / bit width / channel can be reset at runtime via `esp_gmf_mixer_set_audio_info()`. The first input blocks for 0 time, others block for the maximum delay: this ensures sound output immediately when the main track has data, and secondary tracks only mix in when they have data.

aud_drc: Single-band dynamic range control. In addition to the five time and curve parameters attack / release / hold / makeup / knee, you can also set input/output breakpoint curves via `esp_gmf_drc_set_points()` (supporting up to several `esp_ae_drc_point_t` points). Combined with `aud_eq`, this creates a typical master bus compression chain.

aud_mbc: Multi-band dynamic compression. Each band independently adjusts threshold / ratio / attack / release / hold / knee / makeup; set crossover frequencies between bands via `set_fc`; use `set_solo` and `set_bypass` for debugging to listen to or bypass a specific band.

aud_howl: Howling suppression; detects and attenuates feedback howling produced by the microphone, amplifier, and speaker loop. The algorithm evaluates three criteria simultaneously for each FFT frequency bin: PAPR (peak-to-average power ratio), PHPR (peak-to-harmonic power ratio), and PNPR (peak-to-noise power ratio). Frequency bins meeting any threshold are marked as howling candidates; the algorithm dynamically inserts biquad notch filters at those frequencies and reduces overall gain to suppress new howling peaks.

The optional fourth criterion IMSD (inter-frame spectral magnitude deviation) is enabled via `enable_imsd`, which is more sensitive to sustained stable frequencies and is suitable for mixed speech and music content; disabling it in pure speech scenarios saves memory and CPU.

The processing frame length is determined by `esp_ae_howl_get_frame_size` at open based on sample rate (512 samples/channel when sample_rate < 32000 Hz, otherwise 1024 samples/channel). The algorithm supports in-place processing; input and output can point to the same buffer.

Note

The GMF element wrapper for `aud_howl` (`esp_gmf_howl.h`) is still under development; the specific initialization API is subject to the final merged implementation.

### Channel Layout

aud_intlv: Merges N mono inputs into one N-channel interleaved PCM stream; `src_num` determines the number of input ports. Commonly used to merge AEC reference and microphone channels into stereo for file writing.

aud_deintlv: The reverse operation; splits one interleaved PCM stream into N output ports by channel. Commonly used to split stereo into left and right channels for separate post-processing.

Both only perform memory reorganization without modifying sample values; `process` loops memcpy at sample stride.

### Audio Muxer

aud_muxer: Packages encoded audio data into container format output. Driven by the `esp_muxer` library, supported container formats include TS, MP4, FLV, WAV, CAF, OGG, and AVI. aud_muxer is typically placed after aud_enc, responsible for completing format encapsulation at the end of recording or transcoding pipelines.

Main fields of `esp_gmf_audio_muxer_cfg_t`:

Field | Description
--- | ---
`muxer_type` | Container type: `ESP_MUXER_TYPE_TS / MP4 / FLV / WAV / CAF / OGG / AVI`
`codec` | Codec type of the input audio (corresponding to the output format of aud_enc)
`output_type` | Output mode: `STREAMING` (streaming output via databus) or `FILE` (written to files)
`slice_duration` | Valid in file mode only; duration of each file segment in milliseconds, default 60000
`url_pattern` / `url_ctx` | Valid in file mode only; segmented file path callback that determines which file each segment is written to
`get_codec_spec_info_cb` | Optional. Callback to provide additional metadata such as SPS for formats like AAC that require codec-specific information

Streaming output mode: When `output_type = ESP_GMF_AUDIO_MUXER_OUTPUT_STREAMING`, the element creates an internal block databus at `open`; the muxer writes encapsulated data to the databus via callback, then forwards it to downstream via out_port (e.g., an IO element for file writing or network transmission).

File segment mode: When `output_type = ESP_GMF_AUDIO_MUXER_OUTPUT_FILE`, the element does not occupy out_port; it directly splits and writes a series of files at `slice_duration` intervals via the `url_pattern` callback, suitable for continuous recording scenarios.

    esp_gmf_audio_muxer_cfg_t cfg = {
        .muxer_type  = ESP_MUXER_TYPE_MP4,
        .codec       = ESP_MUXER_AUDIO_CODEC_AAC,
        .output_type = ESP_GMF_AUDIO_MUXER_OUTPUT_STREAMING,
    };
    esp_gmf_element_handle_t muxer_el = NULL;
    esp_gmf_audio_muxer_init(&cfg, &muxer_el);

aud_muxer relies on the `esp_gmf_info_sound_t` (sample rate, bit depth, channel) reported by the upstream aud_enc to initialize the muxer audio stream descriptor; ensure aud_enc completes the `REPORT_INFO` event delivery before aud_muxer by maintaining the standard pipeline connection order enc → muxer.

## Performance

Overall, the timing of each element is primarily determined by the underlying `esp_ae_*` algorithm; the relative overhead of the framework’s acquire-release and runtime method scheduling per `process` call is small (on the order of hundreds of microseconds). When balancing CPU and audio quality:

- The `complexity` field of `aud_rate_cvt` directly trades audio quality for CPU; `perf_type = SPEED` is generally sufficient for embedded player scenarios

- More enabled bands in `aud_eq` / `aud_drc` / `aud_mbc` mean higher cost; use `enable_filter` / `set_bypass` to disable them on demand at runtime

- The throughput of `aud_dec` and `aud_enc` depends on the specific codec format (OPUS, AAC, and FLAC differ significantly); refer to the benchmarks provided by `esp_audio_codec`

- Conversion elements automatically bypass when source and destination parameters are identical; no need to split elements for “possibly unnecessary conversions” in pipeline design

## Application Examples

- `elements/test_apps/main/elements/gmf_audio_el_test.c`: Individual test cases for each element, covering default parameters, runtime setters, reset, etc.

- `elements/test_apps/main/elements/gmf_audio_play_el_test.c`: Comprehensive use case assembling a playback pipeline

- `elements/test_apps/main/elements/gmf_audio_effects_test.c`: Effects pipeline test

- `elements/test_apps/main/elements/gmf_audio_rec_el_test.c`: Recording pipeline test, covering the encoding side

- `gmf_examples/basic_examples/pipeline_play_embed_music`: Complete application project

The upper-level wrappers `esp_audio_simple_player` / `esp_audio_render` also connect audio pipelines through this component internally and can serve as advanced references.

## FAQ

Q: Can `aud_dec` still decode when `dec_type` is not specified?

Yes. This works only when `use_frame_dec = false` (default). In this case, the decoder enables its internal parser to automatically identify the container header and frame sync bytes from the input stream to determine the format and initialize the decoder. If `use_frame_dec = true`, the input is treated as complete encoded frames without going through the parser, so automatic format detection will not work. When the format is known, it is recommended to explicitly set `dec_type` for faster startup and to avoid misidentification.

Q: Under what conditions does `aud_enc` `set_bitrate` take effect?

When the encoder handle has not been created, `esp_gmf_audio_enc_set_bitrate()` validates the parameter and writes it into the `esp_audio_enc_config_t` configuration; when the handle exists, it applies directly to the running encoder. `esp_gmf_audio_enc_reconfig()` and `..._by_sound_info` can replace the full configuration only when state is less than `OPENING`. Use `esp_gmf_audio_enc_get_bitrate()` to read the configured or active bitrate.

Q: Why is there a brief pause after switching the target sample rate in `aud_rate_cvt`?

`set_dest_rate` triggers `need_reopen`; the element destroys the old handle and rebuilds a new one at the next process boundary. The rebuild process causes a brief pause. If a smooth transition is needed, perform the switch after `pause`.

Q: If the main track of `aud_mixer` has no data, will the other tracks block?

The mixer design is “first track blocks 0, others block at maximum delay”; when the main track has no data, it returns immediately, and the remaining tracks mix with zero data. If you want secondary tracks to take over when the main track is missing, swap the connection order and connect the current secondary track to input port 0 as the main track.

Q: Why is the PCM length not half the input when `aud_sonic` has speed=2?

Time-stretch is a non-integer division operation; the element calculates output size by the current speed ratio while retaining cumulative error, so each frame’s output length is not fixed. Downstream elements (such as codec_dev IO) should write to hardware based on `valid_size` and must not assume a fixed length.

Q: How is synchronization guaranteed between multiple inputs of `aud_intlv`?

The interleave element does not perform synchronization; it relies on upstream elements providing a consistent number of samples from each track. The common approach for multiple AEC references is to connect all tracks to the same pipeline using the same task to serially acquire, thereby maintaining alignment.

## API Reference

Header files for this component:

- `esp_gmf_audio_dec.h` / `esp_gmf_audio_enc.h`: Codec elements

- `esp_gmf_audio_helper.h` / `esp_gmf_audio_param.h`: Helper interfaces and parameter definitions

- `esp_gmf_audio_methods_def.h`: Runtime method name and parameter name macros (pure macro definitions; see source header files for details)

- `esp_gmf_rate_cvt.h` / `esp_gmf_ch_cvt.h` / `esp_gmf_bit_cvt.h`: Format conversion elements

- `esp_gmf_asrc.h`: Hardware-assisted sample rate conversion element

- `esp_gmf_eq.h` / `esp_gmf_alc.h` / `esp_gmf_fade.h` / `esp_gmf_sonic.h` / `esp_gmf_mixer.h`: Common audio effect elements

- `esp_gmf_drc.h` / `esp_gmf_mbc.h`: Dynamic range control elements

- `esp_gmf_interleave.h` / `esp_gmf_deinterleave.h`: Channel layout elements

- `esp_gmf_audio_muxer.h`: Audio muxer element

The interface for the element base class `esp_gmf_audio_element_t` is located in GMF Elements.

### Header File

- elements/gmf_audio/include/esp_gmf_audio_dec.h

### Functions

esp_gmf_err_t esp_gmf_audio_dec_init(esp_audio_simple_dec_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF audio decoder with the provided configuration.

  Parameters:

    - config – [in] Pointer to the audio decoder configuration

    - handle – [out] Pointer to the audio decoder handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_audio_dec_reconfig(esp_gmf_element_handle_t handle, esp_audio_simple_dec_cfg_t *config)

  Reconfigure the GMF audio decoder and filled into provided configuration.

  Note

  This function can be called in any state It is recommended to call it before the pipeline run or when the pipeline is paused If called during runtime, ensure the input IO data and the configured decode format are timing-aligned

  Parameters:

    - handle – [in] Audio decoder handle to be reconfigured

    - config – [in] Pointer to the new simple decoder configuration

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_audio_dec_reconfig_by_sound_info(esp_gmf_element_handle_t handle, esp_gmf_info_sound_t *info)

  Reconfigures the GMF audio decoder with default configuration based on provided sound information.

  Note

  The call timing is same as `esp_gmf_audio_dec_reconfig` function

  Parameters:

    - handle – [in] Audio decoder handle to be reconfigured

    - info – [in] Sound information to be configured

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or decoder type provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

### Macros

DEFAULT_ESP_GMF_AUDIO_DEC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_audio_enc.h

### Functions

esp_gmf_err_t esp_gmf_audio_enc_init(esp_audio_enc_config_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF audio encoder with the provided configuration.

  Parameters:

    - config – [in] Pointer to the audio encoder configuration

    - handle – [out] Pointer to the audio encoder handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_audio_enc_get_frame_size(esp_gmf_element_handle_t handle, uint32_t *in_size, uint32_t *out_size)

  Get the input and output frame size information of the GMF audio encoder.

  Parameters:

    - handle – [in] Audio encoder handle

    - in_size – [out] Pointer to store input frame size

    - out_size – [out] Pointer to store suggested output frame size

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or size pointers provided

esp_gmf_err_t esp_gmf_audio_enc_set_bitrate(esp_gmf_element_handle_t handle, uint32_t bitrate)

  Set the bitrate for the GMF audio encoder.

  Note

  When element is in `ESP_GMF_EVENT_STATE_NONE` or `ESP_GMF_EVENT_STATE_INITIALIZED` state, user needs to configure the codec first (e.g., via `esp_gmf_audio_enc_reconfig` or `esp_gmf_audio_enc_reconfig_by_sound_info`) before calling this function

  Parameters:

    - handle – [in] Audio encoder handle

    - bitrate – [in] The bitrate of the encoder

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or bitrate value provided

esp_gmf_err_t esp_gmf_audio_enc_get_bitrate(esp_gmf_element_handle_t handle, uint32_t *bitrate)

  Get the current bitrate of the GMF audio encoder.

  Parameters:

    - handle – [in] Audio encoder handle

    - bitrate – [out] Pointer to store the current bitrate

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or bitrate pointer provided

esp_gmf_err_t esp_gmf_audio_enc_reconfig(esp_gmf_element_handle_t handle, esp_audio_enc_config_t *config)

  Reconfigure the GMF audio encoder and filled into provided configuration.

  Note

  Only allowed when not running, i.e., in the `ESP_GMF_EVENT_STATE_NONE` or `ESP_GMF_EVENT_STATE_INITIALIZED` state

  Parameters:

    - handle – [in] Audio encoder handle to be reconfigured

    - config – [in] Pointer to the new audio encoder configuration

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_audio_enc_reconfig_by_sound_info(esp_gmf_element_handle_t handle, esp_gmf_info_sound_t *info)

  Reconfigures the GMF audio encoder with default configuration for the sound information.

  Note

  1. Only allowed when not running, i.e., in the `ESP_GMF_EVENT_STATE_NONE` or `ESP_GMF_EVENT_STATE_INITIALIZED` state

  1. The actual reconfiguration behavior depends on the relationship between the provided `sound info` and the current encoder configuration (`cfg`):

     - If the `format_id` in `sound info` matches the encoder’s current `type`, and the encoder’s sub-config (`sub cfg`) is not NULL, only the basic fields in the sub-config will be updated with information from `sound info` (e.g., sample rate, channel count).

     - If the `format_id` differs from the current `type`, or if the sub-config is NULL, the encoder will be reconfigured using the default configuration for the specified `format_id`, and the current encoder `type` will be updated accordingly.

  Parameters:

    - handle – [in] Audio encoder handle to be reconfigured

    - info – [in] Sound information to be configured

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or encoder type provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_audio_enc_get_spec_info(esp_gmf_element_handle_t handle, esp_gmf_audio_helper_spec_info_t *spec_info)

  Get the codec specific information of the GMF audio encoder.

  Note

  This function is typically used to get codec-specific codec specific information (e.g., ALAC magic cookie) The codec specific information is available after the encoder is opened The returned codec specific information pointer to the internal buffer, which remains valid until the encoder is closed

  Parameters:

    - handle – [in] Audio encoder handle

    - spec_info – [out] Pointer to store the codec specific information

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle or specific information pointer

### Macros

DEFAULT_ESP_GMF_AUDIO_ENC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_audio_helper.h

### Functions

esp_gmf_err_t esp_gmf_audio_helper_get_audio_type_by_uri(const char *uri, uint32_t *format_id)

  Get audio codec type by uri.

  Parameters:

    - uri – [in] URI of audio codec

    - format_id – [out] Type of audio codec(ESP_FourCC type)

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_NOT_SUPPORT Not supported audio codec type

bool esp_gmf_audio_helper_is_frame_dec(uint32_t dec_type)

  Check if the given decoder type is a frame-based decoder.

  Parameters:

    dec_type – [in] The decoder type to check

  Returns:

    - true If the decoder is frame-based

    - false otherwise

### Structures

struct esp_gmf_audio_helper_spec_info_t

  Codec-specific binary data for a given encoded format.

  Public Members

  void *codec_spec_info

    Codec specified information

  uint32_t spec_info_len

    Length of codec specified information

### Header File

- elements/gmf_audio/include/esp_gmf_audio_param.h

### Functions

esp_gmf_err_t esp_gmf_audio_param_set_dest_rate(esp_gmf_element_handle_t self, uint32_t dest_rate)

  Set frame destination sample rate for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - dest_rate – [in] Destination sample rate

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_dest_bits(esp_gmf_element_handle_t self, uint8_t dest_bits)

  Set frame destination bits for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - dest_bits – [in] Destination bits

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_dest_ch(esp_gmf_element_handle_t self, uint8_t dest_ch)

  Set frame destination channel for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - dest_ch – [in] Destination channel

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_speed(esp_gmf_element_handle_t self, float speed)

  Set speed for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - speed – [in] Audio playback speed

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_pitch(esp_gmf_element_handle_t self, float pitch)

  Set pitch for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - pitch – [in] Audio pitch to set

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_alc_channel_gain(esp_gmf_element_handle_t self, uint8_t ch_idx, float gain_db)

  Set ALC certain channel gain for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - ch_idx – [in] Channel index (0: Left channel 1: Right Channel 0xFF: All channels)

    - gain_db – [in] ALC gain (unit decibel)

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

esp_gmf_err_t esp_gmf_audio_param_set_fade(esp_gmf_element_handle_t self, bool is_fade_in)

  Set fade in/out direction for audio element.

  Parameters:

    - handle – [in] Audio element handle

    - is_fade_in – [in] Whether fade in or out

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_NOT_FOUND Not found the method

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

    - Others Failed to apply method

### Macros

esp_gmf_audio_param_set_alc_gain(self, gain_db)

  Set ALC gain for all channels.

esp_gmf_audio_param_set_fade_in(self)

  Helper wrapper for fade in and fade out setting.

esp_gmf_audio_param_set_fade_out(self)

### Header File

- elements/gmf_audio/include/esp_gmf_rate_cvt.h

### Functions

esp_gmf_err_t esp_gmf_rate_cvt_init(esp_ae_rate_cvt_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF rate conversion with the provided configuration.

  Parameters:

    - config – [in] Pointer to the rate conversion configuration

    - handle – [out] Pointer to the rate conversion handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_rate_cvt_set_dest_rate(esp_gmf_element_handle_t handle, uint32_t dest_rate)

  Set dest rate in the rate conversion handle.

  Parameters:

    - handle – [in] The rate conversion handle

    - dest_ch – [in] The dest rate

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

    - ESP_GMF_ERR_FAIL Failed to set configuration

### Macros

DEFAULT_ESP_GMF_RATE_CVT_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_ch_cvt.h

### Functions

esp_gmf_err_t esp_gmf_ch_cvt_init(esp_ae_ch_cvt_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF channel conversion with the provided configuration.

  Parameters:

    - config – [in] Pointer to the channel conversion configuration

    - handle – [out] Pointer to the channel conversion handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_ch_cvt_set_dest_channel(esp_gmf_element_handle_t handle, uint8_t dest_ch)

  Set dest channel in the channel conversion handle.

  Parameters:

    - handle – [in] The channel conversion handle

    - dest_ch – [in] The dest channel

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

    - ESP_GMF_ERR_FAIL Failed to set configuration

### Macros

DEFAULT_ESP_GMF_CH_CVT_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_bit_cvt.h

### Functions

esp_gmf_err_t esp_gmf_bit_cvt_init(esp_ae_bit_cvt_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF bit conversion with the provided configuration.

  Parameters:

    - config – [in] Pointer to the bit conversion configuration

    - handle – [out] Pointer to the bit conversion handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_bit_cvt_set_dest_bits(esp_gmf_element_handle_t handle, uint8_t dest_bits)

  Set destination bits for the bit conversion handle.

  Parameters:

    - handle – [in] The channel bit handle

    - dest_bits – [in] The destination bits

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

    - ESP_GMF_ERR_FAIL Failed to set configuration

### Macros

DEFAULT_ESP_GMF_BIT_CVT_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_eq.h

### Functions

esp_gmf_err_t esp_gmf_eq_init(esp_ae_eq_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF EQ with the provided configuration.

  Parameters:

    - config – [in] Pointer to the EQ configuration

    - handle – [out] Pointer to the EQ handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_eq_set_para(esp_gmf_element_handle_t handle, uint8_t idx, esp_ae_eq_filter_para_t *para)

  Set the filter parameters for a specific filter identified by ‘idx’.

  Parameters:

    - handle – [in] The EQ handle

    - idx – [in] The index of a specific filter for which the parameters are to be set. eg: 0 refers to the first filter

    - para – [in] The filter setup parameter

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_eq_get_para(esp_gmf_element_handle_t handle, uint8_t idx, esp_ae_eq_filter_para_t *para)

  Get the filter parameters for a specific filter identified by ‘idx’.

  Parameters:

    - handle – [in] The EQ handle

    - idx – [in] The index of a specific filter for which the parameters are to be retrieved. eg: 0 refers to first filter

    - para – [out] The filter setup parameter

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_eq_enable_filter(esp_gmf_element_handle_t handle, uint8_t idx, bool is_enable)

  Choose to enable or disable filter processing for a specific filter identified by ‘idx’ in the equalizer.

  Parameters:

    - handle – [in] The EQ handle

    - idx – [in] The index of a specific filter to be enabled

    - is_enable – [in] The flag of whether to enable band filter processing

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_EQ_CONFIG()

  Default EQ parameters If `para` is NULL in the `esp_ae_eq_cfg_t` , the EQ will use `esp_gmf_default_eq_paras` as default And the `filter_num` will be set to sizeof(esp_gmf_default_eq_paras) / sizeof(esp_ae_eq_filter_para_t)

### Header File

- elements/gmf_audio/include/esp_gmf_alc.h

### Functions

esp_gmf_err_t esp_gmf_alc_init(esp_ae_alc_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF ALC with the provided configuration.

  Parameters:

    - config – [in] Pointer to the ALC configuration

    - handle – [out] Pointer to the ALC handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_alc_set_gain(esp_gmf_element_handle_t handle, uint8_t idx, int8_t gain)

  Set specific channel gain of the ALC handle. Positive gain indicates an increase in volume, negative gain indicates a decrease in volume. 0 gain indicates the volume level remains unchanged.

  Parameters:

    - handle – [in] The ALC handle

    - idx – [in] The channel index of the gain to retrieve. eg: 0 refers to the first channel

    - gain – [in] The gain value needs to conform to the following conditions:

      - Supported range [-64, 63]

      - Below -64 will set to mute

      - Higher than 63 not supported Unit: dB

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_alc_get_gain(esp_gmf_element_handle_t handle, uint8_t idx, int8_t *gain)

  Get the gain for a specific channel from the ALC handle.

  Parameters:

    - handle – [in] The ALC handle

    - ch_idx – [in] The channel index of the gain to retrieve. eg: 0 refers to the first channel

    - gain – [out] Pointer to store the retrieved gain. Unit: dB

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_ALC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_fade.h

### Functions

esp_gmf_err_t esp_gmf_fade_init(esp_ae_fade_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF fade with the provided configuration.

  Parameters:

    - config – [in] Pointer to the fade configuration

    - handle – [out] Pointer to the fade handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_fade_set_mode(esp_gmf_element_handle_t handle, esp_ae_fade_mode_t mode)

  Set the fade process mode.

  Parameters:

    - handle – [in] The fade handle

    - mode – [in] The mode of fade

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_fade_get_mode(esp_gmf_element_handle_t handle, esp_ae_fade_mode_t *mode)

  Get the fade process mode.

  Parameters:

    - handle – [in] The fade handle

    - mode – [out] The mode of fade

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_fade_reset(esp_gmf_element_handle_t handle)

  Reset the internal processing state of the fade element while preserving configuration.

  Parameters:

    handle – [in] The fade element handle

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

    - ESP_GMF_ERR_INVALID_STATE Fade element is not opened

esp_gmf_err_t esp_gmf_fade_reset_weight(esp_gmf_element_handle_t handle)

  Reset the fade process to the initial configuration state. This API is kept for backward compatibility. Internally it calls esp_gmf_fade_reset.

  Parameters:

    handle – [in] The fade handle

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_FADE_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_sonic.h

### Functions

esp_gmf_err_t esp_gmf_sonic_init(esp_ae_sonic_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF sonic with the provided configuration.

  Parameters:

    - config – [in] Pointer to the sonic configuration

    - handle – [out] Pointer to the sonic handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_sonic_set_speed(esp_gmf_element_handle_t handle, float speed)

  Set the audio speed.

  Parameters:

    - handle – [in] The handle of the sonic

    - speed – [in] The scaling factor of audio speed. The range of speed is [0.5, 2.0]

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_sonic_get_speed(esp_gmf_element_handle_t handle, float *speed)

  Get the audio speed.

  Parameters:

    - handle – [in] The handle of the sonic

    - speed – [out] The scaling factor of audio speed

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_sonic_set_pitch(esp_gmf_element_handle_t handle, float pitch)

  Set the audio pitch.

  Parameters:

    - handle – [in] The handle of the sonic

    - pitch – [in] The scaling factor of audio pitch. The range of pitch is [0.5, 2.0]. If the pitch value is smaller than 1.0, the sound is deep voice; if the pitch value is equal to 1.0, the sound is no change; if the pitch value is gather than 1.0, the sound is sharp voice;

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_sonic_get_pitch(esp_gmf_element_handle_t handle, float *pitch)

  Get the audio pitch.

  Parameters:

    - handle – [in] The handle of the sonic

    - pitch – [out] The scaling factor of audio pitch

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_SONIC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_mixer.h

### Functions

esp_gmf_err_t esp_gmf_mixer_init(esp_ae_mixer_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF mixer with the provided configuration.

  Parameters:

    - config – [in] Pointer to the mixer configuration

    - handle – [out] Pointer to the mixer handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_mixer_set_mode(esp_gmf_element_handle_t handle, uint8_t src_idx, esp_ae_mixer_mode_t mode)

  Set the transit mode of a certain stream according to src_idx.

  Parameters:

    - handle – [in] The mixer handle

    - src_idx – [in] The index of a certain source stream which want to set transit mode. eg: 0 refer to first source stream

    - mode – [in] The transit mode of source stream

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mixer_set_audio_info(esp_gmf_element_handle_t handle, uint32_t sample_rate, uint8_t bits, uint8_t channel)

  Set audio information to the mixer handle.

  Parameters:

    - handle – [in] The mixer handle

    - sample_rate – [in] The audio sample rate

    - bits – [in] The audio bits per sample

    - channel – [in] The audio channel

  Returns:

    - ESP_GMF_ERR_OK Operation succeeded

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

    - ESP_GMF_ERR_FAIL Failed to set configuration

### Macros

DEFAULT_ESP_GMF_MIXER_CONFIG()

  Default mixer source info If `src_info` is NULL in `esp_ae_mixer_cfg_t`, the mixer will use esp_gmf_default_mixer_src_info as default And `src_num` will set to `sizeof(esp_gmf_default_mixer_src_info) / sizeof(esp_ae_mixer_info_t)`;.

### Header File

- elements/gmf_audio/include/esp_gmf_drc.h

### Functions

esp_gmf_err_t esp_gmf_drc_init(esp_ae_drc_cfg_t *config, esp_gmf_element_handle_t *handle)

  Initialize the GMF DRC element with the provided configuration.

  Parameters:

    - config – [in] Pointer to the DRC configuration (see esp_ae_drc_cfg_t)

    - handle – [out] Pointer to the DRC element handle to be created

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_drc_set_attack_time(esp_gmf_element_handle_t handle, uint16_t attack_time)

  Set the attack time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - attack_time – [in] Attack time, range: [0, 500], unit: ms

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_attack_time(esp_gmf_element_handle_t handle, uint16_t *attack_time)

  Get the attack time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - attack_time – [out] Attack time in milliseconds

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_set_release_time(esp_gmf_element_handle_t handle, uint16_t release_time)

  Set the release time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - release_time – [in] Release time, range: [0, 500], unit: ms

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_release_time(esp_gmf_element_handle_t handle, uint16_t *release_time)

  Get the release time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - release_time – [out] Release time in milliseconds

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_set_hold_time(esp_gmf_element_handle_t handle, uint16_t hold_time)

  Set the hold time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - hold_time – [in] Hold time, range: [0, 100], unit: ms

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_hold_time(esp_gmf_element_handle_t handle, uint16_t *hold_time)

  Get the hold time of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - hold_time – [out] Hold time in milliseconds

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_set_makeup_gain(esp_gmf_element_handle_t handle, float makeup_gain)

  Set the makeup gain of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - makeup_gain – [in] Makeup gain, range: [-10.0, 10.0], unit: dB

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_makeup_gain(esp_gmf_element_handle_t handle, float *makeup_gain)

  Get the makeup gain of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - makeup_gain – [out] Makeup gain in dB

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_set_knee_width(esp_gmf_element_handle_t handle, float knee_width)

  Set the knee width of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - knee_width – [in] Knee width, range: [0.0, 10.0]

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_knee_width(esp_gmf_element_handle_t handle, float *knee_width)

  Get the knee width of the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - knee_width – [out] Knee width factor (softness)

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_set_points(esp_gmf_element_handle_t handle, esp_ae_drc_curve_point *points, uint8_t point_num)

  Set the static curve points of the DRC.

          The curve describes input level (x) to output level (y) mapping in dB.

  Note

  1. The point_num must be greater than or equal to 2 and less than or equal to 6

  1. The x-axis value and y-axis value of the point must be range of [-100.0, 0.0]

  2. The x-axis value of the different point must be unique

  3. The x-axis value of the point must have value of 0.0 and -100.0

  Parameters:

    - handle – [in] DRC element handle

    - points – [in] Array of curve points

    - point_num – [in] Number of points in the array, range: [2, 6]

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_point_num(esp_gmf_element_handle_t handle, uint8_t *point_num)

  Get the number of static curve points configured in the DRC.

  Parameters:

    - handle – [in] DRC element handle

    - point_num – [out] Number of points currently configured

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_drc_get_points(esp_gmf_element_handle_t handle, esp_ae_drc_curve_point *points)

  Retrieve the static curve points of the DRC.

          The provided buffer must be large enough to hold all points (see
          @ref esp_gmf_drc_get_point_num).

  Parameters:

    - handle – [in] DRC element handle

    - points – [out] Output buffer for curve points

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_DRC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_mbc.h

### Functions

esp_gmf_err_t esp_gmf_mbc_init(esp_ae_mbc_config_t *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF multi-band compressor with the provided configuration.

  Parameters:

    - config – [in] Pointer to the MBC configuration

    - handle – [out] Pointer to the MBC element handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_mbc_set_para(esp_gmf_element_handle_t handle, uint8_t band_idx, esp_ae_mbc_para_t *para)

  Set the compressor parameter for a specific band identified by ‘band_idx’.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the parameters are to be set eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - para – [in] The compressor setup parameter

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_get_para(esp_gmf_element_handle_t handle, uint8_t band_idx, esp_ae_mbc_para_t *para)

  Get the compressor parameter for a specific band identified by ‘band_idx’.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the parameters are to be retrieved eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - para – [out] The compressor setup parameter

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_set_fc(esp_gmf_element_handle_t handle, uint8_t fc_idx, uint32_t fc)

  Set the frequency of crossover point identified by ‘fc_idx’.

          The audio spectrum is divided into four bands by three crossover frequencies: low_fc, mid_fc, and high_fc

  Parameters:

    - handle – [in] The MBC element handle

    - fc_idx – [in] The index of a crossover point for which the frequency are to be set eg: 0 refers to the first point (low_fc), 2 refers to the last point (high_fc)

    - fc – [in] The frequency of crossover point, unit: Hz

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_get_fc(esp_gmf_element_handle_t handle, uint8_t fc_idx, uint32_t *fc)

  Get the frequency of crossover point identified by ‘fc_idx’.

  Parameters:

    - handle – [in] The MBC element handle

    - fc_idx – [in] The index of a crossover point for which the frequency are to be retrieved eg: 0 refers to the first point (low_fc), 2 refers to the last point (high_fc)

    - fc – [out] The pointer of frequency of crossover point, unit: Hz

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_set_solo(esp_gmf_element_handle_t handle, uint8_t band_idx, bool enable_solo)

  Set whether to turn on the function of solo for a specific band identified by ‘band_idx’.

          Solo allows user to isolate and listen to a specific frequency band while muting all other bands.
          This helps in focusing on the sound of that individual band without the influence of other frequency ranges.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the solo function is to be set eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - enable_solo – [in] The flag to turn on the solo function True means turn on the solo for a specific band False means turn off the solo for a specific band

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_get_solo(esp_gmf_element_handle_t handle, uint8_t band_idx, bool *enable_solo)

  Get the solo state for a specific band identified by ‘band_idx’.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the solo state is to be retrieved eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - enable_solo – [out] Pointer to store the solo state

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_set_bypass(esp_gmf_element_handle_t handle, uint8_t band_idx, bool enable_bypass)

  Set whether to turn on/off the function of bypass for a specific band identified by ‘band_idx’.

          Bypass lets the signal of a selected frequency band pass through without being processed by the compressor.
          In Bypass mode, the band's compression is temporarily disabled, but the audio signal still passes through.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the bypass function is to be set eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - enable_bypass – [in] The flag to turn on/off the bypass function True means turn on the bypass for a specific band False means turn off the bypass for a specific band

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

esp_gmf_err_t esp_gmf_mbc_get_bypass(esp_gmf_element_handle_t handle, uint8_t band_idx, bool *enable_bypass)

  Get the bypass state for a specific band identified by ‘band_idx’.

  Parameters:

    - handle – [in] The MBC element handle

    - band_idx – [in] The index of a specific band for which the bypass state is to be retrieved eg: 0 refers to the first band (low frequency), 3 refers to the last band (high frequency)

    - enable_bypass – [out] Pointer to store the bypass state True indicates the bypass is enabled for the specified band False indicates the bypass is disabled for the specified band

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid input parameter

### Macros

DEFAULT_ESP_GMF_MBC_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_interleave.h

### Functions

esp_gmf_err_t esp_gmf_interleave_init(esp_gmf_interleave_cfg *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF interleave with the provided configuration.

  Parameters:

    - config – [in] Pointer to the interleave configuration

    - handle – [out] Pointer to the interleave handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

### Structures

struct esp_gmf_interleave_cfg

  Configuration structure for interleave.

  Public Members

  uint32_t sample_rate

    The audio sample rate

  uint8_t bits_per_sample

    The audio bits per sample, supports 16, 24, 32 bits

  uint8_t src_num

    The number of input source num

### Macros

DEFAULT_ESP_GMF_INTERLEAVE_CONFIG()

### Header File

- elements/gmf_audio/include/esp_gmf_deinterleave.h

### Functions

esp_gmf_err_t esp_gmf_deinterleave_init(esp_gmf_deinterleave_cfg *config, esp_gmf_element_handle_t *handle)

  Initializes the GMF deinterleave with the provided configuration.

  Parameters:

    - config – [in] Pointer to the deinterleave configuration

    - handle – [out] Pointer to the deinterleave handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

### Structures

struct esp_gmf_deinterleave_cfg

  Configuration structure for deinterleave.

  Public Members

  uint32_t sample_rate

    The audio sample rate

  uint8_t bits_per_sample

    The audio bits per sample, supports 16, 24, 32 bits

  uint8_t channel

    The audio channel

### Macros

DEFAULT_ESP_GMF_DEINTERLEAVE_CONFIG()

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.