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:
FFmpegの公式サイト (https://ffmpeg.org/download.html) から、Windows用のビルドをダウンロードします。
ダウンロードしたファイルを解凍し、
binディレクトリ(通常、ffmpeg.exeとffprobe.exeが含まれます)をシステムのPATH環境変数に追加します。または、
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スクリプトからインポートされて使用されることを前提としています。