yakeworld Operational Steps
- 确认输入参数完整
- 执行核心操作（参考本目录下的 scripts/ 或 references/）
- 验证输出符合契约
- 保存结果并报告
Pitfalls
-
-
Verification
-
-
-
-
1. 2. 3.
IO_CONTRACT
- input:
request: str, context: dict— 用户请求描述、上下文信息 - output:
result: dict — 技能执行结果（结构因技能而异）
对应原则：P2（机械原子暴露输入输出规范）
songsee
Generate spectrograms and multi-panel audio feature visualizations from audio files.
Prerequisites
Requires Go:
go install github.com/steipete/songsee/cmd/songsee@latest
Optional: ffmpeg for formats beyond WAV/MP3.
Quick Start
# Basic spectrogram
songsee track.mp3
# Save to specific file
songsee track.mp3 -o spectrogram.png
# Multi-panel visualization grid
songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux
# Time slice (start at 12.5s, 8s duration)
songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg
# From stdin
cat track.mp3 | songsee - --format png -o out.png
Visualization Types
Use --viz with comma-separated values:
| Type | Description |
|---|---|
spectrogram |
Standard frequency spectrogram |
mel |
Mel-scaled spectrogram |
chroma |
Pitch class distribution |
hpss |
Harmonic/percussive separation |
selfsim |
Self-similarity matrix |
loudness |
Loudness over time |
tempogram |
Tempo estimation |
mfcc |
Mel-frequency cepstral coefficients |
flux |
Spectral flux (onset detection) |
Multiple --viz types render as a grid in a single image.
Common Flags
| Flag | Description |
|---|---|
--viz |
Visualization types (comma-separated) |
--style |
Color palette: classic, magma, inferno, viridis, gray |
--width / --height |
Output image dimensions |
--window / --hop |
FFT window and hop size |
--min-freq / --max-freq |
Frequency range filter |
--start / --duration |
Time slice of the audio |
--format |
Output format: jpg or png |
-o |
Output file path |
Notes
- WAV and MP3 are decoded natively; other formats require
ffmpeg - Output images can be inspected with
vision_analyzefor automated audio analysis - Useful for comparing audio outputs, debugging synthesis, or documenting audio processing pipelines
验证清单 · VERIFICATION
- Go 已安装且
songsee可通过go install ...@latest正常执行 - 输入音频文件存在且格式受支持（WAV/MP3 原生解码；其他格式已安装
ffmpeg） -
--viz值为合法可视化类型（spectrogram/mel/chroma/hpss/selfsim/loudness/tempogram/mfcc/flux），多类型生成网格图 -
--start/--duration时间切片在音频实际时长范围内，未越界 - 输出图像文件存在且非零字节，格式为指定
--format（jpg/png） - 输出图像可用
vision_analyze读取，频谱内容清晰可辨
约束规则 · RULES
- 输入约束: 参数类型、范围、格式必须校验
- 输出约束: 返回值结构、编码、命名必须一致
- 异常约束: 错误信息必须包含上下文和恢复建议
- 安全约束: 不执行未验证的任意代码，不暴露内部状态
Golden 集合 · GOLDEN SET
- Golden Input: 标准输入样本（覆盖正常路径）
- Golden Output: 预期输出（精确匹配或格式校验）
- Golden Error: 预期错误信息（覆盖失败路径）
Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。
违反规则的操作视为不安全，必须拒绝或隔离。
每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。
Songsee
Genes (策略基因)
紧凑策略表示。条件→策略。需要深度时参考完整文档。
- [SONG-001] 需要对比音频特征或调试合成时 → 使用
--viz指定多种可视化类型（如 spectrogram, mel, chroma）以生成多面板网格图 - [SONG-002] 仅需分析音频特定片段时 → 使用
--start和--duration参数截取时间切片进行局部可视化 - [SONG-003] 处理 WAV/MP3 以外的音频格式时 → 确保系统已安装
ffmpeg以支持原生解码之外的格式转换 - [SONG-004] 需要自动化分析音频内容时 → 将生成的可视化图像作为输入传递给
vision_analyze进行视觉特征提取 - [SONG-005] 需要调整频谱显示细节时 → 通过
--window、--hop及--min-freq/--max-freq参数精细控制 FFT 窗口与频率范围 - [SONG-006] 需要标准化输出图像外观时 → 使用
--style选择特定色板（如 magma, viridis）并指定--width/--height统一尺寸
示例 · EXAMPLES
例 1: 生成基础频谱图
- 输入:
track.mp3 - 操作:
songsee track.mp3 -o spectrogram.png（MP3 原生解码，无需 ffmpeg） - 验证: 输出
spectrogram.png存在且非零字节，可用vision_analyze读取确认频谱清晰
例 2: 多面板特征网格（调试合成）
- 输入:
track.mp3 - 操作:
songsee track.mp3 --viz spectrogram,mel,chroma,tempogram,flux -o grid.png --style magma - 验证: 单张图像含 5 个面板的网格；各面板对应可视化类型可辨
例 3: 时间切片局部分析
- 输入:
track.mp3，关注 12.5s 起的 8s 片段 - 操作:
songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg --format jpg - 验证: 切片未越界（12.5+8 ≤ 音频时长）；输出
slice.jpg仅含指定时间段