Linux Audio开发-ALSA API列表

本文列出了 Linux ALSA (Advanced Linux Sound Architecture) 开发中常用的核心 API 列表，按功能分类。

ALSA PCM 音频流基础 API

API 函数	作用	使用场景
snd_pcm_open()	打开 PCM 设备	初始化音频设备（播放/录制）
snd_pcm_close()	关闭 PCM 设备	释放设备资源
snd_pcm_hw_params_malloc()	分配硬件参数结构体内存	准备设置硬件参数
snd_pcm_hw_params_any()	初始化硬件参数为默认值	首次配置设备参数
snd_pcm_hw_params_set_format()	设置采样格式	指定数据格式如 S16_LE, FLOAT_LE 等
snd_pcm_hw_params_set_rate_near()	设置采样率	配置采样频率（44.1kHz/48kHz 等）
snd_pcm_hw_params_set_channels()	设置声道数	配置单声道/立体声/多声道
snd_pcm_hw_params()	应用硬件参数到设备	最终确认参数配置
snd_pcm_sw_params_malloc()	分配软件参数结构体内存	配置底层缓冲行为
snd_pcm_sw_params_current()	获取当前软件参数	修改前的基础参数
snd_pcm_sw_params_set_avail_min()	设置唤醒阈值	定义触发传输的最小空闲空间
snd_pcm_sw_params()	应用软件参数	配置流控制策略
snd_pcm_writei()	交错模式写入数据（播放）	音频播放的主要输出函数
snd_pcm_readi()	交错模式读取数据（录制）	音频录制的主要输入函数
snd_pcm_prepare()	准备音频流	重置状态（在出错后恢复）
snd_pcm_drain()	排空缓冲区数据	播放收尾（等待缓冲数据播完）
snd_pcm_drop()	立即停止传输	强制中断音频流

错误处理与状态 API

API 函数	作用	使用场景
snd_pcm_state()	获取 PCM 设备当前状态	检测状态如 RUNNING, PREPARED, XRUN 等
snd_pcm_recover()	从错误状态恢复	处理缓存欠载/过载等错误（自动调用 prepare）
snd_strerror()	将错误码转为可读字符串	调试输出错误信息

配置辅助 API

API 函数	作用	使用场景
snd_pcm_format_size()	计算指定格式的帧大小	数据缓冲区分配依据
snd_pcm_frames_to_bytes()	帧数转字节数	计算数据传输量
snd_pcm_hw_params_get_period_size()	获取周期尺寸（帧数）	确定单次读写操作量
snd_pcm_get_htimestamp()	获取精确硬件时间戳	计算精确延迟

异步通知 API

API 函数	作用	使用场景
snd_async_add_pcm_handler()	注册异步回调处理函数	事件驱动处理（需文件描述符）
snd_pcm_wait()	阻塞等待设备可操作状态	轮询式处理替代方案

典型工作流（播放）

// 伪代码示例
1. snd_pcm_open(&handle, "default", SND_PCM_STREAM_PLAYBACK, 0);
2. snd_pcm_hw_params_malloc(&params);
3. snd_pcm_hw_params_any(handle, params);
4. snd_pcm_hw_params_set_access(handle, params, SND_PCM_ACCESS_RW_INTERLEAVED);
5. snd_pcm_hw_params_set_format(handle, params, SND_PCM_FORMAT_S16_LE);
6. snd_pcm_hw_params_set_channels(handle, params, 2);
7. snd_pcm_hw_params_set_rate_near(handle, params, 44100, 0);
8. snd_pcm_hw_params(handle, params);
9. while(playing) {
     snd_pcm_writei(handle, buffer, frames);
     if ((rc = snd_pcm_recover(handle, rc, 0)) < 0) break;
   }
10. snd_pcm_drain(handle);
11. snd_pcm_close(handle);

关键概念补充

• 访问模式：

  • INTERLEAVED：交错数据 (L/R/L/R...)
  • NONINTERLEAVED：分离数据 (LLLL.../RRRR...)

• 状态机：

  OPEN→ SETPARAMS→ PREPARED→ RUNNING→ UNDERRUN/OVERRUN

• 缓冲配置：

  buffer_size(总缓冲区) = period_size(单周期) × period_count(周期数)

官方文档：

ALSA API 文档 (opens new window)

头文件参考： <alsa/asoundlib.h>