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 - Web 字幕形式"
     • "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 はモデルファイルをダウンロードする必要があるため、初回は時間がかかります
• 2 回目以降はキャッシュされたモデルを使用します

メモリ不足の場合：

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

認識精度が低い場合：

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