GMF Pipeline and Task Scheduling

[中文]

This document follows a progressive structure of “Introduction - Principles - Basic Example - Advanced Topics - Miscellaneous,” covering the collaboration, runtime scheduling, error handling, and composition of the pipeline, element, and task.

For element lifecycle, capability, runtime methods, and custom templates, see GMF Elements. For data flow details between elements (payload, port, IO), see Data Flow. For the four data bus implementations, see Data Bus. For the overall architecture and object relationships, see GMF-Core Overview.

Introduction

After reading this document, you will be able to:

• Understand how the task schedules the three callback functions of an element

• Know how events and states flow between the pipeline, task, and user code

• Use the pool to manage element templates in bulk and instantiate various pipelines on demand

• Choose the correct API for multi-pipeline composition, pause, stop, and error recovery

• Build a basic pipeline and start it running

This document only describes the orchestration and control layer. To write your own element, first read the element template in GMF Elements and the acquire-release protocol in Data Flow.

Principles

Responsibilities of Three Objects

Multimedia processing is typically composed of multiple steps chained together, such as “read file - decode MP3 - resample - write I2S.” Each step is an independent algorithm, and they must be started in the correct order, pass data step by step, and clean up together when an error or end-of-stream occurs. GMF-Core splits these concerns across three objects.

An element is the concrete work executor: It implements three callback functions: open, process, and close. The framework guarantees these are called in the order open - process × N - close; element developers only need to focus on the processing logic of a single call.

A pipeline is the orchestrator: It connects multiple elements in sequence and exposes control interfaces such as run, stop, pause, resume, reset, and seek. Application code only interacts with the pipeline; event dispatching, IO open/close, and error cleanup are handled by the pipeline automatically. The pipeline itself does not execute element code.

A task is the executor: It is essentially a runtime unit encapsulated by the framework. A task maintains a job list and calls each element’s callback functions in a defined order. The pipeline describes the “connection topology” and the task describes the “runtime configuration;” separating them allows the same pipeline to be bound to tasks with different configurations (different stack, priority, CPU core).

Overview of the three-object collaboration:

        flowchart TB
    User["User Code"]
    Pipeline["Pipeline"]
    Task["Task"]
    Element["Element Chain"]

    User -->|"run / stop / pause"| Pipeline
    Pipeline -->|"Control Commands"| Task
    Task -->|"State Events"| Pipeline
    Pipeline -->|"State Callback"| User
    Task -->|"Call Callbacks"| Element
    Element -->|"Format Info"| Pipeline
    

Runtime Sequence of Jobs and Events

The open, process, and close of an element all exist as jobs inside the task. When jobs are scheduled and when events are called back follow a fixed sequence. The diagram below shows the complete flow of the control plane and event plane after a run call:

        sequenceDiagram
    participant U as User
    participant P as Pipeline
    participant T as Task
    participant E1 as Element 1
    participant E2 as Element 2

    U->>P: run()
    P->>T: Start task
    T-->>P: CHANGE_STATE: OPENING
    P-->>U: State callback

    T->>E1: open
    T->>E1: process (first round)
    E1-->>P: REPORT_INFO (format)
    P->>E2: Write format info + register open/process job
    T->>E2: open
    T->>E2: process (first round)

    T-->>P: CHANGE_STATE: RUNNING
    P-->>U: State callback

    loop running loop
        T->>E1: process
        T->>E2: process
    end

    Note over T: Trigger STOP / FINISH / ERROR
    T->>E1: close
    T->>E2: close
    T-->>P: CHANGE_STATE: STOPPED/FINISHED/ERROR
    P-->>U: State callback
    

The sequence contains three rules: CHANGE_STATE is reported by the task and forwarded by the pipeline to user callbacks; REPORT_INFO is reported by the element, and the pipeline uses it to write format info into downstream dependent elements; non-dependent elements register open/process jobs at loading_jobs, while dependent elements register open/process jobs after receiving upstream format info.

Element Lifecycle and Three Derived Types

Each element must implement three callback functions, corresponding to the initialization, data processing, and resource cleanup phases, which the framework calls in a fixed order.

open: One-time initialization. The element configures itself based on format information provided by upstream, for example, an MP3 decoder initializes its decoder context, allocates work buffers, and configures filter coefficients based on sample rate. If open succeeds, the element waits for process to be scheduled; if it returns failure, the pipeline immediately enters ERROR and subsequent elements’ open calls are not executed.

process: The data processing main loop. This callback is called repeatedly, each time executing one round of acquire/process/release on the input and output ports. The return value of process determines what the task does next (continue, report completion, report error); specific return codes are listed in the next section.

close: Resource cleanup. Whether the pipeline exits due to normal end-of-stream, user stop, or error, the framework calls the close of each element that has been opened in sequence. The close implementation should correspond one-to-one with resources allocated in open; even if an error occurs, it is recommended to only log the error and let the framework continue executing subsequent elements’ close calls, to avoid resource leaks.

Based on the type of data processed, elements derive into three subclasses, differing in the specialized format information structure each carries.

Derived Class	Info Structure	Fields
esp_gmf_audio_element_t	esp_gmf_info_sound_t	Sample rate, channels, bit depth, FourCC
esp_gmf_video_element_t	esp_gmf_info_video_t	Resolution, frame rate, FourCC
esp_gmf_pic_element_t	esp_gmf_info_pic_t	Width, height

Formats are identified by FourCC. For all macro definitions and a table organized by category, see GMF FourCC.

Task Three-Phase Scheduling

After the task starts, it executes the job list in three phases: opening - running - cleanup.

opening: The task iterates through the job list, calls open for each element in turn, and immediately calls process once on success. The first process call allows elements to report format info early, so downstream dependent elements can be awakened. If an element’s open returns failure, the pipeline immediately enters ERROR.

running: Calls process in the order elements are chained, looping continuously. Each round ends and immediately begins the next, until one of the following exit conditions is triggered:

• An element’s process returns ESP_GMF_JOB_ERR_DONE; the element is permanently complete and removed from the job list. When all elements are DONE, the task enters the FINISH flow.

• An element’s process returns ESP_GMF_JOB_ERR_FAIL; the task immediately enters the ERROR flow.

• An element’s process returns ESP_GMF_JOB_ERR_ABORT; the task enters the ABORT flow.

• The user calls esp_gmf_pipeline_stop(); the task detects the STOP flag at the next job boundary and enters the STOP flow.

cleanup: Regardless of how running is exited, the task appends and executes the close of each element that has been opened. Each open corresponds to one close. After cleanup, the task enters one of STOPPED, FINISHED, or ERROR and notifies the pipeline via an event callback.

Job Return Code Effects on Scheduling

The open, process, and close of an element all exist as jobs inside the framework, and the return value determines how the task schedules next.

Return Code	Value	Scheduling Behavior
ESP_GMF_JOB_ERR_OK	0	Completed normally. One-shot jobs are removed from the list; infinite jobs are retained for the next round.
ESP_GMF_JOB_ERR_CONTINUE	1	Immediately jumps to the first element’s job and begins execution; jobs after the current element are skipped this round. Commonly used when an element finds insufficient data and needs to fetch more.
ESP_GMF_JOB_ERR_DONE	2	Job permanently complete; immediately removed from the list. Even infinite jobs are no longer scheduled.
ESP_GMF_JOB_ERR_TRUNCATE	3	The current job is saved to the job stack; the next round continues from the element that returned ESP_GMF_JOB_ERR_TRUNCATE. Generally used when the output buffer is full and downstream must consume data before writing can continue.
ESP_GMF_JOB_ERR_FAIL	-1	Execution failed; triggers the task’s ERROR flow.
ESP_GMF_JOB_ERR_ABORT	-3	Actively aborted; subsequent flow (STOP or RESET) is determined by the abort strategy.

