minimp3-cj API 接口详解：从 decodeMp3File 到 mp3dec_decode_frame 的完整使用指南

• 音视频
• 音频处理

minimp3_cj 是一个完全由仓颉语言实现的 MP3 解码库，参照著名的 minimp3 C 库重新实现，并在此基础上扩展了 WAV 文件输出能力。本文围绕该库的公开 API 接口展开，完整覆盖两个封装的高级函数、三个底层解码函数、公开常量与核心类型，并结合 src/minimp3.cj 与 src/mp3file.cj 的源码逐层剖析参数含义、内部调用流程与正确的调用姿势。读完本文，你可以直接使用该库完成"MP3 文件转 WAV"以及"内存中 MP3 数据转 PCM"两类任务，并理解底层逐帧解码的状态机机制。

API 总体结构：两层接口设计

从 架构设计文档 与源码组织看，minimp3_cj 的 API 分为两层：

• 已封装的高级 API（位于 src/mp3file.cj）：decodeMp3File与decodeMp3Buffer，屏蔽帧循环、缓冲区管理和 WAV 头生成等细节，适合大多数使用场景；
• 底层解码 API（位于 src/minimp3.cj）：mp3dec_init、mp3dec_reset、mp3dec_decode_frame，提供逐帧解码的完整控制，适合需要自行管理解码进度的场景。

此外库还公开了一个常量MINIMP3_MAX_SAMPLES_PER_FRAME和两个类型mp3dec_t、mp3dec_frame_info_t，它们是调用底层 API 时必须的支撑件。

高级 API：decodeMp3File（MP3 文件转 WAV）

func decodeMp3File(inputPath: String, outputPath: String): (Array<Int16>, Int64, Int64)

源码中的实现流程

查看 decodeMp3File 的实现，其内部流程可以拆解为四步：

1. 文件读取：通过File.readFrom(inputPath)将整个 MP3 读入内存，转换为Array<UInt8>；
2. 逐帧解码循环：内部创建mp3dec_t实例并调用mp3dec_init，然后以mp3dec_decode_frame为核心在while (off < mp3.size)循环中逐帧解码。每帧解码后将n * info.channels个样本追加到pcmData，并依据info.frame_bytes推进偏移量off；当info.frame_bytes == 0时退出循环，这对应"无有效帧可解"的终止条件；
3. WAV 头生成：由 WavWriter.createWavHeader 按标准 RIFF/WAVE 格式逐字节写入 44 字节文件头，包含RIFF/WAVE标识、fmt子块（PCM 格式 = 1、声道数、采样率、字节率、块对齐、位深度）与data子块，数据大小按pcmArray.size * 2（每样本 2 字节）计算；
4. 字节序转换与写盘：WavWriter.pcmToBytes 将Int16样本按小端序展开为字节流，最后拼接头部与数据写入outputPath。

一个值得注意的细节：函数在第一帧成功解码时记录sampleRate与channels（见 src/mp3file.cj 中if (sampleRate == 0)分支），因此采样率与声道数取自音频流的第一个有效帧，这也是返回值元组的来源。

使用示例

import minimp3_cj.* import std.fs.* let (pcmData, sampleRate, channels) = decodeMp3File("input.mp3", "output.wav") println("解码完成！采样率: ${sampleRate} Hz, 声道数: ${channels}")

运行后终端会打印读取的文件名、MP3 大小以及"WAV文件已生成"提示，同时返回的pcmData.size是全部声道交错排列后的总样本数——时长可按Float64(pcmData.size) / Float64(sampleRate * channels)秒计算，这正是 单元测试中的做法。

高级 API：decodeMp3Buffer（内存数据转 PCM）

func decodeMp3Buffer(mp3Data: Array<UInt8>): Array<Int16>

从 实现代码 看，它与decodeMp3File的解码循环几乎一致——同样创建解码器、逐帧调用mp3dec_decode_frame、按n * info.channels收集样本、依据frame_bytes推进偏移并以其为 0 作为终止条件——但去掉了 WAV 头生成与文件写入，直接返回Int16PCM 数组。如果你的下游是自定义音频容器或播放管线，这个接口是更合适的选择。

