让 Agent 原生驱动 WaveTone 2.61cli-anything-wavetone 音频转写工作流实战指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingWaveTone 是一款面向音频转写辅助的 Windows 免费软件可对音频文件进行频谱图与基频分析、调性与和弦检测、音符编辑并通过 GUI 菜单导出 MIDI、文本与处理后的 WAVE 文件。cli-anything-wavetone 是 CLI-Anything 生态中专门为 WaveTone 2.61 打造的 Agent 原生agent-native命令行适配层它通过结构化的 JSON 项目清单manifest准备、检查并启动真实的wavetone.exe。本文以仓库中的技能文档 SKILL.md 为骨架结合 README.md、WAVETONE.md 及全部核心源码系统讲解其命令体系、清单结构、后端定位策略与测试验证方案帮助你或你的 Agent快速上手清单规划 真机启动的 WaveTone 转写工作流。一、背景与设计理念为什么不直接调用 WaveToneWaveTone 2.61 是一个纯 GUI 应用分析设置、MIDI/文本导出、WAVE 导出全部通过模态对话框完成没有公开的控制台帮助、批处理模式、脚本 API 或无头导出命令。这意味着任何想用 Agent 自动化 WaveTone 的尝试都必须面对无法绕过 GUI的现实。cli-anything-wavetone 采取的是一条务实路线见 WAVETONE.md 的 Backend Strategy不重新实现 WaveTone 的分析引擎。真实后端始终是wavetone.execli-anything-wavetone wavetone launch只是把该二进制可选附带一个音频文件参数启动起来。不假装生成原生 WFD 数据。由于 WFD 格式未公开文档化清单只负责记录源音频、预期分析设置、标签、速度tempo元数据以及之后由 WaveTone 自己保存的 WFD 路径。JSON 项目清单是 Agent 面向的规划与控制层真正的分析与导出仍发生在 WaveTone GUI 中。从源码结构看整个 harness 由三部分组成wavetone/agent-harness/cli_anything/wavetone/core/项目清单、音频探测、会话日志、utils/真实后端包装、REPL 皮肤、wavetone_cli.pyClick 命令行入口。这种薄 CLI 层 结构化数据 真实二进制的组合正是 CLI-Anything 让所有软件都变得 Agent 原生的具体实践。二、环境要求与安装2.1 前置条件根据 SKILL.md 的 Requirements使用本技能需要Windows 主机wavetone launch在非 Windows 平台上会被明确拒绝源码见 wavetone_backend.py。本地解压好的 WaveTone 2.61。当不使用默认便携路径时通过环境变量指定后端位置二选一WAVETONE_EXE指向wavetone.exeWAVETONE_HOME指向 WaveTone 解压目录。2.2 后端发现规则后端查找器wavetone_backend.py按以下优先级搜索wavetone.exe命令行--exe显式指定的路径环境变量WAVETONE_EXEWAVETONE_HOME\wavetone.exe与WAVETONE_HOME\WaveTone.exe常见便携解压位置如%USERPROFILE%\Desktop\wavetone2.6.1\wavetone.exe、Downloads下的同名目录、C:\Program Files\WaveTone、C:\Program Files (x86)\WaveTone。找不到时会抛出包含已检查路径清单的明确错误方便排查。2.3 安装 harness在仓库的 wavetone/agent-harness 目录下执行pip install -e .若 WaveTone 不在默认便携路径用 PowerShell 设置后端路径$env:WAVETONE_HOME C:\Users\you\Desktop\wavetone2.6.1 # 或 $env:WAVETONE_EXE C:\Users\you\Desktop\wavetone2.6.1\wavetone.exe安装后获得cli-anything-wavetone控制台命令入口声明见 setup.py。包要求 Python 3.10依赖click8.0.0与prompt-toolkit3.0.0。不带任何子命令直接运行会进入 REPL 交互循环wavetone_cli.py。三、核心命令体系五个命令组一屏概览所有命令都支持顶层--json标志输出机器可读的 JSONemit逻辑见 wavetone_cli.py这是 Agent 解析结果的关键通道。SKILL.md 给出的典型工作流cli-anything-wavetone --json wavetone doctor cli-anything-wavetone --json project new input.wav -o project.wt.json cli-anything-wavetone --project project.wt.json --json audio probe cli-anything-wavetone --project project.wt.json --json project set-tempo --bpm 120 --meter 4/4 cli-anything-wavetone --project project.wt.json --json project add-label chorus --time 64.0 cli-anything-wavetone --project project.wt.json --json wavetone launch五个命令组及其职责对应 SKILL.md 与 wavetone_cli.py 的cli.group定义命令组职责子命令project创建/编辑 JSON 清单new、info、set-tempo、add-label、analysis、attach-wfdaudio在打开前探测音频元数据probewavetone检查并启动真实 GUIdoctor、formats、launchsession记录多步 Agent 工作流的轻量事件日志record、eventsdefaults显示新建清单使用的默认分析设置无子命令四、JSON 项目清单Agent 的作战计划4.1 清单不是 WFD 文件这是本技能最重要的心智模型Agent Guidance 一节明确强调JSON 项目清单不是 WaveTone 的 WFD 文件而是面向 Agent 的、关于源音频、预期分析设置、标签与速度元数据的规划文件。真正的分析数据必须由 WaveTone 自己执行并保存为 WFD/MIDI/text/WAVE 输出。project new创建清单时project.py会自动校验音频文件存在、是文件且扩展名受支持然后生成如下结构{ schema_version: wavetone-project/v1, software: { name: WaveTone, version: 2.61, backend: wavetone.exe }, project: { name: input, created_at: …ISO8601 UTC…, modified_at: … }, audio: { path: …input.wav 的绝对路径…, filename: input.wav, extension: .wav, size_bytes: 123456 }, analysis: { …默认分析设置… }, tempo: { bpm: null, first_bar_time_seconds: 0.0, meter: 4/4 }, labels: [], notes: [], wfd_path: null, limitations: [ WaveTone 2.61 exposes analysis, MIDI/text export, and WAVE export through GUI menus., This manifest is an agent-facing plan; WFD analysis data must be saved by WaveTone itself. ] }schema_version固定为wavetone-project/v1加载时会校验版本避免跨版本误读project.py。limitations字段把GUI 驱动、清单只是规划的边界直接写进了数据让下游 Agent 不会误解清单的能力范围。4.2 支持与拒绝的音频格式受支持的音频扩展名集合project.py.wav、.wave、.aif、.aiff、.mp3、.wma、.aac、.ogg、.oga、.flac、.wv、.ape、.alac、.ttaformats子命令会同时输出扩展名清单与 WaveTone 自述支持的格式名WAVE、AIFF、MP3、WMA、AAC、Vorbis、FLAC、WavPack、Monkeys Audio、ALAC、TTA。不在集合内的扩展名会被project new/audio probe拒绝并给出支持清单避免把 WaveTone 打不开的文件一路带到启动环节。4.3 默认分析设置defaults与analysis子命令新建清单时会注入一组默认分析设置project.py运行cli-anything-wavetone --json defaults可直接查看配置项默认值说明blocks_per_second12每秒分析块数决定时间分辨率blocks_per_semitone5每半音分析块数决定音高分辨率note_rangeC1-B7音符分析范围reference_frequency_hz440.0参考频率A4 基准analyze_fundamental_frequencytrue是否分析基频channelStereo分析声道可选Stereo/L-R/LR/L/Rskip_analysis_dialogfalse是否跳过分析对话框project analysis子命令逐项覆盖这些设置wavetone_cli.py。注意其布尔选项--fundamental/--no-fundamental、--skip-dialog/--show-dialog采用三态设计未提供的选项保持None不会覆盖清单中已有值——这一点有专门的单元测试test_cli_analysis_preserves_omitted_boolean_flags保障。4.4 速度tempo与标签project set-tempo记录 WaveTone 在和弦/音符工作前应使用的速度规划参数为--bpm必填须 0、--first-bar首小节时间默认0.0秒、--meter默认4/4。project add-label追加导航标签参数为标签名位置参数、--time必填秒须 0、可选--note。标签写入后会自动按时间排序project.py保证 Agent 读取labels数组时天然按时间轴顺序。4.5 挂接 WFDattach-wfd当 WaveTone 在 GUI 中完成分析并保存出 WFD 文件后可以用project attach-wfd xxx.wfd把该文件路径挂回清单要求已存在且扩展名为.wfd见 wavetone_cli.py。这样多步骤工作流可以清单 - 分析 - 回填结果路径地串联起来。五、音频探测打开之前的侦察兵audio probe在把音频交给 WaveTone 之前先返回时长、采样率、声道、编码与大小等元数据。其探测策略是三级回退audio.pyWAV/WAVE 文件优先用 Python 标准库wave模块读取probe 方法标记为python-wave不依赖外部工具其余格式调用ffprobeffprobe -show_entries stream…:format… -of json返回编码名、比特率等信息probe 方法标记为ffprobe对非数字元数据做了安全解析_safe_float/_safe_int若 WAV 损坏或 ffprobe 缺失/失败回退到仅基于文件系统 stat 的元数据并给出warning: Install ffprobe for detailed metadata on this format.提示。因此若想对 MP3、FLAC 等格式获得完整探测信息需要环境中存在ffprobe。测试计划中的test_probe_malformed_wav_falls_back_to_stat与test_ffprobe_uses_single_show_entries_argument分别覆盖了这两条回退与参数构造路径。audio probe也支持不带参数、直接基于--project指定清单中的音频路径进行探测便于工作流复用。六、真实后端doctor、formats 与 launch6.1 doctor启动前的体检wavetone doctor检查后端是否就绪wavetone_backend.py输出ready布尔值与逐项checks列表wavetone.exe存在且是文件解压根目录下存在data目录且包含 WaveTone 2.61 打包的解码器支持文件awlib.dll、bass.dll、bassflac.dll、basswma.dll、basswv.dll、bass_aac.dll、bass_alac.dll、bass_ape.dll、bass_tta.dll、asdecoder.exe清单见 wavetone_backend.pywthelp帮助目录存在WaveTone 用 Shift-JIS HTML 帮助文件说明分析与导出当前是 Windows 主机。任一检查不通过ready即为false命令以退出码 1 结束。这正是 SKILL.md 建议把doctor放在工作流第一步的原因——在写清单之前先确认后端可用。6.2 launch启动真实 GUIwavetone launch [audio_path]启动真实的wavetone.exe工作目录设为 exe 所在目录可选携带音频文件作为参数。其实现细节wavetone_backend.py返回backend、executable、cwd、pid、args、running_after_wait、terminated、exit_code等结构化信息--wait N指定等待秒数之后轮询进程是否仍在运行--terminate在等待期后结束进程先terminate超时再kill用于冒烟测试。SKILL.md 特别给出了自动化检查场景的标准写法cli-anything-wavetone --json wavetone launch input.wav --wait 1 --terminate这条命令确认真实后端可以被启动同时不留下常驻的 GUI 进程。若等待期后进程以非零码提前退出CLI 会以该退出码失败对应测试test_wavetone_launch_fails_on_early_nonzero_exit非 Windows 主机上调用则直接报RuntimeError。七、会话日志多步工作流的便签本session命令组为多步 Agent 工作流提供轻量事件日志session.pycli-anything-wavetone session record session.log analysis_started --payload {note: probe done} cli-anything-wavetone session events session.logrecord session_path event [--payload JSON]追加一条{time, event, payload}记录payload 必须是 JSON 对象events session_path列出全部事件文件不存在时返回空列表日志文件结构为{schema_version: wavetone-session/v1, events: []}写入前会递归校验 payload 不含 NaN/Infinity 等非有限浮点数_assert_json_safe保证日志始终是合法 JSON。这让你可以在探测 - 规划 - 启动的每一步落一条带时间戳的事件事后完整还原 Agent 的执行轨迹。八、Agent 使用指南与完整工作流综合 SKILL.md 的 Agent Guidance 与 README 的 Backend Truthfulness一个规范的 Agent 工作流如下体检后端cli-anything-wavetone --json wavetone doctor确认ready: true规划清单cli-anything-wavetone --json project new input.wav -o project.wt.json如需可--name指定项目名默认取音频文件主干名探测音频cli-anything-wavetone --project project.wt.json --json audio probe注入元数据project set-tempo速度与project add-label段落标签如 intro/verse/chorus定制分析如默认设置不满足用project analysis覆盖例如指定--channel LR --note-range C2-C6启动真实分析cli-anything-wavetone --project project.wt.json --json wavetone launch由用户在 GUI 中完成分析与导出回填结果在 GUI 中保存 WFD 后project attach-wfd result.wfd把路径挂回清单project info可随时查看清单全貌。要点提醒JSON 清单只是规划层不要指望它产出 WFD/MIDI/text/WAVE——这些必须由 WaveTone GUI 菜单操作完成这也是清单中limitations字段反复强调的边界。九、测试与验证CI 友好且真实后端可选的方案测试计划与结果详见 tests/TEST.md共 32 项test_core.py24 个单元测试 test_full_e2e.py8 个端到端测试。默认运行无需安装 WaveTonecd wavetone/agent-harness python -m pytest cli_anything/wavetone/tests/ -v默认结果30 passed, 2 skipped跳过两个真实后端测试覆盖清单创建/往返、标签排序、分析设置、WFD 校验、非有限数值拒绝、WAV 探测与回退、会话日志、后端发现等CLI 子进程测试默认解析并使用仓库内的python -m cli_anything.wavetone.wavetone_cli模块即使环境中存在已安装的cli-anything-wavetone也不会静默切换真实后端冒烟测试TestRealWaveToneBackend默认跳过需显式开启$env:CLI_ANYTHING_WAVETONE_REAL_BACKEND 1 $env:WAVETONE_HOME C:\Users\Hp\Desktop\wavetone2.6.1 python -m pytest cli_anything\wavetone\tests\ -v -s开启后结果为32 passeddoctor报告全部打包文件formats输出文档化扩展名并真实启动wavetone.exe加载生成的 WAV、等待后终止。这个默认零依赖可跑、真实后端显式 opt-in的设计让没有 WaveTone 的 CI 与贡献者也能完整执行 CLI 侧测试。十、已知边界与适用前提诚实呈现本 harness 的能力边界WAVETONE.md 的 Known LimitsWFD 不由本 harness 生成格式未文档化真实分析与导出仍在 WaveTone GUI 中完成分析设置、MIDI/text/WAVE 导出均为模态 GUI 流程无头导出的证据有限目前覆盖仅限于启动冒烟测试与音频/项目文件校验直到发现稳定的自动化或脚本化接口为止平台前提wavetone launch仅支持 Windows后端是硬性运行时依赖必须通过WAVETONE_EXE/WAVETONE_HOME或默认便携路径定位到 2.61 解压目录。理解这些边界恰恰是正确使用该工具的前提cli-anything-wavetone 的价值不在于替代 WaveTone 的分析能力而在于为 Agent 提供一条可校验、可规划、可追溯的控制通道把 GUI 软件无缝接入自动化工作流。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
