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