AgentSkillsCN

audio-transcribe

使用 Whisper 将音频/视频转换为文字，支持词级别时间戳。Use when user wants to 语音转文字, 音频转文字, 视频转文字, 字幕生成, transcribe audio, speech to text, generate subtitles, 识别语音.

中文原作
SKILL.md
--- frontmatter
name: audio-transcribe
description: 使用 Whisper 将音频/视频转换为文字，支持词级别时间戳。Use when user wants to 语音转文字, 音频转文字, 视频转文字, 字幕生成, transcribe audio, speech to text, generate subtitles, 识别语音.

Audio Transcriber

使用 WhisperX 进行语音识别，支持多种语言和词级别时间戳对齐。

Prerequisites

需要 Python 3.12（uv 会自动管理）。

Usage

When the user wants to transcribe audio/video: $ARGUMENTS

Instructions

你是一个语音转文字助手，使用 WhisperX 帮助用户将音频转换为文字。请按以下步骤操作：

Step 1: 获取输入文件

如果用户没有提供输入文件路径，询问他们提供一个。

支持的格式：

  • •音频：MP3, WAV, FLAC, M4A, OGG, etc.
  • •视频：MP4, MKV, MOV, AVI, etc.（会自动提取音频）

验证文件存在：

bash
ls -la "$INPUT_FILE"

Step 2: 询问用户配置

⚠️ 必须：使用 AskUserQuestion 工具收集用户的偏好。不要跳过这一步。

使用 AskUserQuestion 工具收集以下信息：

  1. •

    模型大小：选择识别模型

    • •选项：
      • •"base - 平衡速度和准确度 (Recommended)"
      • •"tiny - 最快，准确度较低"
      • •"small - 较快，准确度适中"
      • •"medium - 较慢，准确度较高"
      • •"large-v2 - 最慢，准确度最高"
  2. •

    语言：音频是什么语言？

    • •选项：
      • •"自动检测 (Recommended)"
      • •"中文 (zh)"
      • •"英文 (en)"
      • •"日文 (ja)"
      • •"其他语言"
  3. •

    词级别对齐：是否需要词级别时间戳？

    • •选项：
      • •"是 - 精确到每个词的时间 (Recommended)"
      • •"否 - 只需要句子级别时间（更快）"
  4. •

    输出格式：输出什么格式？

    • •选项：
      • •"TXT - 纯文本带时间戳 (Recommended)"
      • •"SRT - 字幕格式"
      • •"VTT - Web 字幕格式"
      • •"JSON - 结构化数据（含词级别信息）"
  5. •

    输出路径：保存到哪里？

    • •建议默认：与输入文件同目录，文件名为 原文件名.txt（或对应格式）

Step 3: 执行转录脚本

使用 skill 目录下的 transcribe.py 脚本：

bash
uv run /path/to/skills/audio-transcribe/transcribe.py "INPUT_FILE" [OPTIONS]

参数说明：

  • •--model, -m: 模型大小 (tiny/base/small/medium/large-v2)
  • •--language, -l: 语言代码 (en/zh/ja/...)，不指定则自动检测
  • •--no-align: 跳过词级别对齐
  • •--no-vad: 禁用 VAD 过滤（如果转录有时间跳跃/遗漏，使用此选项）
  • •--output, -o: 输出文件路径
  • •--format, -f: 输出格式 (srt/vtt/txt/json)

示例：

bash
# 基础转录（自动检测语言）
uv run skills/audio-transcribe/transcribe.py "video.mp4" -o "video.txt"

# 中文转录，输出 SRT 字幕
uv run skills/audio-transcribe/transcribe.py "audio.mp3" -l zh -f srt -o "subtitles.srt"

# 快速转录，不做词对齐
uv run skills/audio-transcribe/transcribe.py "audio.wav" --no-align -o "transcript.txt"

# 使用更大模型，输出 JSON（含词级别时间戳）
uv run skills/audio-transcribe/transcribe.py "speech.mp3" -m medium -f json -o "result.json"

# 禁用 VAD 过滤（解决时间跳跃/遗漏问题）
uv run skills/audio-transcribe/transcribe.py "audio.mp3" --no-vad -o "transcript.txt"

Step 4: 展示结果

转录完成后：

  1. •告诉用户输出文件的完整路径
  2. •显示部分转录内容预览
  3. •报告总时长和段落数

输出格式说明

TXT 格式

code
[00:00:00.000 - 00:00:03.500] 这是第一句话
[00:00:03.500 - 00:00:07.200] 这是第二句话

SRT 格式

code
1
00:00:00,000 --> 00:00:03,500
这是第一句话

2
00:00:03,500 --> 00:00:07,200
这是第二句话

JSON 格式（含词级别）

json
[
  {
    "start": 0.0,
    "end": 3.5,
    "text": "这是第一句话",
    "words": [
      {"word": "这是", "start": 0.0, "end": 0.5, "score": 0.95},
      ...
    ]
  }
]

常见问题处理

首次运行较慢：

  • •WhisperX 需要下载模型文件，首次运行会比较慢
  • •后续运行会使用缓存的模型

内存不足：

  • •使用更小的模型（tiny 或 base）
  • •确保系统有足够的内存

识别准确度低：

  • •尝试使用更大的模型（medium 或 large-v2）
  • •明确指定语言而不是自动检测

示例交互

用户：帮我把这个视频转成文字

助手：

  1. •检查 uv ✓
  2. •询问视频文件路径
  3. •使用 AskUserQuestion 询问模型、语言、格式等
  4. •执行转录
  5. •展示结果预览和保存路径

交互风格

  • •使用简单友好的语言
  • •解释不同模型大小的区别
  • •如果遇到错误，提供清晰的解决方案
  • •转录成功后给予积极反馈