transcribe_simple.py 技術ドキュメント

プログラムの動作

transcribe_simple.py は、指定された音声ファイルからテキストを文字起こしするためのPythonスクリプトです。主に、AIモデルであるWhisperを利用して音声認識を実行します。このプログラムは、OSの種類に応じて最適なWhisper実装（Windowsでは faster-whisper、Linux/macOSでは openai/whisper）を自動的に選択し、効率的な文字起こしを実現します。

主な機能は以下の通りです。

  • クロスプラットフォーム対応: Windows環境では推論速度に優れた faster-whisper を、LinuxおよびmacOS環境では openai/whisper を自動的に利用します。

  • デバイスの自動検出: 文字起こしに利用可能な計算デバイス（CUDA (NVIDIA GPU)、DirectML (Intel/AMD/NVIDIA GPU)、CPU）を自動的に検出し、最適なデバイスで処理を実行します。

  • 柔軟な入力: 単一の音声ファイルだけでなく、globパターンを使用して複数の音声ファイルを一括で処理できます。

  • 詳細な出力:

    • 時間範囲付きのテキストファイル（各セグメントの開始・終了時刻を含む）。

    • 純粋な文字起こしテキストファイル。

  • 幻覚（Hallucination）抑制機能 (faster-whisper 利用時):

    • 長時間音声で発生しやすい反復的な誤認識（幻覚）を検出・抑制するための高度なアルゴリズムを実装しています。

    • 圧縮率やトークン繰り返し回数に基づいて怪しいセグメントをスキップし、無限ループのような幻覚を防ぎます。

  • 進捗表示: faster-whisper 使用時には、セグメントごとに文字起こしの進捗をコンソールに表示します。

  • 設定可能なパラメータ: モデル名、言語、ビームサイズ、温度（temperature）などのWhisperモデルの動作を制御する様々なパラメータをコマンドライン引数で指定できます。

このプログラムは、特に長時間の講義や会議の音声などにおいて、高精度かつ安定した文字起こしを効率的に行うことを目的としています。

原理

transcribe_simple.py は、OpenAIが開発した大規模な音声認識モデルであるWhisperを基盤としています。Whisperは、多様な音声データとテキストデータで学習されたTransformerベースのエンコーダー・デコーダーモデルであり、多言語対応と高精度な文字起こしが特徴です。

プログラムは、実行されるOSによって異なるWhisper実装を利用し、それぞれ異なる最適化と機能を提供します。

1. faster-whisper (Windows環境)

  • 基盤: faster-whisper は、OpenAI Whisperモデルを CTranslate2 という高速推論エンジンで最適化したものです。これにより、特にGPUでの推論速度が向上します。

  • 量子化: compute_type パラメータを通じて、int8_float16 (CUDA GPU使用時) または int8 (CPU/DirectML使用時) の量子化を利用し、モデルのサイズを削減しつつ計算効率を高めます。

  • チャンク処理: 長時間の音声を効率的に処理するために、内部で音声を小さなチャンク（デフォルト30秒）に分割し、逐次的に文字起こしを行います。

  • 幻覚検出と抑制:

    • 圧縮率による検出: text_compression_ratio 関数は、入力テキストのgzip圧縮率を計算します。これはテキストが繰り返しパターンを含んでいる場合に圧縮率が高くなる性質を利用し、幻覚の兆候を捉えます。具体的には、生のバイト長を圧縮後のバイト長で割ることで圧縮率を求めます。 $\(\text{Compression Ratio} = \frac{\text{Length of Raw Text (bytes)}}{\text{Length of Compressed Text (bytes)}}\)$

    • トークン繰り返しによる検出: normalize_tokens 関数は、英数字や日本語の単語をトークンとして抽出し、looks_like_repetition_loop 関数内でこれらのトークンの出現頻度を分析します。特定のトークンが異常に多く繰り返されている場合、幻覚と判断します。

    • これらの検出ロジックは、--compression-ratio-threshold や --max-bad-segments などのパラメータと組み合わせて、幻覚が疑われるセグメントをスキップしたり、文字起こしを停止したりするために利用されます。

    • VAD (Voice Activity Detection): 音声区間検出フィルター vad_filter=True を使用し、無音区間をスキップして文字起こし対象を音声がある部分に限定することで、処理効率を高め、無駄な認識を減らします。

  • デバイス検出: CTranslate2 が提供する get_cuda_device_count() を利用してCUDAデバイスの有無を判断し、CUDAがあればGPU、なければCPUをデフォルトで利用します。