TRUNCATE combined with the job stack allows an element to pause itself in scenarios where “processing is not complete, but downstream needs to execute first,” waiting for downstream to consume data before resuming. For example, an upstream element with a block-type port returns TRUNCATE when its output buffer is full, letting downstream consume first before resuming the current write flow.

Basic Example

The following uses the pool to manage element templates in bulk and builds a minimal “file - decode - resample - I2S” pipeline. The pool is suitable for registering all supported elements once at application startup, then composing various pipelines by name.

First, at application startup, register the elements and IOs to be used in the pool:

esp_gmf_pool_handle_t pool;
esp_gmf_pool_init(&pool);

esp_gmf_pool_register_element(pool, audio_decoder_handle, NULL);
esp_gmf_pool_register_element(pool, audio_rate_cvt_handle, NULL);
esp_gmf_pool_register_io(pool, file_io_handle, NULL);
esp_gmf_pool_register_io(pool, i2s_io_handle, NULL);

Second, build the pipeline by name, bind the task, load jobs, then run:

const char *el_names[] = {"aud_dec", "aud_rate_cvt"};
esp_gmf_pipeline_handle_t pipe = NULL;
esp_gmf_pool_new_pipeline(pool, "io_file", el_names, 2, "io_i2s", &pipe);

esp_gmf_task_handle_t task = NULL;
esp_gmf_task_cfg_t task_cfg = DEFAULT_ESP_GMF_TASK_CONFIG();
task_cfg.thread.stack = 8 * 1024;
task_cfg.name = "player_task";
esp_gmf_task_init(&task_cfg, &task);

esp_gmf_pipeline_bind_task(pipe, task);
esp_gmf_pipeline_loading_jobs(pipe);
esp_gmf_pipeline_set_event(pipe, my_event_cb, my_ctx);

esp_gmf_pipeline_set_in_uri(pipe, "/sdcard/song.mp3");
esp_gmf_pipeline_run(pipe);

Meaning of each step:

• esp_gmf_pool_new_pipeline() looks up templates by tag string internally, calls esp_gmf_obj_dupl to copy fresh instances, chains them in order, and binds head/tail IOs.

• esp_gmf_task_init() creates a task. esp_gmf_task_cfg_t allows configuring stack size, priority, CPU core, and whether to place the stack in external PSRAM. DEFAULT_ESP_GMF_TASK_CONFIG() provides defaults of 4 KB stack, priority 5, core 0.

• esp_gmf_pipeline_bind_task() establishes the association between the pipeline and the task, and sets the task’s event callback to the pipeline’s internal event handler. After this step, any state change during task execution is sensed by the pipeline.

• esp_gmf_pipeline_loading_jobs() registers the open and process of elements into the task’s job list. Only elements in INITIALIZED state are registered; dependent elements are not registered until the pipeline receives REPORT_INFO from upstream, at which point the pipeline registers their open/process jobs.

• esp_gmf_pipeline_run() starts the task and begins executing the job list in sequence.

To adjust parameters of a specific element, retrieve the handle via esp_gmf_pipeline_get_el_by_name() and modify:

esp_gmf_element_handle_t dec = NULL;
esp_gmf_pipeline_get_el_by_name(pipe, "aud_dec", &dec);
mp3_decoder_cfg_t *cfg = (mp3_decoder_cfg_t *)OBJ_GET_CFG(dec);
cfg->out_rb_size = 8 * 1024;

Without the pool, you can also build manually: call esp_gmf_pipeline_create - register_el - set_io - bind_task - loading_jobs - run in sequence. The pool performs the same steps internally, saving you from writing repetitive registration code.

Advanced Topics

Deferred Startup of Dependent Elements

A common problem in multimedia processing: some elements’ initialization parameters can only be obtained after upstream elements have started processing. A typical example is a resampler, which can only be configured when the input sample rate is known, but the sample rate is only available after the MP3 decoder has parsed the file header. If all elements are opened together when the pipeline starts, the resampler either initializes with incorrect default values or fails to open.

GMF-Core solves this kind of forward dependency using the dependency flag and the REPORT_INFO event:

1. The developer sets dependency = true in the element’s configuration, declaring that the element requires upstream information to initialize.

2. After the pipeline starts, the task calls open and process on non-dependent elements first, and does not schedule dependent elements yet.

3. After the upstream element parses format info in its own open or process, it reports via the REPORT_INFO event.

4. The pipeline receives the event, writes the info into the downstream dependent element, and triggers that element to enter INITIALIZED state.

5. The pipeline registers the open and process jobs for that element, and the task subsequently schedules it according to the job list.

Dependencies can be cascaded: a pipeline can have multiple dependent elements chained together, each registering open/process jobs only after its upstream reports format info. Application code does not need to write coordination logic; the pipeline handles registration and scheduling according to the rules above.

Format Information and REPORT_INFO

Format information is used to pass audio/video parameters between elements; the relevant structures are defined in esp_gmf_info.h. Audio elements commonly use esp_gmf_info_sound_t to describe sample rate, channels, bit depth, and FourCC; video elements use esp_gmf_info_video_t to describe width/height, frame rate, and pixel format. After an element parses format info in open or process, it reports it to the pipeline via the REPORT_INFO event.

esp_gmf_info_sound_t snd = {
    .format_id    = ESP_FOURCC_PCM,
    .sample_rates = 44100,
    .bitrate      = 0,
    .channels     = 2,
    .bits         = 16,
};
esp_gmf_audio_el_set_snd_info(handle, &snd);
esp_gmf_element_notify_snd_info(handle, &snd);

After the pipeline receives REPORT_INFO, it writes the format info into downstream dependent elements and registers open/process jobs for elements whose dependencies are satisfied. Therefore, REPORT_INFO is not only a notification event to the user, but also the trigger for deferred startup of dependent elements. Applications can also actively report format info via esp_gmf_pipeline_report_info() for scenarios where no upstream element reports automatically.

Advanced Pool API

In addition to basic registration and build interfaces, the pool also provides three advanced usages.

Insert high-priority templates: esp_gmf_pool_register_element_at_head() behaves the same as esp_gmf_pool_register_element(), except it inserts the element at the head of the linked list. The pool searches templates in linked list order, with earlier registrations matching first; therefore, a custom element registered with _at_head can override a default implementation with the same name.

Auto-select IO by URL: esp_gmf_pool_get_io_tag_by_url() iterates all IO templates in the pool, calls each IO’s get_score callback to score the URL, and returns the IO tag with the highest score.

char *io_tag = NULL;
esp_gmf_pool_get_io_tag_by_url(pool, "http://server/song.mp3",
                               ESP_GMF_IO_DIR_READER, &io_tag);
/* io_tag is typically "io_http", used as the in_name for esp_gmf_pool_new_pipeline */

For detailed scoring level definitions, see the “URL Scoring Strategy” section in Data Flow.

Iterate registered templates: esp_gmf_pool_iterate_element() and esp_gmf_pipeline_iterate_element() provide an iterator-based traversal, commonly used for log output, capability probing, or debugging. Initialize *iterator to NULL and call repeatedly until ESP_GMF_ERR_NOT_FOUND is returned.

const void *it = NULL;
esp_gmf_element_handle_t el = NULL;
while (esp_gmf_pool_iterate_element(pool, &it, &el) == ESP_GMF_ERR_OK) {
    const char *tag = NULL;
    esp_gmf_obj_get_tag((esp_gmf_obj_handle_t)el, &tag);
    ESP_LOGI("APP", "registered element: %s", tag);
}

Task Strategy and Abort Flow

The task’s default behavior is: when all jobs are DONE, enter FINISHED; when a job FAILs, enter ERROR; when a job ABORTs, enter STOPPED. For scenarios requiring special behavior, register a strategy function via esp_gmf_task_set_strategy_func() to override the default.

