オーディオパイプライン

Audio Pipeline

リンクされた要素のグループの動的な組み合わせは、オーディオパイプラインを使用して行われます。 個々の要素を扱うのではなく、1つのオーディオパイプラインだけを扱います。 すべての要素はリングバッファによって接続されています。 オーディオパイプラインは、要素タスクからアプリケーションへのメッセージの転送も処理します。

Dynamic combination of a group of linked Elements is done using the Audio Pipeline. You do not deal with the individual elements but with just one audio pipeline. Every element is connected by a ringbuffer. The Audio Pipeline also takes care of forwarding messages from the element tasks to an application.

次の図は、player/pipeline_http_mp3の例で使用されている、オーディオパイプラインのHTTPリーダーストリーム、MP3デコーダー、およびI2Sライターストリームの3つの要素の構成を示しています。

A diagram below presents organization of three elements, HTTP reader stream, MP3 decoder and I2S writer stream, in the Audio Pipeline, that has been used in player/pipeline_http_mp3 example.

Sample Organization of Elements in Audio Pipeline

APIリファレンス

API Reference

ヘッダーファイル

Header File

関数

Functions
audio_pipeline_handle_t audio_pipeline_init(audio_pipeline_cfg_t *config)

audio_pipeline_handle_tオブジェクトの初期化audio_pipelineは、オーディオデータストリームを制御し、オーディオ要素をリングバッファに接続します。オーディオ要素を順番に接続して開始し、前の要素からデータを取得して、後の要素に渡します。 また、各要素からイベントを取得したり、イベントを処理したり、上位レイヤーに渡したりします。

Initialize audio_pipeline_handle_t object audio_pipeline is responsible for controlling the audio data stream and connecting the audio elements with the ringbuffer It will connect and start the audio element in order, responsible for retrieving the data from the previous element and passing it to the element after it. Also get events from each element, process events or pass it to a higher layer.

Return
  • 成功した場合のaudio_pipeline_handle_t
    audio_pipeline_handle_t on success
  • エラーがある場合はNULL
    NULL when any errors
Parameters
  • config: 構成-audio_pipeline_cfg_t
    config: The configuration - audio_pipeline_cfg_t

esp_err_t audio_pipeline_deinit(audio_pipeline_handle_t pipeline)

この関数は、audio_pipeline内のすべての要素のリンクを削除し、すべてのイベントの登録をキャンセルし、登録された要素のdestroy関数を呼び出し、init関数によって割り当てられたメモリを解放します。 簡単に言うと、すべてのメモリを解放します。

This function removes all of the element’s links in audio_pipeline, cancels the registration of all events, invokes the destroy functions of the registered elements, and frees the memory allocated by the init function. Briefly, frees all memory.

Return
ESP_OK
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_register(audio_pipeline_handle_t pipeline, audio_element_handle_t el, const char *name)

audio_pipelineの要素を登録すると、各要素は複数回登録できますが、名前（文字列として）はaudio_pipelineで一意である必要があります。これは、audio_pipeline_linkに記載されているリンク作成の要素を識別するために使用されます。

Registering an element for audio_pipeline, each element can be registered multiple times, but name (as String) must be unique in audio_pipeline, which is used to identify the element for link creation mentioned in the audio_pipeline_link

Note
パイプラインの停止またはパイプラインの一時停止は、レジスタの順序に大きく依存します。 要素を厳密に次の順序で登録してください：最初に入力要素、最後に処理要素、最後に出力要素。
Because of stop pipeline or pause pipeline depend much on register order. Please register element strictly in the following order: input element first, process middle, output element last.
Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • el: オーディオエレメントハンドル
    el: The Audio Element Handle
  • name: このaudio_pipelineのaudio_elementの名前識別子
    name: The name identifier of the audio_element in this audio_pipeline

esp_err_t audio_pipeline_unregister(audio_pipeline_handle_t pipeline, audio_element_handle_t el)

audio_pipelineのaudio_elementの登録を解除し、リストから削除します。

Unregister the audio_element in audio_pipeline, remove it from the list.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • el: オーディオエレメントハンドル
    el: The Audio Element Handle

esp_err_t audio_pipeline_run(audio_pipeline_handle_t pipeline)

オーディオパイプラインを開始します。

Start Audio Pipeline.

この関数を使用すると、audio_pipelineは、リンク関数を使用してリンクされたすべての要素のタスクを作成します。

