transcribe2.py Documentation

このドキュメントは、Python言語で記述された transcribe2.py プログラムの技術的な詳細について説明します。


プログラムの動作

transcribe2.py は、Qwen3-ASR API、ローカルのQwen3-ASR、またはWhisperといった複数のASR (Automatic Speech Recognition) バックエンドを統合したコマンドラインインターフェースです。このプログラムの主な目的は、音声または動画ファイルを入力として受け取り、その内容をテキストに文字起こしすることです。

主な機能:

  • 入力ファイルの分割と処理: 長い音声・動画ファイルを、指定された時間(チャンク秒数)に分割し、重複区間(オーバーラップ秒数)を設けて効率的に処理します。これにより、大規模な入力ファイルでも安定して文字起こしが可能です。

  • 処理の再開 (Resume): 文字起こし処理が中断された場合(例: エラー、ユーザーによる中断)、中断時点から処理を再開できるチェックポイント機能を備えています。

  • 多様なASRバックエンドのサポート: Qwen3-ASR API、ローカルQwen3-ASRモデル、Whisperモデルなど、複数のASRエンジンを選択して利用できます。ASR固有の処理は tkasr_*.py というモジュール群に分離されており、このプログラムはそれらを統合する役割を担います。

  • LLM (大規模言語モデル) による校正: 初期文字起こし結果に対して、LLMを使用して誤り訂正や自然な文章への修正を行うことが可能です。

  • 詳細な出力: 文字起こし結果のテキストファイルに加えて、各セグメントの時間情報や言語検出結果を含むJSON形式のメタデータファイルも生成します。

解決する課題:

  • 長時間の音声・動画ファイルに対する文字起こしの手間とエラー率を削減します。

  • 異なるASRバックエンドを統一されたインターフェースで利用できるようにし、バックエンドごとの異なる操作を吸収します。

  • 機械的な文字起こし結果の品質を、LLMの能力を活用して向上させます。

  • 中断された文字起こし作業の効率的な復旧を可能にし、ユーザーの手間を軽減します。


原理

transcribe2.py は、以下の主要な原理とアルゴリズムに基づいて動作します。

  1. 音声ストリームのチャンク処理: 入力音声・動画ファイルは、--chunk-seconds 引数で指定された秒数で分割されます。この際、--overlap-seconds 引数で指定された秒数だけ前後のチャンクと重複する区間が設けられます。これにより、チャンク境界での文脈の途切れによるASR品質の低下を防ぎます。 チャンクの開始時刻 (\(T_i\)) は、以下の式で計算されます。

    \[ S = C - O \]
    \[ T_i = i \cdot S \]

    ここで、\(C\) は chunk_seconds、\(O\) は overlap_seconds、\(S\) はステップ秒数、\(i\) はチャンクインデックス(\(0, 1, 2, \dots\))です。

  2. 遅延ロードによるASRバックエンドの動的選択: --backend 引数で指定されたASRバックエンド(例: qwen-api, qwen-local, whisper)に対応するPythonモジュール(tkasr_qwen_api, tkasr_qwen_local, tkasr_whisper など)は、importlib.import_module を用いて実行時に動的にロードされます。これにより、必要なバックエンドのみがメモリに読み込まれ、リソースの効率的な利用とプログラムの柔軟性が確保されます。

  3. チェックポイントと処理の再開: 各チャンクの文字起こしが完了するたびに、その結果は中間ファイル(例: output.asr.txt.partial.json)にJSON形式で保存されます。このチェックポイントファイルには、完了したセグメントのリスト、入力ファイル情報、ASR設定などが含まれます。 --resume オプションが指定された場合、プログラムはこのチェックポイントファイルを読み込み、保存されている最後のチャンク以降から処理を再開します。これにより、長時間の処理が中断された場合でも、最初からやり直すことなく作業を継続できます。

  4. LLMによる文字起こし結果の校正: ASRバックエンドからの初期文字起こし結果は、そのまま出力されるだけでなく、必要に応じてLLMによる校正プロセスにかけられます。LLMへの入力は、make_boundary_text 関数によって、ASRチャンクの開始・終了時刻や重複区間が明示された特別なフォーマットで生成されます。このフォーマットは、LLMが文字起こしエラーを特定し、より正確で自然なテキストに修正するための文脈情報を提供します。 校正が完了すると、remove_asr_markers 関数によって、LLM入力用の特殊なマーカーは最終的なテキストから除去されます。

  5. FFmpegによる音声抽出: 入力が動画ファイルの場合や、特定の区間の音声抽出が必要な場合は、ffmpeg コマンドラインツールが利用されます。tkasr_common.extract_wav 関数が ffmpeg を呼び出し、指定された開始時刻と長さで音声ストリームを抽出し、一時的なWAVファイルとして保存します。


