GitHub - jdepoix/youtube-transcript-api: This is a python API which allows you to get the transcript/subtitles for a given YouTube video. It also works for automatically generated subtitles and it does not require an API key nor a headless browser, like other selenium based solutions do!

제공된 문서는 youtube-transcript-api라는 Python API에 대한 설명서입니다. 이 API는 특정 YouTube 비디오의 Transcript(자막)를 검색할 수 있도록 설계되었습니다. 핵심적인 특징은 YouTube에서 자동으로 생성된 자막에도 작동하며, API 키나 Selenium 기반 솔루션과 같은 Headless Browser가 필요하지 않다는 점입니다. 이는 YouTube의 비공식적인 내부 API를 직접 활용하여 데이터를 가져오는 방식을 채택하고 있음을 시사합니다.

핵심 방법론 및 기능:

Transcript 검색 (Fetching):

* YouTubeTranscriptApi 클래스의 인스턴스를 생성한 후, fetch(video_id) 메서드를 사용하여 Transcript를 가져옵니다. video_id는 YouTube 비디오 URL에서 추출한 고유 ID를 의미합니다.
* 기본적으로 영어 Transcript를 시도하지만, languages 매개변수를 통해 원하는 언어 코드 목록(우선순위 순)을 지정하여 다른 언어의 Transcript를 검색할 수 있습니다.
* 결과는 FetchedTranscript 객체로 반환됩니다. 이 객체는 text, start, duration과 같은 스니펫(Snippet) 정보를 포함하며, Python의 List처럼 반복(Iterable), 인덱싱(Indexable), 길이 확인(Length)이 가능합니다. Raw 데이터(리스트 형태의 딕셔너리)가 필요하면 to_raw_data() 메서드를 호출합니다.
* $preserve_formatting=True$ 옵션을 통해 HTML 형식(예: $<i>$, $<b>$)을 유지할 수 있습니다.

사용 가능한 Transcript 목록 조회:

* list(video_id) 메서드를 사용하여 특정 비디오에 사용 가능한 모든 Transcript 목록을 TranscriptList 객체로 얻을 수 있습니다.
* TranscriptList는 find_transcript(), find_manually_created_transcript(), find_generated_transcript()와 같은 필터링 메서드를 제공합니다. 이 메서드들은 Transcript 객체를 반환하며, 이 객체에는 자막의 video_id, language, language_code, is_generated (자동 생성 여부), is_translatable (번역 가능 여부), translation_languages (번역 가능한 언어 목록)와 같은 메타데이터가 포함됩니다.
* Transcript 객체의 fetch() 메서드를 호출하여 실제 자막 데이터를 FetchedTranscript 객체로 검색합니다.

Transcript 번역 (Translation):

* Transcript 객체는 translate(target_language_code) 메서드를 제공합니다. 이 메서드는 YouTube의 자동 번역 기능을 활용하여 새로운 Transcript 객체를 반환합니다. 이는 클라이언트 측에서 자체 번역을 수행하는 것이 아니라, YouTube 서버의 번역 기능을 이용한다는 것을 의미합니다.

IP 차단 우회 (Proxy 지원):

* YouTube가 클라우드 IP 또는 과도한 요청으로 인한 IP 차단을 시작함에 따라, RequestBlocked 또는 IpBlocked 예외가 발생할 수 있습니다.
* 이를 우회하기 위해 Residential Proxy 사용을 권장하며, 특히 Rotating Proxy가 가장 안정적이라고 명시하고 있습니다.
* WebshareProxyConfig: Webshare 서비스를 통한 Residential Proxy 통합 지원을 제공합니다. 사용자 이름(proxy_username)과 비밀번호(proxy_password)를 사용하여 쉽게 구성할 수 있으며, 특정 국가의 IP로 제한(filter_ip_locations)할 수도 있습니다.
* GenericProxyConfig: Webshare 이외의 일반적인 HTTP/HTTPS/SOCKS Proxy를 수동으로 설정할 수 있도록 지원합니다. http_url 및 https_url을 통해 Proxy 주소를 지정합니다.
* 이러한 Proxy 지원은 API의 핵심 기능에 안정성을 추가하는 중요한 방법론적 확장입니다.

Request 기본값 재정의:

* requests.Session 객체를 http_client 매개변수로 전달하여 HTTP 요청의 기본값(예: 헤더, SSL 인증서, 쿠키 공유)을 사용자 정의할 수 있습니다.

Cookie 인증:

* 연령 제한 비디오 접근을 위해 Cookie 기반 인증 기능이 있었으나, 현재는 YouTube API 변경으로 인해 비활성화되어 있습니다.

Formatter 모듈:

* 검색된 FetchedTranscript 객체를 특정 형식(예: JSON, WebVTT, SRT, 일반 텍스트)의 문자열로 변환하는 Formatter 서브모듈을 제공합니다.
* JSONFormatter, TextFormatter, WebVTTFormatter, SRTFormatter 등의 내장 Formatter가 있으며, 사용자 정의 Formatter 클래스를 구현할 수도 있습니다. format_transcript() 또는 format_transcripts() 메서드를 오버라이드하여 사용자 로직을 추가합니다.

명령줄 인터페이스 (CLI):

* Python API와 동일한 기능을 명령줄에서도 사용할 수 있도록 CLI를 제공합니다.
* $youtube_transcript_api <video_id> ...$ 형식으로 사용하며, 언어 지정(--languages), 특정 유형(자동/수동) 제외(--exclude-generated, --exclude-manually-created), 출력 형식 지정(--format), 번역(--translate), 사용 가능한 Transcript 목록 조회(--list-transcripts), Proxy 설정(--webshare-proxy-username, --http-proxy) 등 다양한 옵션을 지원합니다.

경고:

* 이 API는 YouTube의 Undocumented API를 사용하므로, YouTube 측의 변경에 따라 작동이 중단될 가능성이 있음을 명시하고 있습니다. 그러나 개발자가 문제가 발생하면 신속하게 대응할 것임을 약속합니다.

결론적으로, youtube-transcript-api는 YouTube 비디오 Transcript를 빠르고 효율적으로 검색, 필터링, 번역하며, IP 차단과 같은 잠재적 문제에 대한 해결책까지 제공하는 포괄적인 Python 라이브러리입니다. 핵심은 YouTube의 내부 API를 직접 활용하여 외부 의존성(API 키, 브라우저)을 최소화하고, 사용 편의성을 극대화하는 데 있습니다.