NAudio 在 Linux 上使用 ALSA 录制音频文件:NAudio.Alsa 与 AlsaIn 完整实战指南

原创2026-10-09 14:46:061,923 阅读
文章标签:音视频音频处理

NAudio 在 Linux 上使用 ALSA 录制音频文件:NAudio.Alsa 与 AlsaIn 完整实战指南

本指南讲解如何使用 NAudio 的 NAudio.Alsa 包在 Linux 平台上通过 ALSA 采集设备录制音频:从环境依赖、包安装,到 AlsaIn 的标准录制模式、设备枚举与选择、格式映射与异常处理,再到后台采集线程与缓冲区复用等底层原理。读完本文,你将能独立编写一个可落地运行的 Linux 录音程序(录制 WAV,并可扩展为 FLAC/Ogg/Opus),并理解 ALSA 设备名、采样格式协商与录制停止时机等关键细节。

一、环境准备:libasound 运行时与包安装

NAudio.Alsa 是 NAudio 在 Linux 上提供 ALSA 录音与放音的独立包。它的核心类型 AlsaIn 实现了 NAudio 标准的 IWaveIn 接口,专门用于从 ALSA 采集(capture)设备录音。

1. 安装 ALSA 运行时

包内部通过 P/Invoke 调用 libasound,其 SONAME 为 libasound.so.2,会被自动解析——不需要安装 -dev 开发头文件包。若系统缺少运行时,先安装:

sudo apt install libasound2t64  # Ubuntu 24.04+(t64 迁移后更名)
sudo apt install libasound2     # 较早的 Debian/Ubuntu

2. 添加 NuGet 包

dotnet add package NAudio.Alsa

两点需要注意(见 src/NAudio.Alsa/README.md):

  • 平台限制:该程序集被标记为 [SupportedOSPlatform("linux")],仅面向 Linux;
  • 不被 meta 包自动引用:NAudio 总包没有 net9.0-linux 目标框架,因此 NAudio.Alsa 不会被隐式带入,必须像上面这样显式引用。

二、标准录制模式:五秒录出一个 WAV 文件

AlsaIn 的用法与 NAudio 的 WaveIn / WasapiCapture 完全一致,遵循标准的 NAudio 录制四步法:

  1. 构造输入设备并设置 WaveFormat;
  2. 订阅 DataAvailable,将采集到的字节写入 WaveFileWriter;
  3. 调用 StartRecording() / StopRecording();
  4. 在 RecordingStopped 回调中(而非 StopRecording() 返回时)释放写入器——因为 RecordingStopped 表示采集线程已完全结束,此时再写文件才是安全的。

参考 RecordAudioFileLinuxAlsa.md 中的完整示例:

using NAudio.Wave;
using NAudio.Wave.Alsa;

var waveFormat = new WaveFormat(44100, 16, 2);
var writer = new WaveFileWriter("recorded.wav", waveFormat);

using var input = new AlsaIn();           // 或 new AlsaIn("hw:0")
input.WaveFormat = waveFormat;

input.DataAvailable += (sender, a) =>
{
    writer.Write(a.Buffer, 0, a.BytesRecorded);
};

input.RecordingStopped += (sender, a) =>
{
    writer.Dispose();
    writer = null;
};

input.StartRecording();
Thread.Sleep(5000);                       // 录制 5 秒
input.StopRecording();

与源码的对照:StartRecording() 内部做了什么

从 AlsaIn.cs 可以看到 StartRecording() 的完整调用链:

var format = AlsaFormat.FromWaveFormat(waveFormat);   // WaveFormat -> ALSA PCMFormat
frameBytes = AlsaFormat.FrameBytes(waveFormat);       // 每帧字节数
pcm.ConfigureHardware(format, waveFormat.Channels, waveFormat.SampleRate);
pcm.ConfigureSoftware(AlsaPcm.PeriodFrames);
pcm.Prepare();
AlsaException.ThrowIfError(AlsaInterop.PcmStart(pcm.Pcm), "snd_pcm_start");
pcm.StartWorker("ALSA Capture", CaptureLoop);