必要な非標準ライブラリとインストール方法

transcribe2.py は、内部的に複数の非標準ライブラリおよびツールに依存しています。

必須ツール:

  • FFmpeg: 音声・動画ファイルの処理(フォーマット変換、音声抽出、時間取得など)に必要です。

    • インストール方法: OSに応じた方法でFFmpegをインストールしてください。例えば、Ubuntu/Debian系であれば sudo apt install ffmpeg、macOSであれば brew install ffmpeg です。インストール後、ffmpeg および ffprobe コマンドがパスから実行できることを確認してください。または、--ffmpeg-dir 引数でFFmpegの実行ファイルがあるディレクトリを指定できます。

Pythonライブラリ:

transcribe2.py は、同じプロジェクト内の tkasr_common や tkasr_llm、そして各ASRバックエンドモジュール (tkasr_qwen_api, tkasr_qwen_local, tkasr_whisper) に依存しています。これらのモジュール自体が、さらに特定のライブラリに依存します。

一般的なインストール手順は以下のようになります。

  1. tkasr プロジェクトのインストール: transcribe2.py が属する tkasr プロジェクト全体(tkasr_common.py などのファイルを含む)が、Pythonの環境変数 PYTHONPATH に含まれるか、transcribe2.py と同じディレクトリ、またはパッケージとしてインストールされている必要があります。

  2. 共通の依存ライブラリ: ASRバックエンドやLLM校正機能を利用するために、以下の基本的なライブラリが一般的に必要となる場合があります。

    pip install "litellm>=1.36.0" "tiktoken>=0.6.0"
    
  3. ASRバックエンド固有の依存ライブラリ: 選択する --backend に応じて、追加のライブラリが必要になります。

    • Qwen3-ASR API (--backend qwen-api): APIクライアントライブラリや requests などが必要になる場合がありますが、これは tkasr_qwen_api モジュールに依存します。通常、pip install requests などで対応できます。

    • ローカルQwen3-ASR (--backend qwen-local): 大規模モデルの実行には、PyTorchとHugging Face transformers ライブラリが必須です。GPUを使用する場合はCUDA対応のPyTorchをインストールしてください。

      pip install "torch>=2.1.0" "transformers>=4.38.0" "accelerate>=0.28.0" "sentencepiece>=0.1.99" "optimum>=1.18.0"
      
    • Whisper (--backend whisper): OpenAIのWhisperモデルを使用します。

      pip install "openai-whisper>=20230918" "ffmpeg-python>=0.2.0"
      

      ffmpeg-python はPythonからFFmpegを操作するためのラッパーですが、tkasr_common が直接FFmpegコマンドを呼び出す場合は不要かもしれません。

推奨されるインストール手順: まず、tkasr プロジェクトのルートディレクトリに移動し、requirements.txt のようなファイルが存在する場合はそれに従ってインストールするのが最も確実です。存在しない場合は、必要なバックエンドに対応する上記コマンドを実行してください。


必要な入力ファイル

transcribe2.py が処理を開始するために必要とする主な入力ファイルは以下の通りです。

  1. 音声・動画ファイル:

    • 引数: input (必須)

    • 形式: FFmpegがサポートするあらゆる音声・動画形式(例: .mp3, .wav, .m4a, .mp4, .mov, .avi など)。

    • 説明: 文字起こしを行いたいメディアファイルです。パスは相対パス、絶対パスのどちらでも指定可能で、*.mp4 のようにglobパターンを使用して複数のファイルを一度に指定することもできます。

  2. LLM設定ファイル:

    • 引数: --llm-config (オプション、LLM校正を有効にする場合)

    • 形式: 環境変数ファイル(例: .env)またはJSON/YAMLファイル。

    • 説明: LLM校正機能を使用する場合、LLMプロバイダーのAPIキーやエンドポイントなどの設定を記述したファイルです。デフォルトは ai.env です。


生成される出力ファイル