With this function audio_pipeline will create tasks for all elements, that have been linked using the linking functions.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_terminate(audio_pipeline_handle_t pipeline)

オーディオパイプラインを停止します。

Stop Audio Pipeline.

この関数を使用すると、audio_pipelineは、リンク関数を使用してリンクされているすべての要素のタスクを破棄します。

With this function audio_pipeline will destroy tasks of all elements, that have been linked using the linking functions.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_resume(audio_pipeline_handle_t pipeline)

この関数は、すべての要素をRUNNING状態に設定し、audio_pipelineの固有の機能としてオーディオデータを処理します。

This function will set all the elements to the RUNNING state and process the audio data as an inherent feature of audio_pipeline.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_pause(audio_pipeline_handle_t pipeline)

この関数は、すべての要素をPAUSED状態に設定します。 データ処理が停止されることを除いて、すべてが同じままです。

This function will set all the elements to the PAUSED state. Everything remains the same except the data processing is stopped.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_stop(audio_pipeline_handle_t pipeline)

リンクされたすべての要素を停止します。 同期を維持するためにaudio_pipeline_wait_for_stopとともに使用されます。 パイプライン内の要素のリンク状態は保持され、イベントは引き続き登録されます。 停止したaudio_pipelineは、audio_pipeline_resumeによって再起動します。

Stop all of the linked elements. Used with audio_pipeline_wait_for_stop to keep in sync. The link state of the elements in the pipeline is kept, events are still registered. The stopped audio_pipeline restart by audio_pipeline_resume.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_wait_for_stop(audio_pipeline_handle_t pipeline)

audio_pipeline_stop関数は、要素にリクエストを送信して終了します。 しかし、時間制限のあるタスクを取り除くには時間が必要です。 この関数は、パイプライン内のすべての要素が実際に停止するまで、portMAX_DELAYを待機します。

The audio_pipeline_stop function sends requests to the elements and exits. But they need time to get rid of time-blocking tasks. This function will wait portMAX_DELAY until all the Elements in the pipeline actually stop.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_link(audio_pipeline_handle_t pipeline, const char *link_tag[], int link_num)

audio_pipelineに追加されたaudio_elementは、この関数によって呼び出される前に接続が解除されます。 audio_pipeline_registerによってすでに登録されている要素の名前に基づいて、データのパスはlink_tagの順序でリンクされます。 インデックス0の要素が最初で、インデックスlink_num - 1が最後です。 また、audio_pipelineは、すべての要素のイベントをサブスクライブします。

The audio_element added to audio_pipeline will be unconnected before it is called by this function. Based on element’s name already registered by audio_pipeline_register, the path of the data will be linked in the order of the link_tag. Element at index 0 is first, and index link_num -1 is final. As well as audio_pipeline will subscribe all element’s events.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • link_tag: 要素名の配列はaudio_pipeline_registerによって登録されました
    link_tag: Array of element name was registered by audio_pipeline_register
  • link_num: link_tag配列の要素の総数
    link_num: Total number of elements of the link_tag array

esp_err_t audio_pipeline_unlink(audio_pipeline_handle_t pipeline)

要素の接続を削除し、イベントのサブスクライブを解除します。

Removes the connection of the elements, as well as unsubscribe events.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

audio_element_handle_t audio_pipeline_get_el_by_tag(audio_pipeline_handle_t pipeline, const char *tag)

タグによって登録済みパイプラインから保持されていない要素を検索します。

Find un-kept element from registered pipeline by tag.

Return
  • エラーがある場合はNULL
    NULL when any errors
  • 成功したその他
    Others on success
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • tag: 文字ポインタ
    tag: A char pointer

audio_element_handle_t audio_pipeline_get_el_once(audio_pipeline_handle_t pipeline, const audio_element_handle_t start_el, const char *tag)

開始要素に基づいて、登録されたパイプラインからタグによって保持されていない要素を検索します。

Based on beginning element to find un-kept element from registered pipeline by tag.

Return
  • エラーがある場合はNULL
    NULL when any errors
  • 成功したその他
    Others on success
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • start_el: 特定の開始要素
    start_el: Specific beginning element
  • tag: 文字ポインタ
    tag: A char pointer

esp_err_t audio_pipeline_remove_listener(audio_pipeline_handle_t pipeline)