The strategy function is called at two trigger points:

• GMF_TASK_STRATEGY_TYPE_FINISH: when all jobs return DONE

• GMF_TASK_STRATEGY_TYPE_ABORT: when a job returns ABORT

The return value of the strategy function determines which path the task takes next:

• GMF_TASK_STRATEGY_ACTION_DEFAULT: follow the default flow to enter the terminal state

• GMF_TASK_STRATEGY_ACTION_RESET: load the reset job for each element, restore to INITIALIZED. Suitable for “auto-advance to next track after playback ends” scenarios, avoiding rebuilding the entire pipeline.

• GMF_TASK_STRATEGY_ACTION_STOP: load close jobs to enter the STOP flow

Strategy functions must not call any task or pipeline control APIs internally, as this would trigger timeout errors. If waiting for an external event is needed, use a blocking mechanism such as a semaphore.

The semantic difference between stop and abort: stop is initiated by the user calling esp_gmf_pipeline_stop() / esp_gmf_task_stop(); the task detects the STOP flag at the next job boundary and enters cleanup - a soft stop where the currently executing job completes its current call before exiting. abort is triggered by an element returning ESP_GMF_JOB_ERR_ABORT in process, or by the data layer calling esp_gmf_db_abort / esp_gmf_io_abort; when a network disconnection occurs, the HTTP IO reports ESP_GMF_IO_ABORT, and the element converts this IO error into an ABORT return code for the job. After abort, the task enters STOPPED or RESET based on the strategy function; combined with the RESET action, this enables a recovery flow without destroying the pipeline, such as “resume playing the same audio after reconnecting” or “switch to the next track.”

Error Handling Path

When any element’s job returns FAIL, the task cleans up and notifies in the following order:

1. The task removes all unexecuted process jobs from the job list, preventing new data processing actions.

2. The task appends the close of each element that has been opened to the end of the job list.

3. The task executes each close in turn, allowing elements to release their allocated resources.

4. The pipeline’s event handler receives CHANGE_STATE = ERROR and calls the close of the input and output IOs to close the peripherals.

5. The pipeline forwards the ERROR event to the user-registered callback.

This path is idempotent: even if a close itself fails, the task continues processing remaining closes until the list is empty, preventing a single element’s failure from blocking the entire cleanup flow. After entering ERROR, the pipeline stays in that state; esp_gmf_pipeline_reset() must be called to clear the state before the pipeline can be restarted.

A failed open of the input or output IO also triggers the same path. For example, when an input file cannot be opened, the pipeline’s event handler detects that the IO open returned non-OK, directly switches the state to ERROR, and initiates cleanup.

Combining Multiple Pipelines

An application is often composed of multiple pipelines (for example, a decode pipeline and a render pipeline bridged by a ringbuffer). GMF-Core provides the following interfaces to support pipeline composition.

Event cascading: esp_gmf_pipeline_reg_event_recipient() adds connectee to connector’s evt_conveyor chain. After this, any REPORT_INFO event received by connector is also forwarded to connectee, so dependent elements in the downstream pipeline can be awakened when the upstream pipeline obtains format info.

esp_gmf_pipeline_connect_pipe() additionally, on top of event cascading, directly connects the out port of an element in connector to the in port of an element in connectee. This is used when fine-grained connection of specific elements across two pipelines is needed.

Pre/post callbacks: esp_gmf_pipeline_set_prev_run_cb() and esp_gmf_pipeline_set_prev_stop_cb() allow inserting custom actions before run and stop. A common use case is dependency management: notifying downstream to stop first before upstream stops, preventing downstream from continuing to wait for data after upstream has stopped. These callbacks can also be triggered manually via esp_gmf_pipeline_prev_run() / esp_gmf_pipeline_prev_stop(); once triggered manually, they are not called again by run / stop.

pause-on-start: esp_gmf_pipeline_set_pause_on_start() makes the pipeline immediately enter PAUSED after run, without executing process. A typical use case is when multiple pipelines need to start simultaneously: each enters PAUSED first, then a unified resume ensures a synchronized start.

IO replacement: esp_gmf_pipeline_replace_in() / esp_gmf_pipeline_replace_out() allow replacing the head/tail IOs when the pipeline is not in RUNNING state, for scenarios such as “switching to a different song.” Ownership of the replaced old IO is returned to the user, who must destroy it manually.

Miscellaneous

Valid States for Control APIs

The pipeline exposes a unified set of control APIs that are all forwarded to the bound task internally. The table below lists the valid call states for each API; calling in an invalid state returns ESP_GMF_ERR_NOT_SUPPORT or ESP_GMF_ERR_INVALID_STATE. For the complete state enumeration, see GMF-Core Overview.

API	Valid States	Effect
esp_gmf_pipeline_run()	INITIALIZED / STOPPED / FINISHED	Triggers prev_run callback (if configured), starts the task, enters OPENING
esp_gmf_pipeline_stop()	RUNNING / PAUSED	Triggers prev_stop callback (if configured), requests the task to stop, enters STOPPED
esp_gmf_pipeline_pause()	RUNNING	Suspends process scheduling, preserves context, enters PAUSED
esp_gmf_pipeline_resume()	PAUSED	Releases the suspend semaphore, restores to RUNNING
esp_gmf_pipeline_reset()	Non-RUNNING	Clears job list, resets element and port state, returns to INITIALIZED
esp_gmf_pipeline_seek()	PAUSED / STOPPED / FINISHED	Calls the input IO’s seek interface to jump to a specified position

A few details worth noting:

• pause sets the PAUSE flag; the task blocks on a semaphore at the next job boundary. resume releases the semaphore to let the task continue. Pause occurs at job boundaries, not inside jobs, to avoid interrupting an element in the middle of data processing.

• reset clears the task’s job list and calls each element’s reset_state and reset_port. After reset, before running again, esp_gmf_pipeline_loading_jobs() must be called to reload jobs.

• seek is only meaningful for streaming formats that support independent frame decoding (such as MP3, AAC, TS). The pipeline must be in a non-running state before calling, to avoid the IO being read concurrently during seek.

Timeout and Synchronization Semantics

All control APIs block by default, with a maximum wait time controlled by DEFAULT_TASK_OPT_MAX_TIME_MS (2000 ms). This timeout can be adjusted via esp_gmf_task_set_timeout().

stop behaves slightly differently: even if it times out and returns ESP_GMF_ERR_TIMEOUT, the stop action continues in the background. The retry logic inside the task continues to wait until all jobs exit, ensuring resources are in a stable state. pause similarly takes effect even after timeout; the caller can choose to wait again or proceed with subsequent flow.

Stop and Timeout

esp_gmf_pipeline_stop() returning ESP_GMF_ERR_TIMEOUT does not mean the stop failed; it means the synchronous wait did not complete within the time limit, while the stop action continues in the background. The common cause is an element performing a long blocking operation in process (such as waiting for network data or a mutex). Two ways to handle this: increase the value set by esp_gmf_task_set_timeout(), or check the task’s abort flag in the element implementation to exit proactively.

Dependency Not Started

If an element still has not opened after loading_jobs, it is usually because it is marked as dependency = true but upstream has never reported format info. Confirm that the upstream element calls esp_gmf_element_notify_snd_info (or the corresponding derived class’s notify interface) in its open or process, or that the application layer actively reports info via esp_gmf_pipeline_report_info().

Recovery from ERROR

Calling run in ERROR state returns ESP_GMF_ERR_NOT_SUPPORT. The recovery steps are: call esp_gmf_pipeline_reset() to return the state to INITIALIZED, then call esp_gmf_pipeline_loading_jobs() to reload jobs, and only then can you run.

Pipeline Blocked after Abort