import minimp3_cj.* import std.fs.* let mp3Data = File.readFrom("sample/demo.mp3") let mp3Bytes = Array<UInt8>(Int64(mp3Data.size), {k: Int64 => UInt8(mp3Data[k])}) let pcmData = decodeMp3Buffer(mp3Bytes) println("解码得到 ${pcmData.size} 个PCM样本")

底层 API：解码器生命周期管理

mp3dec_init

func mp3dec_init(decoder: mp3dec_t): Unit

初始化解码器。从 实现 看，它做的事情很轻：将dec.header[0]置 0，标记"当前没有正在延续的帧头"，使解码器进入等待帧同步的状态。

mp3dec_reset

func mp3dec_reset(decoder: mp3dec_t): Unit

比init彻底得多，它清除解码器的全部内部状态（见 实现）：

• reserv（比特池残留标记）与free_format_bytes归零；
• header与reserv_buf（511 字节的比特池缓冲区）全部清零；
• mdct_overlap（两个声道、每声道 288 个Float64的 IMDCT 重叠缓冲）与qmf_state（15×2×32 的 QMF 滤波器组状态）全部清零。

两者差异的实战意义：mp3dec_init用于解码器首次投入使用时；而mp3dec_reset在 mp3dec_decode_frame 内部 也会在帧头比对失败、需要重新搜索同步点时被自动调用，保证解码器不会因为残留的上一帧状态产生错位。

底层 API：mp3dec_decode_frame（核心解码函数）

func mp3dec_decode_frame(decoder: mp3dec_t, mp3: Array<UInt8>, mp3_bytes: Int64, pcm: Array<Int16>, info: mp3dec_frame_info_t): Int64

返回值语义：解码出的时域样本数（单声道计）；返回 0 表示未解出有效帧。注意返回值是"每声道样本数"，写入 PCM 的实际元素个数是返回值 * info.channels。

内部处理流程

阅读 mp3dec_decode_frame 的实现，一次调用内部经过以下步骤：

1. 帧延续判断：若上一帧头仍有效（dec.header[0] == 0xFF且头部一致），直接按已知帧大小定位；否则先mp3dec_reset，再调用mp3d_find_frame2重新做帧同步搜索，得到帧偏移i与frame_size；
2. 帧信息提取：从 4 字节帧头解析声道数（HDR_IS_MONO决定 1/2 声道）、采样率（hdr_sample_rate_hz）、层号（info.layer = 4 - HDR_GET_LAYER(hdr)，即 Layer I/II/III 对应 3/2/1）与比特率（hdr_bitrate_kbps），并回填info.frame_bytes = i + frame_size；
3. Layer III 分支：依次执行L3_read_side_info（边信息解析）、L3_restore_reservoir（比特池恢复）、逐 granule 的L3_decode（霍夫曼解码、反量化、立体声处理、IMDCT 等），最后经mp3d_synth_granule做 QMF 合成输出 PCM，并以L3_save_reservoir保存比特池供下一帧使用；
4. Layer I/II 分支：执行L12_read_scale_info、L12_dequantize_granule、L12_apply_scf_384后再做 QMF 合成。

这些位运算细节由 src/macros/header_macros.cj 中的宏展开完成，例如HDR_GET_SAMPLE_RATE、HDR_GET_BITRATE直接操作帧头第 2 字节的对应位段，避免在热路径上写重复的掩码表达式。

正确的逐帧调用姿势

使用底层 API 时，标准调用模式如下（与 README 示例一致）：

import minimp3_cj.* import std.fs.* // 初始化解码器 var decoder = mp3dec_t() mp3dec_init(decoder) // 读取MP3文件 let mp3Data = File.readFrom("sample/demo.mp3") let mp3Bytes = Array<UInt8>(Int64(mp3Data.size), {k: Int64 => UInt8(mp3Data[k])}) // 解码音频帧 var frameInfo = mp3dec_frame_info_t() var pcmBuffer = Array<Int16>(MINIMP3_MAX_SAMPLES_PER_FRAME, repeat: Int16(0)) let samples = mp3dec_decode_frame(decoder, mp3Bytes, mp3Bytes.size, pcmBuffer, frameInfo) // 获取音频信息 println("采样率: ${frameInfo.hz} Hz") println("声道数: ${frameInfo.channels}") println("比特率: ${frameInfo.bitrate_kbps} kbps")

