audio-tools

---

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 确认

依赖检查

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

# 检查环境状态
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