NAudio 在 Linux 上使用 ALSA 录制音频文件:NAudio.Alsa 与 AlsaIn 完整实战指南
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 录制四步法:
- 构造输入设备并设置
WaveFormat; - 订阅
DataAvailable,将采集到的字节写入WaveFileWriter; - 调用
StartRecording()/StopRecording(); - 在
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 录音最容易出错的地方,原则如下:
- 调用
StopRecording()只是请求停止并解除阻塞读取(内部执行snd_pcm_drop让阻塞的snd_pcm_readi立即返回,然后 join 线程); - 真正可以安全释放写入器的时机是
RecordingStopped事件——它带有一个StoppedEventArgs,其Exception属性在采集线程因错误退出时携带异常信息(正常停止则为null); 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)的录音任务。