transcribe2.py は、文字起こしプロセスが完了すると、以下のファイルを生成します。

  1. 文字起こしテキストファイル:

    • ファイル名: <入力ファイル名>.asr.txt (例: audio.mp3 -> audio.asr.txt)

    • 内容: 最終的な文字起こし結果がプレーンテキスト形式で保存されます。LLM校正が有効な場合、校正後のテキストが出力されます。

  2. 詳細な結果情報ファイル (JSON):

    • ファイル名: <入力ファイル名>.asr.json (例: audio.mp3 -> audio.asr.json)

    • 内容: 文字起こしに関する詳細なメタデータと結果がJSON形式で保存されます。これには以下の情報が含まれます。

      • source: 入力ファイルのパス。

      • duration_seconds: 入力音声の総時間。

      • backend: 使用されたASRバックエンドの名前。

      • chunk_seconds, overlap_seconds: チャンク分割設定。

      • output: 出力テキストファイルのパス。

      • segments: 各ASRセグメントの詳細なリスト。各セグメントには、開始時刻 (start)、終了時刻 (end)、文字起こしテキスト (text)、検出された言語 (language)、処理にかかった時間 (elapsed_seconds)、ASRバックエンドからの追加メタデータ (metadata) などが含まれます。

  3. チェックポイントファイル (JSON):

    • ファイル名: <入力ファイル名>.asr.txt.partial.json (例: audio.mp3 -> audio.asr.txt.partial.json)

    • 内容: 処理中のチャンクごとの文字起こし結果が逐次保存される一時ファイルです。プログラムが中断した場合の再開 (--resume) に使用されます。文字起こしが完全に成功すると、このファイルは削除されます。


コマンドラインでの使用例 (Usage)

transcribe2.py は、コマンドライン引数を使用して動作を制御します。

python transcribe2.py <input> [OPTIONS]

主要な引数:

  • input (必須): 文字起こしを行う音声・動画ファイルのパス。globパターン(例: *.mp4)も使用可能です。

  • --backend {qwen-api,qwen-local,whisper}: 使用するASRバックエンドを指定します。

    • qwen-api: Qwen3-ASR APIを使用。

    • qwen-local: ローカルでQwen3-ASRモデルを使用。

    • whisper: Whisperモデルを使用。

    • デフォルト: qwen-api

  • -m, --model: ASRバックエンドで使用するモデルの名前またはパス。

    • デフォルト: Qwen/Qwen3-ASR-1.7B (Qwenの場合)

  • -l, --lang: 文字起こしする言語を指定。ja (Japanese), en (English), zh (Chinese), ko (Korean) の短縮形が LANGUAGE_NAMES で定義されています。auto を指定すると自動検出されます。

    • デフォルト: ja

  • --output: 出力ファイルのベースパスを指定します。指定しない場合、入力ファイルと同じディレクトリに <入力ファイル名>.asr.txt および .asr.json が生成されます。複数入力時は --output は指定できません。

  • --ffmpeg-dir: FFmpegとFFprobeの実行ファイルが格納されているディレクトリのパス。これらがシステムパスにない場合に指定します。

  • --chunk-seconds: 音声ファイルを分割するチャンクの秒数。

    • デフォルト: 240

  • --overlap-seconds: チャンク間の重複秒数。

    • デフォルト: 10

  • --resume: 中断された文字起こし処理を再開します。前回のチェックポイントファイル(.partial.json)を読み込みます。

  • --context, --prompt: ASRまたはLLM校正に与える初期プロンプトまたは文脈情報。

  • --no-correct: LLMによる文字起こし結果の校正を無効にします。

Qwen ASR API 関連 (--backend qwen-api 時):

  • --api-base: Qwen ASR APIのエンドポイントURL。

  • --timeout: APIリクエストのタイムアウト秒数。

ローカル Qwen3-ASR 関連 (--backend qwen-local 時):

  • -d, --device: 推論に使用するデバイス(例: cuda, cpu, auto)。

  • --dtype: モデルのデータ型(例: bfloat16, float16, float32, auto)。

  • --timestamps: タイムスタンプを生成するかどうか(0 または 1)。

  • --aligner: アライナーモデルのパス。

  • --attention: アテンション機構の種類(例: sdpa, eager, flash_attention_2, auto)。

Whisper 関連 (--backend whisper 時):

  • --beam-size: ビームサーチのビームサイズ。

  • --temperature: サンプリングの温度。カンマ区切りで複数の値を指定可能。

  • --compression-ratio-threshold: 無音区間の検出閾値。

  • --log-prob-threshold: ログ確率の閾値。

  • --no-speech-threshold: 無音検出の閾値。

LLM校正関連 (LLM校正を有効にする場合):

  • --llm-config: LLM設定ファイルのパス。

  • --llm-provider: LLMプロバイダー(例: lmstudio, openai)。

  • --llm-model: LLM校正に使用するモデル。

  • --llm-max-tokens: LLMへの入力の最大トークン数。

  • --correction-chars: LLM校正に渡すテキストの最大文字数。