After an element returns ABORT, the task enters the strategy function. If the strategy function returns GMF_TASK_STRATEGY_ACTION_DEFAULT, the pipeline exits via the STOPPED path and must be reset before it can run again. If you want automatic recovery after abort, register a strategy function returning GMF_TASK_STRATEGY_ACTION_RESET. Strategy functions must not call any pipeline control APIs.

State Still RUNNING after Pause

This should not occur under normal circumstances. pause waits for the task to process the pause request; only after the task enters PAUSED does it return ESP_GMF_ERR_OK. Therefore, querying the state after pause returns OK should read PAUSED, not RUNNING.

If the task does not reach the next job boundary promptly, pause returns ESP_GMF_ERR_TIMEOUT. This return value only means the synchronous wait timed out this time, not that the pause request was cancelled; the pause request will still take effect at the next job boundary. Therefore, querying the state immediately after a timeout return may still show RUNNING.

API Reference

Core header files covered in this document:

• esp_gmf_pipeline.h: Pipeline creation, control, and cascading

• esp_gmf_task.h: Task configuration, control, and strategy

• esp_gmf_job.h: Job structures, return codes, and job stack

• esp_gmf_pool.h: Pool registration and instantiation

• esp_gmf_info.h: Audio/video format information structures

For element base class and three derived element interfaces, see the “API Reference” in GMF Elements; for IO interfaces, see Data Flow.

Header File

• gmf_core/include/esp_gmf_pipeline.h

Functions

esp_gmf_err_t esp_gmf_pipeline_create(esp_gmf_pipeline_handle_t *pipeline)

Create a new GMF pipeline.

Parameters:

pipeline – [out] Pointer to store the newly created GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pipeline_destroy(esp_gmf_pipeline_handle_t pipeline)

Destroy a GMF pipeline, freeing associated resources.

Parameters:

pipeline – [in] GMF pipeline handle to destroy

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

esp_gmf_err_t esp_gmf_pipeline_set_io(esp_gmf_pipeline_handle_t pipeline, esp_gmf_io_handle_t io, int dir)

Set the I/O handle for a GMF pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• io – [in] GMF I/O handle

• dir – [in] I/O direction (input or output)

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or I/O port is invalid

esp_gmf_err_t esp_gmf_pipeline_register_el(esp_gmf_pipeline_handle_t pipeline, esp_gmf_element_handle_t el)

Register a GMF element with a GMF pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• el – [in] GMF element handle to register

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG if the pipeline handle or element is invalid

esp_gmf_err_t esp_gmf_pipeline_list_el(esp_gmf_pipeline_handle_t pipeline)

List all GMF elements in the pipeline.

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

esp_gmf_err_t esp_gmf_pipeline_set_event(esp_gmf_pipeline_handle_t pipeline, esp_gmf_event_cb cb, void *ctx)

Set the event callback function for a GMF pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• cb – [in] Event callback function

• ctx – [in] Context to be passed to the callback function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

esp_gmf_err_t esp_gmf_pipeline_bind_task(esp_gmf_pipeline_handle_t pipeline, esp_gmf_task_handle_t task)

Bind a given task to the pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• task – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or task handle is invalid

esp_gmf_err_t esp_gmf_pipeline_loading_jobs(esp_gmf_pipeline_handle_t pipeline)

Load linked element jobs to the bind task on the specific pipeline.

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or task handle is invalid

esp_gmf_err_t esp_gmf_pipeline_set_in_uri(esp_gmf_pipeline_handle_t pipeline, const char *uri)

Set the input URI for the specific pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• uri – [in] Input URI

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

• ESP_GMF_ERR_MEMORY_LACK Memory allocation for URI failed

esp_gmf_err_t esp_gmf_pipeline_set_out_uri(esp_gmf_pipeline_handle_t pipeline, const char *uri)

Set the output URI for specific pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• uri – [in] Output URI

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

• ESP_GMF_ERR_MEMORY_LACK Memory allocation for URI failed

esp_gmf_err_t esp_gmf_pipeline_reg_event_recipient(esp_gmf_pipeline_handle_t connector, esp_gmf_pipeline_handle_t connectee)

Register an event recipient for specific pipeline.

Parameters:

• connector – [in] GMF pipeline handle of the connector

• connectee – [in] GMF pipeline handle of the connectee

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handles are invalid

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pipeline_connect_pipe(esp_gmf_pipeline_handle_t connector, const char *connector_name, esp_gmf_port_handle_t connector_port, esp_gmf_pipeline_handle_t connectee, const char *connectee_name, esp_gmf_port_handle_t connectee_port)

Connect two GMF pipelines.

Parameters:

• connector – [in] GMF pipeline handle of the connector

• connector_name – [in] Name of the connector element

• connector_port – [in] Port handle of the connector element

• connectee – [in] GMF pipeline handle of the connectee

• connectee_name – [in] Name of the connectee element

• connectee_port – [in] Port handle of the connectee element

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the handles are invalid

• ESP_GMF_ERR_NOT_FOUND The connector_name is not in the connector pipeline, or connectee_name is not in the connectee pipeline

• ESP_GMF_ERR_NOT_SUPPORT The given port is not support

esp_gmf_err_t esp_gmf_pipeline_set_prev_run_cb(esp_gmf_pipeline_handle_t pipeline, esp_gmf_pipeline_prev_act prev_run, void *ctx)

Set action callback before do esp_gmf_pipeline_run If prev_run is NULL, no previous run function will be invoked.

Parameters:

• pipeline – [in] Handle to the GMF pipeline

• prev_run – [in] Callback function to execute before run the pipeline

• ctx – [in] Context to be passed to the previous action function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid pipeline or callback argument

esp_gmf_err_t esp_gmf_pipeline_set_prev_stop_cb(esp_gmf_pipeline_handle_t pipeline, esp_gmf_pipeline_prev_act prev_stop, void *ctx)

Set action callback before do esp_gmf_pipeline_stop If prev_stop is NULL, no previous stop function will be invoked.

Parameters:

• pipeline – [in] Handle to the GMF pipeline

• prev_stop – [in] Callback function to execute before stop the pipeline

• ctx – [in] Context to be passed to the previous action function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid pipeline or callback argument

esp_gmf_err_t esp_gmf_pipeline_prev_run(esp_gmf_pipeline_handle_t pipeline)

Manually trigger the previous run action for a pipeline.

Note

Typically used to perform setup operations before dependency pipelines run

Parameters:

pipeline – [in] Handle to the GMF pipeline

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid pipeline

esp_gmf_err_t esp_gmf_pipeline_prev_stop(esp_gmf_pipeline_handle_t pipeline)

Manually trigger the previous stop action for a pipeline.

Note

Typically used to perform cleanup operations before dependency pipelines stop

Parameters:

pipeline – [in] Handle to the GMF pipeline

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid pipeline

esp_gmf_err_t esp_gmf_pipeline_set_pause_on_start(esp_gmf_pipeline_handle_t pipeline, bool enable)

Set pause_on_start flag for a GMF pipeline.

Note

Typically used to configure the pipeline behavior to pause status after call esp_gmf_pipeline_run This must be called before esp_gmf_pipeline_run

Parameters:

• pipeline – [in] Handle to the GMF pipeline

• enable – [in] Enable or disable automatic paused when pipeline start run

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid pipeline

esp_gmf_err_t esp_gmf_pipeline_run(esp_gmf_pipeline_handle_t pipeline)

Run the specific pipeline using esp_gmf_task_run, which blocks by default for DEFAULT_TASK_OPT_MAX_TIME_MS To change the waiting time, use esp_gmf_task_set_timeout

Note

This API will automatically trigger the prev_run action if configured and not manually triggered yet

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or thread handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT Indicating the state of task is ESP_GMF_EVENT_STATE_PAUSED or ESP_GMF_EVENT_STATE_RUNNING