也就是说,StartRecording() 会依次完成:格式映射 → 硬件参数协商 → 软件参数协商 → snd_pcm_prepare → snd_pcm_start → 启动后台采集线程。其中任何一步失败都会抛出对应异常(详见第五节)。

WaveFormat 的约束

AlsaIn 的默认 WaveFormat 为 44100 Hz / 16 bit / 2 声道(见 AlsaIn.cs)。该属性在录制期间被锁定——从 AlsaIn.cs 可以看到,录制中修改会抛出 InvalidOperationException("Cannot change WaveFormat while recording"),这一行为也有对应的测试覆盖(见 tests/NAudio.Alsa.Tests/AlsaCaptureTests.cs):

Assert.Throws<InvalidOperationException>(
    () => input.WaveFormat = new WaveFormat(48000, 16, 2));

三、选择与枚举录制设备

AlsaIn 有两个构造函数(见 AlsaIn.cs):

  • new AlsaIn()——等价于 new AlsaIn("default"),使用系统默认 PCM 设备;
  • new AlsaIn(string device)——指定 ALSA PCM 名称,例如 "hw:0"、"hw:1" 或 "hw:CARD=PCH,DEV=0"。

枚举所有采集设备

AlsaDeviceEnumerator.GetCaptureDevices() 返回 IReadOnlyList<AlsaDeviceInfo>,每个 AlsaDeviceInfo 包含可直接传给构造函数的 Name 与人类可读的 Description。参考 RecordAudioFileLinuxAlsa.md 的示例:

foreach (var device in AlsaDeviceEnumerator.GetCaptureDevices())
{
    Console.WriteLine($"{device.Name} - {device.Description}");
}
// using var input = new AlsaIn("hw:1");

底层实现基于 ALSA 的 snd_device_name_hint(见 AlsaDeviceEnumerator.cs),并利用 IOID 提示过滤方向:

  • IOID == "Input" → 采集设备(GetCaptureDevices);
  • IOID == "Output" → 播放设备(GetPlaybackDevices);
  • IOID 缺失 = 双向设备,会同时出现在两个列表中——测试 AlsaDeviceEnumeratorTests.cs 用 "null" 设备验证了这一行为。

枚举得到的 Name 可以直接用于打开设备,EnumeratedNameCanBeOpened 测试同样验证了这一点。

四、DataAvailable 回调语义:缓冲区是复用的

DataAvailable 的事件参数类型是 WaveInEventArgs,其 Buffer 为 byte 数组、BytesRecorded 为本回调实际采集到的字节数。关键约束:该缓冲区在下一次回调时会被复用,因此必须在处理器返回前把数据写出或复制(参考 RecordAudioFileLinuxAlsa.md)。

上面的示例中 writer.Write(a.Buffer, 0, a.BytesRecorded) 属于“同步写出、立即返回”的安全用法;如果你需要把数据交给异步队列或其他线程处理,必须先 a.Buffer 的副本。

采集循环的底层实现

从 AlsaIn.cs 可以看到后台线程的 CaptureLoop:

var buffer = new byte[AlsaPcm.PeriodFrames * frameBytes];
while (pcm.Running)
{
    nint read = AlsaInterop.PcmReadI(pcm.Pcm, buffer, AlsaPcm.PeriodFrames);
    if (read < 0) { /* 过载恢复:snd_pcm_recover + snd_pcm_start,或抛出 AlsaException */ }
    DataAvailable?.Invoke(this, new WaveInEventArgs(buffer, (int)read * frameBytes));
}
RecordingStopped?.Invoke(this, new StoppedEventArgs(error));

几个实现要点(印证自 AlsaPcm.cs):

  • 周期(period):PeriodFrames = 1024,Periods = 4(AlsaPcm.cs)。即每 1024 帧触发一次 DataAvailable,设备环形缓冲区共 4 个周期;
  • 阻塞式读取:工作线程执行阻塞的 snd_pcm_readi,每次读满一个周期后抛出一个 DataAvailable 事件;
  • 过载(overrun)恢复:读取返回负值时调用 snd_pcm_recover,恢复失败才抛出 AlsaException,因此偶发的短暂过载不会直接终止录音;
  • 线程属性:采集线程名为 "ALSA Capture"、IsBackground = true、优先级 AboveNormal(AlsaPcm.cs)。在 Linux 上这等价于一次 nice() 提升,无需 root 权限;若在重负载下追求无毛刺录音,仍需要调用方/系统层面配合 RT 调度(rtkit / SCHED_FIFO);
  • 线程总是先 join 再关句柄:StopWorker 幂等,且若在 DataAvailable 处理器内调用 StopRecording() 不会自 join 造成死锁——这是有专门回归测试保障的(见 AlsaCaptureTests.cs)。

