Cochlea 是一个为 AI 智能体设计的无界面、确定性音频引擎。整个工作流是：作曲 → 渲染 → 探测 → 校验，过程中不需要音频设备，不需要人类耳朵，也不需要 ffmpeg。
用途
Cochlea 让智能体能够以数据形式编写乐谱，将其离线渲染为确定性的 PCM 音频，然后通过数值特征（响度、起音、音高、调性、频谱图等）来“聆听”音频并做出断言。它解决了智能体无法直接处理原始音频样本的难题：一段 7 秒的 48kHz 32 位浮点 PCM 就有 2.7 MB，而 3 分钟的同类音频约 66 MB，不适合直接交给智能体处理。Cochlea 提供的是几 KB 的 JSON 报告和一张小尺寸频谱图。
主要能力
- 作曲：乐谱是纯数据，包含轨道、音符、逐参数自动化、速度映射和可选的主控段。支持 RON 序列化（version: 1）和 Rust 构建器。位置表示如
bar(3).beat(2)，时值使用精确分数如Dur::quarter()、"3/16"。 - 渲染：音频以 64 样本块渲染，在事件边界拆分，音符时间采样级精确。输出确定性 PCM，可渲染为 WAV 或 FLAC。
- 探测：
cochlea probe生成 JSON 报告，包含响度（集成 LUFS、瞬时最大值、真峰值、LRA）、起音、YIN 音高、量化旋律、MFCC 音色摘要、色度与调性、速度和节奏（分开报告）、立体声宽度与相关性、静音、尾部、削波、结构边界等。 - 频谱图：
cochlea spectro渲染梅尔频谱图 PNG，可叠加节拍网格、起音、音高标注，支持差异热图，并可通过--sheet将长曲目平铺成一张联系表。 - 断言与验证：乐谱内嵌
verify:断言，cochlea render score.ron --verify运行断言，失败时以非零退出并输出机器可读的 JSON 失败报告。 - 差异比较：
cochlea diff在特征空间比较两个文件，报告音色、响度、音高差异，可生成带符号的差异热图。--tier2可将差异判定变为门禁（字节相同或 Tier-2 等价退出 0，否则退出 1），适合 CI 或智能体捕捉回归。
使用方式
命令行
- 从 RON 乐谱渲染：
cochlea render score.ron --out mix.wav - 探测为 JSON：
cochlea probe mix.wav --json report.json - 生成频谱图：
cochlea spectro mix.wav --out spec.png - 验证断言：
cochlea render score.ron --verify - 探测任意 WAV、FLAC（位精确解码）、mp3、ogg，无需乐谱。
- 所有读取工具支持
--from/--to进行帧精确窗口分析。 probe --digest打印确定性文本摘要，限制在约 40 行内。
MCP 服务器
cochlea-mcp 是一个基于 stdio 的 MCP 服务器，暴露 12 个工具：render_score、probe_audio、spectrogram、lint_score、probe_digest、loudness_timeline、beat_grid、audio_diff、import_midi、export_midi、transcribe_audio、score_reference。每个工具都是对匹配库调用的薄封装。特性包括：
- 自教授：
score_reference返回完整的作曲参考，包括 RON 语法、实时预设目录、所有可自动化参数、断言和可运行示例。 - 直接展示：
spectrogram以内联 MCP 图像内容（base64 PNG，尺寸受限）返回图片，支持标注节拍、起音和音高。 - 可缩放：
probe_audio和spectrogram接受from_s/to_s，只分析长文件的某一段。 - 可限制范围：
cochlea-mcp --root DIR拒绝任何解析到 DIR 之外的读写（含符号链接和..）。
安装
所有九个 crate 已发布在 crates.io。也可从源码安装：git clone https://github.com/richer-richard/cochlea && cd cochlea && cargo install --path crates/cli。
适用场景
- AI 智能体自动作曲、渲染和验证音频作品。
- 自动化音频质量检查与回归测试，无需人工听审。
- 在 CI 流程中捕捉音频渲染的意外变化。
- 对现有音频文件进行特征分析，无需乐谱。
- 通过 MCP 协议为智能体提供音频处理能力。
限制
- 音频是“折叠”而非“映射”，滤波器与延迟带状态，因此逐样本纯度不是契约；确定性分为三级，Tier 1 需要特定编译与运行时选择。
- WAV 和 FLAC 解码位精确；mp3 和 ogg 仅用于分析输入，对给定构建可复现，但无法声称与原始样本完全一致。
- 设计上不依赖 ffmpeg，无子进程调用、无系统编解码器、无 GPU、无音频设备。
- 乐谱写入位置不在 tick 网格上是错误，不会被静默舍入。
- 价格、收费、平台等未在资料中提供。
