audio-transcribe

音频转录器

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

前置条件

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

用法

当用户想要转录音频/视频时：$ARGUMENTS

说明

步骤 1：获取输入文件

如果用户尚未提供输入文件路径，请让他们提供。

支持的格式：

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

确认文件存在：

ls -la "$INPUT_FILE"

步骤 2：询问用户配置

警告：必须使用 AskUserQuestion 收集用户偏好。不要跳过此步骤。

使用 AskUserQuestion 收集以下信息：

1. 模型大小：选择识别模型

   • 选项：
     • "base - 速度和准确度均衡（推荐）"
     • "tiny - 速度最快，准确度较低"
     • "small - 速度较快，准确度适中"
     • "medium - 速度较慢，准确度较高"
     • "large-v2 - 速度最慢，准确度最高"

2. 语言：音频使用什么语言？

   • 选项：
     • "自动检测（推荐）"
     • "中文（zh）"
     • "英语（en）"
     • "日语（ja）"
     • "其他"

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

   • 选项：
     • "是 - 为每个词提供精确时间（推荐）"
     • "否 - 仅提供句子级时间（更快）"

4. 输出格式：要输出什么格式？

   • 选项：
     • "TXT - 带时间戳的纯文本（推荐）"
     • "SRT - 字幕格式"
     • "VTT - 网页字幕格式"
     • "JSON - 结构化数据（含词级信息）"

5. 输出路径：保存到哪里？

   • 默认：与输入文件相同的目录，文件名为 <original_name>.txt（或对应格式）

步骤 3：运行转录脚本

使用技能目录中的 transcribe.py 脚本：

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）

示例：

# Basic transcription (auto-detect language)
uv run skills/audio-transcribe/transcribe.py "video.mp4" -o "video.txt"

# Chinese transcription, output SRT subtitles
uv run skills/audio-transcribe/transcribe.py "audio.mp3" -l zh -f srt -o "subtitles.srt"

# Fast transcription, skip word alignment
uv run skills/audio-transcribe/transcribe.py "audio.wav" --no-align -o "transcript.txt"

# Use a larger model, output JSON (with word-level timestamps)
uv run skills/audio-transcribe/transcribe.py "speech.mp3" -m medium -f json -o "result.json"

# Disable VAD filtering (fix time jumps / missing segments)
uv run skills/audio-transcribe/transcribe.py "audio.mp3" --no-vad -o "transcript.txt"

步骤 4：展示结果

转录完成后：

1. 显示完整的输出文件路径
2. 展示转录内容的预览
3. 报告总时长和片段数

输出格式参考

TXT 格式

[00:00:00.000 - 00:00:03.500] This is the first sentence
[00:00:03.500 - 00:00:07.200] This is the second sentence

SRT 格式

1
00:00:00,000 --> 00:00:03,500
This is the first sentence

2
00:00:03,500 --> 00:00:07,200
This is the second sentence

JSON 格式（含词级信息）

[
  {
    "start": 0.0,
    "end": 3.5,
    "text": "This is the first sentence",
    "words": [
      {"word": "This", "start": 0.0, "end": 0.5, "score": 0.95},
      ...
    ]
  }
]

故障排除

首次运行较慢：

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

内存不足：

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

识别准确度较低：

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