2. openai/whisper (Linux/macOS環境)

  • 基盤: PyTorch上で動作するOpenAIの公式Whisper実装です。

  • 処理: faster-whisper と異なり、本スクリプトではチャンク処理や高度な幻覚検出ロジックは明示的に実装されていません。model.transcribe メソッドが一括で音声を処理します。

  • condition_on_previous_text=False: 長時間音声における幻覚のリスクを軽減するため、前の認識結果を次の認識の文脈として利用しない設定を推奨しています。

  • デバイス検出: torch.cuda.is_available() を利用してCUDAデバイスの有無を判断し、CUDAがあればGPU、なければCPUをデフォルトで利用します。

3. 共通の原理

  • 言語判定: --lang オプションで言語を指定しない場合、Whisperモデルが音声データから自動的に言語を判定します。

  • ffprobe の利用: 入力音声ファイルの正確な再生時間 (duration) を取得するために ffprobe コマンドラインツールが利用されます。これは文字起こしの進捗表示やログ記録に役立ちます。

  • temperature パラメータ: テキスト生成の多様性を制御します。値を大きくするとより多様な候補からサンプリングされ、小さくすると最も確率の高い候補が選ばれやすくなります。複数の値をタプルで指定すると、複数のパスを試行して最適な結果を選択します。

  • beam_size パラメータ: ビームサーチの幅を決定します。値を大きくすると探索空間が広がり、より良い仮説が見つかる可能性がありますが、計算コストが増大します。

これらの仕組みにより、transcribe_simple.py はプラットフォームの特性を活かし、効率的かつ高品質な音声文字起こしを提供します。

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

transcribe_simple.py を実行するために、いくつかのPythonライブラリと外部ツールが必要です。

Pythonライブラリ

以下のライブラリは pip コマンドでインストールできます。

  1. torch:

    • PyTorchはAIモデルの演算基盤となるライブラリです。特にGPUを使用する場合は、CUDA対応版のインストールが必要です。

    • openai/whisper (Linux/macOS) で必須です。

    • インストールコマンド（CPU版）：

      pip install torch

    • インストールコマンド（CUDA版、システムに合ったバージョンを確認）：

      # 例: CUDA 11.8の場合
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

      最新の情報は PyTorch公式ウェブサイト を参照してください。

  2. faster-whisper:

    • Windows環境でより高速な文字起こしを行うために使用されます。

    • インストールコマンド：

      pip install faster-whisper

  3. openai-whisper:

    • LinuxおよびmacOS環境で標準のWhisper実装として使用されます。

    • インストールコマンド：

      pip install openai-whisper

    • 注意: faster-whisper と openai-whisper はOSによって自動的に選択されるため、通常は両方をインストールする必要はありませんが、両方のOSで利用する可能性がある場合は両方インストールしておくことを推奨します。

外部ツール

  1. ffmpeg および ffprobe:

    • 音声ファイルの処理や、再生時間を取得するために必要です。これらのツールはPythonライブラリではなく、システムにインストールされた実行可能ファイルとして利用されます。

    • Windows: FFmpeg公式サイト からダウンロードし、実行ファイル（ffmpeg.exe, ffprobe.exe）をシステムのPATH環境変数に追加してください。

    • Linux (Ubuntu/Debian系):

      sudo apt update
sudo apt install ffmpeg

    • macOS (Homebrewを使用):

      brew install ffmpeg

必要な入力ファイル

プログラムが受け付ける入力ファイルは以下の通りです。

  • 音声ファイル:

    • プログラムは、音声データを含むファイルを入力として受け取ります。対応するフォーマットはWhisperモデルおよび ffmpeg がサポートするものに依存しますが、一般的には以下の形式が利用可能です。

      • .mp3

      • .wav

      • .m4a

      • .flac

      • .ogg

      • その他、ffmpeg が読み取れる形式

  • ファイル名とパス:

    • コマンドライン引数 infile として、単一のファイルパス、または複数のファイルにマッチするglobパターン（例: "audio/*.mp3"）を指定できます。

    • ファイルはプログラムを実行する環境からアクセス可能な場所に存在する必要があります。

入力ファイルの具体的なデータ構造は特にありません。音声データが格納されている標準的なオーディオファイルであれば問題ありません。

生成される出力ファイル

transcribe_simple.py は、文字起こしの結果として以下の2種類のテキストファイルを生成します。

  1. 時間範囲付きテキストファイル (--outfile1 で指定)

    • ファイル名:

      • --outfile1 引数で指定がない場合、入力ファイル名（拡張子を除く）に -time.txt が付加されます。 例: input.mp3 -> input-time.txt

      • --outfile1 で明示的にファイル名を指定した場合はその名前が使用されます。

    • 内容:

      • 各行が1つの文字起こしセグメントに対応し、そのセグメントの開始時刻と終了時刻が [開始秒 - 終了秒] の形式でテキストの前に付加されます。

      • 例:

        [0.00 - 4.56] こんにちは、これはテストです。