• ESP_GMF_ERR_INVALID_STATE The task is not running

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_pipeline_stop(esp_gmf_pipeline_handle_t pipeline)

Stop a running pipeline using esp_gmf_task_stop, which blocks by default for DEFAULT_TASK_OPT_MAX_TIME_MS To change the waiting time, use esp_gmf_task_set_timeout

Note

This API will automatically trigger the prev_stop action if configured and not manually triggered yet

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or thread handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is ESP_GMF_EVENT_STATE_NONE

• ESP_GMF_ERR_INVALID_STATE The task is not running

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_pipeline_pause(esp_gmf_pipeline_handle_t pipeline)

Pause a running GMF pipeline using esp_gmf_task_pause, which blocks by default for DEFAULT_TASK_OPT_MAX_TIME_MS To change the waiting time, use esp_gmf_task_set_timeout

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or thread handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is not ESP_GMF_EVENT_STATE_RUNNING

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_pipeline_resume(esp_gmf_pipeline_handle_t pipeline)

Resume a paused GMF pipeline using esp_gmf_task_resume, which blocks by default for DEFAULT_TASK_OPT_MAX_TIME_MS To change the waiting time, use esp_gmf_task_set_timeout

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or thread handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is not ESP_GMF_EVENT_STATE_PAUSED

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_pipeline_reset(esp_gmf_pipeline_handle_t pipeline)

Reset the GMF pipeline to its initial state, including job lists, port states, and element states To run the pipeline again, esp_gmf_pipeline_loading_jobs must be called.

Parameters:

pipeline – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

esp_gmf_err_t esp_gmf_pipeline_seek(esp_gmf_pipeline_handle_t pipeline, uint64_t pos)

Seeking to a specific position in the pipeline calls io_seek, which means it only supports streaming audio formats like MP3, AAC, and TS, where each frame can be decoded independently.

Parameters:

• pipeline – [in] GMF pipeline handle

• pos – [in] Position to seek to

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

• ESP_GMF_ERR_INVALID_STATE

esp_gmf_err_t esp_gmf_pipeline_get_linked_pipeline(esp_gmf_pipeline_handle_t connector, const void **iterator, esp_gmf_pipeline_handle_t *connectee)

Retrieve the linked pipeline from given pipeline.

Parameters:

• connector – [in] Handle to the GMF connector pipeline

• iterator – [out] A void pointer to the iterative pipeline

• connectee – [out] Handle to the connected pipeline

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid connector or connectee handle

• ESP_GMF_ERR_NOT_FOUND No linked pipeline found

• ESP_GMF_ERR_INVALID_STATE Connector is not in a valid state for linking

esp_gmf_err_t esp_gmf_pipeline_get_in(esp_gmf_pipeline_handle_t pipeline, esp_gmf_io_handle_t *io_handle)

Get the input I/O of a GMF pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• io_handle – [out] Pointer to store the input I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

esp_gmf_err_t esp_gmf_pipeline_get_out(esp_gmf_pipeline_handle_t pipeline, esp_gmf_io_handle_t *io_handle)

Get the output I/O of a GMF pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• io_handle – [out] Pointer to store the output I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline or thread handle is invalid

esp_gmf_err_t esp_gmf_pipeline_replace_in(esp_gmf_pipeline_handle_t pipeline, esp_gmf_io_handle_t new_one)

Replace the input I/O of a GMF pipeline with a new one.

Note

Call esp_gmf_pipeline_get_in function before you call this function Because of the pineline in will be overwritten and the replaced MUST release by user

Parameters:

• pipeline – [in] GMF pipeline handle

• new_one – [in] New input I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or new I/O handle is invalid

• ESP_GMF_ERR_INVALID_STATE The pipeline is running, replace is not safe

esp_gmf_err_t esp_gmf_pipeline_replace_out(esp_gmf_pipeline_handle_t pipeline, esp_gmf_io_handle_t new_one)

Replace the output I/O of a GMF pipeline with a new one.

Note

Call esp_gmf_pipeline_get_out function before you call this function Because of the pineline in will be overwritten and the replaced MUST release by user

Parameters:

• pipeline – [in] GMF pipeline handle

• new_one – [in] New output I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or new I/O port handle is invalid

• ESP_GMF_ERR_INVALID_STATE The pipeline is running, replace is not safe

esp_gmf_err_t esp_gmf_pipeline_get_head_el(esp_gmf_pipeline_handle_t pipeline, esp_gmf_element_handle_t *head)

Get the header GMF element in the pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• head – [out] Head element of the pipeline

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or head element is invalid

esp_gmf_err_t esp_gmf_pipeline_get_next_el(esp_gmf_pipeline_handle_t pipeline, esp_gmf_element_handle_t head, esp_gmf_element_handle_t *next)

Get the next GMF element in the pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• head – [in] Head element of the pipeline

• next – [out] Pointer to store the next GMF element handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or head element is invalid

esp_gmf_err_t esp_gmf_pipeline_get_el_by_name(esp_gmf_pipeline_handle_t pipeline, const char *tag, esp_gmf_element_handle_t *out_handle)

Get a element in specific pipeline by its name.

Parameters:

• pipeline – [in] GMF pipeline handle

• tag – [in] Name of the wanted element

• out_handle – [out] Pointer to store the element handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle or tag is invalid

• ESP_GMF_ERR_NOT_FOUND It’s not found the element by given tag

esp_gmf_err_t esp_gmf_pipeline_iterate_element(esp_gmf_pipeline_handle_t handle, const void **iterator, esp_gmf_element_handle_t *el)

Iterate pipeline to retrieve element.

Parameters:

• handle – [in] GMF pipeline handle

• iterator – [out] To retrieve first element set *iterator = NULL, after that do not modify *iterator any more

• el – [out] To store retrieved element handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_NOT_FOUND Iterate finished, no more elements found

esp_gmf_err_t esp_gmf_pipeline_reg_el_port(esp_gmf_pipeline_handle_t pipeline, const char *tag, esp_gmf_io_dir_t io_dir, esp_gmf_io_handle_t port)

Register an I/O port for an element within the pipeline.

Parameters:

• pipeline – [in] GMF pipeline handle

• tag – [in] Name of the GMF element

• io_dir – [in] I/O direction type (input or output)

• port – [in] I/O port handle to register

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle, tag, or port handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The specified port type is not supported, or the element can’t connect more port, or the given direction is not supported

• ESP_GMF_ERR_NOT_FOUND It’s not found the element by given tag

esp_gmf_err_t esp_gmf_pipeline_report_info(esp_gmf_pipeline_handle_t pipeline, esp_gmf_info_type_t info_type, void *value, int len)

Report information from first element of pipeline.

Note

This function is only for the GMF’s first element, which does not report music information. However, this information is used by the linked elements. For example, if the pipeline is rate conversion -> channel conversion -> encoder -> file, the rate conversion and channel conversion elements require the music information to trigger their loading jobs. Therefore, this API is called to report the music information to the first element.

Parameters:

• pipeline – [in] The handle to the GMF pipeline

• info_type – [in] The type of information to report, specified by esp_gmf_info_type_t

• value – [in] Pointer to the buffer where the information will be stored

• len – [in] Length of the buffer pointed to by value, in bytes

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid argument(s) provided

• ESP_GMF_ERR_MEMORY_LACK Insufficient memory to store the information

• ESP_GMF_ERR_NOT_SUPPORTED The requested information type is not supported

esp_gmf_err_t esp_gmf_pipeline_show(esp_gmf_pipeline_handle_t handle)

Print information about a GMF pipeline.

Parameters:

handle – [in] GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the pipeline handle is invalid

Structures

struct esp_gmf_pipeline

Structure representing a pipeline in GMF.

Public Members

esp_gmf_element_handle_t head_el

Handle of the first element in the pipeline

esp_gmf_element_handle_t last_el

