Audio module

The audio module library is an interface to audio processing functions that coordinate audio states and the exchange of audio-related data of an LE Audio application, such as nRF5340 Audio applications.

Overview 

The audio module is an interface for constructing custom audio processing modules, such as decoder, encoder, and I2S output. It provides a common interface to audio processing algorithms. The operation of the module is determined by a set of user provided functions that perform the processing.

Using this interface, you can open and configure the custom modules, connect to them, and start and stop them. You can also send audio data to and from the application.

There are three module types:

Input - Obtains data internally within the module (for example I2S input) and outputs the data to another module, the application or both.
Output - Takes input from another module or the application and outputs the data internally within the module (for example I2S output).
Input-Output - Takes input from another module or the application, processes the data and then outputs the data to another module, the application or both.

This is an example of how you can connect modules together:

Implementation 

The audio module is implemented as a set of functions. These functions call out to the user’s implementation that are wrapped in the audio_module_functions API. The following figure shows how the audio module functions and the user provided functions relate:

The following table outlines the available functions that are defined in audio_module_functions and whether they are mandatory or not:

Function	Mandatory/Optional	Comment
`audio_module_functions.*open`	Optional	Perform any operations necessary to open the module implementation.
`audio_module_functions.*close`	Optional	Tidy up and close the module implementation.
`audio_module_functions.*configure_set`	Mandatory	Configure the module implementation to perform a particular operation.
`audio_module_functions.*configuration_get`	Mandatory	Return the internal configuration of the module implementation.
`audio_module_functions.*start`	Optional	Perform any operations necessary to set the module implementation running.
`audio_module_functions.*stop`	Optional	Perform any operations necessary to stop the module implementation.
`audio_module_functions.*data_process`	Mandatory	Process the data within the module implementation.

A module implementation can run only if these user provided functions are defined and given to the audio module. The audio module framework itself cannot perform any tasks, as it merely supplies a consistent way to interface to an audio algorithm.

The following figure show the internal states of the audio module:

Configuration 

To use the audio module library, set the following Kconfig options to y in the project configuration file prj.conf:

Application integration 

To create your own audio module for an LE Audio application, complete the following steps:

Write the mandatory functions required by the function table API in Implementation.
Write any optional functions.
Assign the function table to an instance of an audio module.

The audio application opens the module, configures it and connects it to other modules, the application or both. The module can then be started and you can transfer data in accordance to what type the module is. The module types are described in Overview.

The following figure demonstrates a simple decoding audio system, where the decoded audio is sent to an I2S output and returned to the application:

Dependencies 

This library uses the following nRF Connect SDK library:

Data FIFO

API documentation 

Header file: include/audio_module/audio_module.h

Source files: subsys/audio_module/audio_module.c

group audio_module

Audio module for LE Audio applications.

Defines

AUDIO_MODULE_LOCATIONS_NUM: Number of valid location bits.

Typedefs

typedef void (*audio_module_response_cb)(struct audio_module_handle_private *handle, struct audio_data const *const audio_data)

Callback function for a response to a data_send as supplied by the module user.

Param handle:: [in/out] The handle of the module that sent the audio data.
Param audio_data:: [in] The audio data to operate on.

Enums

enum audio_module_type

Module type.

Values:

enumerator AUDIO_MODULE_TYPE_UNDEFINED

enumerator AUDIO_MODULE_TYPE_INPUT

enumerator AUDIO_MODULE_TYPE_OUTPUT

enumerator AUDIO_MODULE_TYPE_IN_OUT

enum audio_module_state

Module state.

Values:

enumerator AUDIO_MODULE_STATE_UNDEFINED

enumerator AUDIO_MODULE_STATE_CONFIGURED

enumerator AUDIO_MODULE_STATE_RUNNING

enumerator AUDIO_MODULE_STATE_STOPPED

Functions

int audio_module_open(struct audio_module_parameters const *const parameters, struct audio_module_configuration const *const configuration, char const *const name, struct audio_module_context *context, struct audio_module_handle *handle)

Open an audio module.

Parameters:

parameters – [in] Pointer to the module set-up parameters.
configuration – [in] Pointer to the module’s configuration.
name – [in] A NULL terminated string giving a unique name for this module instance.
context – [in/out] Pointer to the private context for the module.
handle – [out] Pointer to the module’s private handle.

Returns:

0 if successful, error otherwise.

int audio_module_close(struct audio_module_handle *handle)

Close an opened audio module.

Parameters:

handle – [in/out] The handle to the module instance.

Returns:

0 if successful, error otherwise.

int audio_module_reconfigure(struct audio_module_handle *handle, struct audio_module_configuration const *const configuration)

Reconfigure an opened audio module.

Parameters:

handle – [in/out] The handle to the module instance.
configuration – [in] Pointer to the module’s configuration to set.

Returns:

0 if successful, error otherwise.

int audio_module_configuration_get(struct audio_module_handle const *const handle, struct audio_module_configuration *configuration)

Get the configuration of an audio module.

Parameters:

handle – [in] The handle to the module instance.
configuration – [out] Pointer to the module’s current configuration.

Returns:

0 if successful, error otherwise.

int audio_module_connect(struct audio_module_handle *handle_from, struct audio_module_handle *handle_to, bool connect_external)

Connect two audio modules together or connect to the module’s TX FIFO.

Note

The function should be called once for every individual connection.

Parameters:

handle_from – [in/out] The handle for the module for output.
handle_to – [in/out] The handle of the module for input, should be NULL if connect_external flag is true.
connect_external – [in] Flag to indicate if the from module should put its output audio data items onto its TX FIFO for access via an external system.

Returns:

0 if successful, error otherwise.

int audio_module_disconnect(struct audio_module_handle *handle, struct audio_module_handle *handle_disconnect, bool disconnect_external)

Disconnect audio modules from each other or disconnect the module’s TX FIFO. The function should be called for all individual disconnections.

Parameters:

handle – [in/out] The handle for the module.
handle_disconnect – [in/out] The handle of the module to disconnect, should be NULL if disconnect_external flag is true.
disconnect_external – [in] Flag to indicate that the output audio data items should stop being put on handle TX FIFO.

Returns:

0 if successful, error otherwise.

int audio_module_start(struct audio_module_handle *handle)

Start processing audio data in the audio module given by handle.

Parameters:

handle – [in/out] The handle for the module to start.

Returns:

0 if successful, error otherwise.

int audio_module_stop(struct audio_module_handle *handle)

Stop processing audio data in the audio module given by handle.

Parameters:

handle – [in/out] The handle for the module to be stopped.

Returns:

0 if successful, error otherwise.

int audio_module_data_tx(struct audio_module_handle *handle, struct audio_data const *const audio_data, audio_module_response_cb response_cb)

Send an audio data item to an audio module, all data is consumed by the module.

Parameters:

handle – [in/out] The handle for the receiving module instance.
audio_data – [in] Pointer to the audio data to send to the module.
response_cb – [in] Pointer to a callback to run when the buffer is fully consumed in a module.

Returns:

0 if successful, error otherwise.

int audio_module_data_rx(struct audio_module_handle *handle, struct audio_data *audio_data, k_timeout_t timeout)

Retrieve an audio data item from an audio module.

Parameters:

handle – [in/out] The handle to the module instance.
audio_data – [out] Pointer to the audio data from the module.
timeout – [in] Non-negative waiting period to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.

Returns:

0 if successful, error otherwise.

int audio_module_data_tx_rx(struct audio_module_handle *handle_tx, struct audio_module_handle *handle_rx, struct audio_data const *const audio_data_tx, struct audio_data *audio_data_rx, k_timeout_t timeout)

Send an audio data to an audio module and retrieve an audio data from an audio module.

Note

The audio data is processed within the module or sequence of modules. The result is returned via the module or final module’s output FIFO. All the input data is consumed within the call and thus the input data buffer maybe released once the function returns.

Parameters:

handle_tx – [in/out] The handle to the module to send the input audio data to.
handle_rx – [in/out] The handle to the module to receive audio data from.
audio_data_tx – [in] Pointer to the audio data to send.
audio_data_rx – [out] Pointer to the audio data received.
timeout – [in] Non-negative waiting period to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.

