audio-tools

SKILL.md

---
name: audio-tools
version: 1.0.0
description: >
  音视频处理工具集。支持以下操作：
  - 从视频文件中提取音频并保存为 WAV 格式
  - 对音频文件按指定开始时间和持续时长进行截取
  - 播放指定的视频或音频文件（调用系统默认播放器）
  - 语音识别转文字（Whisper），输出 JSON 格式（含时间戳、置信度）
  - 提取音频/视频元数据（码率、采样率、时长、编码等）
  触发词：提取音频、截取音频、音频截取、剪切音频、播放视频、播放音频、
  视频转音频、wav提取、音频剪辑、从视频提取、audio extract、clip audio、play video、play audio、
  语音转文字、音频转录、语音识别、提取文字、transcribe、STT、
  查看音频信息、提取元数据、文件信息、码率、采样率、metadata
work_dir: D:\workbuddy
runtime: python
script: scripts/audio_tools.py
---

# Audio Tools Skill

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

## 工作目录

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

## 环境要求

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

### 依赖检查
执行前会自动检查以下环境，缺失时给出安装指引：
```bash
# 检查环境状态
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（备选）
```bash
pip install moviepy
```

---

## 功能说明 & SOP

### 功能 1：提取视频音频

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

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

**调用脚本**：
```bash
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. 输出结果文件路径

**调用脚本**：
```bash
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. **系统默认播放器** - 用户习惯，界面友好

**调用脚本**：
```bash
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. 输出转录结果摘要

**调用脚本**：
```bash
# 基础用法（自动检测语言，使用 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 结构示例**：
```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 格式元数据（可选保存到文件）

**调用脚本**：
```bash
# 终端输出元数据
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 执行：
```bash
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 执行：
```bash
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 执行：
```bash
python D:\workbuddy\skills\audio-tools\scripts\audio_tools.py play --input "D:\workbuddy\lecture.mp4"
```
输出：`✅ 已调用系统默认播放器打开：D:\workbuddy\lecture.mp4`