[4.56 - 8.12] 日本語の音声認識の例です。
[8.12 - 12.00] 幻覚検出機能も備わっています。

      • faster-whisper 使用時に幻覚が検出され、スキップされたセグメントがある場合、その情報もこのファイルに記録されます。 例:

        [120.50 - 125.10] [SKIPPED: probable repetition loop: token 'the' repeated 15/20 times]

  2. 純粋なテキストファイル (--outfile2 で指定)

    • ファイル名:

      • --outfile2 引数で指定がない場合、入力ファイル名（拡張子を除く）に .txt が付加されます。 例: input.mp3 -> input.txt

      • --outfile2 で明示的にファイル名を指定した場合はその名前が使用されます。

    • 内容:

      • 文字起こしされたすべてのテキストが、時間情報なしで連結された形式で保存されます。

      • セグメント間の改行は基本的に含まれません。

      • 例:

        こんにちは、これはテストです。日本語の音声認識の例です。幻覚検出機能も備わっています。

両ファイルともUTF-8エンコーディングで保存されます。

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

transcribe_simple.py は、コマンドライン引数を使用して動作をカスタマイズします。

基本的な実行形式:

python transcribe_simple.py <infile> [オプション]

利用可能な引数:

  • infile (必須):

    • 入力音声ファイル名。globパターン（例: "audio/*.mp3"）を使用して複数のファイルを指定できます。

  • --outfile1 <ファイル名>:

    • 時間範囲付き出力テキストファイルの名前。省略した場合、入力ファイル名から自動生成されます（例: input.mp3 -> input-time.txt）。

  • --outfile2 <ファイル名>:

    • 純粋なテキスト出力ファイルの名前。省略した場合、入力ファイル名から自動生成されます（例: input.mp3 -> input.txt）。

  • -m, --model <モデル名> (デフォルト: base):

    • 使用するWhisperモデルのサイズ。例: tiny, base, small, medium, large, large-v2, large-v3。

    • 英語専用モデル（例: base.en）も利用可能です。

  • -d, --device <デバイス名> (デフォルト: "" (自動判定)):

    • 文字起こしに使用するデバイスを指定します。

    • cuda: NVIDIA GPUを使用します。

    • dml: DirectML (Windows上のIntel/AMD/NVIDIA GPU) を使用します（faster-whisper のみ）。

    • cpu: CPUを使用します。

    • 空文字を指定すると、利用可能なデバイスを自動で検出します。

  • -l, --lang <言語コード> (デフォルト: ja):

    • 文字起こしに使用する言語の2文字ISO 639-1コード（例: en, ja, zh）。

    • 空文字を指定すると、Whisperが自動的に言語を判定します。

  • --pause <0|1> (デフォルト: 0):

    • プログラム終了時にEnterキー入力を要求するかどうか。1 で有効、0 で無効。バッチ処理などで自動終了させたい場合に 0 を指定します。

faster-whisper 向けの安定化パラメータ (Windowsでのみ有効)

これらのパラメータは faster-whisper が内部的に持つ機能を制御し、特に長時間の音声における文字起こし品質と安定性を向上させます。openai/whisper ではこれらの引数は無視されます。

  • --beam-size <整数> (デフォルト: 5):

    • ビームサーチの幅。探索する仮説の数を増やし、より良い結果を見つける可能性を高めますが、処理時間は増加します。

  • --chunk-length <秒> (デフォルト: 30):

    • faster-whisper が音声を分割して処理する内部チャンクの長さ（秒単位）。

  • --temperature <値> (デフォルト: "0,0.2,0.4,0.6"):

    • サンプリングの温度。0 は決定論的、大きな値は多様な結果を生成します。

    • 単一の浮動小数点数（例: "0"）またはカンマ区切りの浮動小数点数リスト（例: "0,0.2,0.4,0.6"）を指定できます。リストの場合、モデルは各温度で文字起こしを試み、最適なものを選択します。

  • --condition-on-previous-text <0|1> (デフォルト: 0):

    • 前の認識結果を次のチャンクの文脈として利用するかどうか。

    • 1 は利用、0 は利用しない。長時間の音声では幻覚のリスクを減らすため 0 が推奨されます。

  • --compression-ratio-threshold <浮動小数点数> (デフォルト: 2.4):

    • 反復テキスト検出用の圧縮率のしきい値。これを超える圧縮率のセグメントは幻覚とみなされる可能性があります。

  • --log-prob-threshold <浮動小数点数> (デフォルト: -1.0):

    • 低信頼度デコードを検出するための対数確率のしきい値。

  • --no-speech-threshold <浮動小数点数> (デフォルト: 0.6):

    • 無音と判定するためのしきい値。この値より小さいスコアのセグメントは無音とみなされスキップされる可能性があります。

  • --repetition-penalty <浮動小数点数> (デフォルト: 1.05):

    • 反復的なテキスト生成を抑制するためのペナルティ値。値が大きいほど抑制効果が高まります。

  • --no-repeat-ngram-size <整数> (デフォルト: 3):

    • 指定したサイズのn-gramが繰り返されるのを抑制します。0 で無効化します。

  • --max-bad-segments <整数> (デフォルト: 3):

    • 反復幻覚らしいセグメントが連続して検出された場合、文字起こしを停止する回数。無限ループを防ぐためのセーフガードです。

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

