tkasr_common プログラム仕様
tkasrプロジェクトで共有されるデータ型やファイル/音声処理のヘルパー関数を提供します。
音声認識(ASR)関連のアプリケーションで共通して利用されるユーティリティ機能を集約しています。 ファイル操作、FFmpeg/FFprobeの利用、ASR結果のデータ構造などが含まれます。
tkasr_usage
- class tkasr_common.ASRResult(text: str, segments: list[Segment] = <factory>, language: str | None = None, metadata: dict[str, ~typing.Any]=<factory>)
ベースクラス:
object音声認識全体の単一結果を表すデータクラス。
- パラメータ:
text -- 音声認識された完全なテキスト。
segments -- テキストを時間情報付きのセグメントに分割したリスト。
language -- 認識された言語コード(例: "en", "ja")。
metadata -- その他のメタデータ。
- exception tkasr_common.OptionalDependencyError
ベースクラス:
RuntimeErrorオプションのバックエンドまたは機能がインストールされていない場合に発生するエラー。
- class tkasr_common.Segment(start: float | None, end: float | None, text: str)
ベースクラス:
object音声認識結果の1セグメントを表すデータクラス。
- パラメータ:
start -- セグメントの開始時間(秒)。
end -- セグメントの終了時間(秒)。
text -- セグメントのテキスト。
- tkasr_common.audio_duration(source: Path, ffprobe: str) float
音声ファイルの長さを取得します。
ffprobe コマンドを使用して音声ファイルの duration 情報を抽出し、 秒単位の浮動小数点数として返します。
- パラメータ:
source (Path) -- 音声ファイルへのパス。
ffprobe (str) -- ffprobe 実行ファイルのフルパス。
- 戻り値:
音声ファイルの長さ(秒)。
- 戻り値の型:
- 例外:
RuntimeError -- 音声ファイルの長さを取得できなかった場合。
- tkasr_common.extract_wav(source: Path, start: float, length: float, destination: Path, ffmpeg: str) None
音声ファイルから指定された範囲をWAV形式で抽出します。
ffmpeg コマンドを使用して、元の音声ファイルから指定された開始時間と長さの部分を モノラル、16kHzサンプリングレート、PCM_s16le形式のWAVファイルとして出力します。
- tkasr_common.ffmpeg_commands(directory: Path | None) tuple[str, str]
FFmpegとFFprobeの実行可能ファイルのパスを決定します。
指定されたディレクトリが存在しない場合、またはディレクトリ内に`ffmpeg`と`ffprobe`が見つからない場合はエラーとなります。 Windows環境では実行ファイルに`.exe`拡張子が付与されます。 `directory`が`None`の場合、システムPATHから`ffmpeg`と`ffprobe`を検索します。
- パラメータ:
directory (Optional[Path]) -- FFmpegバイナリが格納されているディレクトリのパス。None の場合はシステムのPATHから検索されます。
- 戻り値:
FFmpegとFFprobeのフルパスのタプル。
- 戻り値の型:
- 例外:
RuntimeError -- 指定されたディレクトリに ffmpeg または ffprobe が見つからない場合。
- tkasr_common.hms(seconds: float | None) str
秒数を HH:MM:SS.ss 形式の文字列に変換します。
None が指定された場合は ??:??:??.?? を返します。 負の秒数は0として扱われます。
- tkasr_common.run_command(command: list[str]) str
外部コマンドを実行し、その標準出力を取得します。
subprocess.run を使用してコマンドを実行し、エラーが発生した場合は適切な RuntimeError を発生させます。 コマンドが見つからない場合や、コマンドがエラー終了した場合に詳細なエラーメッセージを提供します。
- パラメータ:
- 戻り値:
コマンドの標準出力。
- 戻り値の型:
- 例外:
RuntimeError -- コマンドが見つからない場合、またはコマンドがエラー終了した場合。
- tkasr_common.save_json(path: Path, value: dict[str, Any]) None
指定されたパスに辞書をJSON形式で保存します。
一時ファイルに書き込んだ後、元のファイルを置き換えることで、 ファイル破損のリスクを低減するアトミックな保存を試みます。 非ASCII文字も正しく保存されます。
- tkasr_common.write_outputs(output: Path, result: ASRResult, report: dict[str, Any], corrected: str | None) None
音声認識結果とレポートを複数のファイル形式で出力します。
以下のファイルを出力します: - 時刻付きテキストファイル (例:
{output_stem}-time.txt) - プレーンテキストファイル (例:{output_stem}.txt) - JSON形式のレポートファイル (例:{output_stem}-info.json) corrected が提供されている場合、校正済みテキストファイルも出力されます (例:{output_stem}.corrected.txt)。