npn160603-hash/professional-caption-design

professional-caption-design は何をしますか？

タイムスタンプ付きの単語を縦型動画のオンスクリーンキャプションに変換します。ステータス: 実装済み、テスト済み。

目的

単語を読みやすいキューブロックにグループ化し、測定された行幅に基づいてレイアウトし、少数の名前付きルックでスタイルを適用し、ASS / SRT / WebVTT をエクスポートし、レイアウトの問題を報告します。

サポートされる入力

• 単語タイミング: {"text", "start", "end"} または {"words": [...]} 形式の JSON リスト。時刻は秒単位。 テキストは読み込み時に Unicode NFC に正規化されるため、ベトナム語のダイアクリティカルマークが確実に比較・レンダリングされます。
• ハイライトするキーワードのオプションリスト、および数字を含むトークンをハイライトするオプションフラグ。

音声認識は含まれていません。 単語タイミングは呼び出し元から提供される必要があります。

サポートされる出力

• captions.ass (libass スタイル、レンダリングパイプラインで焼き込み)
• captions.srt、captions.vtt (プレーンテキスト、プレーヤーやプラットフォーム向け)
• level (error | warning)、code、message、cue インデックスを含む問題のリスト

実行

python3 -m uvs.captions examples/demo_caption/words.json --style bold_shorts \
  --keywords "cháo,5" --out-dir out/captions

エラーレベルの問題が存在する場合、終了コードは 1 です。Python の場合: uvs.captions.build_captions(...) そして write_outputs(build, out_dir)。

パラメータ

• style: documentary_minimal、bold_shorts、cinematic、emotional_storytelling。 各スタイルはフォント、サイズ、ウェイト、色、アウトライン、シャドウ、下部安全マージン (margin_v)、サイドマージン、最大行数 (2)、およびアニメーション (fade、pop、none) を設定します。
• frame_w、frame_h: デフォルト 1080x1920。
• SegmentConfig: max_gap (0.45 秒)、max_duration (2.8 秒、目標)、hard_max_duration (3.4 秒、文末はこの値を上限にキューを終了する場合あり)、min_duration (0.7 秒)。

依存関係

• Python 3.10+、Pillow。
• フォントファイルを見つけるための fontconfig (fc-match)。fontconfig がない場合は Pillow のデフォルトフォントが使用され、幅チェックは近似値になります。バリデータはそのフォールバックを報告しないため、fontconfig をインストールしたままにしてください。
• スタイルで指定されたフォントファミリ（デフォルト Inter）が libass と fontconfig のためにインストールされている必要があります。

レイアウトルール

• 幅は実際のフォントファイルで測定されます。使用可能な幅は frame_w - 2*margin_h - 2*outline です。
• 2行の分割は、測定された幅でバランスが取られ、句読点後の改行に小さなボーナスが与えられます。
• キューは、文末、長い無音、時間制限、または次の単語が 2 行に収まらない場合に分割されます。
• ハイライトされたキーワードは色が変わります。bold_shorts スタイルでは、一時的に拡大表示されます (pop)。 他の単語はアニメーションしないため、すべての単語が同じように動くわけではありません。
• ユーザーテキスト内の ASS オーバーライド構文 ({、}、\) は類似の文字に置き換えられます。

例

examples/demo_caption/words.json は手動でタイミングを合わせたベトナム語のプレースホルダーです。実際のナレーションには対応していません。デモを実行する: python3 -m uvs.render --out out/demo。

制約事項

• プラットフォームのキャプションルール（たとえば各プラットフォームの行長や読み取り速度の制限）に対して検証されていません。too_fast しきい値 (22 文字/秒) はヒューリスティックです。
• 話者認識スタイルはなく、言語ごとの改行辞書もありません（ベトナム語はスペースでのみ改行）。
• 「Documentary Minimal」、「Bold Shorts」、「Cinematic」、「Emotional Storytelling」は実装済みです。 「Clean Modern」、「Podcast Highlight」、「Educational」は実装されていません。

エラーハンドリング

• 空のテキスト、負の時間、または順序が不正な時間は、読み込み時に ValueError を発生させます。
• 不明なスタイルは KeyError を発生させます。
• レイアウトの問題は、静かに修正されるのではなく、問題として報告されます: line_overflow、too_many_lines、 overlap、outside_frame、non_positive_duration、empty_cue (エラー); short_cue、long_cue、orphan_word、too_fast、space_before_punctuation、 missing_space_after_punctuation、double_space、not_nfc (警告)。
• render_captioned はエラーがある場合のレンダリングを拒否します。

テスト

tests/unit/test_captions.py (読み込み、レイアウト、セグメンテーション、検証、エクスポート)。 tests/render/test_pipeline.py::RenderTests はデモをレンダリングし、寸法、コーデック、フレームレート、 キャプションテキストが ASS ファイルに含まれていることを確認します。

統合

レンダリングパイプライン (uvs/render.py) は build_captions と write_outputs を呼び出し、次に ASS ファイルを ffmpeg -vf ass=... で焼き込みます。スタイルとキーワードオプションは、パイプラインの CLI に直接マッピングされます。