transcribe_simple.py 技術ドキュメント

プログラムの動作

transcribe_simple.py は、指定された音声ファイル（または複数の音声ファイル）を OpenAI Whisper モデルを使用して文字起こしするPythonプログラムです。主に以下の機能を提供します。

  • 音声ファイルの文字起こし: 入力された音声ファイルを指定されたWhisperモデルと言語設定で文字起こしします。

  • GPUの利用確認: プログラム開始時に、PyTorchがGPUを利用可能か、その場合はどのGPUが利用されているかを表示します。

  • 複数の出力形式:

    • 文字起こしされたテキストと、各セグメントの開始・終了時間を含むファイルを生成します。

    • 純粋な文字起こしテキストのみを含むファイルを生成します。

  • 柔軟な設定: 使用するWhisperモデル、デバイス（GPU/CPU）、文字起こし言語、出力ファイル名をコマンドライン引数で細かく指定できます。

  • ワイルドカード対応: 入力ファイル名にワイルドカード（*など）を使用することで、複数のファイルを一度に処理できます。

このプログラムは、音声コンテンツをテキストデータとして利用したいユーザー（例: 会議の議事録作成、動画コンテンツの字幕作成、音声データのテキスト検索化）のために、簡潔なインターフェースで高品質な文字起こし機能を提供することを目的としています。

原理

transcribe_simple.py は、OpenAIが開発した汎用音声認識モデルである Whisper を利用しています。Whisperは、大量の多言語音声データと多様なタスクで学習された強力なニューラルネットワークモデルです。

  1. モデルのロード: プログラムは whisper.load_model() 関数を使用して、指定されたモデル名（例: base, small, medium, large）に基づいてWhisperモデルをメモリにロードします。この際、GPUが利用可能で指定がなければGPU（CUDA）を優先的に使用し、高速な推論を実現します。--device オプションで cpu を明示的に指定することも可能です。

  2. 音声の前処理: model.transcribe() メソッドが呼び出されると、まず入力音声ファイルが読み込まれ、Whisperモデルが処理できる形式（通常は16kHzのモノラルPCMオーディオ）に内部で変換されます。その後、モデルの入力要件に合わせて音響特徴量（例えばメルスペクトログラム）が計算されます。

  3. 文字起こし（推論）: Whisperモデルは、内部的にはEncoder-Decoderアーキテクチャを持つTransformerベースのニューラルネットワークです。

    • エンコーダ: 前処理された音響特徴量を入力として受け取り、音響情報から高次元の表現（特徴ベクトル）を生成します。

    • デコーダ: エンコーダからの情報を受け取り、過去に生成されたテキストのトークンと組み合わせて、次のテキストトークンを予測します。このプロセスを繰り返すことで、最終的なテキストシーケンスが生成されます。

    このモデルは、音声からテキストへの変換だけでなく、言語識別やセグメント化（音声を意味のある短い区間に分割すること）、各セグメントの開始・終了時間の推定も同時に行います。これは、モデルが多岐にわたるタスクで共同学習されているためです。

  4. 結果の出力: model.transcribe() メソッドは、文字起こしされた全文テキスト、および各セグメント（時間範囲と対応するテキスト）を含む辞書形式の結果を返します。プログラムはこの結果を解析し、2種類の指定された出力ファイルに整形して書き込みます。

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

transcribe_simple.py を実行するためには、以下の非標準ライブラリが必要です。

  • openai-whisper: OpenAI WhisperモデルのPython実装。

  • torch: PyTorchというオープンソースの機械学習フレームワーク。Whisperの実行基盤となります。

  • ffmpeg (必須ではありませんが推奨): Whisperは内部で ffmpeg を使用して様々な音声ファイルを処理します。システムにインストールされていない場合、一部のファイル形式でエラーが発生する可能性があります。

インストールは pip コマンドを使用して行います。

pip install openai-whisper torch

ffmpeg はOSのパッケージマネージャーを使用してインストールするか、公式サイトからダウンロードしてください。

