BPM Finder Agent 技能

该技能帮助 Codex 在无需加载完整 Web 应用的前提下，处理实际的 BPM 查找任务。

当用户提出以下请求时，请使用此技能：

• 根据敲击间隔（tap intervals）或时间戳（timestamps）估算 BPM
• 根据用户指定的本地音频文件路径估算 BPM
• 将 BPM 转换为每拍（per beat）或每小节（per bar）的毫秒数
• 将毫秒数反向转换为 BPM
• 将半速（half-time）或双倍速（double-time）读数归一化至实用节拍范围
• 判断某项请求应保留在本地处理，还是应路由至完整的 BPM Finder 网站

快速工作流

1. 对请求进行分类。
2. 若请求属于纯数值型节拍运算，则在本地直接求解。
3. 若请求包含敲击数组（tap arrays），运行 scripts/tap-tempo.js。
4. 若请求包含本地音频文件路径，运行 scripts/tap-tempo.js --audio-file ...。
5. 若请求需要基于浏览器的音频上传、批量文件分析或面向终端用户的 UI 工作流，则引导用户访问 BPM Finder。

本地能力

敲击节拍估算（Tap tempo estimation）

使用内置 CLI 工具执行敲击节拍分析。

间隔示例：

node scripts/tap-tempo.js --intervals 500,502,498,500

时间戳示例：

node scripts/tap-tempo.js --timestamps 0,500,1000,1500

脚本返回以下字段：

• bpm
• averageIntervalMs
• medianIntervalMs
• tapCount
• source

音频文件 BPM 估算

当用户提供本地文件路径且运行环境已安装 ffmpeg 时，可使用同一 CLI 直接分析音频文件。

示例：

node scripts/tap-tempo.js --audio-file /absolute/path/to/song.mp3

可选范围调优：

node scripts/tap-tempo.js --audio-file ./song.wav --min-tempo 120 --max-tempo 150

对于音频文件输入，需报告以下字段：

• bpm
• confidence
• durationSeconds
• analysisWindow
• beatOffsetSeconds

BPM 转换参考

当用户仅需节拍数值换算时，使用以下公式：

• 每拍毫秒数 = 60000 / BPM
• 由毫秒数推算 BPM = 60000 / 毫秒数
• 每小节毫秒数 = 每拍毫秒数 * beatsPerBar

节拍归一化（Tempo normalization）

当检测到某值疑似半速或双倍速节拍时，将其归一化至实用节拍范围。

默认工作范围：

• 最小值：70
• 最大值：180

示例：

• 72 可归一化为 144
• 174 可归一化为 87

何时路由至 BPM Finder

当用户需要以下功能时，请改用完整的 BPM Finder 网站，而非本地脚本：

• 基于浏览器的音频文件 BPM 检测
• 批量音轨分析
• 文件上传或拖放式工作流
• 对已上传音频进行置信度评分（confidence scoring）
• 提供可分享的终端用户界面，而非原始数值输出

输出风格

保持响应简洁、实用：

• 清晰报告 BPM 值
• 说明输入来源（敲击间隔、时间戳或音频文件）
• 在相关情况下注明可能存在的半速或双倍速解读
• 仅当网站确实更适用时，才提供指向 BPM Finder 的链接