This paper describes the youtube-transcript-api Python library, an open-source tool designed to programmatically retrieve transcripts and subtitles for YouTube videos. The primary goal of the library is to provide a lightweight, efficient, and self-contained solution that does not require an API key, nor reliance on headless browsers or Selenium, which are common with other transcript extraction methods.

The core methodology of the library involves reverse-engineering and utilizing an undocumented part of the YouTube API, specifically the internal endpoints that the YouTube web-client itself uses to fetch transcript data. This approach allows the library to bypass the limitations and overhead associated with official API rate limits or browser automation. The library directly makes HTTP requests to these internal YouTube endpoints, parses the returned data, and structures it into user-friendly Python objects. It effectively handles both manually created and automatically generated subtitles, and crucially, supports translation of these subtitles.

Key functionalities include:

• Transcript Fetching: Users can retrieve transcripts for a given video_id using YouTubeTranscriptApi().fetch(video_id). By default, it attempts to fetch English transcripts but allows specifying a list of preferred language codes (e.g., ['de', 'en']) in descending priority. The fetched data is encapsulated in a FetchedTranscript object, which behaves like a list of FetchedTranscriptSnippet objects, each containing text, start time, and duration. A to_raw_data() method provides the data as a list of dictionaries: [{'text': '...', 'start': 0.0, 'duration': 1.54}, ...]. The FetchedTranscript object also includes metadata such as video_id, language, language_code, and is_generated.
• Transcript Listing and Filtering: The YouTubeTranscriptApi().list(video_id) method returns a TranscriptList object, which allows users to discover all available transcripts for a video. This object supports filtering to find specific transcript types, such as find_transcript(), find_manually_created_transcript(), or find_generated_transcript(). These methods return Transcript objects, which contain metadata (e.g., is_generated, is_translatable, translation_languages) and a fetch() method to retrieve the actual transcript data.
• Transcript Translation: The library leverages YouTube's automatic translation feature. A Transcript object can be translated using its translate(target_language_code) method, which returns a new Transcript object representing the translated version.
• Proxy Support and IP Ban Workarounds: Recognizing that YouTube actively blocks IPs from cloud providers or those making excessive requests, the library provides robust proxy configuration. It offers specialized integration with Webshare's residential rotating proxies via WebshareProxyConfig, allowing users to specify credentials and filter IP locations. Alternatively, a GenericProxyConfig class supports any standard HTTP/HTTPS/SOCKS proxy. This mechanism, based on requests.Session, helps mitigate RequestBlocked or IpBlocked exceptions by rotating through a pool of proxy addresses.
• Custom requests.Session Integration: For advanced users, the library allows injecting a pre-configured requests.Session object into the YouTubeTranscriptApi constructor. This enables fine-grained control over HTTP client settings, such as custom headers, SSL verification, or cookie sharing across multiple instances.
• Formatters: A formatters submodule provides utilities to convert FetchedTranscript objects into various string formats. Built-in formatters include JSONFormatter, TextFormatter, WebVTTFormatter, and SRTFormatter. Users can also implement custom formatters by inheriting from the Formatter base class.
• Command-Line Interface (CLI): The library exposes its core functionalities via a CLI, allowing users to fetch, list, and translate transcripts directly from the command line, with options for language preferences, exclusion of certain transcript types, output formatting (e.g., JSON), and proxy configuration.

Limitations and Warnings:
A significant caveat is the reliance on an undocumented YouTube API. This means the library's functionality is subject to breakage if YouTube alters its internal API structure, necessitating prompt updates from the maintainers. Additionally, while cookie-based authentication for age-restricted videos was planned, the current implementation is noted as broken due to recent changes in YouTube's authentication mechanisms. The persistent challenge of IP bans from YouTube means that even with proxy solutions, reliability is maximized by using rotating proxy pools.