Returns:

0 if successful, error otherwise.

int audio_module_names_get(struct audio_module_handle const *const handle, char **base_name, char *instance_name)

Helper to get the base and instance names for a given audio module handle.

Parameters:

handle – [in] The handle to the module instance.
base_name – [out] Pointer to the name of the module.
instance_name – [out] Pointer to the name of the current module instance.

Returns:

0 if successful, error otherwise.

int audio_module_state_get(struct audio_module_handle const *const handle, enum audio_module_state *state)

Helper to get the state of a given audio module handle.

Parameters:

handle – [in] The handle to the module instance.
state – [out] Pointer to the current module’s state.

Returns:

0 if successful, error otherwise.

int audio_module_number_channels_calculate(uint32_t locations, int8_t *number_channels)

Helper to calculate the number of channels from the channel map for the given audio data.

Parameters:

locations – [in] Channel locations to calculate the number of channels from.
number_channels – [out] Pointer to the calculated number of channels in the audio data.

Returns:

0 if successful, error otherwise.

struct audio_module_functions

#include <audio_module.h>

Private pointer to a module’s functions.

Public Members

int (*open)(struct audio_module_handle_private *handle, struct audio_module_configuration const *const configuration)

Open an audio module with the specified initial configuration.

Note

This is an optional function for an audio module.

Param handle:: [in/out] The handle to the module instance.
Param configuration:: [in] Pointer to the desired initial configuration to set.
Return:: 0 if successful, error otherwise.

int (*close)(struct audio_module_handle_private *handle)

Close an open audio module.

Note

This is an optional function for an audio module.

Param handle:: [in/out] The handle to the module instance.
Return:: 0 if successful, error otherwise.

int (*configuration_set)(struct audio_module_handle_private *handle, struct audio_module_configuration const *const configuration)

Reconfigure an audio module after it has been opened with its initial configuration.

Note

This is a mandatory function for an audio module.

Param handle:: [in/out] The handle to the module instance.
Param configuration:: [in] Pointer to the desired configuration to set.
Return:: 0 if successful, error otherwise.

int (*configuration_get)(struct audio_module_handle_private const *const handle, struct audio_module_configuration *configuration)

Get the configuration of an audio module.

Note

This is a mandatory function for an audio module.

Param handle:: [in] The handle to the module instance.
Param configuration:: [out] Pointer to the module’s current configuration.
Return:: 0 if successful, error otherwise.

int (*start)(struct audio_module_handle_private *handle)

Start an audio module.

Note

This is an optional function for an audio module.

Param handle:: [in/out] The handle for the module to start.
Return:: 0 if successful, error otherwise.

int (*stop)(struct audio_module_handle_private *handle)

Stop an audio module.

Note

This is an optional function for an audio module.

Param handle:: [in/out] The handle for the module to stop.
Return:: 0 if successful, error otherwise.

int (*data_process)(struct audio_module_handle_private *handle, struct audio_data const *const audio_data_rx, struct audio_data *audio_data_tx)

The core data processing for an audio module. Can be either an input, output or input/output module type.

Note

This is a mandatory function for an audio module.

Param handle:: [in/out] The handle to the module instance.
Param audio_data_rx:: [in] Pointer to the input audio data or NULL for an input module.
Param audio_data_tx:: [out] Pointer to the output audio data or NULL for an output module.
Return:: 0 if successful, error otherwise.

struct audio_module_description: #include <audio_module.h>

A module’s minimum description.

struct audio_module_thread_configuration: #include <audio_module.h>

Module’s thread configuration structure.

struct audio_module_parameters: #include <audio_module.h>

Module’s generic set-up structure.

struct audio_module_handle: #include <audio_module.h>

Private module handle.

struct audio_module_message: #include <audio_module.h>

Private structure describing a data_in message into the module thread.

Audio module

Overview

Implementation

Configuration

Application integration

Dependencies

API documentation

Overview 

Implementation 

Configuration 

Application integration 

Dependencies 

API documentation 