Handle of the last element in the pipeline

esp_gmf_io_handle_t in

Handle of the input I/O port

esp_gmf_io_handle_t out

Handle of the output I/O port

esp_gmf_event_item_t *evt_conveyor

Event conveyor list

esp_gmf_event_cb evt_acceptor

Event acceptor callback function

esp_gmf_event_cb user_cb

User callback function

void *user_ctx

User context

esp_gmf_event_state_t state

Current state of the pipeline

esp_gmf_task_handle_t thread

Handle of the task associated with the pipeline

esp_gmf_pipeline_prev_act prev_run

A pointer to the previous run callback

esp_gmf_pipeline_prev_act prev_stop

A pointer to the previous stop callback

void *prev_run_ctx

The previous run context

void *prev_stop_ctx

The previous stop context

uint8_t prev_state

The previous action state

uint8_t pause_on_start

Whether automatic paused before processing

void *lock

Lock for thread synchronization

struct esp_gmf_pipeline_cfg

The GMF pipeline configuration structure.

Public Members

esp_gmf_event_cb event

Event callback function

Macros

ESP_GMF_PIPELINE_GET_IN_INSTANCE(p)

ESP_GMF_PIPELINE_GET_OUT_INSTANCE(p)

ESP_GMF_PIPELINE_GET_FIRST_ELEMENT(p)

ESP_GMF_PIPELINE_GET_LAST_ELEMENT(p)

Type Definitions

typedef struct esp_gmf_pipeline *esp_gmf_pipeline_handle_t

Pointer to a GMF pipeline.

typedef esp_gmf_err_t (*esp_gmf_pipeline_prev_act)(void *handle)

Function pointer type for pipeline previous action callback.

typedef struct esp_gmf_pipeline esp_gmf_pipeline_t

Structure representing a pipeline in GMF.

typedef struct esp_gmf_pipeline_cfg esp_gmf_pipeline_cfg_t

The GMF pipeline configuration structure.

Header File

• gmf_core/include/esp_gmf_task.h

Functions

esp_gmf_err_t esp_gmf_task_init(esp_gmf_task_cfg_t *config, esp_gmf_task_handle_t *tsk_hd)

Initialize a GMF task.

Parameters:

• config – [in] Configuration for the GMF task

• tsk_hd – [out] Pointer to store the GMF task handle after initialization

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the configuration or handle is invalid

• ESP_GMF_ERR_MEMORY_LACK If there is insufficient memory to perform the initialization

• Others Indicating failure

esp_gmf_err_t esp_gmf_task_deinit(esp_gmf_task_handle_t handle)

Deinitialize a GMF task, freeing associated resources.

Parameters:

handle – [in] GMF task handle to deinitialize

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If the configuration or handle is invalid

esp_gmf_err_t esp_gmf_task_register_ready_job(esp_gmf_task_handle_t handle, const char *label, esp_gmf_job_func job, esp_gmf_job_times_t times, void *ctx, bool done)

Register a ready job to the specific GMF task This function allows dynamically registering a job to the task and the job will be executed in the order of registration.

Note

This function can only be called when the task is not running, and it’s not thread safe

Parameters:

• handle – [in] GMF task handle

• label – [in] Label for the job

• job – [in] Job function to register

• times – [in] Job execution times configuration

• ctx – [in] Context to be passed to the job function

• done – [in] Flag indicating whether the job is done

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_MEMORY_LACK Insufficient memory to perform the registration

esp_gmf_err_t esp_gmf_task_insert_head_job(esp_gmf_task_handle_t handle, const char *label, esp_gmf_job_func job, esp_gmf_job_times_t times, void *ctx)

Insert a job at the head of the job list in a GMF task This function allows dynamically inserting a job at the head of the job list and the previous head job will be moved to the second position.

Note

This function can only be called when the task is not running, and it’s not thread safe

Parameters:

• handle – [in] GMF task handle

• label – [in] Label for the job

• job – [in] Job function to insert

• times – [in] Job execution times configuration

• ctx – [in] Context to be passed to the job function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_MEMORY_LACK Insufficient memory to perform the insertion

esp_gmf_err_t esp_gmf_task_set_event_func(esp_gmf_task_handle_t handle, esp_gmf_event_cb cb, void *ctx)

Set the event callback function for a GMF task.

Parameters:

• handle – [in] GMF task handle

• cb – [in] Event callback function

• ctx – [in] Context to be passed to the callback function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

esp_gmf_err_t esp_gmf_task_set_strategy_func(esp_gmf_task_handle_t handle, esp_gmf_task_strategy_func func, void *ctx)

Set the strategy function for a GMF task, when the task is triggered by the strategy type, the strategy function will be called Currently, it supports the strategy type of GMF_TASK_STRATEGY_TYPE_ABORT and GMF_TASK_STRATEGY_TYPE_FINISH and the action of GMF_TASK_STRATEGY_ACTION_DEFAULT, GMF_TASK_STRATEGY_ACTION_RESET, and GMF_TASK_STRATEGY_ACTION_STOP is supported.

Note

In strategy function, do not call the task API or pipeline API, otherwise it will cause a timeout error. If you want to waiting some special outside event then return to the task, you can use the user event such as semaphore to block the strategy function.

Parameters:

• handle – [in] GMF task handle

• func – [in] Strategy function to set

• ctx – [in] Context to be passed to the strategy function

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

esp_gmf_err_t esp_gmf_task_set_pause_on_start(esp_gmf_task_handle_t handle)

Set pause on start for the task. If set, the task will behavior to pause status after call esp_gmf_task_run

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

esp_gmf_err_t esp_gmf_task_run(esp_gmf_task_handle_t handle)

Run the specific GMF task.

Note

The function returns once the worker task receives the run command If internal IO blocks (e.g., due to poor network conditions), the user may call esp_gmf_task_stop() to abort the ongoing jobs

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT Indicating the state of task is ESP_GMF_EVENT_STATE_PAUSED or ESP_GMF_EVENT_STATE_RUNNING

• ESP_GMF_ERR_INVALID_STATE The task is not running

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_task_stop(esp_gmf_task_handle_t handle)

Stop a running or paused GMF task.

    Guarantees all task jobs have exited before returning, ensuring resources are in a stable state

    Stop is executed in two stages:
    1. Wait up to the configured timeout
    2. If timeout occurs, print a warning and continue waiting until all jobs exit

Note

This API acts as the lifecycle synchronization barrier Operations that timed out in other APIs are guaranteed to be fully resolved when this function returns

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success or the task already stopped

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is ESP_GMF_EVENT_STATE_NONE

• ESP_GMF_ERR_INVALID_STATE The task is not running

• ESP_GMF_ERR_TIMEOUT The synchronization operation has timed out, but the stop still takes effect

esp_gmf_err_t esp_gmf_task_pause(esp_gmf_task_handle_t handle)

Pause a running GMF task This function may block for either the DEFAULT_TASK_OPT_MAX_TIME_MS or the time set by esp_gmf_task_set_timeout This function is used to pause a GMF task during its execution lifecycle. You can call this function after the task has been started with esp_gmf_task_run. The pause can only happen while the task is actively running. After all task elements (jobs) are completed or the task is stopped, pausing is no longer possible.

Note

- If ESP_GMF_ERR_TIMEOUT is returned, the pause operation is still effective. This just means the function did not finish waiting for the pause within the timeout, but the pause will still take effect in the background

• Calling esp_gmf_task_run or esp_gmf_task_resume will automatically clear the pause bit and restore the task to normal running state This makes it easy and intuitive—there’s no need to manually clear the pause status

• Supports the block time is zero, it will block until the pause operation is completed

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success or the task already paused

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is not ESP_GMF_EVENT_STATE_RUNNING

• ESP_GMF_ERR_TIMEOUT The synchronization operation has timed out, but the pause still takes effect

