Communitygithub.com

Aikoin/youtube-transcript-doc

YouTube 영상을 정교한 이중 언어·클릭 가능 타임스탬프의 Feishu/Lark 문서로 변환합니다 — Mira/Claude 스킬.

youtube-transcript-doc란 무엇인가요?

이 스킬은 YouTube 동영상(또는 자막이 있는 모든 동영상)의 자막을 추출하고 정리하여, Feishu/Lark에서 바로 읽고 시간戳을 클릭해 이동할 수 있는 전문적인 문서를 생성합니다. 전체 파이프라인은 동영상 링크 처리부터 SRT 자막 다운로드(third-party 사이트 우회, 브라우저 수동 다운로드 등 내성적인 폴백 체인), 화자 기준 문단 분할(`scripts/parse_srt.py`), 잡음 제거 및 번역(`references/clean-translate.md`), 그리고 `content.json` 구조를 통해 Feishu XML 조각 생성(`scripts/build_doc.py`)을 포함합니다. 최종적으로 lark-doc skill을 통해 Feishu에 게시되며, 사용자는 옵션으로 아름다운 SVG 화이트보드 요약(beautiful-feishu-whiteboard 방식)을 추가할 수 있습니다. 이 스킬은 Cursor, Claude Code 등에서 사용하기에 적합하며, 사용자 피드백(코멘트)을 반영한 반복 개선도 지원합니다. 특히 Feishu 화이트보드에서 모든 텍스트는 반드시 밝은 배경(크림/노랑)에 진한 잉크 색상으로 배치해야 한다는 중요한 레이아웃 규칙이 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add Aikoin/youtube-transcript-doc

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

YouTube 영상 → 정제된 기록 문서

YouTube(또는 자막이 있는) 동영상을 읽기 쉽고, 이동 가능하며, 보관 가능한 Feishu(飞书) 기록 문서로 만듭니다.

전체 흐름: 동영상 읽기 → SRT 가져오기 → 문단 분석 → 정제+번역 → Feishu 문서 생성 → (선택) 시각적 요약 화이트보드

언제 사용하나

사용자가 동영상 링크를 주며 기록문 / 타임라인 / 회의록 정리 / 자막 추출 / 중영 대조 / "이 동영상을 보고 정리해줘" 요청을 할 때 사용합니다.

프로세스

1. video_id 및 기본 정보 얻기

URL에서 11자리 video id를 추출합니다. 가능하다면 제목, 길이, 게스트/게시자를 함께 기록하여 문서 헤더 정보 상자에 넣습니다.

2. 자막 가져오기 (가장 쉽게 막히는 단계)

YouTube에 직접 연결하여 자막을 가져오는 것은 거의 항상 차단됩니다. 끈질기게 하지 마세요. references/fetch-srt.md의 폴백 체인을 따르세요:

  • Third-party 자막 사이트 (downsub 우선, remote browser로 열기 → download.subtitle.to 다운로드 blob 추출 → curl로 직접 가져오기)
  • 브라우저로 페이지 텍스트 스크래핑 → 사용자 수동 내보내기

가져온 후 transcript.srt로 저장합니다.

3. 화자 문단으로 분석

python scripts/parse_srt.py transcript.srt --video-id <VIDEO_ID> --out turns.json

>> 화자 표시로 분할 (표시가 없으면 고정 길이 분할로 폴백). 이 단계가 "한 문장이 두 조각으로 나뉘는" 문제를 근본적으로 해결합니다 — 이전에는 고정 초 단위로 강제 분할하면 문장이 중간에 잘렸지만, 화자 turn 단위로 분할하면 각 단락이 완전한 발화가 됩니다. 스크립트는 또한 순수 감탄사의 독립 단락을 제거합니다.

4. 정제 + 번역

references/clean-translate.md를 따라: 감탄사 제거, 더듬는 반복 제거, ASR 오류(이름/용어/회사명) 수정, 단락별 번역. 약 100단락 정도면 2-3개 배치로 나누어 병렬 서브 에이전트로 처리하며, 공유 용어 수정 테이블을 사용하고 각각 {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. Feishu에 게시

lark-doc skill (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로 댓글을 가져와 하나씩 처리합니다. 단락 분할 오류가 있으면 3단계로 돌아가 화자 turn으로 다시 분할하고, 잘못된 분할 위에 패치를 하지 마세요.

리소스

  • scripts/parse_srt.py — SRT → 화자 단락 JSON
  • scripts/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를 사용한 시각적 요약 화이트보드 생성 ("텍스트는 반드시 밝은 배경 위에" 함정 포함)

관련 스킬