YouTube 動画 → 洗練された逐語録ドキュメント
YouTube(または字幕付き)動画を、読みやすく、ジャンプでき、情報を蓄積できるFeishu逐語録ドキュメントに変換します。
全体的な流れ:動画を読み込む → SRTを取得 → パラグラフに分割 → クリーニング+翻訳 → Feishuドキュメント生成 →(オプション)視覚的サマリーホワイトボード。
いつ使うか
ユーザーから動画リンクが送られてきて、逐語録 / タイムライン / 会議メモ風の整理 / 字幕抽出 / 中英対訳 / 「この動画を見てまとめて」といったリクエストがあった場合。
フロー
1. video_idと基本情報を取得
URLから11桁のvideo idを抽出。可能であればタイトル、長さ、ゲスト/投稿者も取得し、ドキュメントのヘッダー情報ボックスに記録。
2. 字幕を取得(最もボトルネックになりやすいステップ)
YouTubeに直接接続して字幕を取得しようとすると、ほぼ間違いなくスクレイピング対策に阻まれるので、無理に直結しない。references/fetch-srt.mdのフォールバックチェーンに従う:
サードパーティの字幕サイト(downsubを最優先。リモートブラウザで開く→download.subtitle.toのダウンロードblobを抽出→curlで直接取得)
→ ブラウザでページテキストを取得 → ユーザーに手動エクスポートを依頼。取得後はtranscript.srtとして保存。
3. 話者ターンでパラグラフに分割
python scripts/parse_srt.py transcript.srt --video-id <VIDEO_ID> --out turns.json
>>話者マーカーで分割(マーカーがない場合は固定長でフォールバック分割)。このステップで「ひとつの文が二つに分断される」問題を根本的に解決——
以前は固定秒数で強制分割していたため文が途中で切れていたが、話者ターンで分割すれば各パラグラフは完全な発言になる。スクリプトは同時に、純粋なフィラーのみの独立したパラグラフを削除する。
4. クリーニング+翻訳
references/clean-translate.mdに従う:フィラーの削除、吃音の重複削除、ASR誤認識(人名/用語/会社名)の修正、
パラグラフごとに翻訳。100パラグラフ近くある場合は2〜3バッチに分割し、並列サブエージェントで処理。共通の用語修正テーブルを共有し、各サブエージェントは{index:{en,zh}}形式のJSONを出力。これらをマージして1つのcontentファイルを作成。
コンテンツの準備ができたら、scripts/build_doc.pyのヘッダーコメントに記載された構造に従ってcontent.jsonを作成(meta / sections トピック別セクション / highlights ハイライトカード / paras 本文 / bilingual スイッチを含む)。その後:
python scripts/build_doc.py turns.json content.json --outdir frags/
frags/intro.xmlとfrags/sec_0.xml … sec_N.xmlを生成。
書式の鉄則(実際のユーザーフィードバックから蓄積され、build_doc.pyに組み込み済み。絶対に覆さないこと):
- タイトルはシンプルに、「中英対訳」などのラベルは付けない;
- 中英は色で区別する(英語はグレー、中国語は黒)。EN/ZHの文字は書かない;
- パラグラフ全体をハイライトしない。ハイライトが必要な箇所は⭐マークのみ使用。黄色ハイライトは上部のカードに限定;太字/ハイライトの具体的な短いフレーズは人間に委ねる。
5. Feishuに公開
lark-docスキル(docs +createでドキュメントを作成しintroを書き込み、その後docs +update --command appendでセクションごとに追記)を使用。
呼び出しの詳細はreferences/publish-lark.mdを参照。公開後、ドキュメントURLをユーザーに提供。
6.(オプション)視覚的サマリーホワイトボードを生成
ユーザーは逐語録を入手した後、同じドキュメント内に要点を抽出した視覚的な図を埋め込みたいと希望することが多い。beautiful-feishu-whiteboardのアプローチを使用し、
手作業でSVGをレイアウト(Mermaidの自動レイアウトは使わない)、Feishuで編集可能なホワイトボードとして書き込む。完全なフローと注意点は
references/whiteboard-summary.mdを参照。
最も重要で、最も失敗しやすい鉄則:Feishuホワイトボードはレンダリング時にテキストを強制的に濃色に変換する。そのため、
すべてのテキストは薄い背景(クリーム/イエロー)上に濃墨色で配置する。色は枠線/カラーバー/ブロックマーカー/バッジにのみ使用し、テキストを決して彩度の高い色のブロックの上に置かない。
ローカルのPNGプレビューのテキスト色は信用できない。必ず書き込んだ後、+query --output_as imageで実際のオンライン画像を確認してコントラストを確認する。
イテレーション
ユーザーはドキュメント内にコメントを残して修正を依頼することがよくある。lark-docの+get-commentsでコメントを取得し、1つずつ対応する。
文の分割ミスが含まれる場合は、ステップ3に戻って話者ターンで再分割する。誤った分割の上にパッチを当ててはいけない。
リソース
scripts/parse_srt.py— SRT → 話者ターンパラグラフJSONscripts/build_doc.py— パラグラフ+翻訳 → Feishu XMLフラグメント(書式は組み込み済み)references/fetch-srt.md— 字幕取得のフォールバックチェーン(重要)references/clean-translate.md— クリーニング/翻訳/書式仕様references/publish-lark.md— lark-docでのドキュメント作成と追記、コメント取得references/whiteboard-summary.md— beautiful-feishu-whiteboardを使用した視覚的サマリーホワイトボード生成(「テキストは必ず薄い背景の上に」という落とし穴を含む)