esp_gmf_err_t esp_gmf_task_resume(esp_gmf_task_handle_t handle)

Resume a paused GMF task only This function may block for either the DEFAULT_TASK_OPT_MAX_TIME_MS or the time set by esp_gmf_task_set_timeout.

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

• ESP_GMF_ERR_NOT_SUPPORT The state of task is not ESP_GMF_EVENT_STATE_PAUSED

• ESP_GMF_ERR_TIMEOUT Indicating that the synchronization operation has timed out

esp_gmf_err_t esp_gmf_task_reset(esp_gmf_task_handle_t handle)

Reset a GMF task to its initial state.

Parameters:

handle – [in] GMF task handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

esp_gmf_err_t esp_gmf_task_set_timeout(esp_gmf_task_handle_t handle, int wait_ms)

Set the synchronization timeout for run, stop, pause, and resume operations.

Parameters:

• handle – [in] GMF task handle

• wait_ms – [in] Timeout duration in milliseconds

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

esp_gmf_err_t esp_gmf_task_get_state(esp_gmf_task_handle_t handle, esp_gmf_event_state_t *state)

Get the state of the specific task.

Parameters:

• handle – [in] GMF task handle

• state – [out] Pointer to store the GMF event state

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Indicating the handle is invalid

Structures

struct esp_gmf_task_config

GMF task configuration.

    Configuration structure for GMF tasks, specifying parameters such as stack size,
    priority, CPU core affinity, and whether the stack is allocated in external memory.

Public Members

int stack

Size of the task stack

int prio

Priority of the task

uint32_t core

CPU core affinity for the task

uint32_t stack_in_ext

Flag indicating if the stack is in external memory

struct esp_gmf_task_cfg_t

GMF Task configuration.

    Configuration structure for GMF tasks, specifying parameters such as thread configuration,
    task name, user context, and callback function.

Public Members

esp_gmf_task_config_t thread

Configuration settings for the task thread

const char *name

Name of the task

void *ctx

User context

esp_gmf_event_cb cb

Callback function for task events

Macros

ESP_GMF_MAX_DELAY

GMF_TASK_STRATEGY_TYPE_FINISH

GMF task strategy type: abort or finish.

Strategy type for finish flow, when all jobs are finished

GMF_TASK_STRATEGY_TYPE_ABORT

Strategy type for abort flow, when job returns ESP_GMF_JOB_ERR_ABORT

GMF_TASK_STRATEGY_ACTION_DEFAULT

GMF task strategy action when the task is triggered by the strategy type.

    For the GMF_TASK_STRATEGY_TYPE_FINISH and GMF_TASK_STRATEGY_TYPE_ABORT, the default action is GMF_TASK_STRATEGY_ACTION_DEFAULT

Going to the default flow (done to finish or abort to stop)

GMF_TASK_STRATEGY_ACTION_RESET

Going to the reset flow, loading the elements’ reset jobs

GMF_TASK_STRATEGY_ACTION_STOP

Going to the stop flow, loading the elements’ close jobs

DEFAULT_ESP_GMF_STACK_SIZE

DEFAULT_ESP_GMF_TASK_PRIO

DEFAULT_ESP_GMF_TASK_CORE

DEFAULT_ESP_GMF_TASK_CONFIG()

Type Definitions

typedef void *esp_gmf_task_handle_t

GMF Task Handle.

typedef esp_gmf_err_t (*esp_gmf_task_strategy_func)(esp_gmf_task_handle_t handle, uint8_t strategy_type, void *ctx, uint8_t *out_action)

Strategy function for GMF task Set the strategy function for the task, can be used to inject specific logic to let the task have special behavior e.g. the strategy function will be called when the task is triggered by the strategy type and the action will be returned to the task to decide the next action.

Param handle:

[in] GMF task handle

Param strategy_type:

[in] Strategy type

Param ctx:

[in] Context

Param out_action:

[out] Output strategy action

typedef struct esp_gmf_task_config esp_gmf_task_config_t

GMF task configuration.

    Configuration structure for GMF tasks, specifying parameters such as stack size,
    priority, CPU core affinity, and whether the stack is allocated in external memory.

Header File

• gmf_core/include/esp_gmf_job.h

Functions

static inline void esp_gmf_job_str_cat(char *target, int target_size, const char *src1, const char *src2, int src2_len)

Concatenate two strings into the target string.

Note

The src1 and src2 will be truncated if the target buffer is not large enough If the src1 + src2 is longer than the target buffer, the src2 will be truncated only

Parameters:

• target – [inout] Pointer to the target buffer where the concatenated string will be stored

• target_size – [in] Size of the target buffer

• src1 – [in] Pointer to the null-terminated string to be concatenated from the beginning

• src2 – [in] Pointer to the string to be concatenated

• src2_len – [in] Length of the src2 string to be concatenated

static inline esp_gmf_err_t esp_gmf_job_stack_create(esp_gmf_job_stack_t **stack)

static inline esp_gmf_err_t esp_gmf_job_stack_push(esp_gmf_job_stack_t *stack, uint32_t node_addr)

static inline esp_gmf_err_t esp_gmf_job_stack_pop(esp_gmf_job_stack_t *stack, uint32_t *node_addr)

static inline void esp_gmf_job_stack_clear(esp_gmf_job_stack_t *stack)

static inline esp_gmf_err_t esp_gmf_job_stack_remove(esp_gmf_job_stack_t *stack, uint32_t node_addr)

static inline esp_gmf_err_t esp_gmf_job_stack_is_empty(const esp_gmf_job_stack_t *stack, bool *empty)

static inline void esp_gmf_job_stack_destroy(esp_gmf_job_stack_t *stack)

static inline void esp_gmf_job_stack_show(const esp_gmf_job_stack_t *stack, int line)

Structures

struct _esp_gmf_job_t

This structure represents a job in the GMF A job encapsulates a function to be executed, along with its context and other properties.

Public Members

struct _esp_gmf_job_t *prev

Pointer to the previous job in the linked list

struct _esp_gmf_job_t *next

Pointer to the next job in the linked list

const char *label

Label identifying the job

esp_gmf_job_func func

Function pointer to the job’s function

void *ctx

Context pointer to be passed to the job’s function

void *para

Parameter pointer to be passed to the job’s function

esp_gmf_job_times_t times

Times the job should be executed

esp_gmf_job_err_t ret

Return value of the job function

uint8_t is_deleted

Flag indicating the job is marked for deletion (for infinite jobs only)

struct esp_gmf_job_node

struct esp_gmf_job_stack_t

Macros

ESP_GMF_JOB_LABLE_MAX_LEN

ESP_GMF_JOB_STR_OPEN

ESP_GMF_JOB_STR_PROCESS

ESP_GMF_JOB_STR_CLOSE

ESP_GMF_JOB_STR_RESET

ESP_GMF_JOB_STACK_SHOW(stack)

Type Definitions

typedef esp_gmf_job_err_t (*esp_gmf_job_func)(void *self, void *para)

Function pointer type for GMF job functions.

Param self:

[in] A pointer to the job itself, allowing the function to access its internal data if needed

Param para:

[in] A pointer to additional parameters needed by the job function

Return:

• A value of type esp_gmf_job_err_t indicating the execution status of the job function

typedef struct _esp_gmf_job_t esp_gmf_job_t

This structure represents a job in the GMF A job encapsulates a function to be executed, along with its context and other properties.

typedef struct esp_gmf_job_node esp_gmf_job_node_t

Enumerations

enum esp_gmf_job_status_t

This enumeration defines different states that a GMF job can be in.

Values:

enumerator ESP_GMF_JOB_STATUS_SUSPENDED

The job is suspended

enumerator ESP_GMF_JOB_STATUS_READY

The job is ready

enumerator ESP_GMF_JOB_STATUS_RUNNING

