# MoonEcho 任务规划书 ## 1. 项目基本信息 - 项目名称：月响 / MoonEcho - 仓库地址：https://github.com/lin2077-zeming/MoonEcho - 参赛赛事：2026 MoonBit 黑客松，十月赛 - 当前规划日期：2026-10-07 - 报名与验收截止：2026-10-31 - 主要实现语言：MoonBit - 建议许可证：Apache-2.0 - 建议 MoonCakes 模块名：`/moonecho` - 项目定位：AI 应用、数据处理、工具库 - 音频输入依赖：`Ridge-Lab/moonwavkit@0.1.3` - 频谱依赖：`chgttyyr/MoonSpectrum@0.2.2` ## 2. 一句话目标 MoonEcho 是一个纯 MoonBit、本地优先的音频指纹检索与音频对齐引擎。给出一段短音频，它能在离线音频库中定位这段音频来自哪个文件、出现在第几秒，并给出可解释的匹配置信度。 ## 3. 背景与选题理由 MoonBit 生态已有 WAV 读写、OGG/Opus 解码、FFT/STFT、音频 DSP 和音频引擎等基础项目，但缺少从音频输入到指纹索引、片段检索、时间对齐和置信度评分的完整闭环。 MoonEcho 不重复实现已有底层库，而是在它们之上补齐内容检索层： - 输入层：PCM/WAV，必要时预留 OGG/Opus 适配接口。 - 特征层：STFT、对数频谱、频谱峰值。 - 指纹层：峰值配对、哈希编码、稳定快照格式。 - 检索层：倒排索引、时间偏移投票、候选择优。 - 应用层：CLI、WASM 演示、JSON/Markdown 报告。 该项目边界清晰，适合在一个月内交付，并且具备真实用途： - 音频素材库去重。 - 播客广告和固定片段的重复检测。 - 视频剪辑中的音轨对齐。 - 本地音乐识别。 - 浏览器内离线音频检索。 ## 4. 项目目标 ### 4.1 必须完成 - 提供纯 MoonBit 实现的 PCM/WAV 读取和预处理能力。 - 实现确定性 STFT、对数频谱和频谱峰值提取。 - 实现音频指纹编码和可持久化索引快照。 - 实现查询片段匹配，返回文件、时间偏移和置信度。 - 提供至少一个可运行 CLI 示例。 - 提供一个 WASM 或浏览器可演示路径。 - 提供完整测试、CI、README、许可证和 mooncakes.io 发布材料。 ### 4.2 推荐完成 - 支持增量向索引追加音频。 - 支持白噪声、音量变化、静音填充和裁剪。 - 支持索引快照版本升级与校验。 - 提供 Top-K 候选和匹配解释报告。 - 提供基准测试，记录准确率、延迟和内存开销。 ### 4.3 暂不纳入 - 不实现完整音频编解码器矩阵，首期只保证 PCM/WAV 链路。 - 不训练神经网络模型，先使用经典声学指纹算法。 - 不实现云端服务、账号系统或数据库服务。 - 不直接复制 Chromaprint、Dejavu 或其他上游项目代码。 - 不提交版权不明的音乐或测试音频。 ## 5. 核心用户故事 1. 作为素材库维护者，我希望对音频库建立索引，找出重复或高度相似的音频文件。 2. 作为视频剪辑者，我希望输入一段背景音乐片段，系统返回它来自哪个音乐文件以及时间点。 3. 作为播客制作者，我希望发现节目中重复出现的片头、片尾或广告片段。 4. 作为浏览器应用开发者，我希望在本地 WASM 环境中完成匹配，不上传音频。 5. 作为 MoonBit 开发者，我希望把 MoonEcho 作为库集成到自己的音频处理项目中。 ## 6. 功能范围 ### 6.1 音频预处理 - 读取 WAV/PCM 数据。 - 支持 8/16/24/32 位 PCM 和浮点 PCM 的基础读取。 - 多声道降为单声道。 - 重采样到统一采样率。 - 分帧、窗函数和静音检测。 ### 6.2 频谱特征 - 实现或封装确定性 FFT。 - 生成短时傅里叶变换频谱。 - 计算对数幅度谱。 - 提取局部频谱峰值。 - 支持可配置频率范围、帧长、跳步和峰值密度。 ### 6.3 音频指纹 - 将峰值配对编码为稳定哈希。 - 指纹包含频点、时间差和哈希摘要。 - 提供确定性编码与解码格式。 - 提供快照版本号、校验和和边界检查。 ### 6.4 检索索引 - 基于哈希建立倒排索引。 - posting list 记录音频 ID 和时间位置。 - 查询时统计时间偏移投票。 - 支持候选过滤、Top-K 排序和置信度计算。 - 支持索引快照保存、加载和校验。 ### 6.5 匹配与报告 - 返回最佳匹配文件和偏移时间。 - 输出候选列表和命中证据。 - 支持 JSON、Text 和 Markdown 报告。 - 对误报、低置信度和不匹配给出明确原因。 ### 6.6 CLI 与演示 - `moonecho index`：建立索引。 - `moonecho match`：查询片段。 - `moonecho inspect`：检查指纹或快照。 - `moonecho bench`：运行基准测试。 - `moonecho demo`：运行最小端到端示例。 - WASM 路径优先做单文件或小音频集演示。 ## 7. 系统结构 建议仓库结构： ```text MoonEcho/ docs/ 任务规划书.md 项目申报书.md 算法说明.md src/ pcm/ spectrum/ fingerprint/ index/ match/ report/ cmd/ moonecho/ examples/ basic/ match-clip/ testdata/ generated/ fixtures/ bench/ wasm/ .github/workflows/ci.yml LICENSE README.md moon.mod.json moon.pkg ``` 包边界原则： - `pcm` 只处理音频样本和格式。 - `spectrum` 只处理频谱和峰值。 - `fingerprint` 只处理指纹编码。 - `index` 只处理索引结构和快照。 - `match` 只处理候选评分和置信度。 - `report` 只处理输出格式。 - `cmd/moonecho` 只负责参数解析和串联流程。 ## 8. 里程碑计划 ### M0 项目奠基：2026-10-07 至 2026-10-09 交付： - 完成任务规划书。 - 初始化 MoonBit 项目结构。 - 建立 README、LICENSE、CI 骨架。 - 在 GitHub 建立首批 issue。 - 提交 2 到 3 个有意义的初始 commit。 验收： - `moon check` 通过。 - `moon test` 通过。 - CI 能运行检查、构建和测试。 ### M1 音频与频谱：2026-10-10 至 2026-10-14 交付： - `audio` 包基于 MoonWavKit 完成 WAV/PCM 适配和安全边界。 - `spectrum` 包基于 MoonSpectrum 完成 FFT/STFT 和合成信号适配。 - `spectrum` 包补充二维时频局部峰值提取、阈值过滤和每帧数量限制。 - 生成第一批合成测试音频。 - 完成 FFT、STFT、峰值提取单元测试。 验收： - WAV/PCM 输入链路复用成熟依赖，不重复实现完整 WAV 解析。 - 正弦波频率识别正确。 - STFT 输出尺寸稳定。 - 峰值提取对合成信号结果确定。 - 测试不依赖网络和外部音频。 ### M2 指纹与索引：2026-10-15 至 2026-10-19 交付： - `fingerprint` 包完成峰值配对和哈希编码。 - `index` 包完成倒排索引和 posting list。 - 指纹快照格式 v1 完成。 - 指纹 v1 字节布局、哈希规则和校验方式写入 `docs/fingerprint-v1.md`。 - 索引快照 v1 字节布局、posting 记录和校验方式写入 `docs/index-v1.md`。 - 索引快照 v2 增加 processing profile，并写入 `docs/index-v2.md`。 - 完成指纹确定性、快照 round-trip 和边界测试。 验收： - 同一输入生成完全相同的指纹。 - 不同采样率规范到统一采样率后结果稳定。 - 快照损坏能返回明确错误。 - 索引可保存、加载、再次查询。 ### M3 匹配闭环：2026-10-20 至 2026-10-24 交付： - `match` 包完成偏移投票和候选评分。 - 匹配算法、置信度和 margin 规则写入 `docs/matching.md`。 - 实现 Top-K 候选和置信度。 - 实现裁剪、静音、增益、噪声等鲁棒性测试。 - 鲁棒性场景、指标定义和计时口径写入 `docs/benchmark.md`。 - 样本级对齐算法和更强的 chirp/多音/脉冲语料写入 `docs/alignment.md`。 - 完成 `moonecho index` 和 `moonecho match`。 - CLI 参数、输出和复现注意事项写入 `docs/cli.md`。 - 完成基础端到端示例。 验收： - 无噪声裁剪片段可稳定命中。 - 带静音或音量变化的片段可稳定命中。 - 不相关片段不会给出高置信度结果。 - 查询报告包含文件、偏移和解释信息。 ### M4 演示与质量：2026-10-25 至 2026-10-28 交付： - WASM 或浏览器演示路径。 - `wasm-gc` 浏览器匹配演示、内置合成语料和 Node 冒烟测试。 - `moonecho bench` 基准命令。 - manifest 批量建库、快照追加和重复 track id 检查。 - 快照信息查询以及 `index`、`match`、`info`、`bench` 的 JSON 输出。 - 准确率、延迟、内存和索引大小报告。 - README 完整化。 - 算法说明和开源来源说明。 验收： - 新用户可按 README 在 10 分钟内运行示例。 - WASM 演示能完成至少一次查询。 - 基准结果可复现。 - CLI 的批量、追加、信息和 JSON 路径可由脚本稳定调用。 - README 明确说明支持范围和限制。 ### M5 验收与发布：2026-10-29 至 2026-10-31 交付： - 发布到 mooncakes.io。 - 完成第三方许可证说明、发布清单和 `moon package` 归档检查。 - 完成项目申报书。 - 完成验收演示说明。 - 整理最终 commit、issue、PR 和 changelog。 - 完成最终自检。 验收： - `moon check`、`moon test`、格式检查全部通过。 - GitHub 仓库公开可访问。 - CI 全绿。 - LICENSE、README、示例、测试和发布信息齐全。 - 所有关键功能均由参赛者理解并能够解释。 ## 9. 测试策略 ### 9.1 单元测试 - PCM 字节序和样本格式转换。 - 单声道化和重采样边界。 - FFT/STFT 对已知信号的输出。 - 峰值提取对合成信号的确定性。 - 指纹哈希编码和解码。 - 索引插入、查询和快照 round-trip。 - 匹配评分和置信度边界。 ### 9.2 集成测试 - 对音频库建索引，再查询完整曲目。 - 查询裁剪片段。 - 查询带静音片段。 - 查询带噪声片段。 - 查询带增益变化片段。 - 查询不相关音频作为负样本。 ### 9.3 属性测试与模糊测试 - 任意合法 PCM 数据不应导致崩溃。 - 任意截断快照应返回结构化错误。 - 索引加载后查询结果应与原始索引一致。 - 指纹编码解码应满足 round-trip。 ### 9.4 质量指标 建议首期目标： - 干净裁剪片段 Top-1 命中率：大于或等于 98%。 - 时间偏移误差：小于或等于 0.5 秒。 - 加噪片段 Top-1 命中率：大于或等于 90%。 - 负样本误报率：小于或等于 1%。 - 基准测试可重复运行。 上述指标可根据实际测试集调整，但必须在 README 中如实记录。 ## 10. 数据与许可证策略 - 测试音频优先使用程序生成的正弦波、chirp、噪声、和弦和混合信号。 - 如需真实音频，只使用 CC0、公共领域或自录素材。 - 不提交未授权的商业音乐或影视音频。 - 参考 Dejavu 等项目的算法思想时，在 README 和算法说明中标注来源。 - 不直接复制 LGPL 或其他限制性许可证项目的代码。 - 所有第三方依赖必须记录名称、链接、许可证和用途。 ## 11. 开源合规与工程规范 - 使用 Apache-2.0 或 MIT 作为项目许可证。 - 所有文件使用清晰、可追踪的提交信息。 - 每个较大功能使用 issue 记录目标和验收标准。 - 功能开发使用分支或小步提交，保留可追溯记录。 - README 必须包含安装、运行、测试、示例和限制说明。 - CI 必须覆盖格式检查、构建、测试和示例运行。 - 发布前检查 `moon.mod.json`、仓库地址、许可证和关键词。 ## 12. 风险与应对 | 风险 | 影响 | 应对 | |---|---|---| | FFT/STFT 性能不足 | 大音频索引慢 | 先处理短音频，使用固定配置和性能基准，必要时优化窗长和跳步 | | 鲁棒性不足 | 噪声或变速后匹配失败 | 先完成裁剪、静音、增益和低噪声，变速作为增强项 | | 测试音频版权风险 | 影响开源合规 | 只使用生成音频和 CC0 素材 | | 范围过大 | 无法按期验收 | 冻结首版范围，编解码器和神经网络模型全部后置 | | 索引快照不兼容 | 后续维护困难 | 快照带版本号、校验和和迁移策略 | | WASM 演示耗时 | 影响文档和发布 | WASM 只做最小演示，核心验收以 Native CLI 和库为准 | | 与已有项目重叠 | 影响评审 | 明确 MoonEcho 是检索层，不重复 DSP、解码和音频引擎 | ## 13. 完成定义 一个任务只有同时满足以下条件才算完成： - 代码已合并到主分支。 - 有对应测试，且正常和异常路径均有覆盖。 - `moon check` 和 `moon test` 通过。 - README 或文档已更新。 - 示例可运行。 - 无未说明的第三方代码或素材。 - 相关 issue 已关闭并记录验证方式。 ## 14. 第一批 GitHub Issues 建议 1. 初始化 MoonBit 项目骨架和 CI。 2. 实现 WAV/PCM 读取与单声道预处理。 3. 实现 FFT/STFT 和合成测试。 4. 实现频谱峰值提取。 5. 设计音频指纹 v1 格式。 6. 实现倒排索引和快照。 7. 实现匹配投票和置信度。 8. 实现 `moonecho index` 和 `moonecho match`。 9. 增加鲁棒性测试集和基准。 10. 完成 WASM 演示、README 和 mooncakes 发布。 ## 15. 下一步执行顺序 1. 初始化 MoonBit 项目结构。 2. 创建 README、LICENSE、CI 和基础测试。 3. 提交第一个可运行空示例。 4. 建立 GitHub issues 和里程碑。 5. 开始实现 `pcm` 与 `spectrum`。