例1: 基本的な日本語音声ファイルの文字起こし

sample.wav という日本語の音声ファイルを base モデルで文字起こしします。出力ファイル名は自動で生成されます。

python transcribe_simple.py sample.wav -m base -l ja

実行結果の説明: このコマンドを実行すると、sample-time.txt と sample.txt の2つのファイルが生成されます。

  • sample-time.txt の内容（例）：

    [0.00 - 3.50] こんにちは、これは音声認識のテストです。
[3.50 - 7.80] プログラムは正常に動作しています。

  • sample.txt の内容（例）：

    こんにちは、これは音声認識のテストです。プログラムは正常に動作しています。

また、コンソールには文字起こしの進捗と最終的なテキストが表示されます。

例2: 複数の英語音声ファイルを large モデルで文字起こし (faster-whisper の詳細設定を含む)

lectures/ ディレクトリ内のすべての .mp3 ファイルを large モデルで英語に文字起こしし、faster-whisper の安定化パラメータを適用します。出力ファイル名をカスタムで指定します。

python transcribe_simple.py "lectures/*.mp3" \
    --outfile1 all_lectures_timed.txt \
    --outfile2 all_lectures_full.txt \
    -m large-v3 \
    -l en \
    -d cuda \
    --beam-size 8 \
    --temperature "0.0,0.5" \
    --condition-on-previous-text 0 \
    --repetition-penalty 1.1 \
    --max-bad-segments 5

実行結果の説明: この例では、lectures/ 以下の複数のMP3ファイルを対象にしています。

  • -m large-v3: 最も高精度な large-v3 モデルを使用します。

  • -l en: 言語を英語に指定します。

  • -d cuda: CUDA対応GPUが利用可能であれば、それを使用するように明示的に指定します。

  • --beam-size 8: ビームサーチの幅を広げ、より網羅的に探索することで精度向上を図ります。

  • --temperature "0.0,0.5": サンプリング温度 0.0 (決定論的) と 0.5 (やや多様性あり) の両方で試行し、より良い結果を選択します。

  • --condition-on-previous-text 0: 長時間音声でよく発生する幻覚を防ぐため、前のテキストに依存しない設定にします。

  • --repetition-penalty 1.1: 繰り返し表現を抑制するペナルティをやや強く設定します。

  • --max-bad-segments 5: 幻覚らしいセグメントが5回連続したら処理を停止し、無限ループを回避します。

出力は all_lectures_timed.txt と all_lectures_full.txt に結合された形で保存されます。faster-whisper を使用するWindows環境では、文字起こしの進行中に各セグメントの時刻とテキストがリアルタイムでコンソールに表示され、進捗が確認できます。幻覚が検出された場合は警告メッセージが表示されます。

例3: max-bad-segments による幻覚停止のシミュレーション

（この例は、実際の音声ファイルではなく、機能の説明です。） 仮に、非常に品質の低い音声や、モデルが混乱しやすい特定のパターンを含む音声ファイルを処理しているとします。スクリプトが反復幻覚を検出した場合、--max-bad-segments で指定した回数を超えると、処理を中断します。

python transcribe_simple.py problematic_audio.mp3 \
    -m base \
    --max-bad-segments 3

実行結果の説明: 文字起こし中に、looks_like_repetition_loop 関数によって反復幻覚が3回連続して検出された場合、プログラムは以下のような警告メッセージとともに文字起こしを中断します。

[WARN] skipped probable repetition loop at 00:02:15.3 - 00:02:20.1 ( 45.12%): text compression ratio 3.52 >= 2.40
       preview: the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the the
[WARN] skipped probable repetition loop at 00:02:20.1 - 00:02:24.9 ( 46.50%): token 'a' repeated 25/30 times
       preview: a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
[WARN] skipped probable repetition loop at 00:02:24.9 - 00:02:29.8 ( 47.88%): text compression ratio 4.10 >= 2.40
       preview: and and and and and and and and and and and and and and and and and and and and and and and and and and and and and and and and and
[WARN] 3 suspicious segments were detected. Stopping transcription to avoid a long hallucination tail.

この機能は、長時間の音声ファイルでモデルが無限に同じ内容を生成し続ける、いわゆる「幻覚ループ」に陥るのを防ぎ、リソースの無駄遣いを避けるために重要です。