#moonaudio

let bytes = read_your_file()               // 由宿主提供 Bytes（见「关于文件 IO」）
let audio  = @moonaudio.decode(bytes)      // 自动识别 WAV / AIFF / AU / FLAC
println(audio.sample_rate)                 // 44100
println(audio.frames())                    // 采样帧数
println(audio.peak_dbfs())                 // 峰值电平

• 输入：RIFF/WAVE（含 RIFX、WAVE_FORMAT_EXTENSIBLE、μ-law/A-law）、AIFF/AIFC（含 80-bit 扩展浮点采样率）、Sun .au、原生 FLAC（含 LPC / Rice / 中-边声道去相关 / CRC 校验）。
• 处理：AudioBuffer（交织 Double，归一化到 [-1, 1]）、采样格式转换、G.711、dBFS、重采样（线性 / 三次 / 窗函数 sinc）、FFT 与频谱图、RBJ biquad 滤波器、统计与静音裁剪。
• 输出：WAV / AIFF / AU 编码，以及频谱图 CSV/SVG、Markdown 报告。
• 安全：每一次多字节读取都做边界检查，畸形文件只报错不崩溃；FLAC 逐帧校验 CRC-8/CRC-16。

#特性

#与生态中现有音频包的区别

#快速开始

#安装

# 安装 MoonBit 工具链（已安装可跳过）
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash   # macOS / Linux
# Windows: irm https://cli.moonbitlang.com/install/powershell.ps1 | iex

moon add Sakuraqwq1/moonaudio

git clone https://github.com/Sakuraqwq1/moonaudio
cd moonaudio
moon check
moon test

#解码

let audio = @moonaudio.decode(bytes)
println("\{audio.sample_rate} Hz, \{audio.channels} ch, \{audio.frames()} frames")
println("peak: \{audio.peak_dbfs()} dBFS, rms: \{audio.rms_dbfs()} dBFS")

#编码

// 16-bit PCM WAV
let wav = @wav.encode(audio)
// 24-bit AIFF
let aiff = @aiff.encode(audio, format=@audio.I24)
// 32-bit float .au
let au = @au.encode(audio, format=@audio.F32)

#处理

let loud = audio.copy()
loud.normalize(target=0.9)                  // 峰值归一到 0.9
let mono = loud.remix(1)                    // 立体声下混
let resampled = @resample.resample(mono, 48000)
let filtered = @dsp.Biquad::new(
  @dsp.LowPass, 48000, 4000.0,
).apply_buffer(resampled)

#分析

let stats = @dsp.analyse(audio)
println(stats.to_lines())                   // key=value 列表，顺序稳定

let spec = @dsp.spectrogram(audio, fft_size=1024, hop=256)
println(spec.to_csv())
println(spec.to_svg())                      // 直接可放进网页的灰度频谱图

#容器探测

match @moonaudio.sniff(bytes) {
  Some(container) => println(container.to_name())   // "wav" | "aiff" | "au" | "flac"
  None => println("unrecognised")
}

#命令行 demo

# 端到端自检：生成 → 编码 → 解码 → 分析 → 重采样，输出 Markdown 报告
moon run cmd/main -- demo

# 生成 440 Hz 正弦波 WAV（base64）
moon run cmd/main -- tone --freq 440 --ms 500 > tone.b64

# 小文件可以直接当参数传
moon run cmd/main -- info "$(cat tone.b64)"
moon run cmd/main -- stats "$(cat tone.b64)"

# 大一点的用环境变量，绕开命令行长度限制
export AUDIO_B64="$(cat tone.b64)"
moon run cmd/main -- convert @AUDIO_B64 --rate 48000 --format s24 --container aiff

# moonaudio demo

- module version: `0.3.2`
- generated: 1.000 s of 440 Hz at 44.1 kHz, peak 0.800
- encoded: 88244 byte WAV, sniffed as wav
- header: 44100 Hz, 1 ch, 16 bit (s16), pcm, 44100 frames
- roundtrip: 44100 frames, peak -1.938 dBFS, rms -4.949 dBFS, crest 1.414
- AIFF 24-bit: 132354 bytes, decoded peak 0.800
- AU float64: 352824 bytes, decoded peak 0.800
- resampled 44.1 kHz -> 48 kHz: 48000 frames, peak 0.800
- FFT peak: 441.431 Hz for the 440 Hz tone (10.767 Hz per bin)
- spectrogram: 170 frames x 513 bins, bin width 43.066 Hz, frame 0 peak 430.664 Hz
- high pass 200 Hz: peak 0.824, rms 0.554

#示例

moon run examples/basic    # 20 行：生成正弦 → WAV 编码 → 门面解码 → 打印电平
moon run examples/tour     # 分节导览：合成、分析、滤波、重采样、容器往返

