> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 启用基于 TinyALSA 的应用

> 在 Qualcomm Linux 上使用 PCM API 和虚拟混音器控件启用基于 TinyALSA 的音频应用。

TinyALSA 是一个将 ALSA 内核接口封装为客户端可调用 API 的库。它还提供了一个插件接口以模拟 ALSA API。

在以下位置查找 TinyALSA 源代码：

`build-qcom-wayland/workspace/sources/tinyalsa` 和

`build-qcom-wayland/workspace/sources/tinycompress`。

下图显示了 TinyALSA 插件架构。

<div className="flex flex-col items-center gap-2">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-staging/zh/Technologies/Audio/media/qualcomm-linux-iot-audio-voice/tinyalsa_plugin_architecture.svg" alt="TinyALSA plug-in architecture" />

  <p className="text-sm text-gray-700">
    TinyALSA 插件架构
  </p>
</div>

TinyALSATiny compressClientALSA/ASoC kernel frameworkCompress pluginPCM pluginMixer pluginPCMLibaudiorouteMixerCompressASoC driversOpen source/FrameworkLegend

TinyALSA 插件架构

内核中的 ALSA 框架为 PCM、compress 和 mixer 暴露卡和设备节点。

PCM、mixer 和 compress 插件是 TinyALSA 插件。它们将来自应用的所有 PCM、mixer 和 compress 调用路由到插件特定的实现。

插件创建带有 PCM、compress 和 mixer 节点的虚拟声卡。虚拟节点映射到设备上的 `.so` 文件（动态可加载共享对象）。

虚拟声卡配置在 `card-defs.xml` 文件中。此文件位于设备上的 `/etc/` 文件夹中。

## **TinyALSA API**

