transcribe_qwen_asr_api.py ドキュメント

概要

ローカルの Qwen3-ASR vLLM サーバーを用いて、音声・動画ファイル（ WAV / MP3 / MP4 ）の文字起こしを行うスクリプトです。長いメディアファイルを ffmpeg を使って一定時間ごとのチャンク（WAVファイル）に分割し、OpenAI互換の音声認識APIエンドポイントに送信します。進捗を逐次保存するため、途中でのエラーや中断から再開する機能を備えています。本プログラムはユーティリティ・データ処理プログラムであるため、複雑な数学的理論に基づく計算は行いません。

依存関係

  • 非標準ライブラリ: コードからは確認できません（Python標準ライブラリのみを使用しています）。

  • 外部システム依存: コマンドラインツールとして ffmpeg および ffprobe がシステムの PATH に存在し、実行可能である必要があります。

入出力仕様

  • 入力ファイル

    • WAV, MP3, MP4 などの音声または動画ファイル。

  • 出力ファイル

    • 文字起こし結果テキスト（ .txt ）: マージされた最終的なテキストファイル。デフォルトでは入力ファイルの拡張子を .qwen.txt に変更した名前で保存されます。

    • セグメント情報 JSON（ .segments.json ）: 各チャンクの区間情報、テキスト、APIからの応答内容を含むファイル。

    • チェックポイント JSON（ .partial.json ）: 実行中の状態を逐次保存するファイル。完了時またはエラー発生時に作成され、再開処理に使用されます。

    • チャンクディレクトリ（ .chunks ）: --keep-wav オプションを指定した場合、分割された一時的な音声チャンクファイル（ .wav ）が保存されるディレクトリ。

オプション

  • input (位置引数): 入力ファイルのパス。

  • --api-base: API のベースURLを指定します（既定: http://192.168.27.18:8001/v1 ）。

  • --model: 使用するASRモデル名を指定します（既定: Qwen/Qwen3-ASR-1.7B ）。

  • --output: 出力テキストファイルのパスを指定します。省略時は入力名に基づく .qwen.txt ファイルが使用されます。

  • --chunk-seconds: 1チャンクあたりの音声長を秒単位で指定します（既定: 240 ）。

  • --overlap-seconds: 隣接するチャンク間のオーバーラップ（重なり）時間を秒単位で指定します（既定: 10 ）。

  • --timeout: 各APIリクエストのタイムアウト時間を秒単位で指定します（既定: 1800 ）。

  • --resume: 処理が中断された場合に、残っている .partial.json ファイルを読み込み、未完了のチャンクから文字起こしを再開します。

  • --keep-wav: APIに送信するために分割した一時的なWAVファイルを削除せず、出力先と同じ階層の .chunks ディレクトリに保持します。

動作原理

  1. ffprobe を用いて入力ファイルの総再生時間（秒）を取得します。

  2. 総再生時間を基に、 --chunk-seconds と --overlap-seconds の設定に従って音声を分割する開始時刻のリストを計算します。

  3. ffmpeg を使用して、対象区間をサンプリングレート 16000 Hz、モノラル、16-bit PCM の WAV形式で抽出し、一時ファイルとして保存します。

  4. 抽出したWAVファイルを、 urllib.request を用いて指定されたAPIエンドポイント（ /audio/transcriptions ）に multipart/form-data 形式で送信し、文字起こし結果を取得します。

  5. チャンクごとの処理が完了するたびに、結果を .partial.json に保存します。

  6. すべてのチャンクの処理が完了すると、前後のチャンクのテキストの末尾と先頭を比較し、オーバーラップによって生じた重複部分を除去しながら結合します。

  7. 結合された最終的なテキストを出力ファイルに書き出し、セグメント情報をJSONファイルに保存します。

実行例

# 基本的な実行（デフォルト設定を使用）
python transcribe_qwen_asr_api.py sample.mp4

# APIのURL、モデル名、出力先ファイル名を明示的に指定して実行
python transcribe_qwen_asr_api.py sample.wav --api-base http://127.0.0.1:8001/v1 --model my-asr-model --output result.txt

# 処理が中断した場合に、保存されたチェックポイントから再開する
python transcribe_qwen_asr_api.py sample.mp4 --resume

# チャンクの長さを120秒、重なりを5秒に変更し、分割されたWAVファイルを保存する
python transcribe_qwen_asr_api.py sample.mp3 --chunk-seconds 120 --overlap-seconds 5 --keep-wav