需要解完整文件时，按 高级 API 中的循环写法 重复调用：每次传入mp3.slice(off, size - off)，成功解码后将off累加info.frame_bytes，遇到info.frame_bytes == 0时停止。每帧应准备一块至少MINIMP3_MAX_SAMPLES_PER_FRAME个样本的pcm缓冲区，单帧最多输出 1152 个样本（每声道），乘以最多 2 个声道后正好落在该上界内。

公开常量与类型

MINIMP3_MAX_SAMPLES_PER_FRAME

let MINIMP3_MAX_SAMPLES_PER_FRAME: Int64 = 2304

定义于 src/minimp3.cj，源码中写作1152 * 2：1152 是 MPEG-1 Layer II/III 单帧最大样本数（Layer I 为 384，MPEG-2/2.5 为 576，可对照 hdr_frame_samples 实现），乘以 2 是为立体声预留的每声道样本数上界。它是准备 PCM 输出缓冲区时的基准尺寸。

mp3dec_t（解码器实例类型）

class mp3dec_t

解码器实例，包含解码状态和内部缓冲区。从 类定义 可以看到其成员构成：

调用方只需mp3dec_t()构造并交给mp3dec_init/mp3dec_reset管理，不必直接触碰成员；但理解上述成员有助于理解为什么同一个文件解码过程中必须复用同一个mp3dec_t实例——比特池与滤波状态跨越帧边界。

mp3dec_frame_info_t（帧信息结构）

class mp3dec_frame_info_t

包含帧的详细信息，字段定义见 src/minimp3.cj：

集成、构建与测试验证

集成到你的项目

在cjpm.toml的[dependencies]中加入：

[dependencies] minimp3_cj = {git = "https://gitcode.com/Cangjie-SIG/minimp3-cj.git", branch = "main"}

然后执行一次cjpm build。本库以静态库形式发布（见 cjpm.toml 中output-type = "static"），开发基线为仓颉 SDK 1.0.0（见 README 说明）。

用单元测试验证 API 行为

仓库自带针对两个高级 API 的测试，见 src/tests/mp3file_test.cj：

• testDecodeMp3Buffer：对sample/demo.mp3调用decodeMp3Buffer，断言 PCM 结果非空；
• testDecodeMp3File：调用decodeMp3File输出到sample/output.wav，依次断言 PCM 非空、采样率大于 0、声道数为 1 或 2，且输出文件大于 44 字节（WAV 头大小）。仓库中已附带一次运行的产物 sample/output.wav 可供对照。

# 运行所有测试 cjpm test # 运行特定测试（测试类名为 MP3FileTests） cjpm test --filter=MP3FileTests.testDecodeMp3Buffer cjpm test --filter=MP3FileTests.testDecodeMp3File

需要注意：README 与 设计文档 中示例写的是MP3PCMTests，而当前仓库中实际的测试类名是MP3FileTests（见 测试文件），以源码为准。

选型小结

• 目标是把 MP3 文件落地成标准 WAV：直接用decodeMp3File，它替你完成文件 IO、帧循环、WAV 头与小端字节序转换；
• 目标是拿到 PCM 数据做后续处理（自定义容器、混音、分析）：用decodeMp3Buffer；
• 需要流式处理、进度控制或复用解码器状态：用mp3dec_init+mp3dec_decode_frame组合，按info.frame_bytes推进、以frame_bytes == 0终止，PCM 缓冲区按MINIMP3_MAX_SAMPLES_PER_FRAME准备；状态异常时用mp3dec_reset彻底清场。

以上所有接口签名与行为均可在当前仓库源码中逐项核验：高级 API 见 src/mp3file.cj，底层解码与类型定义见 src/minimp3.cj，帧头解析宏见 src/macros/header_macros.cj，整体分层关系可参考 doc/design.md 中的架构说明。

• 音视频
• 音频处理