transcribe2 プログラム仕様

統合ASR CLI。

ASR固有の処理は tkasr_*.py に分離し、このモジュールは入力分割、 再開、出力、LLM校正の呼出しだけを担当する。

transcribe2.py Documentation

transcribe2.build_parser() → ArgumentParser

コマンドライン引数パーサーを構築する。

ASR処理とLLM校正に関連する様々なオプションを含む ArgumentParser オブジェクトを生成します。 引数は、バックエンド、API設定、共通の音声処理、LLM校正、ローカルQwen設定、Whisper設定など、 機能ごとにグループ化されています。

戻り値:

(argparse.ArgumentParser) 設定済みの ArgumentParser オブジェクト。

transcribe2.create_backend(args: Namespace)

選択されたASRバックエンドだけを遅延 import して生成する。

指定されたバックエンド名に基づいて、対応するモジュールを動的にインポートし、 そのモジュール内の Backend クラスのインスタンスを生成して返します。

パラメータ:

args -- (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。args.backend に使用するバックエンド名が含まれる。

戻り値:

(Any) 選択されたASRバックエンドのインスタンス。

transcribe2.load_checkpoint(checkpoint_path: Path, source: Path, args: Namespace, initial_state: dict[str, Any]) → dict[str, Any]

--resume 時に、同じ入力ファイルのチェックポイントだけを復元する。

チェックポイントファイルが存在し、かつ --resume オプションが指定されている場合に、 その内容を読み込み、状態を復元します。 ただし、復元するチェックポイントが現在の入力ファイルと異なる場合はエラーとします。

パラメータ:
  • checkpoint_path -- (Path) チェックポイントファイルのパス。

  • source -- (Path) 現在処理中の入力ファイルのパス。

  • args -- (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。args.resume オプションの有無をチェックする。

  • initial_state -- (dict[str, Any]) チェックポイントが存在しない場合に返される初期状態。

戻り値:

(dict[str, Any]) 復元された、または初期状態の辞書。

例外:

RuntimeError -- チェックポイントの入力ファイルが現在処理中のファイルと異なる場合。

transcribe2.main() → int

スクリプトのエントリポイント。

コマンドライン引数を解析し、入力ファイルを glob 展開して、 それぞれのファイルに対して文字起こしと校正の処理 (process_file) を実行します。 引数の検証もここで行われます。

戻り値:

(int) 成功時には 0、エラー時には 1 を返すシステム終了コード。

例外:
  • SystemExit -- 処理中にエラーが発生した場合、またはユーザーによって中断された場合。

  • RuntimeError -- 入力ファイルが見つからない、複数入力時に --output が指定された、または引数の値が不正な場合。

transcribe2.make_boundary_text(chunks: list[dict[str, Any]], overlap_seconds: float) → str

LLM校正のため、各ASRチャンクと重複区間を明示した文字列を作る。

生成される文字列は、各ASRチャンクの開始・終了時刻と、チャンク間の重複区間を示すマーカーを含みます。 これにより、LLMは元の音声における文脈や区切りを理解しやすくなります。 マーカーの例:

[[ASR_CHUNK 0001 START=0.0s END=240.0s]]
最初のチャンクのテキスト
[[/ASR_CHUNK 0001]]
[[ASR_BOUNDARY 0001|0002 OVERLAP=10.0s]]
[[ASR_CHUNK 0002 START=230.0s END=470.0s]]
次のチャンクのテキスト
[[/ASR_CHUNK 0002]]
パラメータ:
  • chunks -- (list[dict[str, Any]]) ASR結果のチャンクのリスト。各チャンクは index, start, end, text などのキーを持つ。

  • overlap_seconds -- (float) チャンク間の重複秒数。

戻り値:

(str) LLM校正用の境界情報を含むテキスト。

transcribe2.make_timestamp_segments(chunks: list[dict[str, Any]]) → list[Segment]

チャンク内の相対時刻を、入力ファイル全体での絶対時刻へ変換する。

各ASRチャンクは自身の開始時刻を基準とした相対的なセグメント情報を持つ可能性があります。 この関数は、これらの相対時刻を、元の入力音声ファイル全体における絶対時刻に変換し、 単一の Segment オブジェクトのリストとして結合します。

パラメータ:

chunks -- (list[dict[str, Any]]) ASR結果のチャンクのリスト。各チャンクは start と asr_segments のキーを持つ。

戻り値:

(list[Segment]) 入力ファイル全体の絶対時刻に対応するセグメントのリスト。

transcribe2.normalize_language(value: str) → str | None

短縮言語名をASRバックエンド用の名称に変換する。

パラメータ:

value -- (str) 言語名(例: "ja", "en", "auto")。

戻り値:

(str | None) 正規化された言語名。認識できない場合や "auto" の場合は None。

transcribe2.process_file(source: Path, args: Namespace, ffmpeg: str, ffprobe: str) → None

1入力ファイルをASRし、必要ならLLM校正して出力する。

この関数は、単一の音声/動画ファイルを受け取り、以下の処理を実行します。

  1. 音声ファイルを指定されたチャンクサイズとオーバーラップで分割。

  2. 各チャンクに対してASRバックエンドを呼び出し、文字起こしを実行。

  3. --resume オプションが指定されている場合は、中断箇所から処理を再開。

  4. 中間結果をチェックポイントファイルに保存。

  5. 全てのチャンクの処理が完了したら、必要に応じてLLMによる校正を実施。

  6. 最終的な文字起こし結果とメタデータを出力ファイルに書き込み。

パラメータ:
  • source -- (Path) 処理対象の音声・動画ファイルのパス。

  • args -- (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。

  • ffmpeg -- (str) ffmpeg実行ファイルのパス。

  • ffprobe -- (str) ffprobe実行ファイルのパス。

戻り値:

(None)

例外:

RuntimeError -- チェックポイントのチャンク数が入力条件と一致しない場合。

transcribe2.remove_asr_markers(text: str) → str

最終的なASR原文から、LLM用のチャンク管理行だけを取り除く。

[[ASR_...]] で始まる行と [[/ASR_...]] で始まる行を削除します。

パラメータ:

text -- (str) ASR結果とLLM校正用のマーカーを含むテキスト。

戻り値:

(str) マーカーが除去されたクリーンなテキスト。