Rust MP3 编码器

一个基于 Shine 库的纯 Rust MP3 编码器实现。该项目严格遵循 Shine C 语言参考实现，提供完整的 MP3 Layer III 编码功能，支持各种采样率、比特率和声道配置。

项目地址: https://github.com/wshon/shine-rs

特性

• 🦀 纯 Rust 实现 - 利用 Rust 的内存安全和性能优势
• 🎯 严格遵循 Shine - 算法与 Shine C 实现完全一致，确保输出质量
• 🎵 完整的 MP3 Layer III 支持 - 实现完整的 MP3 编码流水线
• ⚡ 高性能 - 优化的算法实现，保持与 Shine 相同的性能特征
• 🔧 灵活配置 - 支持多种采样率、比特率和声道模式
• 📊 标准兼容 - 符合 ISO/IEC 11172-3 标准
• 🧪 全面测试 - 包含单元测试、集成测试和与 Shine 的对比验证
• 🛠️ 实用工具 - 提供 WAV 转 MP3 命令行工具和测试数据收集工具
• 📋 调试支持 - 可选的调试日志和帧数限制功能

支持的格式

采样率

• MPEG-1: 32000, 44100, 48000 Hz
• MPEG-2: 16000, 22050, 24000 Hz
• MPEG-2.5: 8000, 11025, 12000 Hz

比特率

• MPEG-1: 32-320 kbps
• MPEG-2: 8-160 kbps
• MPEG-2.5: 8-64 kbps

声道模式

• 单声道 (Mono)
• 立体声 (Stereo)
• 联合立体声 (Joint Stereo)
• 双声道 (Dual Channel)

快速开始

使用命令行工具

# 基本用法：WAV 转 MP3

cd tools && cargo run --bin wav2mp3 ..\testing\fixtures\audio\sample-3s.wav ..\testing\fixtures\output\wav2mp3_output.mp3


# 指定比特率和立体声模式

cd tools && cargo run --bin wav2mp3 input.wav output.mp3 128 stereo


# 调试模式：限制编码帧数

cd tools && cargo run --bin wav2mp3 input.wav output.mp3 --max-frames 10

作为库使用

[dependencies]

shine-rs = { git = "https://github.com/wshon/shine-rs" }

use shine_rs::{Mp3Encoder, Mp3EncoderConfig, StereoMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建编码器配置
    let config = Mp3EncoderConfig::new()
        .sample_rate(44100)
        .bitrate(128)
        .channels(2)
        .stereo_mode(StereoMode::Stereo);
    
    // 创建编码器
    let mut encoder = Mp3Encoder::new(config)?;
    
    // 编码 PCM 数据
    let pcm_data = vec![0i16; encoder.samples_per_frame()];
    let mp3_frames = encoder.encode_interleaved(&pcm_data)?;
    
    // 完成编码
    let final_data = encoder.finish()?;
    
    println!("编码完成，生成 {} 字节 MP3 数据", final_data.len());
    Ok(())
}

💡 提示: 项目还提供了底层接口，直接对应 Shine C 实现。详见 高级 API 使用指南。

项目结构

shine-rs/
├── src/                        # Rust 源代码
│   ├── bitstream.rs           # 比特流处理
│   ├── encoder.rs             # 主编码器（底层接口）
│   ├── mp3_encoder.rs         # 高级编码器接口
│   ├── huffman.rs             # Huffman 编码
│   ├── mdct.rs                # MDCT 变换
│   ├── quantization.rs        # 量化算法
│   ├── subband.rs             # 子带分析
│   ├── tables.rs              # 查找表
│   └── ...                    # 其他模块
├── tools/                     # 命令行工具
│   └── wav2mp3/               # WAV 转 MP3 工具
├── ref/shine/                 # Shine C 参考实现
├── testing/                   # 测试相关文件
│   ├── fixtures/              # 测试数据和音频文件
│   ├── integration/           # 集成测试
│   └── regression/            # 回归测试数据
├── docs/                      # 项目文档
└── scripts/                   # 辅助脚本

