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)