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 -- その他のメタデータ。

language: str | None = None
metadata: dict[str, Any]
segments: list[Segment]
text: str
exception tkasr_common.OptionalDependencyError

ベースクラス: RuntimeError

オプションのバックエンドまたは機能がインストールされていない場合に発生するエラー。

class tkasr_common.Segment(start: float | None, end: float | None, text: str)

ベースクラス: object

音声認識結果の1セグメントを表すデータクラス。

パラメータ:
  • start -- セグメントの開始時間(秒)。

  • end -- セグメントの終了時間(秒)。

  • text -- セグメントのテキスト。

end: float | None
start: float | None
text: str
tkasr_common.audio_duration(source: Path, ffprobe: str) → float

音声ファイルの長さを取得します。

ffprobe コマンドを使用して音声ファイルの duration 情報を抽出し、 秒単位の浮動小数点数として返します。

パラメータ:
  • source (Path) -- 音声ファイルへのパス。

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

戻り値:

音声ファイルの長さ(秒)。

戻り値の型:

float

例外:

RuntimeError -- 音声ファイルの長さを取得できなかった場合。

tkasr_common.extract_wav(source: Path, start: float, length: float, destination: Path, ffmpeg: str) → None

音声ファイルから指定された範囲をWAV形式で抽出します。

ffmpeg コマンドを使用して、元の音声ファイルから指定された開始時間と長さの部分を モノラル、16kHzサンプリングレート、PCM_s16le形式のWAVファイルとして出力します。

パラメータ:
  • source (Path) -- 元の音声ファイルへのパス。

  • start (float) -- 抽出開始時間(秒)。

  • length (float) -- 抽出する長さ(秒)。

  • destination (Path) -- 抽出されたWAVファイルの出力パス。

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

戻り値:

None

戻り値の型:

None

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のフルパスのタプル。

戻り値の型:

tuple[str, str]

例外:

RuntimeError -- 指定されたディレクトリに ffmpeg または ffprobe が見つからない場合。

tkasr_common.hms(seconds: float | None) → str

秒数を HH:MM:SS.ss 形式の文字列に変換します。

None が指定された場合は ??:??:??.?? を返します。 負の秒数は0として扱われます。

パラメータ:

seconds (Optional[float]) -- 変換する秒数。

戻り値:

フォーマットされた時間文字列。

戻り値の型:

str

tkasr_common.run_command(command: list[str]) → str

外部コマンドを実行し、その標準出力を取得します。

subprocess.run を使用してコマンドを実行し、エラーが発生した場合は適切な RuntimeError を発生させます。 コマンドが見つからない場合や、コマンドがエラー終了した場合に詳細なエラーメッセージを提供します。

パラメータ:

command (list[str]) -- 実行するコマンドとその引数を表す文字列のリスト。

戻り値:

コマンドの標準出力。

戻り値の型:

str

例外:

RuntimeError -- コマンドが見つからない場合、またはコマンドがエラー終了した場合。

tkasr_common.save_json(path: Path, value: dict[str, Any]) → None

指定されたパスに辞書をJSON形式で保存します。

一時ファイルに書き込んだ後、元のファイルを置き換えることで、 ファイル破損のリスクを低減するアトミックな保存を試みます。 非ASCII文字も正しく保存されます。

パラメータ:
  • path (Path) -- 保存先のファイルパス。

  • value (dict[str, Any]) -- 保存する辞書データ。

戻り値:

None

戻り値の型:

None

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)。

パラメータ:
  • output (Path) -- 出力ファイル名のベースパス(拡張子なし)。 例: Path("output/audio") と指定すると、output/audio-time.txt などが生成されます。

  • result (ASRResult) -- 音声認識の結果データ。

  • report (dict[str, Any]) -- その他のレポート情報。

  • corrected (Optional[str]) -- 校正済みのテキスト。提供されている場合のみ出力されます。

戻り値:

None

戻り値の型:

None