音视频音频处理【免费下载链接】NAudioAudio and MIDI library for .NET项目地址https://gitcode.com/gh_mirrors/na/NAudio点击查看免费下载本篇指南基于 NAudio 仓库中的 PlayAudioFileMacOS.md 文档展开系统讲解在 macOS 上通过NAudio.MacOS包中的CoreAudioPlayer播放任意IWaveProvider以 WAV 文件为例的完整流程从安装预发布包、默认设备播放、设备枚举与选择、隐藏设备获取到硬件音量控制与逐通道音量调节。阅读本文后你将能够在 macOS 应用中以最小代码量完成音频播放并理解其内部格式协商、自动重采样与 HAL 格式变更自愈机制具备直接投入实战与二次开发的能力。为什么 macOS 上需要 CoreAudioPlayer在 NAudio 生态中Windows 平台常见的WaveOut、WasapiOut等输出设备实现依赖 WASAPI / WaveOut 等 Windows 专属 APImacOS 上并不存在这些 API。因此 NAudio 为 macOS 提供了独立的NAudio.MacOS包其中包含Core Audio Framework音频 HAL的托管封装围绕 Apple 的 Core Audio HAL API 提供设备枚举、属性读取、I/O 回调注册等基础能力CoreAudioPlayer位于NAudio.Wave命名空间一个通过 Core Audio HAL 播放音频的IWavePlayer实现也是 NAudio 用户在 macOS 上进行播放时的默认选择CoreAudioRecorder对应的录音实现Audio Toolbox 的 Audio Converter Services 与 Extended Audio File Services提供 macOS 原生重采样器、MP3只读、MP4/AAC、OGG Vorbis只读、FLAC 等文件读写能力。从源码注释可见CoreAudioPlayer被标记为[SupportedOSPlatform(ios2.0)]与[SupportedOSPlatform(macos10.5)]即支持 iOS 2.0 与 macOS 10.5 及以上版本见 CoreAudioPlayer.BaseAPI.cs。包引用状态预发布Pre-releaseNAudio.MacOS属于独立分包不包含在NAudio元包meta-package中必须显式引用。同时该包目前仍处于预发布阶段其 API 仍在演进、可能发生破坏性变更因此安装时需要使用--prerelease开关dotnet add package NAudio.MacOS --prerelease这一点在包的 README.md 中也有同样说明该包仍处于 pre-release 阶段可能发生破坏性代码变更请自行评估使用风险。最小播放示例默认输出设备播放 WAV 文件CoreAudioPlayer可以播放你提供的任意IWaveProvider。对于 WAV 文件可以直接使用 NAudio Core 库中的WaveFileReader读取using NAudio.Wave; using (var audioFile new WaveFileReader(any.wav)) using (var outputDevice new CoreAudioPlayer()) // 默认输出设备 { outputDevice.Init(audioFile); outputDevice.Play(); while (outputDevice.PlaybackState PlaybackState.Playing) { Thread.Sleep(200); } }代码要点new CoreAudioPlayer()的无参构造函数会通过AudioSystemObject.Instance.DefaultOutputDevice自动选定系统默认输出设备见 CoreAudioPlayer.BaseAPI.csInit(IWaveProvider)完成设备初始化、格式协商与 I/O 回调注册之后才能调用Play()主线程通过轮询PlaybackState并在循环中Thread.Sleep(200)等待播放自然结束避免using块提前释放资源播放结束后Dispose会一并释放设备监听句柄、I/O 过程与数据源。仓库中的集成测试给出了同样的使用范式测试CanPlayThreeSecondSignal用SignalGenerator生成 3 秒白噪声覆盖 44100/48000/52000/64000 Hz、单声道/双声道/三声道/四声道以及 IEEE float 与非 float 共 8 种组合均通过Init → Play → 轮询 PlaybackState → Stop → Dispose的流程验证见 CoreAudioPlayerTests.cs。无需手动协商格式内部自动重采样[!NOTE]CoreAudioPlayer不需要你在调用方做任何设备格式协商该工作由类的内部算法完成。当你的 wave provider 的格式与 HAL 当前格式不一致时它会在内部重采样以匹配。由于 HAL 格式经常变化该类会为你妥善处理这些变化。这个零配置承诺在源码层面有明确支撑。以Init为入口Initialize(bool) 会执行以下决策流程通过selectedDevice.GetStreams(AudioObjectPropertyScopeConstants.Output)获取设备的输出流列表逐个检查流的VirtualFormatNativeHAL 虚拟格式寻找与 provider 格式匹配采样率、位深、块对齐、声道数、编码全部一致的流直接复用若设备流是**非交错non-interleaved**布局则要求所有流格式一致并重建交错后的描述符多数情况下由此引入重采样需求若没有匹配的流则选定第一条流并启用内部重采样器。当需要重采样时ResamplerSource会创建LowLevelAudioConverter底层即 macOS Audio Converter Services把 provider 的数据按目标 ASBD 转换后交给 HAL 缓冲见 CoreAudioPlayer.ResamplerSource.cs当格式完全匹配时则使用RawSource直接把 provider 的数据拷贝进 HAL 缓冲零额外转换开销见 CoreAudioPlayer.RawSource.cs。应对 HAL 格式变化与设备失效在 I/O 过程中CoreAudioPlayer还通过属性监听实现了两类自愈虚拟格式变化OnVirtualFormatChanged当设备流的虚拟格式发生改变时先停止当前 I/O 过程销毁旧的数据源含重采样器再从零开始Initialize()若此前正在播放则自动恢复播放见 CoreAudioPlayer.InitAPI.cs流变更OnStreamsChanged输出流集合变化时同样执行停止 → 重建 → 恢复流程见 CoreAudioPlayer.InitAPI.cs设备失效OnDeviceWillBeDestroyed当所选设备即将被移除时播放器进入Invalidated状态并通过PlaybackStopped事件以CoreAudioException携带kAudioHardwareBadDeviceError通知调用方见 CoreAudioPlayer.InitAPI.cs。仓库测试IsHardenedAgainstVirtualFormatChanges专门验证了播放器在外部线程随机修改流虚拟格式时仍能正确重建初始化逻辑见 CoreAudioPlayerTests.cs。选择输出设备进行播放如果不想使用系统默认输出设备可以先通过 HAL 音频系统对象AudioSystemObject的Devices属性枚举系统当前安装的全部设备using NAudio.MacOS.CoreAudio; // 枚举所有可提供输出的设备。 foreach (var device in AudioSystemObject.Instance.Devices) { if (device.GetStreams(AudioObjectPropertyScopeConstants.Output).Length 0) { Console.WriteLine(${device.Name} - {device.Manufacturer}); } } // 选定设备后将其交给播放器 // using var createdPlayer new CoreAudioPlayer(chosenDevice);要点说明AudioSystemObject.Instance是 HAL 音频系统对象的单例入口源码中对应kAudioHardwarePropertyDevices属性枚举见 AudioSystemObject.cs用GetStreams(AudioObjectPropertyScopeConstants.Output)的返回值长度来判断设备是否具备输出能力选定的设备对象通过new CoreAudioPlayer(AudioDevice device)构造函数传入见 CoreAudioPlayer.BaseAPI.cs。注意该构造函数会校验设备IsAlive若设备即将被移除会抛出InvalidOperationException。[!NOTE]Devices属性返回的是调用时刻系统中安装的全部设备既包含输出设备也包含输入设备筛选输出设备是调用方自己的职责。[!NOTE] 你也可以通过音频系统对象实例提供的ConvertUIDToDevice方法获取隐藏设备hidden device。前提是你必须知道该设备的 UID。任何设备都可以通过其DeviceUID属性取得 UID对于CoreAudioPlayer则可以通过Device属性拿到它正在使用的设备对象进而读取DeviceUID。这一补充说明在源码中有完整对应AudioSystemObject.ConvertUIDToDevice(string uid)用于按 UID 解析设备见 AudioSystemObject.csAudioDevice.DeviceUID读取设备的kAudioDevicePropertyDeviceUID见 AudioDevice.cs而CoreAudioPlayer.Device属性直接暴露当前选中的设备对象见 CoreAudioPlayer.BaseAPI.cs。关于播放状态与暂停语义PlaybackState只会返回Playing或Stopped两种状态——这是因为 HAL 的 I/O 过程模型中没有暂停概念HAL 按需周期性回调每个 I/O 过程因此Pause()在实现上直接硬连线到Stop()自然也就不存在Paused状态见 CoreAudioPlayer.BaseAPI.cs。若你的业务逻辑依赖暂停语义需要自行维护目标暂停位置并在恢复时重新Init并Play相应片段。另外Stop()对PlaybackStopped事件做了去重仅在状态为Playing时触发一次事件避免源数据自然耗尽与主动Stop()造成事件重复派发见 CoreAudioPlayer.BaseAPI.cs。播放过程中的异常也会通过StoppedEventArgs.Exception透出测试中正是通过检查该字段来断言播放未被异常中断。改变设备的增益音量整体音量Volume 属性直接设置CoreAudioPlayer实例上的Volume属性即可改变设备音量createdPlayer.Volume 0.8f;关于该属性的实现与约束见 CoreAudioPlayer.BaseAPI.cs取值范围为0f到1f越界赋值会抛出ArgumentOutOfRangeException赋值操作会遍历所选设备的ControlList对所有AudioLevelControl且Kind AudioControlKind.VolumeControl的控件设置ScalarValue读取操作会基于每个音量控件的DecibelRange与DecibelValue反算标量值并取最小值源码注释提醒某些情况下 HAL 的属性更新存在滞后读取可能返回过时的 1但赋值总能达到预期效果。[!WARNING] 与许多其他IWavePlayer实现不同此实现直接修改设备的硬件音量控制。系统用户通常会将音量设置为期望值因此不建议你修改该值。如果只想调整增益而不打扰用户设置的系统音量请使用VolumeSampleProvider。也就是说软件增益的推荐做法是把VolumeSampleProvider注入到音频链路中例如var volumeProvider new VolumeSampleProvider(sampleSource.ToSampleProvider()) { Volume 0.8f }; // outputDevice.Init(volumeProvider.ToWaveProvider());VolumeSampleProvider位于NAudio.Wave.SampleProviders命名空间是 NAudio Core 库提供的通用软件增益组件不影响任何硬件音量状态。逐通道音量遍历设备控制列表在某些情况下你可能希望按通道分别修改音量。做法是取出设备的控制列表并逐个遍历控件foreach (var control in createdPlayer.Device.ControlList) { if (control is AudioLevelControl lc lc.Kind AudioControlKind.VolumeControl) { System.Console.WriteLine(Modifying volume of channel {0}., lc.Element); lc.ScalarValue 0.8f; } }说明CoreAudioPlayer.Device.ControlList等价于调用所选设备对象的ControlList属性底层读取设备的kAudioObjectPropertyControlList见 AudioDevice.csAudioLevelControl是音量电平控件的托管封装其ScalarValue属性读写设备的kAudioLevelControlPropertyScalarValue见 AudioLevelControl.cslc.Element标识该控件对应的通道元素据此可以仅对特定声道例如只降低左声道进行调节设备也提供ConstructControlListChangedEvent()等方法用于监听控制列表变化见 AudioDevice.cs适合实现音量面板的实时刷新。播放器其他实用能力一览CoreAudioPlayer除播放与音量控制外还实现了 NAudio 的若干标准接口见 CoreAudioPlayer.BaseAPI.cs接口 / 能力说明IWavePlayer提供Init、Play、Pause、Stop、PlaybackState、PlaybackStopped等标准播放契约IWaveLatencyAverageLatency由设备输出延迟与所选数据源的流延迟相加求得CurrentLatency优先根据 I/O 回调中的采样时间/主机时间戳实时计算时间戳无效时回退到AverageLatency见 CoreAudioPlayer.IOProcedureBase.csIWavePositionGetPosition()返回累计播放字节数暂停时记账、停止时清零语义与WaveOut的waveOutReset/waveOutPause对齐见 CoreAudioPlayer.BaseAPI.csOutputWaveFormat返回当前实际交付给 HAL 的虚拟格式含重采样后的目标格式IAsyncDisposableDisposeAsync()将线程安全的Dispose()调度到线程池执行其中PlaybackStopped事件的派发遵循创建播放器时的SynchronizationContext若创建线程存在同步上下文如 UI 线程事件会投递回该上下文执行避免在 HAL I/O 线程上直接回调用户代码见 CoreAudioPlayer.BaseAPI.cs。数据流向与 I/O 过程原理源码级为了更深入理解CoreAudioPlayer这里梳理其数据管线对应源码文件见 src/NAudio.MacOS/Wave/ 下的CoreAudioPlayer.*.csIWaveProvider │ ProviderFormatMatchesPlayerFormat 判定是否匹配 HAL 虚拟格式 ▼ RawSource格式匹配直接拷贝 │ 或 ResamplerSource格式不匹配经 LowLevelAudioConverter 重采样/声道转换 ▼ PlayerProcedureCoreAudioIOProcedure 子类HAL I/O 回调 ├── InterleavedProcedure交错布局只填充 EnabledBufferIndex 指定的缓冲 └── NonInterleavedProcedure非交错布局先读入临时交错缓冲再按通道拆写 ▼ HAL AudioBufferList → 音频设备两个 I/O 过程实现各有讲究InterleavedProcedure会完整填满分配给它的 HAL 缓冲循环读取直到缓冲耗尽且只写入EnabledBufferIndex指定的那一个缓冲——因为输出AudioBufferList中每个设备流都有一个缓冲禁用流对应的缓冲会被 HAL 丢弃若全部填充会造成数据源被多次消费见 CoreAudioPlayer.InterleavedProcedure.csNonInterleavedProcedure按每帧通道字节数 × 通道数的步长把交错的中间缓冲数据拆解写入各通道缓冲并自动扩容临时缓冲见 CoreAudioPlayer.NonInterleavedProcedure.cs基类PlayerProcedure在源数据耗尽后不会立即停止而是等到下一个 I/O 周期再停确保 HAL 已消费完缓冲中最后的数据避免截断见 CoreAudioPlayer.IOProcedureBase.cs。常见问题与最佳实践小结找不到 NAudio.MacOS 包该包仅以预发布版本发布dotnet add package必须带--prerelease。播放无声或采样率不对无需自行重采样——播放器会根据 HAL 虚拟格式自动插入LowLevelAudioConverter请勿在 provider 侧重复重采样避免双重转换带来的音质损耗。想控制音量但不想动系统音量使用VolumeSampleProvider做软件增益CoreAudioPlayer.Volume只应在明确需要修改硬件音量时才使用。监听播放结束/异常订阅PlaybackStopped并检查StoppedEventArgs.Exception事件在存在同步上下文时会回投到创建线程派发。设备被拔出怎么办播放器会通过PlaybackStopped携带CoreAudioExceptionkAudioHardwareBadDeviceError通知你此时应释放旧实例并重新枚举设备重建播放器。多设备选择结合AudioSystemObject.Instance.Devices、DeviceUID与ConvertUIDToDevice可以在启动时记住用户选择的设备 UID下次直接解析并传入构造函数从而支持隐藏设备。延伸阅读PlayAudioFileMacOS.md本文对应的原始文档src/NAudio.MacOS/README.mdNAudio.MacOS包的能力边界与预发布状态说明CoreAudioPlayer.BaseAPI.cs播放器公开 API、音量与状态管理实现CoreAudioPlayer.InitAPI.cs格式匹配、重采样决策与自愈逻辑CoreAudioPlayerTests.cs多格式播放与虚拟格式变更压力测试PlayAudioFileLinuxAlsa.md 与 PlayAudioFileMacOS.md 对应的其他平台播放指南可作横向对比Linux 侧对应NAudio.Alsa包的AlsaOut。赞分享音视频音频处理【免费下载链接】NAudioAudio and MIDI library for .NET项目地址https://gitcode.com/gh_mirrors/na/NAudio点击查看免费下载相关推荐使用 NAudio.MacOS 的 Extended Audio File Services 读取音频文件macOS 解码与播放实战使用 NAudio.MacOS 的 Extended Audio File Services 读取音频文件macOS 解码与播放实战 导读 本文讲解 NAu音视频音频处理Vue Audio Player 音频播放器组件完整指南Vue Audio Player 音频播放器组件完整指南 Vue Audio Player 是一个轻量级且功能丰富的 Vue.js 组件专为满足PC和移动端音NAudio 3 的 macOS 原生音频封装架构解析Core Audio HAL 播放录制与 Audio Toolbox 重采样与文件读写设计NAudio 3 的 macOS 原生音频封装架构解析Core Audio HAL 播放录制与 Audio Toolbox 重采样与文件读写设计 NAudio音视频音频处理上一篇如何在3个步骤内将PixelCNN扩展到自定义数据集图像生成模型完整适配指南下一篇Morphic性能瓶颈分析数据库查询与API请求优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考