YouTube 트랜스크립트

개요

YouTube URL을 깔끔한 읽기용 문서로 변환합니다. 단순히 자막을 그대로 덤프하는 것이 아닙니다. YouTube의 네이티브 자막을 우선 사용하고, 자막이 없거나 사용할 수 없거나 실질적으로 불완전한 경우에만 음성-텍스트 변환(ASR)으로 대체합니다.

워크플로우

입력이 YouTube URL인지 확인합니다.
메타데이터를 수집하고 네이티브 자막 또는 자동 생성 자막의 가용 여부를 검사합니다.
트랜스크립트 예상 언어를 추출 전에 결정합니다. 사용자가 영어 트랜스크립트를 요청하면 --language en을 전달합니다. 사용자가 원어를 유지하도록 요청하면, 알려진 경우 음성 트랙을 선호합니다. 그렇지 않으면 확인될 때까지 언어를 미결정 상태로 처리합니다.
자막 추출이 ASR보다 빠르고 저렴하므로 자막 추출을 선호합니다.
가져오기 직후 report.json을 검사하고, 조립 또는 렌더링 전에 selected_language가 의도한 언어와 일치하는지 확인합니다.
자막 추출이 실패하거나, 실질적으로 불완전하거나, 사용 가능한 자막 트랙의 언어가 모호한 경우에만 ASR으로 대체합니다.
메타데이터를 수집합니다: 제목, 게시 날짜, 채널, URL, 그리고 사용 가능한 경우 소스 챕터.
트랜스크립트를 자막 조각이 아닌 읽기 가능한 문단으로 정규화합니다.
제목, 날짜, 소스 메타데이터, 요약, 챕터 목록 및 트랜스크립트 본문이 포함된 문서를 빌드합니다.
최종 결과물을 현재 프로젝트 폴더 안에 PDF로 저장합니다.
프롬프트에서 명시적으로 요청한 경우에만 중국어 번역을 추가합니다.

환경 계약

환경이 다음을 제공할 것으로 예상합니다:

python3
YouTube 페이지 및 모든 트랜스크립트 소스에 접근할 수 있는 네트워크
자막 우선 경로에 대한 메타데이터 및 자막 추출을 위한 yt-dlp
대체 경로를 위한 로컬 Whisper 호환 ASR 도구 또는 호스팅된 트랜스크립션 API
scripts/에 번들된 스크립트

필요한 기능이 없으면 정확히 어떤 종속성이 누락되었는지 말하고 트랜스크립트가 완료되었다고 주장하기 전에 중단하십시오.

소스 선택

자막 우선 경로

네이티브 자막 또는 자동 생성 YouTube 자막이 존재하는 경우 이 경로를 선호합니다.

먼저 메타데이터 및 자막 가용성을 가져옵니다.
의도한 언어로 된 최상의 자막 트랙을 다운로드합니다.
수동 자막과 자동 자막이 모두 있으면 수동 자막을 선호합니다.
사용자가 대상 트랜스크립트 언어를 지정하면 --language로 명시적으로 전달합니다.
사용자가 언어를 지정하지 않으면, 음성 언어가 알려져 있거나 신뢰할 수 있게 추론할 수 있는 경우에만 보존합니다. 사용 가능한 자막 트랙이 여러 언어에 걸쳐 있고 음성 언어를 알 수 없는 경우, 자막 경로를 중단하고 임의로 하나를 선택하는 대신 모호한 것으로 처리합니다.
자막이 부분적이거나, 동기화가 심하게 맞지 않거나, 큰 음성 부분이 누락된 경우 ASR로 전환합니다.
자막 가져오기 후 report.json을 검사하고 selected_language가 의도한 트랜스크립트 언어와 일치하지 않으면 결과를 거부합니다.

환경에서 사용 가능한 경우 유용한 도구:

메타데이터 및 자막 추출을 위한 yt-dlp
존재하는 경우 scripts/의 표준 추출 래퍼

ASR 대체 경로

자막 추출을 사용할 수 없거나 품질이 충분하지 않은 경우에만 ASR을 사용합니다.

YouTube 오디오를 다운로드하거나 액세스합니다.
알려진 경우 소스 언어로 트랜스크립션을 실행합니다.
트랜스크립트에 원래 언어를 보존합니다.
기본적으로 번역하지 마십시오.
최종 읽기 가능한 문서 및 PDF의 진실 공급원(source of truth)으로 트랜스크립트를 사용합니다.

사용 가능한 경우 일반적인 옵션:

로컬 Whisper / faster-whisper
호스팅된 트랜스크립션 API

실패 정책

다음 중 하나라도 해당되면 중단하고 실패를 설명하십시오:

입력이 유효한 YouTube URL이 아님
메타데이터를 가져올 수 없음
자막을 사용할 수 없고 ASR 대체 수단도 없음
ASR 경로에 대한 오디오 다운로드 실패
트랜스크립트가 신뢰할 수 있는 요약을 지원하기에는 너무 불완전함

작업이 가능하지만 품질이 제한된 경우 경고와 함께 계속 진행하십시오:

자막이 존재하지만 부분적이거나, 노이즈가 있거나, 동기화가 맞지 않는 것으로 보임
ASR이 완료되었지만 구두점이나 화자 경계가 약함
챕터 경계를 노이즈가 있는 트랜스크립트 텍스트에서 추론해야 함

다음과 같은 경우 중단하고 명시적인 언어로 다시 실행하십시오:

사용자가 영어 트랜스크립트를 기대했는데 report.json이 영어가 아닌 트랙을 선택함
사용자가 소스 언어 보존을 기대했지만 선택한 자막 언어가 모호하거나 명확히 번역된 것임

출력 계약

사용자가 달리 요청하지 않는 한, 현재 프로젝트 폴더에 다음을 포함하는 깔끔한 PDF를 생성하십시오:

제목
게시 날짜
채널 또는 출처가 포함된 소스 줄
요약 또는 부제
상단 근처의 챕터 목록
원래 언어의 읽기 가능한 트랜스크립트 본문
유용한 경우에만 대략적인 타임스탬프 마커(예: 20분마다)

주요 결과물로 거대한 구조화되지 않은 자막 텍스트 블록을 반환하지 마십시오.

포맷팅 규칙

Harness Engineering 기사와 같은 OpenAI 롱폼 게시물을 모델로 하여 여유로운 공백, 강력한 제목 계층, 간결한 메타데이터, 명확한 섹션 구분 및 읽기 가능한 문단 너비를 적용합니다.

YouTube Transcript와 같은 오버라인 또는 섹션 레이블로 시작합니다.
제목을 먼저 배치합니다.
1페이지에는 반복되는 페이지 헤더 레이블과 상단 구분선 블록을 넣지 않습니다.
2페이지부터는 상단 구분선의 페이지 상단으로부터의 거리가 하단 구분선의 페이지 하단으로부터의 거리와 일치하도록 배치합니다.
2페이지부터 상단 구분선 바로 위에 Sissi Skill - YouTube Transcript to PDF 페이지 레이블을 배치합니다.
제목 바로 아래에 게시 날짜와 소스 메타데이터를 배치합니다.
문서 상단 근처에 챕터 목록을 배치합니다.
챕터 메타데이터가 존재하는 경우 트랜스크립트 본문 내 해당 위치에 챕터 제목을 다시 삽입합니다.
문단을 짧고 읽기 쉽게 유지합니다.
본문 문단을 양쪽 정렬하여 텍스트 블록 너비가 구분선 너비와 일치하도록 합니다.
자막 조각을 산문 스타일의 문단으로 병합합니다.
자막 분할로 인한 중복 반복을 제거합니다.
편집상 유용하지 않는 한 반복되는 화살표나 독립형 음악 표시기와 같은 명백한 노이즈를 제거합니다.
화자 이름을 임의로 만들지 마십시오.
조밀한 타임스탬프 노이즈를 내보내지 마십시오.
탐색 보조 수단으로만 20분 마커를 삽입합니다.
동영상이 20분 미만이면 마커를 완전히 생략합니다.
모든 페이지에 바닥글 공백 밴드를 예약하고 회색 가로선으로 본문 텍스트와 분리합니다.
본문 텍스트가 바닥글 구분선에 가깝게 실행되도록 하여 최종 줄이 겹치지 않고 대략 한 줄 위에 놓이도록 합니다.

가독성 휴리스틱

자막을 정규화할 때:

겹치는 자막 창에서 정확히 반복되는 내용을 중복 제거합니다.
시간 간격, 문장 끝 및 문단 길이로 긴 텍스트를 문단으로 분할합니다.
자막 스트림이 아닌 에세이 산문처럼 느껴지는 문단 길이를 선호합니다.
소스가 제공하는 경우 구두점을 보존합니다.
소스 구두점이 좋지 않은 경우 가독성에 필요한 최소한의 구두점만 추가합니다.

요약 및 챕터

트랜스크립트를 구축한 후 다음을 생성합니다:

