Audio Tools Skill

音视频处理工具集，支持三项核心功能：提取音频、截取音频片段、播放媒体文件。

工作目录

所有输入文件默认从 D:\workbuddy 读取，输出文件也保存到 D:\workbuddy（除非用户指定其他路径）。

环境要求

Python 版本

• 要求: Python 3.8 或更高版本
• 检查: 运行 python --version 确认

依赖检查

执行前会自动检查以下环境，缺失时给出安装指引：

# 检查环境状态
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py --check

检查内容包括：

• Python 版本
• ffmpeg / ffprobe / ffplay 可用性
• moviepy 安装状态
• openai-whisper 安装状态

依赖说明

本 Skill 优先使用 ffmpeg，查找优先级如下：

1. Skill 本地 bin 目录（D:\workbuddy\skills\audio-tools\bin\ffmpeg.exe）
2. 系统 PATH 中的 ffmpeg
3. 如均未找到，自动降级使用 moviepy（Python 库，首次使用时自动安装）

缺失依赖时的提示

如果 ffmpeg 和 moviepy 都未找到，脚本会输出：

[WARN] No media processing tool found!

[SOLUTION] Choose one of the following:

  Option 1 - Bundled ffmpeg (Recommended):
           Place ffmpeg.exe in: D:\workbuddy\skills\audio-tools\bin\

  Option 2 - System ffmpeg:
           Windows: winget install ffmpeg

  Option 3 - MoviePy (Python fallback):
           pip install moviepy

方式一：Bundled ffmpeg（推荐）

将 ffmpeg 放入 Skill 本地目录，实现零依赖部署：

D:\workbuddy\skills\audio-tools\
├── bin\
│   ├── ffmpeg.exe      ← 放入这里
│   └── ffprobe.exe     ← 可选，查时长用
├── scripts\
│   └── audio_tools.py
└── SKILL.md

方式二：系统 ffmpeg

# Windows - 使用 winget
winget install ffmpeg

# 或从 https://ffmpeg.org/download.html 下载，解压后将 bin 目录加入系统 PATH

方式三：moviepy（备选）

pip install moviepy

---

功能说明 & SOP

功能 1：提取视频音频

用户意图识别关键词：提取音频、视频转音频、从视频提取、wav 提取

执行流程：

1. 确认输入视频文件路径（相对路径自动拼接工作目录 D:\workbuddy）
2. 确认输出 WAV 文件路径（默认与输入同名，后缀改为 .wav，保存到 D:\workbuddy）
3. 调用脚本执行提取
4. 输出结果文件路径

调用脚本：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py extract \
  --input "D:\workbuddy\video.mp4" \
  --output "D:\workbuddy\video.wav"

参数说明：

参数	必填	说明
--input	✅	输入视频文件路径（支持 mp4/mkv/avi/mov/flv 等）
--output	❌	输出 WAV 文件路径（默认：同目录同名 .wav）

---

功能 2：截取音频片段

用户意图识别关键词：截取音频、剪切音频、音频截取、音频剪辑、clip audio

执行流程：

1. 确认输入音频文件路径
2. 确认开始时间（--start，格式：秒数 或 HH:MM:SS）
3. 确认截取时长（--duration，单位：秒）
4. 确认输出路径（默认：原文件名加 _clip 后缀）
5. 调用脚本执行截取
6. 输出结果文件路径

调用脚本：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py clip \
  --input "D:\workbuddy\audio.wav" \
  --start 30 \
  --duration 60 \
  --output "D:\workbuddy\audio_clip.wav"

参数说明：

参数	必填	说明
--input	✅	输入音频文件路径（支持 wav/mp3/flac/aac 等）
--start	✅	开始时间，支持秒数（如 30）或时间格式（如 00:00:30）
--duration	✅	截取时长（秒）
--output	❌	输出文件路径（默认：原文件名加 _clip 后缀）

---

功能 3：播放媒体文件

用户意图识别关键词：播放视频、播放音频、play video、play audio、打开播放

执行流程：