The job is running

enum esp_gmf_job_times_t

This enumeration specifies how many times a GMF job should be executed.

Values:

enumerator ESP_GMF_JOB_TIMES_NONE

The job should not be executed

enumerator ESP_GMF_JOB_TIMES_ONCE

The job should be executed once

enumerator ESP_GMF_JOB_TIMES_INFINITE

The job should be executed indefinitely

enum esp_gmf_job_err_t

This enumeration specifies the error status of a GMF job.

Values:

enumerator ESP_GMF_JOB_ERR_TRUNCATE

The job has been truncated

enumerator ESP_GMF_JOB_ERR_DONE

The job has been completed

enumerator ESP_GMF_JOB_ERR_CONTINUE

The job should continue

enumerator ESP_GMF_JOB_ERR_OK

The job has executed successfully

enumerator ESP_GMF_JOB_ERR_FAIL

The job has failed to execute

enumerator ESP_GMF_JOB_ERR_ABORT

The job has been aborted

Header File

• gmf_core/include/esp_gmf_pool.h

Functions

esp_gmf_err_t esp_gmf_pool_init(esp_gmf_pool_handle_t *handle)

Initialize a GMF pool.

Parameters:

handle – [out] Pointer to store the handle of the initialized GMF pool

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pool_deinit(esp_gmf_pool_handle_t handle)

Deinitialize a GMF pool, freeing registered elements and I/O instances.

Parameters:

handle – [in] GMF pool handle to deinitialize

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pool_register_element(esp_gmf_pool_handle_t handle, esp_gmf_element_handle_t el, const char *tag)

Register a GMF element to specific pool.

Note

Once an element is registered to the pool, the pool takes ownership of it The user should avoid destroying the element manually to prevent issues caused by the pool accessing an invalid element

Parameters:

• handle – [in] GMF pool handle

• el – [in] GMF element handle to register

• tag – [in] Tag associated with the element

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pool_register_element_at_head(esp_gmf_pool_handle_t handle, esp_gmf_element_handle_t el, const char *tag)

Insert a GMF element at the head of specific pool.

Note

This API functions like esp_gmf_pool_register_element, except that it inserts the element at the head of the pool to ensure higher search priority

Parameters:

• handle – [in] GMF pool handle

• el – [in] GMF element handle to register

• tag – [in] Tag associated with the element

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pool_register_io(esp_gmf_pool_handle_t handle, esp_gmf_io_handle_t port, const char *tag)

Register a GMF I/O instance with a GMF pool.

Parameters:

• handle – [in] GMF pool handle

• port – [in] GMF I/O handle to register

• tag – [in] Tag associated with the I/O port

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pool_new_pipeline(esp_gmf_pool_handle_t handle, const char *in_name, const char *el_name[], int num_of_el_name, const char *out_name, esp_gmf_pipeline_handle_t *pipeline)

Create a new GMF pipeline from the specific pool It checks if the element is already registered. If so, it duplicates them, links them together Similarly to the element, it checks the I/O ports, duplicates them, and then adds input and output ports to the pipeline If either in_name or out_name is NULL, the corresponding port will be ignored.

Parameters:

• handle – [in] GMF pool handle

• in_name – [in] Name of the input element

• el_name – [in] Array of names for intermediate elements

• num_of_el_name – [in] Number of elements in the el_name array

• out_name – [in] Name of the output element

• pipeline – [out] Pointer to store the created GMF pipeline handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

• ESP_GMF_ERR_INVALID_ARG Invalid argument or the number of names is incorrect

• ESP_GMF_ERR_NOT_SUPPORT Not support port type

• ESP_GMF_ERR_NOT_FOUND Not found the specific instance

• ESP_GMF_ERR_FAIL Others failed

esp_gmf_err_t esp_gmf_pool_new_io(esp_gmf_pool_handle_t handle, const char *name, esp_gmf_io_dir_t dir, esp_gmf_io_handle_t *new_io)

Create a new I/O instance from the GMF pool by given name.

Parameters:

• handle – [in] GMF pool handle

• name – [in] Name of the I/O handle

• dir – [in] Direction of the I/O (reader or writer)

• new_io – [out] Pointer to the new I/O handle to be created

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

• ESP_GMF_ERR_NOT_FOUND Not found the specific I/O instance

esp_gmf_err_t esp_gmf_pool_new_element(esp_gmf_pool_handle_t handle, const char *el_name, esp_gmf_element_handle_t *new_el)

Create a new element from the GMF pool by given name.

Parameters:

• handle – [in] GMF pool handle

• el_name – [in] Name of the element

• new_el – [out] Pointer to the new element handle to be created

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

• ESP_GMF_ERR_NOT_FOUND Not found the specific element instance

esp_gmf_err_t esp_gmf_pool_iterate_element(esp_gmf_pool_handle_t handle, const void **iterator, esp_gmf_element_handle_t *el)

Iterate pool to retrieve element.

Parameters:

• handle – [in] GMF pool handle

• iterator – [out] To retrieve first element set *iterator = NULL, after that do not modify *iterator any more

• el – [out] To store retrieved element handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_NOT_FOUND Iterate finished, no more elements found

esp_gmf_err_t esp_gmf_pool_get_io_tag_by_url(esp_gmf_pool_handle_t handle, const char *url, esp_gmf_io_dir_t dir, char **tag)

Find the best-matched IO tag for a given URL and direction.

Note

This API traverses the registered IO list, evaluates the matching score for each IO and returns the IO tag with the highest score

Parameters:

• handle – [in] GMF pool handle

• url – [in] The URL to check

• dir – [in] The IO direction

• tag – [out] Pointer to store the resulting IO tag

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_NOT_FOUND No suitable IO found

void esp_gmf_pool_show_lists(esp_gmf_pool_handle_t handle, int line, const char *func)

Print information about elements and IOs registered in a GMF pool.

Parameters:

• handle – [in] GMF pool handle

• line – [in] Line of log

• func – [in] Function name of log

Macros

ESP_GMF_POOL_SHOW_ITEMS(x)

Type Definitions

typedef struct esp_gmf_pool *esp_gmf_pool_handle_t

Header File

• gmf_core/include/esp_gmf_info.h

Structures

struct esp_gmf_info_metadata_t

Structure representing metadata information for a GMF element.

Public Members

void *content

Pointer to the content

int length

Length of the content

void *ctx

User context

struct esp_gmf_info_sound_t

Structure representing sound-related information for a GMF element.

Public Members

uint32_t format_id

Audio format FourCC representation refer to esp_fourcc.h for more details

int sample_rates

Sample rate

int bitrate

Bits per second

uint16_t channels

Number of channels

uint16_t bits

Bit depth

struct esp_gmf_info_video_t

Structure representing sound-related information for a GMF element.

Public Members

uint32_t format_id

Video format FourCC representation refer to esp_fourcc.h for more details

uint16_t height

Height of the picture

uint16_t width

Width of the picture

uint16_t fps

Frame per sample

uint32_t bitrate

Bits per second

struct esp_gmf_info_pic_t

Structure representing picture-related information for a GMF element.

Public Members

uint16_t height

Height of the picture

uint16_t width

Width of the picture

struct esp_gmf_info_file_t

Structure representing file-related information for a GMF element.

Public Members

const char *uri

Uniform Resource Identifier (URI) of the file

uint64_t size

Total size of the file

uint64_t pos

Byte position in the file

Enumerations

enum esp_gmf_info_type_t

Enum representing the type of information for a GMF element.

Values:

enumerator ESP_GMF_INFO_SOUND

Sound-related information

enumerator ESP_GMF_INFO_VIDEO

Video-related information

enumerator ESP_GMF_INFO_FILE

File-related information

enumerator ESP_GMF_INFO_PIC

Picture-related information

---

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.