transcribe2.py ダウンロード/コピー

transcribe2.py をダウンロード

transcribe2.py
transcribe2.py
  1#!/usr/bin/env python3
  2"""統合ASR CLI。
  3
  4ASR固有の処理は ``tkasr_*.py`` に分離し、このモジュールは入力分割、
  5再開、出力、LLM校正の呼出しだけを担当する。
  6
  7:doc:`transcribe2_usage`
  8"""
  9
 10from __future__ import annotations
 11
 12import argparse
 13import glob
 14import importlib
 15import json
 16import math
 17import tempfile
 18import time
 19from pathlib import Path
 20from typing import Any
 21
 22from tkasr_common import (
 23    ASRResult,
 24    OptionalDependencyError,
 25    Segment,
 26    audio_duration,
 27    extract_wav,
 28    ffmpeg_commands,
 29    save_json,
 30    write_outputs,
 31)
 32
 33
 34LANGUAGE_NAMES = {"ja": "Japanese", "en": "English", "zh": "Chinese", "ko": "Korean"}
 35BACKEND_MODULES = {
 36    "qwen-api": "tkasr_qwen_api",
 37    "qwen-local": "tkasr_qwen_local",
 38    "whisper": "tkasr_whisper",
 39}
 40
 41
 42def normalize_language(value: str) -> str | None:
 43    """短縮言語名をASRバックエンド用の名称に変換する。
 44
 45    :param value: (str) 言語名(例: "ja", "en", "auto")。
 46    :returns: (str | None) 正規化された言語名。認識できない場合や "auto" の場合は None。
 47    """
 48    value = value.strip()
 49    return None if not value or value.lower() == "auto" else LANGUAGE_NAMES.get(value.lower(), value)
 50
 51
 52def make_boundary_text(chunks: list[dict[str, Any]], overlap_seconds: float) -> str:
 53    """LLM校正のため、各ASRチャンクと重複区間を明示した文字列を作る。
 54
 55    生成される文字列は、各ASRチャンクの開始・終了時刻と、チャンク間の重複区間を示すマーカーを含みます。
 56    これにより、LLMは元の音声における文脈や区切りを理解しやすくなります。
 57    マーカーの例::
 58
 59        [[ASR_CHUNK 0001 START=0.0s END=240.0s]]
 60        最初のチャンクのテキスト
 61        [[/ASR_CHUNK 0001]]
 62        [[ASR_BOUNDARY 0001|0002 OVERLAP=10.0s]]
 63        [[ASR_CHUNK 0002 START=230.0s END=470.0s]]
 64        次のチャンクのテキスト
 65        [[/ASR_CHUNK 0002]]
 66
 67    :param chunks: (list[dict[str, Any]]) ASR結果のチャンクのリスト。各チャンクは `index`, `start`, `end`, `text` などのキーを持つ。
 68    :param overlap_seconds: (float) チャンク間の重複秒数。
 69    :returns: (str) LLM校正用の境界情報を含むテキスト。
 70    """
 71    lines: list[str] = []
 72    for position, chunk in enumerate(chunks):
 73        number = int(chunk["index"]) + 1
 74        if position:
 75            lines.append(
 76                f"[[ASR_BOUNDARY {number - 1:04d}|{number:04d} "
 77                f"OVERLAP={overlap_seconds:.1f}s]]"
 78            )
 79        lines.extend(
 80            [
 81                f"[[ASR_CHUNK {number:04d} START={chunk['start']:.1f}s "
 82                f"END={chunk['end']:.1f}s]]",
 83                str(chunk["text"]).strip(),
 84                f"[[/ASR_CHUNK {number:04d}]]",
 85            ]
 86        )
 87    return "\n".join(line for line in lines if line)
 88
 89
 90def remove_asr_markers(text: str) -> str:
 91    """最終的なASR原文から、LLM用のチャンク管理行だけを取り除く。
 92
 93    ``[[ASR_...]]`` で始まる行と ``[[/ASR_...]]`` で始まる行を削除します。
 94
 95    :param text: (str) ASR結果とLLM校正用のマーカーを含むテキスト。
 96    :returns: (str) マーカーが除去されたクリーンなテキスト。
 97    """
 98    return "\n".join(
 99        line
100        for line in text.splitlines()
101        if not line.startswith("[[ASR_") and not line.startswith("[[/ASR_")
102    ).strip()
103
104
105def create_backend(args: argparse.Namespace):
106    """選択されたASRバックエンドだけを遅延 import して生成する。
107
108    指定されたバックエンド名に基づいて、対応するモジュールを動的にインポートし、
109    そのモジュール内の `Backend` クラスのインスタンスを生成して返します。
110
111    :param args: (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。`args.backend` に使用するバックエンド名が含まれる。
112    :returns: (Any) 選択されたASRバックエンドのインスタンス。
113    """
114    module = importlib.import_module(BACKEND_MODULES[args.backend])
115    return module.Backend(args)
116
117
118def load_checkpoint(
119    checkpoint_path: Path,
120    source: Path,
121    args: argparse.Namespace,
122    initial_state: dict[str, Any],
123) -> dict[str, Any]:
124    """--resume 時に、同じ入力ファイルのチェックポイントだけを復元する。
125
126    チェックポイントファイルが存在し、かつ `--resume` オプションが指定されている場合に、
127    その内容を読み込み、状態を復元します。
128    ただし、復元するチェックポイントが現在の入力ファイルと異なる場合はエラーとします。
129
130    :param checkpoint_path: (Path) チェックポイントファイルのパス。
131    :param source: (Path) 現在処理中の入力ファイルのパス。
132    :param args: (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。`args.resume` オプションの有無をチェックする。
133    :param initial_state: (dict[str, Any]) チェックポイントが存在しない場合に返される初期状態。
134    :returns: (dict[str, Any]) 復元された、または初期状態の辞書。
135    :raises RuntimeError: チェックポイントの入力ファイルが現在処理中のファイルと異なる場合。
136    """
137    if not args.resume or not checkpoint_path.exists():
138        return initial_state
139
140    state = json.loads(checkpoint_path.read_text(encoding="utf-8"))
141    if Path(state.get("source", "")).resolve() != source:
142        raise RuntimeError("チェックポイントの入力ファイルが異なります。")
143
144    print(f"再開: {len(state['segments'])} チャンク完了")
145    return state
146
147
148def make_timestamp_segments(chunks: list[dict[str, Any]]) -> list[Segment]:
149    """チャンク内の相対時刻を、入力ファイル全体での絶対時刻へ変換する。
150
151    各ASRチャンクは自身の開始時刻を基準とした相対的なセグメント情報を持つ可能性があります。
152    この関数は、これらの相対時刻を、元の入力音声ファイル全体における絶対時刻に変換し、
153    単一の `Segment` オブジェクトのリストとして結合します。
154
155    :param chunks: (list[dict[str, Any]]) ASR結果のチャンクのリスト。各チャンクは `start` と `asr_segments` のキーを持つ。
156    :returns: (list[Segment]) 入力ファイル全体の絶対時刻に対応するセグメントのリスト。
157    """
158    segments: list[Segment] = []
159    for chunk in chunks:
160        rows = chunk["asr_segments"] or [
161            {"start": 0.0, "end": chunk["end"] - chunk["start"], "text": chunk["text"]}
162        ]
163        for row in rows:
164            segments.append(
165                Segment(
166                    start=None if row["start"] is None else row["start"] + chunk["start"],
167                    end=None if row["end"] is None else row["end"] + chunk["start"],
168                    text=row["text"],
169                )
170            )
171    return segments
172
173
174def process_file(source: Path, args: argparse.Namespace, ffmpeg: str, ffprobe: str) -> None:
175    """1入力ファイルをASRし、必要ならLLM校正して出力する。
176
177    この関数は、単一の音声/動画ファイルを受け取り、以下の処理を実行します。
178
179    1. 音声ファイルを指定されたチャンクサイズとオーバーラップで分割。
180    2. 各チャンクに対してASRバックエンドを呼び出し、文字起こしを実行。
181    3. `--resume` オプションが指定されている場合は、中断箇所から処理を再開。
182    4. 中間結果をチェックポイントファイルに保存。
183    5. 全てのチャンクの処理が完了したら、必要に応じてLLMによる校正を実施。
184    6. 最終的な文字起こし結果とメタデータを出力ファイルに書き込み。
185
186    :param source: (Path) 処理対象の音声・動画ファイルのパス。
187    :param args: (argparse.Namespace) コマンドライン引数を格納する名前空間オブジェクト。
188    :param ffmpeg: (str) ffmpeg実行ファイルのパス。
189    :param ffprobe: (str) ffprobe実行ファイルのパス。
190    :returns: (None)
191    :raises RuntimeError: チェックポイントのチャンク数が入力条件と一致しない場合。
192    """
193    output_path = (args.output or source.with_suffix(".asr.txt")).resolve()
194    checkpoint_path = output_path.with_suffix(output_path.suffix + ".partial.json")
195
196    total_seconds = audio_duration(source, ffprobe)
197    step_seconds = args.chunk_seconds - args.overlap_seconds
198    starts = [
199        index * step_seconds
200        for index in range(math.ceil(total_seconds / step_seconds))
201        if index * step_seconds < total_seconds - 0.01
202    ]
203
204    engine = create_backend(args)
205    engine.load()
206
207    initial_state = {
208        "source": str(source),
209        "duration_seconds": total_seconds,
210        "backend": engine.describe(),
211        "chunk_seconds": args.chunk_seconds,
212        "overlap_seconds": args.overlap_seconds,
213        "segments": [],
214    }
215    state = load_checkpoint(checkpoint_path, source, args, initial_state)
216    completed_count = len(state["segments"])
217    if completed_count > len(starts):
218        raise RuntimeError("チェックポイントのチャンク数が入力条件と一致しません。")
219
220    with tempfile.TemporaryDirectory(prefix="tkasr-") as temporary_dir:
221        for index, start in enumerate(starts[completed_count:], start=completed_count):
222            length = min(args.chunk_seconds, total_seconds - start)
223            wav_path = Path(temporary_dir) / f"chunk_{index:04d}.wav"
224            extract_wav(source, start, length, wav_path, ffmpeg)
225
226            began = time.monotonic()
227            result = engine.transcribe(wav_path, normalize_language(args.lang), args.context)
228            elapsed = time.monotonic() - began
229
230            state["segments"].append(
231                {
232                    "index": index,
233                    "start": start,
234                    "end": start + length,
235                    "text": result.text,
236                    "language": result.language,
237                    "elapsed_seconds": elapsed,
238                    "metadata": result.metadata,
239                    "asr_segments": [
240                        {"start": segment.start, "end": segment.end, "text": segment.text}
241                        for segment in result.segments
242                    ],
243                }
244            )
245            save_json(checkpoint_path, state)
246            print(
247                f"[{index + 1}/{len(starts)}] {start:.1f}-{start + length:.1f}s "
248                f"({elapsed:.1f}s): {result.text[:100]}",
249                flush=True,
250            )
251
252    marked_text = make_boundary_text(state["segments"], args.overlap_seconds)
253    raw_result = ASRResult(
254        text=remove_asr_markers(marked_text),
255        segments=make_timestamp_segments(state["segments"]),
256    )
257
258    corrected_text = None
259    if not args.no_correct:
260        from tkasr_llm import correct
261
262        corrected_text = correct(
263            marked_text,
264            config=args.llm_config,
265            provider=args.llm_provider,
266            model=args.llm_model,
267            context=args.context,
268            max_tokens=args.llm_max_tokens,
269            maximum_chars=args.correction_chars,
270        )
271
272    write_outputs(output_path, raw_result, {**state, "output": str(output_path)}, corrected_text)
273
274
275def build_parser() -> argparse.ArgumentParser:
276    """コマンドライン引数パーサーを構築する。
277
278    ASR処理とLLM校正に関連する様々なオプションを含む `ArgumentParser` オブジェクトを生成します。
279    引数は、バックエンド、API設定、共通の音声処理、LLM校正、ローカルQwen設定、Whisper設定など、
280    機能ごとにグループ化されています。
281
282    :returns: (argparse.ArgumentParser) 設定済みの `ArgumentParser` オブジェクト。
283    """
284    parser = argparse.ArgumentParser(
285        description="Qwen3-ASR API / local Qwen3-ASR / Whisper 統合文字起こし"
286    )
287    parser.add_argument("input", help="音声・動画ファイル(glob可)")
288    parser.add_argument("--backend", choices=BACKEND_MODULES, default="qwen-api")
289    parser.add_argument("-m", "--model", default="Qwen/Qwen3-ASR-1.7B")
290    parser.add_argument("-l", "--lang", default="ja")
291    parser.add_argument("--output", type=Path)
292
293    api = parser.add_argument_group("Qwen ASR API")
294    api.add_argument("--api-base", default="http://192.168.27.18:8001/v1")
295    api.add_argument("--timeout", type=float, default=1800)
296
297    common = parser.add_argument_group("共通の音声処理")
298    common.add_argument("--ffmpeg-dir", type=Path)
299    common.add_argument("--chunk-seconds", type=float, default=240)
300    common.add_argument("--overlap-seconds", type=float, default=10)
301    common.add_argument("--resume", action="store_true")
302    common.add_argument("--context", "--prompt", dest="context", default="")
303
304    llm = parser.add_argument_group("LLM校正(tkai_lib_litellm.py)")
305    llm.add_argument("--no-correct", action="store_true")
306    llm.add_argument("--llm-config", default="ai.env")
307    llm.add_argument("--llm-provider", default="lmstudio")
308    llm.add_argument("--llm-model", default="openai/gpt-oss-20b")
309    llm.add_argument("--llm-max-tokens", type=int, default=16384)
310    llm.add_argument("--correction-chars", type=int, default=4000)
311
312    local_qwen = parser.add_argument_group("ローカル Qwen3-ASR")
313    local_qwen.add_argument("-d", "--device", default="auto")
314    local_qwen.add_argument("--dtype", choices=["auto", "bfloat16", "float16", "float32"], default="auto")
315    local_qwen.add_argument("--timestamps", type=int, choices=[0, 1], default=1)
316    local_qwen.add_argument("--aligner", default="Qwen/Qwen3-ForcedAligner-0.6B")
317    local_qwen.add_argument("--attention", choices=["auto", "sdpa", "eager", "flash_attention_2"], default="auto")
318    local_qwen.add_argument("--max-inference-batch-size", type=int, default=1)
319    local_qwen.add_argument("--max-new-tokens", type=int, default=4096)
320
321    whisper = parser.add_argument_group("Whisper")
322    whisper.add_argument("--beam-size", type=int, default=5)
323    whisper.add_argument("--temperature", default="0,0.2,0.4,0.6")
324    whisper.add_argument("--compression-ratio-threshold", type=float, default=2.4)
325    whisper.add_argument("--log-prob-threshold", type=float, default=-1.0)
326    whisper.add_argument("--no-speech-threshold", type=float, default=0.6)
327
328    return parser
329
330
331def main() -> int:
332    """スクリプトのエントリポイント。
333
334    コマンドライン引数を解析し、入力ファイルを glob 展開して、
335    それぞれのファイルに対して文字起こしと校正の処理 (`process_file`) を実行します。
336    引数の検証もここで行われます。
337
338    :returns: (int) 成功時には 0、エラー時には 1 を返すシステム終了コード。
339    :raises SystemExit: 処理中にエラーが発生した場合、またはユーザーによって中断された場合。
340    :raises RuntimeError: 入力ファイルが見つからない、複数入力時に --output が指定された、または引数の値が不正な場合。
341    """
342    args = build_parser().parse_args()
343
344    print("\n=== 入力パラメータ ===")
345    for name, value in vars(args).items():
346        print(f"{name} = {value}")
347    print("======================\n")
348
349    files = [Path(path).resolve() for path in sorted(glob.glob(args.input))]
350
351    if not files:
352        raise RuntimeError(f"入力ファイルがありません: {args.input}")
353    if len(files) > 1 and args.output:
354        raise RuntimeError("複数入力時は --output を指定できません。")
355    if args.chunk_seconds <= 0:
356        raise RuntimeError("--chunk-seconds は正の値にしてください。")
357    if not 0 <= args.overlap_seconds < args.chunk_seconds:
358        raise RuntimeError("--overlap-seconds は0以上かつ --chunk-seconds 未満にしてください。")
359
360    ffmpeg, ffprobe = ffmpeg_commands(args.ffmpeg_dir)
361    for source in files:
362        process_file(source, args, ffmpeg, ffprobe)
363    return 0
364
365
366if __name__ == "__main__":
367    try:
368        raise SystemExit(main())
369    except KeyboardInterrupt:
370        print("\n中断しました。--resume で再開できます。")
371        raise SystemExit(130)
372    except (RuntimeError, OptionalDependencyError) as exc:
373        print(f"エラー: {exc}")
374        raise SystemExit(1)