Communitygithub.com

Aikoin/youtube-transcript-doc

將 YouTube 影片轉換為精美、雙語、附可點擊時間戳的飛書逐字稿文件 — 適用於 Mira/Claude 的技術。

youtube-transcript-doc 是什麼?

這個 AI 技術(技術)的目標是將 YouTube 影片(或任何附字幕的影片)自動轉換為一篇結構化、可讀性高、且可直接用於飛書的逐字稿文檔。它不僅提取字幕,還會進行清理(刪除語氣詞、口吃、ASR 錯誤)、分段翻譯(支援中英雙語)、並按照說話人段落進行分割,徹底解決「一句話被切成兩段」的痛點。技術支援從影片 URL 提取影片 ID、抓取 SRT 字幕(透過第三方字幕站點降級鏈)、解析說話人段落、清洗與翻譯、並生成符合飛書版式(英文灰色、中文黑色、不整段高亮)的 XML 片段。最後透過 lark-doc 技術發佈到飛書。此技術特別適合開發者、研究員、或任何需要將影片內容整理成會議記錄、學習筆記或知識庫的人。它也能生成可視化總結白板(SVG 手動排版),並處理飛書白板的文字顏色渲染問題(文字必須放在淺色背景上)。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add Aikoin/youtube-transcript-doc

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 → 說話人段落 JSON
  • scripts/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 生成可視化總結白板(包含「文字必須上淺底」的踩坑)

相關技能