#moonflac-encoder

状态：核心功能可用。STREAMINFO + MD5、定长块帧与 CRC-8/CRC-16、CONSTANT / VERBATIM / FIXED(0–4) / LPC(1–12) 子帧、Rice 分区搜索、立体声去相关、流式/增量编码均已实现；压缩率在 12 组测试信号中 11 组优于或持平 libFLAC 默认设置。具体版本与变更见 CHANGELOG。

#安装

moon add Sakuraqwq1/moonflac-encoder

#为什么需要它

• 解码有，编码没有；
• 用 MoonBit 写的工具、游戏、编辑器，能读 FLAC，但没法写出 FLAC；
• 想把素材压缩成无损体积、想在 CI 里生成 .flac 测试数据，只能退回 C 工具链。

#当前能力

#用法（库）

// 交织的有符号 PCM，已经缩放到 bits_per_sample 的二进制补码范围
let samples : Array[Int64] = [0L, 100L, 200L, 300L]
let flac : Bytes = @moonflac_encoder.encode(samples, 44100, 1, 16)

#用法（命令行）

# 自检：合成 1 秒 440 Hz 正弦，编码后打印 base64
moon run cmd/main -- selftest

# 把 base64 的 WAV 编码成 base64 的 FLAC
moon run cmd/main -- encode "$(base64 -w0 input.wav)"

# 生成测试信号（采样率 声道 位深 帧数 类型）
moon run cmd/main -- gen 44100 2 16 4096 0

# 同时输出源 PCM（base64），用于和任意解码器做逐位比对
moon run cmd/main -- gen 44100 2 16 4096 0 --pcm

# MD5 自检，验证摘要实现
moon run cmd/main -- md5 abc

#流式 / 增量编码

let encoder = @moonflac_encoder.stream_encoder(44100, 2, 16)
let mut out = @moonflac_encoder.stream_header(encoder)   // fLaC + STREAMINFO
for chunk in incoming_pcm {                              // 任意切片大小
  out = out + @moonflac_encoder.stream_write(encoder, chunk)
}
out = out + @moonflac_encoder.stream_finish(encoder)     // 冲掉最后一个不满的块

#性能

#验证方式

1. 用 MoonBit 编码器产出 .flac；
2. 交给 Python soundfile（libsndfile，完全独立于 MoonBit 生态）解码；
3. 把解码出的 PCM 按 FLAC 规范（小端、ceil(bits/8) 字节）重新拼字节流，算 MD5；
4. 与文件 STREAMINFO 里记录的 MD5 比对。

#测试

python tools/verify.py matrix      # 96 例跨解码器矩阵，逐样本比对 STREAMINFO 摘要
python tools/verify.py benchmark   # 同一段 PCM 上与 libFLAC 的体积对比

moon check --deny-warn
moon test  --deny-warn
moon fmt --check

#与生态内解码器的互操作

#实现要点

• 位流优先：FLAC 帧是连续的位流，所有字段经由一个 MSB-first 的 BitWriter 写出，避免手工对齐出错。
• 代价精确：每个子帧候选（CONSTANT / FIXED 0–4 / LPC / VERBATIM）都按实际位数计算，包括子帧头、残差头与 Rice 分区搜索——选型时的代价与最终写出的位数完全一致，因此不存在"选了更差的编码"的情况。
• LPC 与固定预测同等对待：两种候选都按实际位数计算代价，取最小者；双音素材上 LPC 让单声道从 4,311 B 降到 3,537 B（−18%），立体声从 9,241 B 降到 5,436 B（−41%），而噪声素材不会被误选成 LPC。
• 阶数用残差能量估计：先算 1..12 阶的自相关与 Levinson-Durbin 递推，用各阶残差能量估出最省的阶，只对该阶及其前后各一阶做精确代价计算，避免逐阶全算。
• 代价用 Int64 累加：32 位精度会让 24-bit 噪声的位数估算溢出，从而误选编码器写不下的参数——这一点在开发中被矩阵测试抓出过。
• MD5 自实现：核心库没有 MD5，而 STREAMINFO 的校验依赖它；实现后用 RFC 1321 标准向量验证。

#路线图

• 流式 / 增量编码（StreamEncoder）
• 压缩率对齐 libFLAC：加窗（apodization）后 12 组测试信号中 11 组优于或持平 libFLAC 默认设置，最差一组（单声道正弦）高 3.2%
• 自适应块长
• 12 / 20 / 32 bit 的参考解码器验证（当前矩阵覆盖 8 / 16 / 24）

#许可证与参考

• 规范：RFC 9639（FLAC，2024-12）、xiph.org/flac 格式文档
• 未复制任何第三方源码；STREAMINFO 的 MD5 语义按 RFC 9639 §8.4 实现（交织、小端、每样本 ceil(bits/8) 字节）