tkasr_common.py ライブラリ ドキュメント

ライブラリの機能や目的

tkasr_common.py は、tkasr プロジェクトで使用される共有データ型とファイル/オーディオヘルパーを提供するライブラリです。主な目的は、自動音声認識 (ASR) の結果を標準化された形式で表現し、オーディオファイルの処理(期間の取得、WAV形式でのセグメント抽出)を行うためのユーティリティ機能を提供することです。

このライブラリは、以下の課題を解決します。

  • ASR 結果(テキスト、タイムスタンプ付きセグメント、言語、メタデータ)の一貫したデータ構造化。

  • 外部のFFmpegツールを利用したオーディオファイル操作の抽象化。

  • ASR処理の出力(時刻付きテキスト、プレーンテキスト、JSONレポートなど)を複数のファイル形式で容易に保存する機能。

  • エラーハンドリングと、特定の依存関係が見つからない場合のわかりやすいエラーメッセージの提供。

importする方法

このライブラリを他のPythonプログラムからインポートするには、以下のように記述します。

# 特定のクラスや関数をインポートする場合
from pathlib import Path
from tkasr_common import (
    OptionalDependencyError, Segment, ASRResult,
    run_command, ffmpeg_commands, audio_duration,
    extract_wav, hms, save_json, write_outputs
)

# モジュール全体をインポートし、tkasr_common. というプレフィックスを付けて使用する場合
import tkasr_common

# 例: ASRResult オブジェクトを作成する
result = tkasr_common.ASRResult(text="これはテストです。", language="ja")
print(result.text)

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

tkasr_common.py ライブラリ自体は、dataclasses, json, subprocess, pathlib, typing といったPython標準ライブラリのみを使用しており、pip を使用してインストールする必要がある非標準のPythonライブラリはありません。

しかし、本ライブラリの一部の機能(オーディオ処理)は、外部のバイナリツールである FFmpeg と ffprobe に依存しています。 これらのツールがシステムにインストールされ、Pythonスクリプトから実行可能なパスに設定されている必要があります。

FFmpegのインストール方法:

FFmpegは、多くのオペレーティングシステムで利用可能です。

  • Windows:

    1. FFmpegの公式サイト (https://ffmpeg.org/download.html) から、Windows用のビルドをダウンロードします。

    2. ダウンロードしたファイルを解凍し、bin ディレクトリ(通常、ffmpeg.exe と ffprobe.exe が含まれます)をシステムのPATH環境変数に追加します。

    3. または、ffmpeg_commands 関数を使用する際に、--ffmpeg-dir オプションで bin ディレクトリのパスを直接指定することもできます。

  • macOS: Homebrewを使用している場合、ターミナルで以下のコマンドを実行します。

    brew install ffmpeg
    
  • Linux (Debian/Ubuntu系): ターミナルで以下のコマンドを実行します。

    sudo apt update
    sudo apt install ffmpeg
    
  • Linux (Fedora系): ターミナルで以下のコマンドを実行します。

    sudo dnf install ffmpeg
    

インストール後、ターミナルで ffmpeg -version および ffprobe -version を実行し、正しくインストールされているか確認してください。

importできる変数と関数

クラス

OptionalDependencyError

  • 説明: 選択されたオプションのバックエンドまたは機能がインストールされていない場合に発生するカスタム実行時エラーです。

Segment

  • 説明: 音声認識結果における単一のテキストセグメント(区間)を表すデータクラスです。

  • 属性:

    • start: Optional[float] - セグメントの開始時刻(秒)。None の場合もあります。

    • end: Optional[float] - セグメントの終了時刻(秒)。None の場合もあります。

    • text: str - セグメントのテキスト内容。

ASRResult

  • 説明: 完全な音声認識結果を表すデータクラスです。

  • 属性:

    • text: str - 音声認識された全体のテキスト。

    • segments: list[Segment] - 個々のセグメントのリスト。デフォルトは空のリストです。

    • language: Optional[str] - 音声の言語。None の場合もあります。

    • metadata: dict[str, Any] - その他のメタデータ。デフォルトは空の辞書です。

関数

run_command(command: list[str]) -> str

  • 動作: 指定されたコマンドをサブプロセスとして実行し、標準出力を文字列として返します。コマンドの実行に失敗した場合や、実行ファイルが見つからない場合に RuntimeError を発生させます。

  • 引数:

    • command: list[str] - 実行するコマンドとその引数を表す文字列のリスト。例: ["ffmpeg", "-i", "input.mp3"]

  • 戻り値: str - コマンドの標準出力。

ffmpeg_commands(directory: Optional[Path]) -> tuple[str, str]

  • 動作: ffmpeg および ffprobe バイナリのパスを決定します。directory が指定されない場合は、システムのPATHから検索します。Windowsでは .exe サフィックスを自動的に追加します。指定されたディレクトリ内にバイナリが見つからない場合は RuntimeError を発生させます。

  • 引数:

    • directory: Optional[Path] - ffmpeg および ffprobe バイナリが存在するディレクトリのパス。None の場合、PATHから検索します。

  • 戻り値: tuple[str, str] - (ffmpegバイナリへのパス, ffprobeバイナリへのパス) のタプル。

audio_duration(source: Path, ffprobe: str) -> float

  • 動作: ffprobe を使用して、指定されたオーディオファイルの長さを秒単位で取得します。

  • 引数:

    • source: Path - 期間を取得したいオーディオファイルのパス。

    • ffprobe: str - ffprobe バイナリへのパス。

  • 戻り値: float - オーディオファイルの長さ(秒)。

extract_wav(source: Path, start: float, length: float, destination: Path, ffmpeg: str) -> None

  • 動作: ffmpeg を使用して、元のオーディオファイルから特定の区間のモノラルWAVファイルを抽出します。出力は16kHzサンプリングレート、16bit PCM(PCM_S16LE)形式です。

  • 引数:

    • source: Path - 元のオーディオファイルのパス。

    • start: float - 抽出を開始する時刻(秒)。

    • length: float - 抽出する区間の長さ(秒)。

    • destination: Path - 抽出されたWAVファイルを保存するパス。

    • ffmpeg: str - ffmpeg バイナリへのパス。

  • 戻り値: None

hms(seconds: Optional[float]) -> str

  • 動作: 秒数を HH:MM:SS.ms 形式の文字列にフォーマットします。seconds が None の場合は ??:??:??.?? を返します。

  • 引数:

    • seconds: Optional[float] - フォーマットする秒数。

  • 戻り値: str - フォーマットされた時刻文字列。

save_json(path: Path, value: dict[str, Any]) -> None

  • 動作: 指定された辞書を、指定されたパスにJSONファイルとして安全に保存します。一時ファイルに書き込み、成功した場合に元のファイルと置き換えることで、書き込み中のデータ破損を防ぎます。

  • 引数:

    • path: Path - JSONファイルを保存するパス。

    • value: dict[str, Any] - JSONとして保存する辞書データ。

  • 戻り値: None

write_outputs(output: Path, result: ASRResult, report: dict[str, Any], corrected: Optional[str]) -> None

  • 動作: ASR結果とレポートを指定された出力パスに基づいて複数のファイル形式で書き出します。

    • output.stem + "-time.txt": 時刻付きのテキストファイル。

    • output.with_suffix(".txt"): プレーンなテキストファイル。

    • output.stem + "-info.json": ASRに関する追加情報を含むJSONファイル。

    • plain_file.stem + ".corrected.txt": 修正済みテキストが存在する場合に作成されるファイル。

  • 引数:

    • output: Path - 出力ファイルのベースパス(例: /path/to/audio.wav なら /path/to/audio がベース)。

    • result: ASRResult - 書き出すASR結果データ。

    • report: dict[str, Any] - info.json に保存される追加のレポート情報。

    • corrected: Optional[str] - 修正されたテキスト。None でない場合、別のファイルとして保存されます。

  • 戻り値: None

main scriptとして実行したときの動作

tkasr_common.py には、if __name__ == "__main__": ブロックが実装されていません。 したがって、このスクリプトを python tkasr_common.py のように直接実行しても、何も特別な処理は行われません。クラスや関数が定義されるだけで、何らかの出力や副作用が発生することはありません。このファイルは、他のPythonスクリプトからインポートされて使用されることを前提としています。