延迟估算:IWaveLatency

AlsaIn 同时实现了 IWaveLatency(AlsaIn.cs):

  • AverageLatency:稳态延迟 ≈ PeriodFrames × Periods / SampleRate(例如 44.1 kHz 下约 1024×4/44100 ≈ 93ms);
  • CurrentLatency:通过 snd_pcm_delay 实时查询采集侧尚未读取的帧数,即最旧未读样本的“年龄”;查询失败或未运行时回退到 AverageLatency。

如果你需要低延迟监听或精确的时间对齐,这两个属性值得关注。

五、录制格式映射:支持哪些格式,什么时候抛异常

AlsaIn 不做任意格式转换,而是把 NAudio 的 WaveFormat 直接映射为 ALSA 的 interleaved 小端采样格式。映射表实现在 AlsaFormat.cs:

WaveFormat(Encoding / BitsPerSample) ALSA PCM 格式
IeeeFloat 32-bit SND_PCM_FORMAT_FLOAT_LE
Pcm 8-bit SND_PCM_FORMAT_U8
Pcm 16-bit SND_PCM_FORMAT_S16_LE
Pcm 24-bit SND_PCM_FORMAT_S24_3LE
Pcm 32-bit SND_PCM_FORMAT_S32_LE
其他(如 A-law、Mu-law、GSM 等) 抛出 NotSupportedException

也就是说,支持的录制格式限定为:8/16/24/32-bit PCM 或 32-bit IEEE float。测试 AlsaFormatTests.cs 用 A-law 格式验证了不支持格式抛 NotSupportedException 的行为。

每帧字节数按 BitsPerSample / 8 × Channels 计算(AlsaFormat.cs),例如 16-bit/2 声道为 4 字节、24-bit/2 声道为 6 字节。

异常类型速查

场景 异常 触发时机
WaveFormat 没有 ALSA 映射(非 PCM/float) NotSupportedException StartRecording() 中的格式映射阶段
设备无法以请求的参数打开(如设备不存在、权限不足) AlsaException 构造 AlsaIn 或 StartRecording()
录制中修改 WaveFormat InvalidOperationException 属性 setter
重复调用 StartRecording() InvalidOperationException StartRecording()

AlsaException 封装了 libasound 的负值错误码:ErrorCode 属性保存原始错误码,Function 属性记录失败的 libasound 函数名,消息文本则由 snd_strerror 生成(见 AlsaException.cs),排查问题非常方便。

设备名选择:default / plughw: 优于裸 hw:

ALSA 设备名的行为差异直接影响格式协商成功率:

  • 裸 hw:N:直接访问硬件,只接受设备原生支持的格式与采样率。例如某声卡硬件只支持 48 kHz,用 new AlsaIn("hw:0") + 44.1 kHz 配置就会失败;
  • plughw:N 与 default:走插件层,ALSA 会自动完成格式/采样率转换,任意合法 PCM 格式都可以工作。

因此,除非你确定设备硬件原生支持你请求的格式与采样率,否则优先使用 default 或 plughw: 设备(参考 RecordAudioFileLinuxAlsa.md)。ConfigureHardware 内部也确实使用 snd_pcm_hw_params_set_rate_near 等“就近协商”调用(AlsaPcm.cs),插件层设备通常能把请求值精确落入支持范围。

六、录制停止与资源释放的最佳实践

