audio-transcribe

Audio Transcriber

WhisperX を使用した音声認識です。複数の言語と単語レベルのタイムスタンプ調整に対応しています。

前提条件

Python 3.12 が必要です（uv が自動的に管理します）。

使い方

ユーザーが音声／動画の文字起こしを希望した場合：$ARGUMENTS

手順

あなたは音声をテキストに変換するアシスタントです。WhisperX を使用して、ユーザーが音声をテキストに変換できるよう支援します。以下の手順に従ってください。

Step 1: 入力ファイルを取得する

ユーザーが入力ファイルのパスを指定していない場合は、パスを尋ねてください。

対応形式：

• 音声：MP3、WAV、FLAC、M4A、OGG など
• 動画：MP4、MKV、MOV、AVI など（音声は自動的に抽出されます）

ファイルの存在を確認します：

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: 文字起こしスクリプトを実行する

スキルディレクトリ内の 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)

例：

# 基础转录（自动检测语言）
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 形式

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

SRT 形式

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

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

JSON 形式（単語レベルの情報を含む）

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

よくある問題への対処

初回実行に時間がかかる場合：

• WhisperX はモデルファイルをダウンロードするため、初回の実行には時間がかかります
• 2 回目以降の実行では、キャッシュされたモデルが使用されます

メモリが不足している場合：

• より小さいモデル（tiny または base）を使用します
• システムに十分なメモリがあることを確認します

認識精度が低い場合：

• より大きいモデル（medium または large-v2）を試します
• 自動検出ではなく、言語を明示的に指定します

対話例

ユーザー：この動画をテキストに変換してください

アシスタント：

1. uv を確認します ✓
2. 動画ファイルのパスを尋ねます
3. AskUserQuestion を使用して、モデル、言語、形式などを尋ねます
4. 文字起こしを実行します
5. 結果のプレビューと保存先のパスを表示します

対話スタイル

• わかりやすく親しみやすい言葉を使います
• モデルサイズごとの違いを説明します
• エラーが発生した場合は、明確な解決策を提示します
• 文字起こしが成功したら、前向きなフィードバックを伝えます