このaudio_pipelineからイベントリスナーを削除します。

Remove event listener from this audio_pipeline.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_set_listener(audio_pipeline_handle_t pipeline, audio_event_iface_handle_t evt)

このオーディオパイプラインのイベントリスナーを設定します。このパイプラインからのすべてのイベントをevtでリッスンできます

Set event listner for this audio_pipeline, any event from this pipeline can be listen to by evt

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • evt: イベントハンドル
    evt: The Event Handle

audio_event_iface_handle_t audio_pipeline_get_event_iface(audio_pipeline_handle_t pipeline)

このパイプラインを使用してイベントifaceを取得します。

Get the event iface using by this pipeline.

Return
イベントハンドル
The Event Handle
Parameters
  • pipeline: パイプライン
    pipeline: The pipeline

esp_err_t audio_pipeline_link_insert(audio_pipeline_handle_t pipeline, bool first, audio_element_handle_t prev, ringbuf_handle_t conect_rb, audio_element_handle_t next)

特定のaudio_elementをaudio_pipelineに挿入します。前の要素は、リングバッファによって次の要素に接続します。

Insert the specific audio_element to audio_pipeline, previous element connect to the next element by ring buffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • first: 前の要素は最初の入力要素であり、trueに設定する必要があります
    first: Previous element is first input element, need to set true
  • prev: 前の要素
    prev: Previous element
  • conect_rb: リングバッファを接続します
    conect_rb: Connect ring buffer
  • next: 次の要素
    next: Next element

esp_err_t audio_pipeline_register_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

NULLで終了する要素のリストをaudio_pipelineに登録します。

Register a NULL-terminated list of elements to audio_pipeline.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • element_1: audio_pipelineに追加する要素。
    element_1: The element to add to the audio_pipeline.
  • ...: audio_pipelineに追加する追加の要素。
    ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_unregister_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

NULLで終了する要素のリストをaudio_pipelineに登録解除します。

Unregister a NULL-terminated list of elements to audio_pipeline.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • element_1: audio_pipelineに追加する要素。
    element_1: The element to add to the audio_pipeline.
  • ...: audio_pipelineに追加する追加の要素。
    ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_link_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

NULLで終了する要素のリストをaudio_pipelineに追加します。

Adds a NULL-terminated list of elements to audio_pipeline.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • element_1: audio_pipelineに追加する要素。
    element_1: The element to add to the audio_pipeline.
  • ...: audio_pipelineに追加する追加の要素。
    ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_listen_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

要素のイベントのNULLで終了するリストをaudio_pipelineにサブスクライブします。

Subscribe a NULL-terminated list of element’s events to audio_pipeline.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • element_1: audio_pipelineをサブスクライブする要素イベント。
    element_1: The element event to subscribe to the audio_pipeline.
  • ...: audio_pipelineにサブスクライブする追加の要素イベント。
    ...: Additional elements event to subscribe to the audio_pipeline.

esp_err_t audio_pipeline_check_items_state(audio_pipeline_handle_t pipeline, audio_element_handle_t dest_el, audio_element_status_t status)

宛先要素の状態を更新し、リンクされたすべての要素の状態が同じであることを確認します。

Update the destination element state and check the all of linked elements state are same.

Return
  • ESP_OKすべてのリンクされた要素の状態は同じです。
    ESP_OK All linked elements state are same.
  • ESP_FAILすべてのリンクされた要素の状態が同じではありません。
    ESP_FAIL All linked elements state are not same.
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • dest_el: 宛先要素
    dest_el: Destination element
  • status: 新しいステータス
    status: The new status

esp_err_t audio_pipeline_reset_items_state(audio_pipeline_handle_t pipeline)

パイプライン要素アイテムの状態をAEL_STATUS_NONEにリセットします

Reset pipeline element items state to AEL_STATUS_NONE

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_ringbuffer(audio_pipeline_handle_t pipeline)

パイプライン要素のリングバッファをリセットします。

Reset pipeline element ringbuffer.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_elements(audio_pipeline_handle_t pipeline)

パイプラインのリンクされた要素の状態をリセットします。

Reset Pipeline linked elements state.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_kept_state(audio_pipeline_handle_t pipeline, audio_element_handle_t el)

特定の要素の保持状態をリセットします。

Reset the specific element kept state.