核心算法流程

PCM 输入 → 子带滤波 → MDCT 变换 → 量化循环 → Huffman 编码 → 比特流输出

每个步骤都严格按照 Shine C 实现，确保算法的正确性和输出的一致性。

开发状态

✅ 已完成 - 该项目已实现完整的 MP3 编码功能：

• 项目结构和基础设施
• 配置管理模块
• 查找表和常量
• 比特流写入器
• 子带滤波器（32 频带分析）
• MDCT 变换（修正离散余弦变换）
• 量化循环（比特率控制）
• Huffman 编码器
• 主编码器集成
• 与 Shine 输出完全一致验证

质量保证

• 算法验证: 所有核心算法都与 Shine C 实现逐行对比验证
• 输出一致性: 生成的 MP3 文件与 Shine 输出完全相同（SHA256 哈希匹配）
• 全面测试: 包含单元测试、集成测试、属性测试和回归测试
• 标准符合: 严格遵循 ISO/IEC 11172-3 MP3 标准

构建和测试

# 构建项目

cargo build


# 运行所有测试

cargo test


# 运行集成测试

cargo test --test integration_full_pipeline_validation


# 使用测试数据验证实现

cargo run --bin validate_test_data testing/fixtures/data/sample-3s_128k_6f.json


# 运行命令行工具

cd tools && cargo run --bin wav2mp3 testing/fixtures/audio/sample-3s.wav output.mp3

调试和开发

# 启用调试日志

cd tools && RUST_LOG=debug cargo run --bin wav2mp3 input.wav output.mp3


# 限制编码帧数（调试用）

cd tools && cargo run --bin wav2mp3 input.wav output.mp3 --max-frames 5


# 收集测试数据（需要相应的工具）

cargo run --bin collect_test_data input.wav test_data.json 128

性能和兼容性

性能特征

• 算法优化: 基于 Shine 的高效 C 实现移植
• 内存安全: Rust 的零成本抽象和内存安全保证
• 编码速度: 与 Shine C 实现相当的编码性能
• 资源使用: 优化的内存布局和缓存友好的数据访问

兼容性

生成的 MP3 文件与以下解码器完全兼容：

• FFmpeg/libmp3lame
• Windows Media Player
• VLC Media Player
• 各种移动设备播放器
• 所有符合 MP3 标准的播放器

质量保证

• 位级精确: 与 Shine 生成完全相同的 MP3 比特流
• 标准符合: 严格遵循 ISO/IEC 11172-3 标准
• 回归测试: 防止算法修改引入的问题
• 持续验证: 每次修改都与 Shine 输出对比验证

文档

• 项目结构说明 - 详细的项目组织结构
• 测试数据框架 - 测试数据收集和验证系统
• 帧数限制功能 - 调试和测试的帧数限制功能
• 帧数限制快速参考 - 帧数限制功能的快速使用指南
• 高级 API 使用指南 - 高级接口的使用方法
• 日志系统使用指南 - 调试日志的配置和使用
• 音频文件标准化 - 测试音频文件的组织规范
• 验证记录 - 与 Shine 实现的验证记录

许可证

本项目采用 GNU Library General Public License v2.0 (LGPL-2.0) 发布。详见 LICENSE 文件。

贡献

欢迎贡献！在提交代码前，请确保：

1. 遵循项目的编码规范（严格按照 Shine 实现）
2. 所有测试通过，包括与 Shine 的对比验证
3. 代码通过 cargo clippy 检查，无警告
4. 为新功能添加相应的测试用例

致谢

本项目基于 Shine MP3 编码器库，感谢原作者 Savonet 团队的优秀工作。该项目严格遵循 Shine 的算法实现，确保了 MP3 编码的质量和标准符合性。