コマンドラインでの具体的な使用例

ここでは、transcribe2.py の具体的な使用例をいくつか示します。sample.mp4 という動画ファイルがあると仮定します。

例1: Qwen ASR API を使用した基本的な文字起こし

動画ファイル sample.mp4 をQwen ASR APIを使用して文字起こしし、日本語で出力します。

python transcribe2.py sample.mp4 --backend qwen-api --lang ja

実行結果の説明:

実行中に、各チャンクの処理状況と文字起こしされたテキストの冒頭部分がコンソールに表示されます。 処理が完了すると、以下の2つのファイルが sample.mp4 と同じディレクトリに生成されます。

  • sample.asr.txt:

    これはQwen ASR APIを使って文字起こしされた日本語のテキストです。
    動画の内容がここに続けて出力されます。
    ...
    

    (動画内の音声がテキストに変換されたもの)

  • sample.asr.json:

    {
        "source": "/path/to/sample.mp4",
        "duration_seconds": 120.5,
        "backend": "Qwen ASR API (Qwen/Qwen3-ASR-1.7B)",
        "chunk_seconds": 240.0,
        "overlap_seconds": 10.0,
        "output": "/path/to/sample.asr.txt",
        "segments": [
            {
                "index": 0,
                "start": 0.0,
                "end": 240.0,
                "text": "これはQwen ASR APIを使って文字起こしされた日本語のテキストです。",
                "language": "ja",
                "elapsed_seconds": 15.2,
                "metadata": {},
                "asr_segments": [
                    {"start": 0.0, "end": 5.0, "text": "これはQwen ASR APIを使って"},
                    {"start": 5.1, "end": 10.0, "text": "文字起こしされた日本語のテキストです。"}
                ]
            },
            // ... 他のチャンクのセグメントが続く
        ]
    }
    

    (文字起こし結果の詳細なJSONデータ)

例2: ローカルのWhisperモデルを使用し、LLM校正を無効にする

動画ファイル video/*.mp4 (video ディレクトリ内のすべてのMP4ファイル)をローカルのWhisper large-v2 モデルで文字起こしし、LLMによる校正は行いません。

python transcribe2.py "video/*.mp4" --backend whisper --model large-v2 --lang en --no-correct

実行結果の説明:

指定された video ディレクトリ内のすべてのMP4ファイルが個別に処理されます。例えば video/meeting.mp4 と video/lecture.mp4 が存在する場合、meeting.asr.txt, meeting.asr.json, lecture.asr.txt, lecture.asr.json が生成されます。--no-correct が指定されているため、出力テキストはASRバックエンドから直接得られた生の結果となります。

例3: 中断された文字起こしを再開する

以前に実行した文字起こしが途中で中断され、sample.asr.txt.partial.json が存在する場合、このコマンドで処理を再開できます。

python transcribe2.py sample.mp4 --backend qwen-api --lang ja --resume

実行結果の説明:

プログラムはまず sample.asr.txt.partial.json ファイルを読み込み、既に完了しているチャンクの数を確認します。そして、「再開: X チャンク完了」のようなメッセージを表示し、残りのチャンクから文字起こしを続行します。全てのチャンクが完了すると、sample.asr.txt と sample.asr.json が更新または新規作成され、sample.asr.txt.partial.json は削除されます。

例4: LLM校正を有効にし、カスタムプロンプトと設定ファイルを使用する

Qwenローカルモデルで文字起こしを行い、カスタムのプロンプトを与え、LLM校正を ai.env 設定ファイルと lmstudio プロバイダー、gpt-oss-20b モデルで行います。

python transcribe2.py sample.mp4 \
    --backend qwen-local \
    --model Qwen/Qwen3-ASR-1.7B \
    --lang ja \
    --context "この音声は日本の会議の記録です。専門用語や固有名詞を正確にしてください。" \
    --llm-config ai.env \
    --llm-provider lmstudio \
    --llm-model openai/gpt-oss-20b

実行結果の説明:

このコマンドでは、Qwenローカルモデルが sample.mp4 を文字起こしします。その後、tkasr_llm モジュールが ai.env に定義された設定(例えばAPIキーやエンドポイントなど)を使用して lmstudio プロバイダー経由で openai/gpt-oss-20b モデルを呼び出します。ASR結果に加えて --context で与えられた情報もLLMに渡され、より文脈に即した修正が期待できます。最終的な sample.asr.txt には、LLMによって校正されたテキストが出力されます。