例 (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

例 (macOS with Homebrew):

brew install ffmpeg

必要な入力ファイル

プログラムは以下の入力ファイルを必要とします。

  • 入力音声ファイル: 文字起こしの対象となる音声ファイルです。

    • ファイル形式: Whisperは ffmpeg がサポートする多くの音声および動画ファイル形式に対応しています（例: .mp3, .wav, .flac, .m4a, .mp4 など）。

    • データ構造: 特殊なデータ構造は不要で、一般的な音声ファイルであれば問題ありません。

    • ファイル名: コマンドライン引数 infile で指定します。ワイルドカード（例: audio_*.mp3）を使用して複数のファイルを指定することも可能です。

生成される出力ファイル

プログラムは、文字起こしの結果として以下の2種類のテキストファイルを生成します。

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

    • ファイル名:

      • --outfile1 オプションで指定がない場合: 入力ファイル名に -time.txt を付加したもの（例: sample.mp3 -> sample-time.txt）。

      • --outfile1 オプションで指定された場合: そのファイル名。

    • 内容: 各音声セグメントの開始時間、終了時間、および対応する文字起こしテキストが以下の形式で記述されます。

      [開始時間(秒) - 終了時間(秒)] 文字起こしテキスト

      例:

      [0.00 - 3.45] こんにちは。
[3.45 - 6.80] これはWhisperのテストです。

  2. 純粋テキストファイル (outfile2)

    • ファイル名:

      • --outfile2 オプションで指定がない場合: 入力ファイル名に .txt を付加したもの（例: sample.mp3 -> sample.txt）。

      • --outfile2 オプションで指定された場合: そのファイル名。

    • 内容: 文字起こしされた音声の全文が、時間情報なしで記述されます。 例:

      こんにちは。これはWhisperのテストです。

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

transcribe_simple.py の基本的なコマンドラインでの使用法は以下の通りです。

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

引数:

  • <infile> (必須): 入力音声ファイル名を指定します。ワイルドカード（例: *.mp3）も使用可能です。

オプション:

  • --outfile1 <file>: 時間範囲付きの文字起こし結果を保存するファイル名を指定します。 省略した場合、入力ファイル名に基づいて自動生成されます（例: input.mp3 -> input-time.txt）。

  • --outfile2 <file>: 純粋な文字起こしテキストを保存するファイル名を指定します。 省略した場合、入力ファイル名に基づいて自動生成されます（例: input.mp3 -> input.txt）。

  • -m <model_name>, --model <model_name>: 使用するWhisperモデル名を指定します。 利用可能なモデル: tiny, base, small, medium, large, large-v1, large-v2, large-v3。 各モデルには英語専用版 (tiny.en, base.en など) もあります。 デフォルト値: base

  • -d <device_name>, --device <device_name>: Whisperモデルを実行するデバイスを指定します。 cuda (GPUを使用) または cpu (CPUを使用) を指定できます。 デフォルト値: 空文字列 ("")。空文字列の場合、GPUが利用可能であれば cuda、そうでなければ cpu が自動選択されます。

  • -l <lang>, --lang <lang>: 文字起こしする音声の言語を指定します。 ISO 639-1 コードを使用します（例: JA (日本語), EN (英語), ZH (中国語)）。 デフォルト値: JA

  • --pause <0|1>: プログラム終了時にEnterキーの入力を要求するかどうかを指定します。 0: 要求しない（デフォルト）。 1: 要求する。スクリプトがすぐに閉じないようにする場合に便利です。

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

例1: 日本語音声ファイルをデフォルト設定で文字起こし

sample.mp3 という日本語の音声ファイルがあり、これをデフォルトの base モデルで文字起こしする場合。

python transcribe_simple.py sample.mp3

実行結果:

コンソールにGPUの利用状況、使用モデル、言語が表示された後、文字起こしが実行されます。 処理完了後、以下のようなファイルが生成されます。

  • sample-time.txt: 時間範囲付きの文字起こし結果

    [0.00 - 3.45] こんにちは。
[3.45 - 6.80] これはWhisperのテストです。

  • sample.txt: 純粋な文字起こしテキスト

    こんにちは。これはWhisperのテストです。

また、コンソールには sample.txt の内容がそのまま出力されます。

例2: 英語音声ファイルを特定のモデルとCPUで文字起こし、出力ファイルを指定

english_speech.wav という英語の音声ファイルを、small モデルを使用し、CPUで処理する場合。出力ファイル名も明示的に指定し、終了時に一時停止するように設定します。

python transcribe_simple.py english_speech.wav -m small -l EN -d cpu --outfile1 en_speech_with_time.txt --outfile2 en_speech_full.txt --pause 1

実行結果:

コンソールに「No GPU available」と表示され、[cpu] デバイスが使用されることが示されます。 処理完了後、以下のようなファイルが生成されます。

  • en_speech_with_time.txt: 時間範囲付きの英語文字起こし結果

    [0.00 - 2.10] Hello everyone.
[2.10 - 5.50] This is a test of the Whisper model.

  • en_speech_full.txt: 純粋な英語文字起こしテキスト

    Hello everyone. This is a test of the Whisper model.

コンソールにも上記全文が表示され、最後に「Press ENTER to terminate」というメッセージが表示され、Enterキーを押すまでプログラムは終了しません。

例3: 複数のファイルをワイルドカードで指定

meeting_01.mp3 と meeting_02.mp3 という2つの音声ファイルをまとめて文字起こしする場合。

python transcribe_simple.py "meeting_*.mp3"

実行結果:

meeting_01.mp3 と meeting_02.mp3 のそれぞれに対して、例1と同様の処理が行われます。 具体的には、以下の4つのファイルが生成されます。

  • meeting_01-time.txt

  • meeting_01.txt

  • meeting_02-time.txt

  • meeting_02.txt

各ファイルの文字起こし結果もコンソールに順次表示されます。