jdepoix/youtube-transcript-api

What is this?

youtube-transcript-api is a Python library that lets you fetch the transcript (subtitles) of a YouTube video. It works with both manually created subtitles and YouTube's auto-generated ones, can translate subtitles, and doesn't need a browser (unlike some other tools).

How to install

Use pip:

pip install youtube-transcript-api

Basic usage

Get the transcript for a video by passing its video ID (not the full URL). For example, for https://www.youtube.com/watch?v=12345, the ID is 12345.

from youtube_transcript_api import YouTubeTranscriptApi

ytt_api = YouTubeTranscriptApi()
transcript = ytt_api.fetch(video_id)

By default, it tries to get the English transcript. The returned object behaves like a list: you can iterate over it, index it, and get its length. Each snippet has text, start (seconds), and duration (seconds).

You can also get the raw data as a list of dictionaries with transcript.to_raw_data().

Choosing a language

Pass a list of language codes in order of preference:

ytt_api.fetch(video_id, languages=['de', 'en'])  # tries German first, then English

Listing available transcripts

To see all transcripts for a video:

transcript_list = ytt_api.list(video_id)

You can filter by language and type (manually created vs. auto-generated):

transcript = transcript_list.find_transcript(['de', 'en'])
transcript = transcript_list.find_manually_created_transcript(['de', 'en'])
transcript = transcript_list.find_generated_transcript(['de', 'en'])

Each Transcript object has metadata (video ID, language, whether it's generated, whether it can be translated, etc.) and a .fetch() method to get the actual transcript.

Translating subtitles

You can translate a transcript to another language:

translated = transcript.translate('de')
translated.fetch()

Handling IP bans

YouTube sometimes blocks cloud IPs. The library supports using proxies. It has built‑in support for Webshare rotating residential proxies, or you can use any generic HTTP/HTTPS/SOCKS proxy via GenericProxyConfig.

Custom HTTP settings

You can pass your own requests.Session to set headers, SSL certificates, or share cookies between instances.

Formatters

The library includes formatters to convert a transcript into common formats like JSON, text, SRT, WebVTT, etc. You can also create your own formatter by subclassing Formatter.

CLI

There's also a command‑line tool:

youtube_transcript_api <video_id_1> <video_id_2> ...

It prints the transcripts to the terminal.

Note on age‑restricted videos

Cookie‑based authentication is currently broken, so age‑restricted videos may not be accessible.

---

All information above is taken directly from the project's README.