正确的停止流程是 NAudio 录音最容易出错的地方,原则如下:

  1. 调用 StopRecording() 只是请求停止并解除阻塞读取(内部执行 snd_pcm_drop 让阻塞的 snd_pcm_readi 立即返回,然后 join 线程);
  2. 真正可以安全释放写入器的时机是 RecordingStopped 事件——它带有一个 StoppedEventArgs,其 Exception 属性在采集线程因错误退出时携带异常信息(正常停止则为 null);
  3. RecordingStopped 在采集线程完全结束之后触发(AlsaIn.cs),此时不会再有任何写入发生,释放 WaveFileWriter(它会写入 WAV 头部的数据块大小)是安全的。

这也解释了为什么示例代码要把 writer.Dispose() 放在 RecordingStopped 处理器里,而不是 StopRecording() 之后。

七、进阶:直接录制为 FLAC / Ogg / Opus

WaveFileWriter 只写 WAV(PCM/float 无压缩)。若要直接录制压缩格式,NAudio.Alsa 的 README 推荐与跨平台的 NAudio.SoundFile(基于 libsndfile)配合使用:SoundFileWriter 支持编码 FLAC、Ogg-Vorbis、Opus 等格式,且其输出流(WaveStream/ISampleProvider)与 AlsaIn 的 DataAvailable 字节流是同一套 NAudio 数据管道,替换写入目标即可:

// dotnet add package NAudio.SoundFile
// using NAudio.SoundFile;
using var writer = new SoundFileWriter("captured.flac", new WaveFormat(44100, 16, 2));
using var input = new AlsaIn { WaveFormat = writer.WaveFormat };
input.DataAvailable += (s, a) => writer.Write(a.Buffer, 0, a.BytesRecorded);
input.StartRecording();
Thread.Sleep(5000);
input.StopRecording();

详情可参考 NAudio.SoundFile/README.md(需系统安装 libsndfile)。放音侧的对称用法见 PlayAudioFileLinuxAlsa.md,录音的跨平台对照(macOS 用 NAudio.MacOS 的 AudioInput)见 RecordAudioFileMacOS.md。

八、测试与验证:仓库中的可运行佐证

仓库的 NAudio.Alsa.Tests 项目(tests/NAudio.Alsa.Tests)覆盖了本文涉及的核心行为,可作为验证与参考:

  • AlsaCaptureTests.cs:默认 WaveFormat 已设置、完整录制一轮后 RecordingStopped 无错误触发、DataAvailable 处理器内调用 StopRecording() 不死锁、录制中改格式抛异常;
  • AlsaFormatTests.cs:5 种格式映射与 NotSupportedException、每帧字节数计算;
  • AlsaDeviceEnumeratorTests.cs:播放/采集列表非空、双向设备同时出现在两个方向、枚举出的设备名可被实际打开。

测试使用 ALSA 的 "null" 虚拟 PCM 设备,无需真实声卡即可跑通采集链路,非常适合先验证环境(libasound 是否就绪)再接入真实硬件。

九、常见问题速查

现象 原因与对策
找不到 NAudio.Wave.Alsa 命名空间 未显式添加 NAudio.Alsa 包(meta 包不会带入);或目标平台不是 Linux
AlsaException:打开设备失败 设备名错误、无权限或未安装 libasound2;先用 AlsaDeviceEnumerator.GetCaptureDevices() 确认设备名
NotSupportedException:格式无 ALSA 映射 WaveFormat 编码不是 PCM/IEEE float,或位深不是 8/16/24/32;换用支持的格式
44.1 kHz 在 hw:0 上启动失败 硬件不原生支持该采样率;改用 plughw:0 或 default
数据丢失/波形不连续 确认在 DataAvailable 中同步写出或复制缓冲区;偶发过载已由 snd_pcm_recover 自动恢复
RecordingStopped 一直不来 确认 StopRecording() 已被调用;该事件由采集线程在退出时触发

结语

NAudio.Alsa 的 AlsaIn 用一套与 Windows 端 WaveIn 完全一致的 IWaveIn 抽象,把 ALSA 采集封装成熟悉的 NAudio 事件模型。掌握“设置 WaveFormat → 消费 DataAvailable → 在 RecordingStopped 中收尾”这条主线,加上格式映射表、设备名语义与线程模型这些底层认知,你就能在 Linux 上稳定地完成从麦克风/线路输入到 WAV(乃至 FLAC/Ogg/Opus)的录音任务。

登录后查看全文
NAudio