1. 确认媒体文件路径（相对路径自动拼接工作目录）
2. 优先使用 ffplay（bundled 模式）播放
3. 如 ffplay 不可用，回退到系统默认播放器
4. 输出播放状态

播放工具优先级：

1. ffplay（Skill 本地 bin/ffplay.exe）- 格式支持最全，无系统依赖
2. 系统默认播放器 - 用户习惯，界面友好

调用脚本：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py play \
  --input "D:\workbuddy\video.mp4"

参数说明：

参数	必填	说明
--input	✅	媒体文件路径（视频或音频均可）

---

功能 4：语音识别转文字（Whisper）

用户意图识别关键词：语音转文字、音频转录、语音识别、提取文字内容、transcribe、STT

执行流程：

1. 确认输入音频/视频文件路径
2. 确认 Whisper 模型大小（默认 small，可选 tiny/base/small/medium/large）
3. 确认语言（可选，默认自动检测）
4. 执行转录，生成 JSON 和 TXT 两份输出
5. 输出转录结果摘要

调用脚本：

# 基础用法（自动检测语言，使用 small 模型）
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py transcribe \
  --input "D:\workbuddy\lecture.wav"

# 指定语言和模型
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py transcribe \
  --input "D:\workbuddy\lecture.wav" \
  --model small \
  --language zh

参数说明：

参数	必填	说明
--input	✅	输入音频/视频文件路径
--output	❌	输出 JSON 路径（默认：同名.json）
--model	❌	Whisper 模型：tiny/base/small/medium/large（默认：small）
--language	❌	语言代码，如 zh/en/ja（默认：自动检测）

输出文件：

• 同名.json - 完整 JSON，包含文字、时间戳、置信度
• 同名.txt - 纯文本，仅文字内容

JSON 结构示例：

{
  "text": "完整转录文字...",
  "language": "zh",
  "duration": 120.5,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 5.2,
      "text": "第一段文字",
      "confidence": -0.1234,
      "no_speech_prob": 0.01
    }
  ]
}

---

功能 5：提取音频/视频元数据

用户意图识别关键词：查看音频信息、提取元数据、文件信息、码率、采样率、metadata

执行流程：

1. 确认输入文件路径
2. 优先使用 ffprobe 获取详细元数据
3. ffprobe 不可用时，使用 moviepy 获取基础信息
4. 输出 JSON 格式元数据（可选保存到文件）

调用脚本：

# 终端输出元数据
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py metadata \
  --input "D:\workbuddy\audio.wav"

# 保存到 JSON 文件
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py metadata \
  --input "D:\workbuddy\video.mp4" \
  --output "D:\workbuddy\meta.json"

参数说明：

参数	必填	说明
--input	✅	输入音频/视频文件路径
--output	❌	输出 JSON 路径（默认：终端输出）

输出信息包括：

• 文件基础信息（大小、时长、格式）
• 音频流信息（编码、采样率、声道数）
• 视频流信息（编码、分辨率、帧率）
• 完整 ffprobe 原始数据（如可用）

---

AI 使用规范

1. 路径处理：用户提供相对路径时，自动补全为 D:\workbuddy\<文件名>
2. 工具检测：执行前先检测 ffmpeg 是否可用，不可用则切换 moviepy
3. 错误处理：脚本执行失败时，读取错误信息并告知用户可能的原因和解决方案
4. 输出确认：操作完成后，明确告知用户输出文件的完整路径和文件大小

---

使用示例

用户：帮我把 D:\workbuddy\lecture.mp4 里的音频提取出来

AI 执行：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py extract --input "D:\workbuddy\lecture.mp4"

输出：✅ 提取完成：D:\workbuddy\lecture.wav（大小：12.3 MB）

---

用户：把 lecture.wav 从第 30 秒开始截取 2 分钟

AI 执行：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py clip --input "D:\workbuddy\lecture.wav" --start 30 --duration 120

输出：✅ 截取完成：D:\workbuddy\lecture_clip.wav（时长：120 秒）

---

用户：播放一下 lecture.mp4

AI 执行：

python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py play --input "D:\workbuddy\lecture.mp4"

输出：✅ 已调用系统默认播放器打开：D:\workbuddy\lecture.mp4