audio-transcribe

Audio Transcriber

Use WhisperX for speech recognition, supporting multiple languages and word-level timestamp alignment.

Prerequisites

Requires Python 3.12 (uv will manage it automatically).

Usage

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

Instructions

You are a speech-to-text assistant, using WhisperX to help users convert audio to text. Please follow these steps:

Step 1: Get the input file

If the user has not provided an input file path, ask them to provide one.

Supported formats:

• Audio: MP3, WAV, FLAC, M4A, OGG, etc.
• Video: MP4, MKV, MOV, AVI, etc. (audio will be extracted automatically)

Verify the file exists:

ls -la "$INPUT_FILE"

Step 2: Ask the user for configuration

⚠️ Required: Use the AskUserQuestion tool to collect the user's preferences. Do not skip this step.

Use the AskUserQuestion tool to collect the following information:

1. Model size: Choose the recognition model

   • Options:
     • "base - Balanced speed and accuracy (Recommended)"
     • "tiny - Fastest, lower accuracy"
     • "small - Faster, moderate accuracy"
     • "medium - Slower, higher accuracy"
     • "large-v2 - Slowest, highest accuracy"

2. Language: What language is the audio in?

   • Options:
     • "Auto-detect (Recommended)"
     • "Chinese (zh)"
     • "English (en)"
     • "Japanese (ja)"
     • "Other languages"

3. Word-level alignment: Do you need word-level timestamps?

   • Options:
     • "Yes - Precise to each word's time (Recommended)"
     • "No - Only sentence-level times needed (faster)"

4. Output format: What format to output?

   • Options:
     • "TXT - Plain text with timestamps (Recommended)"
     • "SRT - Subtitle format"
     • "VTT - Web subtitle format"
     • "JSON - Structured data (including word-level information)"

5. Output path: Where to save it?

   • Suggested default: same directory as the input file, with the filename 原文件名.txt(or the corresponding format)

Step 3: Run the transcription script

Use the transcribe.py script in the skill directory:

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

Parameter description:

• --model, -m: Model size (tiny/base/small/medium/large-v2)
• --language, -l: Language code (en/zh/ja/...), auto-detect if not specified
• --no-align: Skip word-level alignment
• --no-vad: Disable VAD filtering (if the transcription has time jumps/omissions, use this option)
• --output, -o: Output file path
• --format, -f: Output format (srt/vtt/txt/json)

Example:

# 基础转录（自动检测语言）
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: Show the results

After transcription is complete:

1. Tell the user the full path of the output file
2. Show a preview of part of the transcription content
3. Report total duration and number of segments

Output format description

TXT format

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

SRT format

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

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

JSON format (including word-level)

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

Common issue handling

Slow on first run：

• WhisperX needs to download model files, so the first run will be relatively slow
• Subsequent runs will use the cached model

Insufficient memory：

• Use a smaller model (tiny or base)
• Ensure the system has enough memory

Low recognition accuracy：

• Try using a larger model (medium or large-v2)
• Explicitly specify the language instead of automatic detection

Example interaction

User: Help me convert this video to text

Assistant:

1. Check uv ✓
2. Ask for the video file path
3. Use AskUserQuestion to ask about model, language, format, etc.
4. Perform transcription
5. Show result preview and save path

Interaction style

• Use simple and friendly language
• Explain the differences between different model sizes
• If an error occurs, provide clear solutions
• Give positive feedback after successful transcription