Return
  • 成功したESP_OK
    ESP_OK on success
  • エラーが発生した場合のESP_FAIL
    ESP_FAIL when any errors
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • el: オーディオ要素ハンドル
    el: The Audio element Handle

esp_err_t audio_pipeline_breakup_elements(audio_pipeline_handle_t pipeline, audio_element_handle_t kept_ctx_el)

特定のパイプラインのリンクされたすべての要素を分割します。 インクルードおよび kept_ctx_elが機能する前（AEL_STATE_RUNNINGまたはAEL_STATE_PAUSED）要素と接続されたリングバッファは予約されます。

Break up all the linked elements of specific pipeline. The include and before kept_ctx_el working (AEL_STATE_RUNNING or AEL_STATE_PAUSED) elements and connected ringbuffer will be reserved.

Note
kept_ctx_elがNULLの場合、予約されている要素はありません。 この関数は、すべての要素のイベントのサブスクライブを解除します。
There is no element reserved when kept_ctx_el is NULL. This function will unsubscribe all element’s events.
Return
  • ESP_OKすべてのリンクされた要素の状態は同じです。
    ESP_OK All linked elements state are same.
  • ESP_ERR_INVALID_ARGパラメーターが無効です。
    ESP_ERR_INVALID_ARG Invalid parameters.
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The audio pipeline handle
  • kept_ctx_el: 宛先保持要素
    kept_ctx_el: Destination keep elements

esp_err_t audio_pipeline_relink(audio_pipeline_handle_t pipeline, const char *link_tag[], int link_num)

audio_pipeline_registerによってすでに登録されている要素の名前に基づいて、 `link_tag内の名前の順序に従ってパイプラインを再リンクします。

Basing on element’s name already registered by audio_pipeline_register, relink the pipeline following the order of names in the `link_tag.

Note
リングバッファが新しいパイプラインを接続するのに十分でない場合、新しいリングバッファが作成されます。
If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.
Return
  • ESP_OKすべてのリンクされた要素の状態は同じです。
    ESP_OK All linked elements state are same.
  • ESP_FAILエラー。
    ESP_FAIL Error.
  • ESP_ERR_INVALID_ARGパラメーターが無効です。
    ESP_ERR_INVALID_ARG Invalid parameters.
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • link_tag: audio_pipeline_registerによって登録された要素名の配列
    link_tag: Array of elements name that was registered by audio_pipeline_register
  • link_num: link_tag配列の要素の総数
    link_num: Total number of elements of the link_tag array

esp_err_t audio_pipeline_relink_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

NULLで終了する要素のリストをaudio_pipelineに追加します。

Adds a NULL-terminated list of elements to audio_pipeline.

Note
リングバッファが新しいパイプラインを接続するのに十分でない場合、新しいリングバッファが作成されます。
If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.
Return
  • ESP_OKすべてのリンクされた要素の状態は同じです。
    ESP_OK All linked elements state are same.
  • ESP_FAILエラー。
    ESP_FAIL Error.
  • ESP_ERR_INVALID_ARGパラメーターが無効です。
    ESP_ERR_INVALID_ARG Invalid parameters.
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • element_1: audio_pipelineに追加する要素。
    element_1: The element to add to the audio_pipeline.
  • ...: audio_pipelineに追加する追加の要素。
    ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_change_state(audio_pipeline_handle_t pipeline, audio_element_state_t new_state)

パイプラインの状態を設定します。

Set the pipeline state.

Return
  • ESP_OKすべてのリンクされた要素の状態は同じです。
    ESP_OK All linked elements state are same.
  • ESP_FAILエラー。
    ESP_FAIL Error.
Parameters
  • pipeline: オーディオパイプラインハンドル
    pipeline: The Audio Pipeline Handle
  • new_state: 新しい状態が設定されます
    new_state: The new state will be set

Structures

struct audio_pipeline_cfg

オーディオパイプライン構成。

Audio Pipeline configurations.

Public Members

int rb_size

オーディオパイプラインリングバッファサイズ

Audio Pipeline ringbuffer size

マクロ

Macros
DEFAULT_PIPELINE_RINGBUF_SIZE
DEFAULT_AUDIO_PIPELINE_CONFIG()

タイプ定義

Type Definitions
typedef struct audio_pipeline *audio_pipeline_handle_t
typedef struct audio_pipeline_cfg audio_pipeline_cfg_t

オーディオパイプライン構成。

Audio Pipeline configurations.