# Customize audio use cases
Customize audio use cases at the platform abstraction layer (PAL) level using PAL APIs, configuration files, and audio graph modifications.
Each audio use case is a graph with subgraphs of a specific type. Each subgraph has one or more functional software blocks (referred to as modules) that perform a specific function.
## Customize audio at the PAL level
PAL provides higher-level audio-specific APIs to access audio hardware and drivers.
Customizing at the PAL level allows you to control stream behavior, device routing, buffer configuration, and platform-specific audio settings.
The PipeWire PAL plug-in (`pw-pal-plugin`) bridges PipeWire streams directly to the PAL API.
It runs as a PipeWire module and handles all audio routing between PipeWire and the AudioReach hardware stack.The plug-in performs the following operations:
- Opens and manages PAL streams for playback and capture.
- Configures mixer controls to set up hardware codec devices and stream configurations.
- Invokes PAL APIs to open and start audio sessions.
- Routes audio data between PipeWire buffers and PAL DMA buffers.
The following table describes the components of the PipeWire PAL plug-in.
Components of the PipeWire PAL plugin
| Component | Description |
| --- | --- |
| Source | A node that produces a stream of data (audio/video frames) and exposes output ports. A PipeWire source node:
Has no requirement to receive data.
Pushes data out via output ports.
Operates on a clock, driver, or capture trigger.
Is usually tied to hardware or software generators.
|
| Sink | A node that consumes incoming data and exposes input ports. A PipeWire sink node:
Receives data via input ports.
Does not generate its own primary data.
Usually interacts with hardware playback/output.
Controls buffering and rendering.
|
The PAL resource manager tracks all active sessions and devices to enable concurrencies. It parses and loads configuration from the following platform XML files:
- `Resource_manager.xml`: Contains device-to-backend mapping and policy making attributes.
- `Card-defs.xml`: Contains virtual PCM and compress nodes and their options.
- `mixer_paths.xml`: Defines all low-level audio routing paths and controls that determine how sound is recorded, processed, and played on the device.
- `plugin_manager.xml`: Links audio streams, sessions, and devices to their corresponding plugin libraries and functions for runtime audio handling.
- `usecaseKvManager.xml`: Maps audio streams and devices to DSP processing graphs, deciding how audio is processed internally on the chip.
You can find the PipeWire PAL plug-in source code at `build-qcom-wayland/workspace/sources/pipewire`.
You can find the PAL source code at `build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx`.
The file `build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx/inc/PalApi.h` lists all APIs exposed by the PAL module.
### PAL APIs
The following are common PAL APIs for controlling and configuring audio
sessions and devices.
#### pal\_init
Initializes PAL, parses the related configuration files, and stores them in a local structure for use.
int32_t pal_init(
Copy to clipboard
- Parameters: None.
- Return value: 0 on success, or an error code on failure.
#### pal\_deinit
De-initializes PAL and frees the resources allocated during initialization.
void pal_deinit()
Copy to clipboard
- Parameters: None.
#### pal\_stream\_open
Opens a stream with the specified configuration, such as source and sink devices and media configuration. Returns the stream handle on success.
int32_t pal_stream_open(
struct pal_stream_attributes *attributes,
uint32_t no_of_devices,
struct pal_device *devices,
uint32_t no_of_modifiers,
struct modifier_kv *modifiers,
pal_stream_callback cb,
uint64_t cookie,
pal_stream_handle_t **stream_handle)
Copy to clipboard
- Parameters
>
>
> pal_stream_open parameters
>
>
> | Parameter | Description |
> | --- | --- |
> | `attributes` | Valid stream attributes obtained from `pal_stream_open`. |
> | `no_of_devices` | Number of audio devices with which to first start the stream. |
> | `devices` | Array of `pal_devices`. Bases the size of the array on the number of devices specified by the client in `no_of_devices`. |
> | `no_of_modifiers` | Number of modifiers. |
> | `modifiers` | Array of modifiers. Modifiers add more key-value pairs. |
> | `cb` | Callback function associated with the stream. This callback function notifies any event. |
> | `cookie` | Client data associated with the stream. The callback function returns this cookie. |
> | `stream_handle` | Updates with the valid stream handle if the operation is successful. |
- Return value: 0 on success, or an error code on failure.
#### pal\_stream\_start
Starts a stream.
int32_t pal_stream_start( pal_stream_handle_t *stream_handle)
Copy to clipboard
- Parameters: stream\_handle - Valid stream handle from `pal_stream_open`.
- Return value: 0 on success, or an error code on failure.
#### pal\_stream\_read
Reads the audio buffer captured from the audio source device.
ssize_t pal_stream_read( pal_stream_handle_t *stream_handle, struct pal_buffer *buf)
Copy to clipboard
- Parameters
>
>
> pal_stream_read parameters
>
>
> | Parameter | Description |
> | --- | --- |
> | `stream_handle` | Valid stream handle from `pal_stream_open`. |
> | `buf` | Pointer to `pal_buffer` that holds audio samples and metadata. |
- Return value: Number of bytes read, or an error code on failure.
#### pal\_stream\_write
Writes the audio buffer for stream rendering over a sink device.
ssize_t pal_stream_write( pal_stream_handle_t *stream_handle,
struct pal_buffer *buf)
Copy to clipboard
- Parameters
>
>
> pal_stream_write parameters
>
>
> | Parameter | Description |
> | --- | --- |
> | `stream_handle` | Valid stream handle from `pal_stream_open`. |
> | `buf` | Pointer to pal\_buffer that holds audio samples and metadata. |
- Return value: Number of bytes written, or an error code on failure.
#### pal\_stream\_stop
Stops a stream.
int32_t pal_stream_stop( pal_stream_handle_t *stream_handle)
Copy to clipboard
- Parameters: `stream_handle` - Valid stream handle from `pal_stream_open`.
- Return value: 0 on success, or an error code on failure.
#### pal\_stream\_close
Closes a stream.
int32_t pal_stream_close( pal_stream_handle_t *stream_handle)
Copy to clipboard
- Parameters: `stream_handle` - Valid stream handle from `pal_stream_open`.
- Return value: 0 on success, or an error code on failure.
### Configure PAL configuration files
Configure audio use cases at the PAL level using the `mixer_paths`, `resourcemanager`, and `usecasekvmanager` XML files.
`mixer_paths_GLYMUR_CRD.xml` and `resourcemanager_GLYMUR_CRD.xml` are used for Glymur Linux.
#### Customize the mixer paths XML file
A mixer control is a control variable exposed from the advanced Linux
sound architecture (ALSA) mixer to user space. It lets user space access
set and get functions and pass parameters to the ALSA mixer.
For example, the following entry enables the mono speaker device in the
`mixer_paths.xml` file. When playback triggers and the selected device is
a speaker, these mixer controls run through the audio route helper class:
Copy to clipboard
The platform uses the `mixer_paths_.xml` file as the
mixer path. This file is in the `/etc/` folder on the target.
#### Customize the resource manager XML file
The `resourcemanager.xml` file includes all possible devices, use cases,
and combinations. It also includes other configurations, module
parameters, and global parameters.
The following example shows a speaker device entry in the resource
manager XML file. It includes all configurations for the speaker device,
such as back-end name, channels, sample rate, and bit width.
PAL_DEVICE_OUT_SPEAKERCODEC_DMA-LPAIF_WSA-RX-0224800016speaker
Copy to clipboard
#### Customize the usecasekvmanager XML file
The `usecasekvmanager.xml` file holds the graph key vector (GKV) details
for each use case. PAL uses this file to get the key-value (KV)
configuration for each use case, then uses that configuration to get
graph information from the ACDB files. This file is in the `/etc` folder
on the device.
The following examples show one stream and device graph key vector configuration.
- Stream KV
>
>
>
>
>
>
>
> Copy to clipboard
- Device KV
>
>
>
>
>
>
> Copy to clipboard
- DevicePP KV
>
>
>
>
>
>
>
> Copy to clipboard
## Customize the audio graph
Each audio use case is a graph with subgraphs of a specific type. Each
subgraph has one or more functional software blocks (referred to as
modules) that perform a specific function. Use the graph terminology,
segments, and sample graph to design and route a custom use case. The
following table defines the audio graph terms.
Audio graph terms
| Term | Definition |
| --- | --- |
| Use case | A graph of modules from source endpoints to sink endpoints that meets the product-defined use case. |
| Graph | A logical interpretation of a group of one or more subgraphs connected together to create a specific use case. |
| Subgraph | A logical abstraction for a group of modules that connect and are manipulated as a single entity. |
| Container | An object that lets the system designer group and run audio processing modules together in a single software thread. |
| Module | The smallest independent processing unit in the signal processing framework. |
| Key-value (KV) pair | The individual key and associated value in a key vector. For example, a key can be a sound device and a value can be headphone, speaker, or another sound device. |
| Key vector | Uniquely identifies a graph or subgraph through a set of KV pairs. |
| Graph key vector (GKV) | A unique identifier that gets a graph, represented by KV pairs.The graph or system designer associates a set of unique keys and values when creating a subgraph from the QACT UI canvas. |
| Calibration key vector (CKV) | A unique identifier that gets calibration data, represented by KV pairs. The graph or system designer associates a set of unique keys and values when storing calibration data. |
| Tag and tag key vector (TKV) | A tag is an identifier that sets runtime parameters for one or more modules. It updates module configurations, for example enabling or disabling echo cancellation or equalization, in a graph at runtime. |
An audio use case has the following segments. The front-end represents
the stream and StreamPP subgraphs, and the back-end represents the
per-stream per-device (PSPD), DevicePP, and device subgraphs. The
following table describes the audio graph segments.
Audio use case segments
| Segment | Description |
| --- | --- |
| Stream | Provides a data write and read interface and performs decoding and encoding of compressed data. |
| StreamPP | Contains stream-based processing modules, for example an equalizer. |
| PSPD | Contains a module to convert the stream media format to the device media format. |
| DevicePP | Contains processing modules for sound device tuning. |
| Device | Hardware endpoint such as CodecDMA (SoundWire), I2S, or TDM port. |
After a front-end connects to a back-end through a routing mixer
control, the full GKV forms by concatenating the subgraph GKVs and the
CKVs assigned through mixer controls. When you open the front-end PCM or
compress device, AGM invokes GSL APIs with the concatenated GKVs and
CKVs to set up the graph in ARE and apply calibration. At the same time,
AGM opens a kernel PCM device that corresponds to the connected
back-ends to begin audio peripheral setup. The following figure shows an
example audio graph for a playback scenario.
The following figure shows an example audio graph for a playback scenario.
Playback audio graph routing client PCM data through containers with decoders, converters, and mixers, labeled with SGKV metadata.
The graph works as follows:
1. The stream subgraph has a write shared memory endpoint, PCM decoder,
and PCM converter. The client passes PCM samples to the write shared
memory endpoint.
2. If conversion is necessary, the PCM converter converts PCM samples to
a format supported by the stream-specific postprocessing modules.
3. The output of the stream subgraph feeds into the stream-device
subgraph, which has the media format converter (MFC). The MFC
converts the stream-subgraph PCM to the device-subgraph PCM format.
4. After conversion, the output of the stream-device subgraph feeds into
the DevicePP subgraph for device-specific postprocessing. A mixer is
placed at the beginning of the subgraph to mix input streams.
5. The output of the DevicePP subgraph feeds into the device subgraph,
which has a hardware endpoint module such as an I2S driver.
The following is the GKV for this example graph:
GKV1:
GKV2:
Copy to clipboard
### Audio graph manager
The Audio Graph Manager (AGM) provides interfaces
that let TinyALSA-based mixer controls and PCM or compress plug-ins
interact and enable audio use cases. AGM runs as part of the PipeWire
service in user space. It provides APIs for mixer plug-ins and PCM or
compress APIs to set up audio use cases, maintains many ALSA clients to
set up use cases, and manages front-end to back-end connections.
The following figure shows the AGM software block at a high level.
AGM service architecture from the AGM API and session objects to graph objects on GSL and device objects on ALSA devices, across user and kernel space.
The following table describes the AGM objects.
AGM objects
| Object | Description |
| --- | --- |
| Session | An audio playback or capture session. Invoking session- specific mixer controls or APIs creates sessions. It provides APIs for TinyALSA plug-ins to configure streams and manages state transitions of graph and device objects. |
| Graph | An audio use case. It interacts with GSL to open, manage, and close graphs. It provides APIs for graph creation, manages graphs, and configures stream and device endpoints. |
| Device | An ALSA device from the ALSA sound card. It enumerates available audio interfaces and provides device APIs for transitioning device states. |
### AudioReach graph services
The AudioReachâ„¢ Signal Processing Framework graph services (ARGS)
consists of the graph service layer (GSL), generic packet router (GPR),
and acdb management layer (AML). ARGS handles initialization and
creation of graphs, and builds packets that send a series of commands to
the AudioReach Engine (ARE).
The following table describes the ARGS components.
ARGS components
| Component | Description |
| --- | --- |
| GSL | The graph service layer is a software driver for ARE that manages graphs, subgraphs, buffers, and configurations. It loads and initializes graphs using graph key vectors (GKVs) and handles data commands and ARE module calibration. |
| GPR | The generic packet router routes audio message packets across ARE and the graph service library. It handles commands for constructing audio graphs and processing audio. |
| AML | The ADCB management layer provides get and set APIs to get and adjust data in acdb files. It provides data abstractions and organization for how the audio driver and its components consume calibration data. |
### Audio calibration database
The audio calibration database (ADCB) is a static database on the
application processor. It holds all tuning and calibration parameters
for the LPAI. The `*.acdb` file format organizes calibration data for
various audio modules and use cases.
Edit the `*.acdb` file format with QACT (a PC tool) and place it on the
device file system in the `/etc/acdbdata/` folder. During use case
initialization or a device switch, the AML queries the ACDB database
with a specified GKV and pushes the device calibration data to ARE.
### AudioReach Engine
The AudioReach Engine (ARE) runs in the LPAI subsystem and performs audio data processing.
The following figure shows the high-level functional blocks used in ARE.

AudioReach Engine architecture showing its components, processing domains, and interaction with modules, hardware drivers, and the RTOS.
The following table describes the ARE components.
ARE components
| Component | Description |
| --- | --- |
| APM | The audio processing manager (APM) sets up and manages the use case graphs in ARE. It provides the standard APIs to the graph management library and the APM client to set up and configure audio use cases. |
| Modules | A module is a functional block in ARE. It performs real-time audio processing in the LPAI subsystem. |
| Containers | A container is a framework implementation that runs a group of data processing modules together in the same software thread. Each container runs in its own software thread. |
Last Published: Sep 08, 2026
[Previous Topic
Enable audio](https://docs.qualcomm.com/bundle/publicresource/80-A0399-50/topics/enable-audio.md) [Next Topic
Troubleshoot audio](https://docs.qualcomm.com/bundle/publicresource/80-A0399-50/topics/troubleshoot.md)