NcmFox 0.2.0

NcmFox

English | 简体中文

一个高性能的 .NET NCM 文件解密库，专为网易云音乐加密音频文件设计。

✨ 项目特色

• 🚀 极致性能 - 采用 SIMD (AVX2/SSE2) 向量化加速，解密速度可达 400-500 MB/s
• 💾 低内存占用 - 使用 ArrayPool 内存池技术，大幅降低 GC 压力
• 🎯 简洁 API - 直观易用的接口设计，几行代码即可完成解密
• 📦 完整元数据 - 支持提取歌曲信息、艺术家、专辑封面等完整元数据
• 🔧 灵活配置 - 支持自定义缓冲区大小、安全限制等参数

📋 环境要求

• .NET 8.0 或更高版本
• 支持的平台：Windows、Linux、macOS

📦 安装

通过 NuGet 安装

dotnet add package NcmFox

通过 Package Manager 安装

Install-Package NcmFox

从源码构建

git clone https://github.com/Xdyu1522/NcmFox.git
cd NcmFox/NcmFox
dotnet build

🚀 快速开始

基础用法

using NcmFox;

// 打开 NCM 文件
var ncm = NcmDecoder.Open("song.ncm");

// 查看元数据
Console.WriteLine($"歌曲: {ncm.MetaData.SongName}");
Console.WriteLine($"艺术家: {string.Join(", ", ncm.MetaData.GetArtists())}");
Console.WriteLine($"专辑: {ncm.MetaData.AlbumName}");
Console.WriteLine($"格式: {ncm.SaveFormat}");

// 解密到文件
ncm.Decode("output.flac");

// 或解密到流
using var ms = new MemoryStream();
ncm.Decode(ms);

自定义配置

using NcmFox.Config;

// 配置全局选项
NcmConfig.Configure(new NcmOptions
{
    BufferSize = 64 * 1024,           // 64 KB 缓冲区
    MaxCoverSize = 10 * 1024 * 1024,  // 最大封面 10 MB
    MaxMetadataSize = 512 * 1024,     // 最大元数据 512 KB
    EnableCoverSizeCheck = true,      // 启用封面大小检查
    EnableMetaDataSizeCheck = true    // 启用元数据大小检查
});

仅提取元数据

using NcmFox;

// 从文件提取（无异常抛出）
if (MetaDataHelper.TryGetMetaData(new FileInfo("song.ncm"), out var meta))
{
    Console.WriteLine($"歌曲: {meta.SongName}");
    Console.WriteLine($"艺术家: {string.Join(", ", meta.GetArtists())}");
    Console.WriteLine($"专辑: {meta.AlbumName}");
    Console.WriteLine($"比特率: {meta.Bitrate}");
    Console.WriteLine($"时长: {meta.Duration}");
}

// 从加密字符串提取
string comment = "163 key(Don't modify):...";
if (MetaDataHelper.TryGetMetaData(comment, out var meta2))
{
    Console.WriteLine($"歌曲: {meta2.SongName}");
}

处理封面图像

var ncm = NcmDecoder.Open("song.ncm");

if (ncm.CoverData != null)
{
    Console.WriteLine($"封面格式: {ncm.CoverData.Format}");
    Console.WriteLine($"封面大小: {ncm.CoverData.Size} 字节");
    
    // 保存封面到文件
    File.WriteAllBytes("cover.jpg", ncm.CoverData.Data);
}

📖 API 参考

NcmDecoder

NcmFile

NcmFile 扩展方法

MetaData

Artist

NcmOptions

⚡ 性能

NcmFox 针对高吞吐量进行了深度优化：

优化技术

Benchmark 结果

测试环境：

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8037)
12th Gen Intel Core i7-1255U 1.70GHz, 1 CPU, 12 logical and 10 physical cores
.NET SDK 10.0.103

关键指标：

• 🚀 并行加速比: 1.9x - 2.0x（接近理想线性加速）
• 💾 内存效率: 极低分配（10-40 KB），无 GC 压力
• 📈 吞吐量: 400-500 MB/s

鲁棒性改进

JSON 解析支持处理脏数据：

• 艺术家 ID 为数字 0 时自动处理为未知
• 混合类型（字符串/数字）统一转换
• 空值自动填充默认值

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 开源协议

本项目采用 MIT 协议开源。

⚠️ 免责声明

本库仅供学习和个人使用。请尊重版权法律和网易云音乐的服务条款。

📮 联系方式

• GitHub Issues: https://github.com/Xdyu1522/NcmFox/issues

🙏 致谢

感谢 JetBrains 为本项目提供 Rider IDE 的非商业许可证支持，这对项目的开发提供了极大的帮助。

Made with ❤️ by Xdyuorine