SimpleAudioPlayer 使用手册（一）：介绍+快速入门

引言

.NET 生态中音频播放库的选择并不多。NAudio 功能完善但仅限 Windows，而跨平台方案往往需要引入庞大臃肿的依赖。SimpleAudioPlayer 以"小而美"为宗旨，用不到 4000 行 C# 代码 + 一个精简的 C 原生库，实现了跨平台的高性能音频播放、录制与流媒体支持。

项目地址：https://github.com/j4587698/SimpleAudioPlayer

技术栈

层次	技术
语言	C# (.NET 8/9/10) + C99 (原生库)
音频后端	miniaudio (Public Domain，单头文件库)
音频解码	FFmpeg 7.1 (libavformat, libavcodec, libswresample, libavutil)
原生互操作	`[LibraryImport]` Source-Generated P/Invoke
原生构建	CMake 3.20+, MSYS2 MinGW (Windows), GCC/Clang (macOS/Linux)
NuGet 打包	SimpleAudioPlayer.Native 作为预编译原生 NuGet 包分发

安装

复制代码

dotnet add package SimpleAudioPlayer --version 2.3.1

最简单的播放

复制代码

using SimpleAudioPlayer;
using SimpleAudioPlayer.Handles;

var player = new AudioPlayer();
player.Load(new FileStreamHandler("song.mp3"));
player.Play();

三步：创建播放器 -> Load(文件句柄) -> Play()。

播放控制

复制代码

player.Play();     // 返回 bool，true 成功
player.Pause();    // 暂停
player.Stop();     // 停止（回到开头）
player.Seek(30);   // 跳转到 30 秒

时间信息

复制代码

double current = player.Time;      // 当前秒数
double total = player.Duration;    // 总时长秒数

音量

复制代码

player.Volume = 0.5;  // 0.0~1.0

事件

复制代码

player.PlaybackStateChanged = state => Console.WriteLine(state);
player.PlaybackFailed = args => Console.WriteLine(args.Result);
player.PlayCompleted = () => Console.WriteLine("完成");

完整示例

复制代码

using SimpleAudioPlayer;
using SimpleAudioPlayer.Handles;

var player = new AudioPlayer();
player.PlaybackStateChanged = state => Console.WriteLine($"状态: {state}");
player.PlaybackFailed = args => Console.WriteLine($"失败: {args.Result}");
player.PlayCompleted = () => Console.WriteLine("完成");

player.Load(new FileStreamHandler("song.mp3"));
Console.WriteLine($"时长: {player.Duration:F1}s");
player.Play();
Thread.Sleep(5000);
player.Stop();
player.Dispose();

错误处理

复制代码

try {
    player.Load(new FileStreamHandler("nonexistent.mp3"));
}
catch (InvalidOperationException ex) {
    Console.WriteLine($"加载失败: {ex.Message}");
}

Dispose

复制代码

using var player = new AudioPlayer();
// 或 player.Dispose()