YouTube 影片 → 精修逐字稿文檔
將一條 YouTube(或附字幕的)影片,製作成一篇可讀、可跳轉、可沉澱的飛書逐字稿文檔。
整條鏈路:讀到影片 → 抓取 SRT → 解析成段落 → 清洗+翻譯 → 生成飛書文檔 →(選用)可視化總結白板。
何時使用
使用者丟來一個影片連結,想要逐字稿 / 時間軸 / 會議記錄式整理 / 字幕提取 / 中英對照 / 「幫我看看這個影片並整理出來」。
流程
1. 取得影片 ID 與基本資訊
從 URL 提取 11 位影片 ID。若能順手取得標題、時長、來賓/發佈者,記下來——寫進文檔頭部資訊框。
2. 抓取字幕(最容易卡住的一步)
直接連線 YouTube 取字幕基本上會被反爬蟲擋掉,不要硬碰硬。按照 references/fetch-srt.md 的降級鏈走:
第三方字幕站(downsub 首選,用 remote browser 開啟→提取 download.subtitle.to 下載 blob→curl 直接取得)
→ browser 抓取頁面文字 → 讓使用者手動匯出。取得後存成 transcript.srt。
3. 解析成說話人段落
python scripts/parse_srt.py transcript.srt --video-id <VIDEO_ID> --out turns.json
按照 >> 說話人標記切分(無標記則回退到固定長度切分)。這一步徹底根治「一句話被拆成兩段」——
之前按固定秒數硬切會攔腰截斷句子,按說話人 turn 切每個段落都是完整發言。腳本同時刪除純語氣詞的獨立段落。
4. 清洗 + 翻譯
按照 references/clean-translate.md:刪除語氣詞、刪除口吃重複、修復 ASR 錯誤(人名/術語/公司名)、
逐段翻譯。近百段時拆成 2–3 批使用並行子 agent 處理,共享一張術語修正表,各自輸出 {index:{en,zh}} 的 JSON,合併成一個 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. 發布到飛書
使用 lark-doc 技能(docs +create 建立文檔寫入 intro,再 docs +update --command append 逐節追加)。
呼叫細節見 references/publish-lark.md。發佈後將文檔網址提供給使用者。
6.(選用)生成可視化總結白板
使用者常在取得逐字稿後想要再一張提煉重點的可視化圖嵌入同一篇文檔。使用
beautiful-feishu-whiteboard 的思路
手工排列 SVG(不是 Mermaid 自動佈局),寫成飛書可編輯白板。完整流程與踩坑見
references/whiteboard-summary.md。
一條最關鍵、最容易翻車的鐵律:飛書白板渲染時會把文字強制壓成深色,所以
所有文字都要放在淺色底(奶油/黃)上用深墨色,彩色只用於邊框/色條/方塊標記/徽章,絕不要把文字放到飽和色塊上。
本地 PNG 預覽的文字顏色不可信,必須寫入後使用 +query --output_as image 回查線上真實圖形再確認對比度。
迭代
使用者常會在文檔裡留下評論再讓你修改。使用 lark-doc 的 +get-comments 拉取評論,逐條落實。
若涉及斷句錯誤——回到第 3 步使用說話人 turn 重新切割,不要在錯誤的分段上打補丁。
資源
scripts/parse_srt.py— SRT → 說話人段落 JSONscripts/build_doc.py— 段落+譯文 → 飛書 XML 片段(版式已內建)references/fetch-srt.md— 抓取字幕降級鏈(重點)references/clean-translate.md— 清洗/翻譯/版式規範references/publish-lark.md— lark-doc 建檔與追加、拉取評論references/whiteboard-summary.md— 使用 beautiful-feishu-whiteboard 生成可視化總結白板(包含「文字必須上淺底」的踩坑)