== synthesis ==
  tone 440 Hz : 22050 frames, peak 0.4
  mixed       : peak 0.666, rms 0.354
  deterministic: true

== analysis ==
  fft peak at bin 128: 1000 Hz (input 1000 Hz)
  spectrogram: 31 frames x 257 bins, 15.625 Hz per bin
  frame 0 peak: 1000 Hz

== resampling ==
  ratio 44100:48000 reduces to 147:160
  expected frames: 4800
  actual frames  : 4800

== containers ==
  wav: 4454 bytes — 22050 Hz, 1 ch, 16 bit (s16), pcm, 2205 frames
  aiff: 6670 bytes — 22050 Hz, 1 ch, 24 bit (s24), AIFF NONE, 2205 frames

#包结构

#测试

moon check --deny-warn
moon test  --deny-warn
moon fmt --check
moon info          # 接口若有变化会更新 pkg.generated.mbti

• audio：缓冲区几何、峰值/RMS、声道转换、切片拼接、量化与反量化、float32 位模式、G.711 往返、字节读取边界。
• wav：8/16/24/32-bit 与 float 往返、LIST/INFO 元数据、WAVE_FORMAT_EXTENSIBLE、RIFX 大端、奇数长度 padding、错误路径。
• aiff：AIFF/AIFC、sowt 小端、float、80-bit 采样率精确值、元数据、SSND 偏移、畸形输入。
• au：8/16/24/32-bit、float、μ-law/A-law、annotation、截断与不支持编码。
• flac：用仓库内独立实现的位流写入器合成符合规范的数据流，覆盖 constant/verbatim/fixed 0-4/LPC、Rice 分区与 escape、wasted bits、左/右/中-边声道、多帧、12/16/20/24-bit、变长块、超长帧号、CRC 校验失败与截断。
• dsp：FFT 与朴素 DFT 对照、逆变换、Parseval、正弦峰值 bin、窗函数性质、频谱图尺寸与峰值频率、滤波器通带/阻带、统计量、淡入淡出、混音。
• resample：三种核的音高与幅度、往返长度、比例约简、非法采样率。

说明：仓库内的测试向量由合成器生成，不依赖外部数据，因此在离线 CI 中也能跑。 另外用官方 ietf-wg-cellar/flac-test-files 的真实文件做过交叉验证：解码后把采样重新编码成 16-bit PCM，重算 MD5 与 FLAC STREAMINFO 里记录的原 PCM 摘要比对，逐采样比特级一致。覆盖的文件有

官方文件	覆盖点	结果
60 - mono audio	单声道基准	一致
38 - 3 channels (3.0)	3 声道独立编码	一致
61 - predictor overflow check, 16-bit	故意让 32 位预测器溢出的极端信号	一致
64 - rice partitions with escape code zero	Rice 分区与 escape 码 0	一致
14 - wasted bits	wasted bits 与立体声去相关	一致

复现方式：git clone 上述测试集，取其中任一 16-bit 文件，用 @moonaudio.decode 解码后以 @wav.encode(..., format=@audio.I16) 写回 WAV，比对 data 块的 MD5 与 STREAMINFO 的 MD5。

#设计要点

• 单一采样表示：所有容器解码成同一种 AudioBuffer（交织 Double，范围 [-1, 1]），因此任意容器都能无缝进入任意 DSP 阶段。
• 显式错误：AudioError 只有四种（Truncated / Unsupported / Invalid / OutOfRange），调用方可以按语义决定重试、跳过还是提示用户。
• 无 panic 解码：所有越界读取都返回 Truncated，不会 trap；FLAC 每帧校验 CRC，损坏的帧会被明确拒绝。
• 确定性：FFT、重采样、噪声生成都是输入的纯函数，白噪声使用显式种子的 xorshift，测试可复现。
• 零依赖：只依赖 moonbitlang/core，可以离线构建，也便于在受限环境（CI、沙箱、wasm 宿主）里使用。

#路线图

• FLAC 编码器（含子帧选择与 Rice 参数搜索）
• 用官方 flac-test-files 的真实文件做一致性交叉验证（见「测试」一节）
• 把该交叉验证固化成 CI 里的定时任务，而不是一次性手动验证
• Ogg 容器与 Vorbis/Opus 解码
• 流式 API（边读边解码，避免整文件驻留内存）
• 更多滤波器类型与多通道声像处理

#许可证与参考

• RIFF/WAVE：Microsoft RIFF 规范与 WAVE_FORMAT_EXTENSIBLE 说明
• AIFF/AIFC：Apple AIFF-C 规范（80-bit 扩展浮点采样率）
• Sun .au：Sun/NeXT 音频文件格式说明
• FLAC：Xiph.Org FLAC 格式规范 / RFC 9639

#English summary