동영상의 주요 주장이나 핵심 내용에 초점을 맞춘 간결한 요약
짧은 제목이 있는 챕터 목록

소스 데이터에 이미 신뢰할 수 있는 챕터 메타데이터가 포함되어 있으면 재사용합니다. 그렇지 않으면 트랜스크립트의 주제 전환에서 챕터를 추론합니다.

예제

예제 1: 팟캐스트 트랜스크립트 패키지

사용자: "이 YouTube 인터뷰를 깔끔한 PDF 트랜스크립트로 만들어 줘."
작업:
1. 메타데이터 및 자막 가용성 가져오기.
2. 사용 가능한 경우 수동 자막 선호.
3. 트랜스크립트 문단 정규화.
4. 요약 및 챕터 목록 생성.
5. 현재 프로젝트 폴더에 PDF 렌더링.
결과: 기사 스타일의 트랜스크립트 PDF와 요약 및 챕터 분석.

예제 2: 기조연설에서 요약 및 트랜스크립트

사용자: "이 기조연설에서 트랜스크립트를 추출하고 각 섹션을 요약해 줘."
작업:
1. 자막 추출 또는 ASR 대체 사용.
2. 소스 챕터가 있으면 재사용하고, 그렇지 않으면 추론.
3. 챕터 구조에 맞춘 간결한 요약 작성.
4. 최종 PDF를 저장하고 요약을 채팅에 반환.
결과: 원시 자막 텍스트 대신 사용 가능한 읽기 자료.

예제 3: 소스 언어 보존

사용자: "이 스페인어 YouTube 강연에서 읽기 가능한 트랜스크립트를 만들어 줘."
작업:
1. 스페인어 트랜스크립트 보존.
2. 명시적으로 요청하지 않는 한 번역하지 않음.
3. 자막이 약한 경우 소스 품질 문제 표시.
결과: 정직한 품질 노트가 포함된 스페인어 트랜스크립트 패키지.

예제 4: 명시적 번역 요청

사용자: "이 YouTube 동영상에서 트랜스크립트 PDF를 만들고 중국어 번역을 추가해 줘."
작업:
1. 먼저 소스 트랜스크립트 추출.
2. 다듬어진 소스 언어 트랜스크립트 생성.
3. 명시적으로 요청되었으므로 중국어 번역 추가.
결과: 소스 텍스트와 번역된 텍스트를 명확히 구분하는 트랜스크립트 패키지.

출력 위치

사용자가 다른 경로를 요청하지 않는 한 최종 PDF를 현재 프로젝트 폴더 안에 저장합니다. 동영상 제목에서 파생된 슬러그 파일명을 선호합니다.

예:

./cult-leaders-have-terrible-pitches.pdf

도우미 스크립트

scripts/fetch_youtube_transcript.py를 표준 추출 진입점으로 사용합니다. URL 유효성 검사, 메타데이터 가져오기, 자막 선택, 품질 검사 및 선택적 ASR 대체를 중앙 집중화하므로 흐름에서 첫 번째 스크립트여야 합니다. 자막을 사용할 수 없고 오디오를 다운로드할 수 있는 경우 scripts/asr_faster_whisper.py를 사용합니다. 로컬 faster-whisper 모델을 사용하여 대체 경로에 대한 세그먼트 JSON을 작성합니다.

scripts/assemble_transcript.py를 사용하여 시간이 지정된 세그먼트를 거친 마커가 있는 읽기 가능한 트랜스크립트 산문으로 변환합니다. 챕터 제목을 정확한 위치의 트랜스크립트 본문에 삽입해야 하는 경우 동일한 스크립트에서 문단 메타데이터 JSON도 작성하여 PDF 렌더러에 전달합니다. 신뢰할 수 있는 소스 챕터가 존재하는 경우 assemble_transcript.py에 전달하여 PDF 렌더링 전에 문단 경계가 챕터 경계와 정렬되도록 합니다.

scripts/render_blog_pdf.py를 사용하여 외부 PDF 종속성 없이 메타데이터, 요약, 챕터 및 트랜스크립트 텍스트를 깔끔한 PDF로 변환합니다. 개발 중에는 scripts/validate_transcript_skill.py를 사용하여 VTT 구문 분석, 중복 정리, 마커 삽입, 챕터 인식 트랜스크립트 메타데이터 및 PDF 렌더링에 대한 오프라인 회귀 검사를 실행합니다. 배포 전에 scripts/package_skill_release.py를 사용하여 README.md, .git/, tests/ 및 __pycache__와 같은 리포지토리 전용 파일을 제외하는 깔끔한 zip을 빌드합니다.