以下是常用的 TinyALSA API。有关所有 API 的完整说明，请参阅 [开源 TinyALSA 文档](https://github.com/tinyalsa/tinyalsa/blob/master/include/tinyalsa/pcm.h)。

### **pcm\_open**

打开 PCM 音频设备以进行输入和输出操作。为通信初始化 PCM 设备，允许对音频数据进行读/写操作。

```text theme={null}
struct pcm *pcm_open(
     unsigned int card,
     unsigned int device,
     unsigned int flags,
     struct pcm_config *config)
```

**参数**

| card   | 卡号。             |
| :----- | :-------------- |
| device | 所选卡中的设备号。       |
| flags  | 用于配置 PCM 设备的标志。 |
| config | 指定音频流参数的结构变量。   |

**返回值**

`pcm* handle`

### **pcm\_is\_ready**

检查 PCM 设备是否准备好进行输入和输出操作。

```text theme={null}
int pcm_is_ready(struct pcm *pcm)
```

**参数**

| pcm | 指向已打开的 PCM 设备的指针。 |
| :-- | :---------------- |

**返回值**

* 如果 PCM 设备已准备好，则为非零
* 如果 PCM 设备未准备好，则为 0

### **pcm\_prepare**

为音频设备的输入和输出操作做准备。

```text theme={null}
int pcm_prepare(
     struct pcm *pcm)
```

**参数**

| pcm | 指向已打开的 PCM 设备的指针。 |
| :-- | :---------------- |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

### **pcm\_start**

启动 PCM 音频设备以进行输入和输出操作。

```text theme={null}
int pcm_start(
     struct pcm *pcm)
```

**参数**

| pcm | 指向已打开的 PCM 设备的指针。 |
| :-- | :---------------- |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

### **pcm\_write**

将音频数据写入音频 PCM 设备。将音频数据作为输入，并将其发送到 PCM 设备以进行播放或处理。

```text theme={null}
int pcm_write(
     struct pcm *pcm,
     const void *data,
     unsigned int count)
```

**参数**

| pcm   | 指向已打开的 PCM 设备的指针。 |
| :---- | :---------------- |
| data  | 要写入的音频数据。         |
| count | 要写入的音频帧数。         |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

### **pcm\_read**

从 PCM 设备获取音频数据，允许应用从麦克风捕获音频数据。

```text theme={null}
int pcm_read(
     struct pcm *pcm,
     void *data,
     unsigned int count)
```

**参数**

| pcm   | 指向已打开的 PCM 设备的指针。 |
| :---- | :---------------- |
| data  | 要读取的音频数据。         |
| count | 要读取的音频帧数。         |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

### **pcm\_stop**

停止 PCM 音频设备的进一步输入和输出操作。

```text theme={null}
int pcm_stop(
     struct pcm *pcm)
```

**参数**

| pcm | 指向已打开的 PCM 设备的指针。 |
| :-- | :---------------- |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

### **pcm\_close**

关闭 PCM 音频设备。释放与 PCM 设备相关的资源并释放内存。

```text theme={null}
int pcm_close(
     struct pcm *pcm)
```

**参数**

| pcm | 指向已打开的 PCM 设备的指针。 |
| :-- | :---------------- |

**返回值**

* 成功时返回 0
* 失败时返回错误代码

## **配置 TinyALSA**

对于来自 TinyALSA 的音频用例，请配置虚拟混音器控件。

由混音器插件创建的这些控件设置了音频用例图和模块。大多数都是基于字节数组的，并使用 `mixer_ctl_set_array` API 进行配置。元数据（称为 'PCM100 metadata'）使用键值 (KV) 对设置。有关实现详情，请参阅 `build-qcom-wayland/workspace/sources/qcom-agm/opensource/agm/plugins/tinyalsa/test/agmmixer.c` 中的 `set_agm_audio_intf_metadata` API。

```text theme={null}
/**
            * Key Vector pair
            */
            struct agm_key_value {
            uint32_t key; /**< key */
            uint32_t value; /**< value */
            };
            /*Sample allocation for the key value pair*/
            gkv = calloc(num_gkv, sizeof(struct agm_key_value));
            ckv = calloc(num_ckv, sizeof(struct agm_key_value));
```

可以在以下位置找到基于 TinyALSA 的 agmplay 和 agmcap 实用程序的示例代码：

`build-qcom-wayland/workspace/sources/qcom-agm/opensource/agm/plugins/tinyalsa/test`。

要从 TinyALSA 启用并执行音频用例：

1. 设置音频接口（后端）设备配置，包括采样率、通道、格式和数据格式。
   ```text theme={null}
   'CODEC_DMA-LPAIF_WSA-RX-0 rate ch fmt' 48000 2 2(PCM_16)
   ```
2. 设置元数据，包括图键、设备的 cal 键和 DevicePP。
   ```text theme={null}
   'CODEC_DMA-LPAIF_WSA-RX-0 metadata' bytes
   ```
3. 设置控件以指示后续混音器配置将为流和 StreamPP 子图设置元数据。零表示后续命令用于流。
   ```text theme={null}
   'PCM100 control' Zero
                       'PCM100 metadata' bytes
   ```
4. 设置控件以指示后续混音器配置将为 DevicePP 和流-设备子图设置元数据。`CODEC_DMA-LPAIF_WSA-RX-0` 表示后续命令用于流-设备。`CODEC_DMA-LPAIF_WSA-RX-0` 是在 ALSA ASOC 框架中注册的音频接口之一。可以在 `/proc/asound/pcm` 中找到所有音频接口的列表。
   ```text theme={null}
   'PCM100 control' CODEC_DMA-LPAIF_WSA-RX-0
                       'PCM100 metadata' bytes
   ```
5. 检索与流和音频接口之间给定会话相关联的所有标签、模块 ID 和实例 ID。
   ```text theme={null}
   'PCM100 getTaggedInfo' bytes
   ```
6. 设置控件以指示后续混音器配置将为流子图上的模块设置参数。
   ```text theme={null}
   'PCM100 control' Zero
                       'PCM100 setParam' bytes
   ```
7. 设置控件以指示后续混音器配置将为 StreamDevice 和 DevicePP 子图上的模块设置参数。
   ```text theme={null}
   'PCM100 control' CODEC_DMA-LPAIF_WSA-RX-0
                       'PCM100 setParam' bytes
   ```
8. 将前端（流）与后端（编解码器/音频接口）连接。
   ```text theme={null}
   'PCM100 connect' CODEC_DMA-LPAIF_WSA-RX-0
   ```
9. 打开 PCM 设备。
   ```text theme={null}
   pcm_open
   ```
10. 为音频设备的输入和输出操作做准备。
    ```text theme={null}
    pcm_prepare
    ```
11. 启动 PCM 音频设备以进行输入和输出操作。
    ```text theme={null}
    pcm_start
    ```
12. 从音频 PCM 设备写入和读取音频数据。
    ```text theme={null}
    pcm_write/pcm_read
    ```
13. 停止 PCM 设备。
    ```text theme={null}
    pcm_stop
    ```
14. 关闭 PCM 音频设备。
    ```text theme={null}
    pcm_close
    ```

可以使用以下命令获取虚拟设备的所有混音器控件：

```text theme={null}
ssh root@ip-addr
```

```text theme={null}
systemctl stop pipewire
```

```text theme={null}
tinymix set -D 100
```

## **后续步骤**

* [自定义音频图](customize-audio-graph) — 在 PAL 级别自定义音频用例
* [故障排除音频](troubleshoot-audio) — 捕获并分析音频日志以解决问题
* [Audio Addendum](https://dragonwingdocs.qualcomm.com/Addendum-docs/Audio/audio-addendum-overview) — 使用 QACT 和 QXDM 进行校准和诊断