作者：WangYF0829（王轶凡）｜创建日期：2026-10-13｜用途：moonmux 项目文档

#moonmux

#2026-11 更新（v0.9.2）

• 已可用（最新发布 v0.9.2）：moon add WangYF0829/moonmux 安装 v0.9.2（2026-11-11 安全/资源边界修复版：MP4 表校验先于分配、Ogg 重同步预算、解码前 gate 与工作量预算、extract --force 收紧、demux 清单提交点、发布包门禁等；此前 v0.9.0 补 MP4 编辑列表与 roll、WAV fact、页校验、CLI 契约、2 GiB 闸门；此前 v0.8.0 修复 TOC/remux 闸门/MP4 读侧，v0.7.x 提供 WAV 块保真与 WavWriter，v0.6.0 性能基准与变异测试，v0.5.0 to-ogg 解封装，v0.4.0 WAV 全格式与流式页读取）。
• 变更明细见 CHANGELOG.md。

#为什么做这个

#功能范围

#作为库使用

moon add WangYF0829/moonmux

import {
  "WangYF0829/moonmux/ogg",
  "WangYF0829/moonmux/wav",
}

fn main {
  // WAV：编码 → 解析往返
  let bytes = @wav.encode_wav(
    { channels: 1, sample_rate: 8000, bits_per_sample: 16 },
    b"\x00\x00\x01\x00",
  )
  match @wav.WavFile::parse(bytes) {
    Some(f) => println("wav ok: " + f.format.sample_rate.to_string())
    None => println("wav parse failed")
  }
  // Ogg：页起始识别
  println("ogg page: " + @ogg.is_page_start(b"OggS", 0).to_string())
}

#退出码约定

#能力边界

#构建与测试

irm https://cli.moonbitlang.cn/install/powershell.ps1 | iex

moon version

moon build
moon test

#性能基准（bench）

moon build --release --target native
node scripts/bench.mjs --runs 5

#变异测试（fuzz）

• 种子：真实 Ogg Opus / Vorbis、CLI 生成的 MP4 与 WAV；
• 变异：随机翻位、块覆盖、截断、插入、删除、整段复制；
• 目标命令：info / verify / seek / dump / to-ogg；
• 断言：退出码只能是 0（成功）/ 1（数据错误）/ 2（用法/I/O），且不超时、不崩溃。

moon build --target native
node scripts/fuzz.mjs --iterations 400 --seed 20261109

#使用

# 查看容器信息（自动识别 Ogg 与 WAV）
#   Ogg：格式、流号、页数、包数、负载字节、各流末粒度；能识别音频流时再给编码/声道/采样率/时长
#   WAV：声道、采样率、位深、PCM 字节数、帧数与时长
moonmux info input.ogg
moonmux info input.wav
moonmux info input.ogg --json    # 单行 JSON，便于脚本处理
#   注：时长为「末粒度 − 首粒度 − pre-skip」，对裁剪过的流是上界

# 结构体检：逐页 CRC + 页序号连续性 + BOS / EOS 完备性 + 段表一致性
#   用于判断文件是容器损坏还是编码问题，并给出损坏的具体位置
moonmux verify input.ogg
moonmux verify input.ogg --json  # 完整 findings（文本只铺前 10 条）

# 解复用：按逻辑流拆出包，每条流一个子目录（s1/、s2/……）
moonmux demux input.ogg ./packets/

# 复用：把包重新封装成 Ogg
#   目录里有子目录 → 每个子目录一条逻辑流，按 Ogg 规则交织（BOS 页置顶、数据页按粒度升序）
#   目录里没有子目录 → 整个目录一条逻辑流
moonmux mux ./packets/ output.ogg

# 链接：把多个 Ogg 文件首尾相接成一个物理流
#   流号不冲突时逐页原样透传（字节级无损）；冲突时把后一个文件相撞的流换新流号
moonmux cat a.ogg b.ogg c.ogg output.ogg

# 拆分：把链接流按链接点切回各自独立的 Ogg 文件（输出 part1.ogg、part2.ogg……）
#   页原样沿用，字节与 CRC 一字节不改 —— 非链接流得到的 part1 与输入完全相同
moonmux split chained.ogg ./parts/

# 抽流：把第 n 条逻辑流单独取出来（页级原样，可与输入逐字节对账）
moonmux extract input.ogg 2 single.ogg

# 页级转储：偏移 / 流号 / 页序 / 粒度 / 标志 / 段数 / 负载
moonmux dump input.ogg
moonmux dump input.ogg --hex     # xxd 兼容，可 `| xxd -r` 还原

# 注释：读取与改写（KEY= 表示删除该键）
moonmux tags input.ogg
moonmux tag input.ogg tagged.ogg TITLE=月光 ARTIST=王轶凡

# 定位：按毫秒找到不晚于该时刻的页（打印页下标、字节偏移与该页起始时间）
#   链接流可用第 3 个参数指定第几段（默认第 1 段）
moonmux seek input.ogg 2500
moonmux seek chained.ogg 500 2

# 转码：Ogg（Opus / Vorbis）→ WAV；默认 16 位，可选 24 位
moonmux to-wav input.ogg output.wav
moonmux to-wav input.ogg output24.wav 24

# 重新封装：Ogg（Opus）→ MP4 / ISOBMFF 音频容器（.m4a，v0.3.x 新增）
#   不做转码：Opus 数据包原样搬运，只重建容器；info 可识别产物
moonmux remux input.ogg output.m4a
moonmux info output.m4a

# 反向解封装：MP4（Opus）→ Ogg（v0.5.0 新增，remux 的逆操作）
#   音频包逐字节还原；注释未随 MP4 保存，输出最小 OpusTags
moonmux to-ogg output.m4a back.ogg
moonmux verify back.ogg

# 裁剪：按毫秒区间裁剪（页精度，头页保留，时间轴归零）
moonmux chop input.ogg clip.ogg 1000 3000

moon build --target native

#项目结构

moonmux/
├── moon.mod / moon.pkg / moonmux.mbt   模块配置与根包
├── ogg/               Ogg 容器（页 / 段 / 包、CRC、交织、链接、结构体检、PageReader）
├── wav/               WAV 容器（全格式读写、块保真、WavWriter）
├── codec/             编解码头解析（OpusHead / Vorbis ID / OpusTags / VorbisComment / TOC）
├── manifest/          demux / mux 的流目录清单
├── pipeline/          转码管线（唯一引入三方解码器的包）
├── mp4/               MP4 / ISOBMFF 写入与解封装
├── cli/               命令行参数解析（纯逻辑）
├── cmd/main/          命令行入口
├── docs/architecture.md   模块边界、关键不变量、测试策略、能力边界
├── examples/          三个可运行示例
├── scripts/           smoke / verify_mp4 / bench / fuzz / install_check
└── testdata/          真实音频样本

#示例（examples/）

#Shell 补全

source scripts/moonmux.bash   # 子命令与文件路径补全

#参考规范

• RFC 3533: The Ogg Encapsulation Format Version 0
• RFC 7845: Ogg Encapsulation for the Opus Audio Codec
• RFC 3534: The application/ogg Media Type
• Microsoft RIFF 规范（WAV）

#参考实现与取舍

#开发状态

#许可证