일반적인 흐름:

python scripts/fetch_youtube_transcript.py "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir ./youtube_transcript_work --language en
sed -n '1,120p' ./youtube_transcript_work/report.json
python scripts/asr_faster_whisper.py ./downloaded-audio.m4a --output ./youtube_transcript_work/segments.json --model small --device cpu --compute-type int8 --beam-size 1 --vad-filter
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt --metadata-output transcript-metadata.json --chapter-breaks-json ./youtube_transcript_work/chapters.json
# 그런 다음 ./youtube_transcript_work/metadata.json에서 제목/날짜/채널을 읽고 렌더러에 전달합니다.
python scripts/render_blog_pdf.py \
  --title "Cult Leaders Have Terrible Pitches" \
  --date "2025-09-16" \
  --channel "The Knowledge Project Podcast" \
  --summary-file summary.txt \
  --chapters-json ./youtube_transcript_work/chapters.json \
  --transcript-metadata-json transcript-metadata.json \
  --transcript transcript.txt \
  --output ./cult-leaders-have-terrible-pitches.pdf
python scripts/validate_transcript_skill.py
python scripts/package_skill_release.py

품질 검사

결과를 반환하기 전에 다음을 확인하십시오:

트랜스크립트 언어가 명시적으로 번역을 요청하지 않는 한 소스 콘텐츠와 일치함
report.json에 의도한 트랜스크립트 언어와 일치하는 selected_language가 표시됨
트랜스크립트가 실질적으로 완전함
챕터 목록이 일관됨
소스 챕터가 있는 경우 인라인 챕터 제목이 올바른 트랜스크립트 위치에 나타남
인접한 챕터 타임스탬프가 1분 미만으로 떨어져 있으면 단일 인라인 챕터 제목으로 축소
트랜스크립트 본문 내 인라인 챕터 제목에서 타임스탬프 생략
문서에 제목, 날짜 및 소스 메타데이터가 있음
PDF가 프로젝트 폴더 내에 성공적으로 기록됨
본문 텍스트가 구분선 규칙과 동일한 너비로 양쪽 정렬됨
본문 텍스트가 바닥글 공백 밴드로 넘어가는 페이지가 없음
최종 문서가 원시 자막이 아닌 기사로 읽을 수 있음

추출 품질이 좋지 않으면 간략히 말하고 약점이 소스 자막에서 오는지 ASR에서 오는지 밝히십시오.

문제 해결

자막을 찾을 수 없음

원인: 동영상에 수동 또는 자동 생성 자막이 없습니다.
조치: ASR 종속성을 사용할 수 있는 경우에만 ASR을 사용하십시오. 그렇지 않으면 중단하고 누락된 기능을 보고하십시오.

자막이 불완전해 보임

원인: 자막 트랙이 음성 부분을 생략하거나 실질적으로 동기화가 맞지 않습니다.
조치: ASR을 사용할 수 있는 경우 전환하고 자막 경로가 거부된 이유를 설명하십시오.

잘못된 언어 트랙 선택

원인: 여러 자막 트랙이 존재하고 자동으로 잘못된 트랙이 선택되었습니다.
조치: 대상 언어를 알고 있는 경우 명시적인 --language와 함께 fetch_youtube_transcript.py를 다시 실행하십시오. 음성 언어를 알 수 없고 사용 가능한 자막 트랙이 다국어인 경우 임의로 선택하는 대신 자막 경로를 모호한 것으로 중단하십시오.

ASR 대체 사용 불가

원인: 로컬 또는 호스팅된 트랜스크립션 경로가 없습니다.
조치: 트랜스크립트가 완료된 것처럼 가장하는 대신 누락된 종속성을 보고하십시오.

PDF가 렌더링되지만 포맷이 저하됨

원인: 트랜스크립트 블록이 너무 길거나, 메타데이터가 누락되었거나, 챕터 배치에 노이즈가 있습니다.
조치: 파일을 반환하기 전에 트랜스크립트 정규화, 챕터 입력 및 렌더링 입력을 다시 확인하십시오.

사용자가 요약만 원함

원인: 사용자가 전체 트랜스크립트 없이 요약을 요청했습니다.
조치: 챕터 제목이 있는 간결한 요약만 생성하십시오.

SissiMeow/codex-skill-YouTube-Transcript-PDF

codex-skill-YouTube-Transcript-PDF란 무엇인가요?

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

문서