youtube-transcript-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3a1c99bcacf517440c8be67c4e72f29406c2a7cee87cb844317a5693d5f1aea
-  data.tar.gz: d19bc462f35d6d50dd13c452b3be468c5efb57bf5cdb894c22ad99be409485da
+  metadata.gz: 6d97023aca42aac08e42c3857d940e3a42ba735c895685522048caee415fe4af
+  data.tar.gz: 1d435b06743716beb8f3e892bc97a2c7d105f6ab710f61659cd24dd6ce438a81
 SHA512:
-  metadata.gz: b87fab280855a4f3f3b22786789085349492d42dd8fff3b14284b762c656757c8bd07fcfbc084ed551bd489c60ab175e4e57216edcd93c27345cfbeac53507f8
-  data.tar.gz: bba30d381a9a685e8c6f1bfeae9fdb40a81a758142a3c0c1659cc1de182266bcb6d85cff575ffade9559c945c9ae23e4c829e10821955605974ee12d499e61e3
+  metadata.gz: 5b5f345ebcef944ba98ae4adcc42d9951c5e04bf0230e98c18dc41e0b3b715cfe57a34722924042cbcf9b7244d00ad31767bc2ce287136656c2b05b3378f2db8
+  data.tar.gz: 07ba07e26a8ff0f895c64767869bda918122c35b21b39b945fc608067d864643712386987155e3ae1dbe24f5310410e642aa58fd03f1c15f4df358567a51fae2

data/README.md

@@ -47,9 +47,9 @@ gem install youtube-transcript-rb
 The easiest way to get a transcript for a given video is to execute:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 api.fetch(video_id)
 ```
 
@@ -62,14 +62,14 @@ api.fetch(video_id)
 This will return a `FetchedTranscript` object looking somewhat like this:
 
 ```ruby
-#<Youtube::Transcript::Rb::FetchedTranscript
+#<YoutubeRb::Transcript::FetchedTranscript
   @video_id="12345",
   @language="English",
   @language_code="en",
   @is_generated=false,
   @snippets=[
-    #<Youtube::Transcript::Rb::TranscriptSnippet @text="Hey there", @start=0.0, @duration=1.54>,
-    #<Youtube::Transcript::Rb::TranscriptSnippet @text="how are you", @start=1.54, @duration=4.16>,
+    #<YoutubeRb::Transcript::TranscriptSnippet @text="Hey there", @start=0.0, @duration=1.54>,
+    #<YoutubeRb::Transcript::TranscriptSnippet @text="how are you", @start=1.54, @duration=4.16>,
     # ...
   ]
 >
@@ -78,7 +78,7 @@ This will return a `FetchedTranscript` object looking somewhat like this:
 This object implements `Enumerable`, so you can iterate over it:
 
 ```ruby
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 fetched_transcript = api.fetch(video_id)
 
 # is iterable
@@ -117,13 +117,13 @@ an array of hashes:
 You can also use the convenience methods on the module directly:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
 # Fetch a transcript
-transcript = Youtube::Transcript::Rb.fetch(video_id)
+transcript = YoutubeRb::Transcript.fetch(video_id)
 
 # List available transcripts
-transcript_list = Youtube::Transcript::Rb.list(video_id)
+transcript_list = YoutubeRb::Transcript.list(video_id)
 ```
 
 ### Retrieve different languages
@@ -132,7 +132,7 @@ You can add the `languages` param if you want to make sure the transcripts are r
 (it defaults to english).
 
 ```ruby
-Youtube::Transcript::Rb::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de', 'en'])
+YoutubeRb::Transcript::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de', 'en'])
 ```
 
 It's an array of language codes in a descending priority. In this example it will first try to fetch the german
@@ -142,7 +142,7 @@ which languages are available first, [have a look at `list`](#list-available-tra
 If you only want one language, you still need to format the `languages` argument as an array:
 
 ```ruby
-Youtube::Transcript::Rb::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de'])
+YoutubeRb::Transcript::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de'])
 ```
 
 ### Preserve formatting
@@ -151,7 +151,7 @@ You can also add `preserve_formatting: true` if you'd like to keep HTML formatti
 and `<b>` (bold).
 
 ```ruby
-Youtube::Transcript::Rb::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de', 'en'], preserve_formatting: true)
+YoutubeRb::Transcript::YouTubeTranscriptApi.new.fetch(video_id, languages: ['de', 'en'], preserve_formatting: true)
 ```
 
 ### List available transcripts
@@ -159,7 +159,7 @@ Youtube::Transcript::Rb::YouTubeTranscriptApi.new.fetch(video_id, languages: ['d
 If you want to list all transcripts which are available for a given video you can call:
 
 ```ruby
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 transcript_list = api.list(video_id)
 ```
 
@@ -220,9 +220,9 @@ puts translated_transcript.fetch
 ### By example
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 
 # retrieve the available transcripts
 transcript_list = api.list('video_id')
@@ -262,7 +262,7 @@ transcript = transcript_list.find_generated_transcript(['de', 'en'])
 You can fetch transcripts for multiple videos at once:
 
 ```ruby
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 
 # Fetch multiple videos
 transcripts = api.fetch_all(['video1', 'video2', 'video3'])
@@ -297,14 +297,14 @@ The `Formatters` module provides a few basic formatters:
 Here is how to import from the `Formatters` module:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
 # Some provided formatter classes, each outputs a different string format.
-Youtube::Transcript::Rb::Formatters::JSONFormatter
-Youtube::Transcript::Rb::Formatters::TextFormatter
-Youtube::Transcript::Rb::Formatters::PrettyPrintFormatter
-Youtube::Transcript::Rb::Formatters::WebVTTFormatter
-Youtube::Transcript::Rb::Formatters::SRTFormatter
+YoutubeRb::Transcript::Formatters::JSONFormatter
+YoutubeRb::Transcript::Formatters::TextFormatter
+YoutubeRb::Transcript::Formatters::PrettyPrintFormatter
+YoutubeRb::Transcript::Formatters::WebVTTFormatter
+YoutubeRb::Transcript::Formatters::SRTFormatter
 ```
 
 ### Formatter Example
@@ -312,12 +312,12 @@ Youtube::Transcript::Rb::Formatters::SRTFormatter
 Let's say we wanted to retrieve a transcript and store it to a JSON file. That would look something like this:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
 transcript = api.fetch(video_id)
 
-formatter = Youtube::Transcript::Rb::Formatters::JSONFormatter.new
+formatter = YoutubeRb::Transcript::Formatters::JSONFormatter.new
 
 # .format_transcript(transcript) turns the transcript into a JSON string.
 json_formatted = formatter.format_transcript(transcript)
@@ -334,7 +334,7 @@ Since `JSONFormatter` leverages `JSON.generate` you can also forward keyword arg
 `.format_transcript(transcript)` such as making your file output prettier:
 
 ```ruby
-json_formatted = Youtube::Transcript::Rb::Formatters::JSONFormatter.new.format_transcript(
+json_formatted = YoutubeRb::Transcript::Formatters::JSONFormatter.new.format_transcript(
   transcript, 
   indent: '  ',
   space: ' '
@@ -346,9 +346,9 @@ json_formatted = Youtube::Transcript::Rb::Formatters::JSONFormatter.new.format_t
 You can also use the `FormatterLoader` to dynamically load formatters by name:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
-loader = Youtube::Transcript::Rb::Formatters::FormatterLoader.new
+loader = YoutubeRb::Transcript::Formatters::FormatterLoader.new
 
 # Load by type name: "json", "pretty", "text", "webvtt", "srt"
 formatter = loader.load("json")
@@ -364,7 +364,7 @@ You can implement your own formatter class. Just inherit from the `Formatter` ba
 `format_transcript` and `format_transcripts` methods which should ultimately return a string:
 
 ```ruby
-class MyCustomFormatter < Youtube::Transcript::Rb::Formatters::Formatter
+class MyCustomFormatter < YoutubeRb::Transcript::Formatters::Formatter
   def format_transcript(transcript, **options)
     # Do your custom work in here, but return a string.
     'your processed output data as a string.'
@@ -382,28 +382,28 @@ end
 The library provides a comprehensive set of exceptions for different error scenarios:
 
 ```ruby
-require 'youtube/transcript/rb'
+require 'youtube_rb/transcript'
 
 begin
-  transcript = Youtube::Transcript::Rb.fetch(video_id)
-rescue Youtube::Transcript::Rb::TranscriptsDisabled => e
+  transcript = YoutubeRb::Transcript.fetch(video_id)
+rescue YoutubeRb::Transcript::TranscriptsDisabled => e
   puts "Subtitles are disabled for this video"
-rescue Youtube::Transcript::Rb::NoTranscriptFound => e
+rescue YoutubeRb::Transcript::NoTranscriptFound => e
   puts "No transcript found for the requested languages"
   puts e.requested_language_codes
-rescue Youtube::Transcript::Rb::NoTranscriptAvailable => e
+rescue YoutubeRb::Transcript::NoTranscriptAvailable => e
   puts "No transcripts are available for this video"
-rescue Youtube::Transcript::Rb::VideoUnavailable => e
+rescue YoutubeRb::Transcript::VideoUnavailable => e
   puts "The video is no longer available"
-rescue Youtube::Transcript::Rb::TooManyRequests => e
+rescue YoutubeRb::Transcript::TooManyRequests => e
   puts "Rate limited by YouTube"
-rescue Youtube::Transcript::Rb::RequestBlocked => e
+rescue YoutubeRb::Transcript::RequestBlocked => e
   puts "Request blocked by YouTube"
-rescue Youtube::Transcript::Rb::IpBlocked => e
+rescue YoutubeRb::Transcript::IpBlocked => e
   puts "Your IP has been blocked by YouTube"
-rescue Youtube::Transcript::Rb::PoTokenRequired => e
+rescue YoutubeRb::Transcript::PoTokenRequired => e
   puts "PO token required - this is a YouTube limitation"
-rescue Youtube::Transcript::Rb::CouldNotRetrieveTranscript => e
+rescue YoutubeRb::Transcript::CouldNotRetrieveTranscript => e
   puts "Could not retrieve transcript: #{e.message}"
 end
 ```
@@ -456,11 +456,11 @@ http_client = Faraday.new do |conn|
   conn.adapter Faraday.default_adapter
 end
 
-api = Youtube::Transcript::Rb::YouTubeTranscriptApi.new(http_client: http_client)
+api = YoutubeRb::Transcript::YouTubeTranscriptApi.new(http_client: http_client)
 api.fetch(video_id)
 
 # Share same connection between two instances
-api_2 = Youtube::Transcript::Rb::YouTubeTranscriptApi.new(http_client: http_client)
+api_2 = YoutubeRb::Transcript::YouTubeTranscriptApi.new(http_client: http_client)
 api_2.fetch(video_id)
 ```
 

data/lib/youtube_rb/transcript/api.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/follow_redirects"
+
+module YoutubeRb
+  module Transcript
+    # Main entry point for fetching YouTube transcripts.
+    # This class provides a simple API for retrieving transcripts from YouTube videos.
+    #
+    # @example Basic usage
+    #   api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
+    #   transcript = api.fetch("dQw4w9WgXcQ")
+    #   transcript.each { |snippet| puts snippet.text }
+    #
+    # @example With language preference
+    #   api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
+    #   transcript = api.fetch("dQw4w9WgXcQ", languages: ["es", "en"])
+    #
+    # @example Listing available transcripts
+    #   api = YoutubeRb::Transcript::YouTubeTranscriptApi.new
+    #   transcript_list = api.list("dQw4w9WgXcQ")
+    #   transcript_list.each { |t| puts t }
+    #
+    class YouTubeTranscriptApi
+      # Default timeout for HTTP requests in seconds
+      DEFAULT_TIMEOUT = 30
+
+      # @param http_client [Faraday::Connection, nil] Custom HTTP client (optional)
+      # @param proxy_config [Object, nil] Proxy configuration (optional)
+      def initialize(http_client: nil, proxy_config: nil)
+        @http_client = http_client || build_default_http_client
+        @proxy_config = proxy_config
+        @fetcher = TranscriptListFetcher.new(
+          http_client: @http_client,
+          proxy_config: @proxy_config
+        )
+      end
+
+      # Fetch a transcript for a video.
+      # This is a convenience method that combines `list` and `find_transcript`.
+      #
+      # @param video_id [String] The YouTube video ID
+      # @param languages [Array<String>] Language codes in order of preference (default: ["en"])
+      # @param preserve_formatting [Boolean] Whether to preserve HTML formatting (default: false)
+      # @return [FetchedTranscript] The fetched transcript
+      # @raise [NoTranscriptFound] If no transcript matches the requested languages
+      # @raise [TranscriptsDisabled] If transcripts are disabled for the video
+      # @raise [VideoUnavailable] If the video is not available
+      #
+      # @example
+      #   api = YouTubeTranscriptApi.new
+      #   transcript = api.fetch("dQw4w9WgXcQ", languages: ["en", "es"])
+      #   puts transcript.first.text
+      #
+      def fetch(video_id, languages: ["en"], preserve_formatting: false)
+        list(video_id)
+          .find_transcript(languages)
+          .fetch(preserve_formatting: preserve_formatting)
+      end
+
+      # List all available transcripts for a video.
+      #
+      # @param video_id [String] The YouTube video ID
+      # @return [TranscriptList] A list of available transcripts
+      # @raise [TranscriptsDisabled] If transcripts are disabled for the video
+      # @raise [VideoUnavailable] If the video is not available
+      #
+      # @example
+      #   api = YouTubeTranscriptApi.new
+      #   transcript_list = api.list("dQw4w9WgXcQ")
+      #
+      #   # Find a specific transcript
+      #   transcript = transcript_list.find_transcript(["en"])
+      #
+      #   # Or iterate over all available transcripts
+      #   transcript_list.each do |transcript|
+      #     puts "#{transcript.language_code}: #{transcript.language}"
+      #   end
+      #
+      def list(video_id)
+        @fetcher.fetch(video_id)
+      end
+
+      # Fetch transcripts for multiple videos.
+      #
+      # @param video_ids [Array<String>] Array of YouTube video IDs
+      # @param languages [Array<String>] Language codes in order of preference (default: ["en"])
+      # @param preserve_formatting [Boolean] Whether to preserve HTML formatting (default: false)
+      # @param continue_on_error [Boolean] Whether to continue if a video fails (default: false)
+      # @yield [video_id, result] Block called for each video with either transcript or error
+      # @yieldparam video_id [String] The video ID being processed
+      # @yieldparam result [FetchedTranscript, StandardError] The transcript or error
+      # @return [Hash<String, FetchedTranscript>] Hash mapping video IDs to transcripts
+      # @raise [CouldNotRetrieveTranscript] If any video fails and continue_on_error is false
+      #
+      # @example Fetch multiple videos
+      #   api = YouTubeTranscriptApi.new
+      #   transcripts = api.fetch_all(["video1", "video2", "video3"])
+      #   transcripts.each { |id, t| puts "#{id}: #{t.length} snippets" }
+      #
+      # @example With error handling
+      #   api = YouTubeTranscriptApi.new
+      #   api.fetch_all(["video1", "video2"], continue_on_error: true) do |video_id, result|
+      #     if result.is_a?(StandardError)
+      #       puts "Error for #{video_id}: #{result.message}"
+      #     else
+      #       puts "Got #{result.length} snippets for #{video_id}"
+      #     end
+      #   end
+      #
+      def fetch_all(video_ids, languages: ["en"], preserve_formatting: false, continue_on_error: false)
+        results = {}
+
+        video_ids.each do |video_id|
+          begin
+            transcript = fetch(video_id, languages: languages, preserve_formatting: preserve_formatting)
+            results[video_id] = transcript
+            yield(video_id, transcript) if block_given?
+          rescue CouldNotRetrieveTranscript => e
+            if continue_on_error
+              yield(video_id, e) if block_given?
+            else
+              raise
+            end
+          end
+        end
+
+        results
+      end
+
+      private
+
+      # Build the default Faraday HTTP client
+      #
+      # @return [Faraday::Connection] The configured HTTP client
+      def build_default_http_client
+        Faraday.new do |conn|
+          conn.options.timeout = DEFAULT_TIMEOUT
+          conn.options.open_timeout = DEFAULT_TIMEOUT
+          conn.request :url_encoded
+          conn.response :follow_redirects
+          conn.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/youtube_rb/transcript/errors.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module YoutubeRb
+  module Transcript
+    # Base error class for all YouTube Transcript errors
+    class Error < StandardError; end
+
+    # Raised when a transcript could not be retrieved
+    class CouldNotRetrieveTranscript < Error
+      WATCH_URL = "https://www.youtube.com/watch?v=%<video_id>s"
+
+      # @return [String] the video ID that caused the error
+      attr_reader :video_id
+
+      # @param video_id [String] the YouTube video ID
+      def initialize(video_id)
+        @video_id = video_id
+        super(build_error_message)
+      end
+
+      # @return [String] the cause of the error
+      def cause_message
+        self.class::CAUSE_MESSAGE
+      end
+
+      private
+
+      def build_error_message
+        video_url = format(WATCH_URL, video_id: @video_id)
+        message = "\nCould not retrieve a transcript for the video #{video_url}!"
+
+        if cause_message && !cause_message.empty?
+          message += " This is most likely caused by:\n\n#{cause_message}"
+          message += github_referral
+        end
+
+        message
+      end
+
+      def github_referral
+        "\n\nIf you are sure that the described cause is not responsible for this error " \
+          "and that a transcript should be retrievable, please create an issue at " \
+          "https://github.com/jdepoix/youtube-transcript-api/issues. " \
+          "Please add which version of youtube_transcript_api you are using " \
+          "and provide the information needed to replicate the error. " \
+          "Also make sure that there are no open issues which already describe your problem!"
+      end
+    end
+
+    # Raised when YouTube data cannot be parsed
+    class YouTubeDataUnparsable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The data required to fetch the transcript is not parsable. This should " \
+                      "not happen, please open an issue (make sure to include the video ID)!"
+    end
+
+    # Raised when a request to YouTube fails
+    class YouTubeRequestFailed < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "Request to YouTube failed: %<reason>s"
+
+      # @return [String] the reason for the failure
+      attr_reader :reason
+
+      # @param video_id [String] the YouTube video ID
+      # @param http_error [StandardError] the HTTP error that occurred
+      def initialize(video_id, http_error)
+        @reason = http_error.to_s
+        super(video_id)
+      end
+
+      def cause_message
+        format(CAUSE_MESSAGE, reason: @reason)
+      end
+    end
+
+    # Raised when a video is unplayable
+    class VideoUnplayable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The video is unplayable for the following reason: %<reason>s"
+
+      # @return [String, nil] the reason the video is unplayable
+      attr_reader :reason
+
+      # @return [Array<String>] additional sub-reasons
+      attr_reader :sub_reasons
+
+      # @param video_id [String] the YouTube video ID
+      # @param reason [String, nil] the reason the video is unplayable
+      # @param sub_reasons [Array<String>] additional details
+      def initialize(video_id, reason = nil, sub_reasons = [])
+        @reason = reason
+        @sub_reasons = sub_reasons
+        super(video_id)
+      end
+
+      def cause_message
+        reason_text = @reason || "No reason specified!"
+
+        if @sub_reasons.any?
+          sub_reasons_text = @sub_reasons.map { |r| " - #{r}" }.join("\n")
+          reason_text = "#{reason_text}\n\nAdditional Details:\n#{sub_reasons_text}"
+        end
+
+        format(CAUSE_MESSAGE, reason: reason_text)
+      end
+    end
+
+    # Raised when a video is unavailable
+    class VideoUnavailable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The video is no longer available"
+    end
+
+    # Raised when an invalid video ID is provided
+    class InvalidVideoId < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "You provided an invalid video id. Make sure you are using the video id and NOT the url!\n\n" \
+                      'Do NOT run: `YoutubeRb::Transcript.fetch("https://www.youtube.com/watch?v=1234")`' \
+                      "\n" \
+                      'Instead run: `YoutubeRb::Transcript.fetch("1234")`'
+    end
+
+    # Raised when YouTube blocks the request
+    class RequestBlocked < CouldNotRetrieveTranscript
+      BASE_CAUSE_MESSAGE = "YouTube is blocking requests from your IP. This usually is due to one of the " \
+                           "following reasons:\n" \
+                           "- You have done too many requests and your IP has been blocked by YouTube\n" \
+                           "- You are doing requests from an IP belonging to a cloud provider (like AWS, " \
+                           "Google Cloud Platform, Azure, etc.). Unfortunately, most IPs from cloud " \
+                           "providers are blocked by YouTube.\n\n"
+
+      CAUSE_MESSAGE = "#{BASE_CAUSE_MESSAGE}" \
+                      "There are two things you can do to work around this:\n" \
+                      "1. Use proxies to hide your IP address.\n" \
+                      "2. (NOT RECOMMENDED) If you authenticate your requests using cookies, you " \
+                      "will be able to continue doing requests for a while. However, YouTube will " \
+                      "eventually permanently ban the account that you have used to authenticate " \
+                      "with! So only do this if you don't mind your account being banned!"
+    end
+
+    # Raised when YouTube blocks the IP specifically
+    class IpBlocked < RequestBlocked
+      CAUSE_MESSAGE = "#{RequestBlocked::BASE_CAUSE_MESSAGE}" \
+                      "Ways to work around this are using proxies or rotating residential IPs."
+    end
+
+    # Raised when too many requests are made (HTTP 429)
+    class TooManyRequests < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "YouTube is rate limiting your requests. Please wait before making more requests."
+    end
+
+    # Raised when transcripts are disabled for a video
+    class TranscriptsDisabled < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "Subtitles are disabled for this video"
+    end
+
+    # Raised when a video is age restricted
+    class AgeRestricted < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "This video is age-restricted. Therefore, you are unable to retrieve " \
+                      "transcripts for it without authenticating yourself.\n\n" \
+                      "Unfortunately, Cookie Authentication is temporarily unsupported, " \
+                      "as recent changes in YouTube's API broke the previous implementation."
+    end
+
+    # Raised when a transcript is not translatable
+    class NotTranslatable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The requested language is not translatable"
+    end
+
+    # Raised when the requested translation language is not available
+    class TranslationLanguageNotAvailable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The requested translation language is not available"
+    end
+
+    # Raised when consent cookie creation fails
+    class FailedToCreateConsentCookie < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "Failed to automatically give consent to saving cookies"
+    end
+
+    # Raised when no transcript is found for the requested languages
+    class NoTranscriptFound < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "No transcripts were found for any of the requested language codes: %<requested_language_codes>s\n\n%<transcript_data>s"
+
+      # @return [Array<String>] the requested language codes
+      attr_reader :requested_language_codes
+
+      # @return [Object] the transcript data (TranscriptList)
+      attr_reader :transcript_data
+
+      # @param video_id [String] the YouTube video ID
+      # @param requested_language_codes [Array<String>] the language codes that were requested
+      # @param transcript_data [Object] the TranscriptList object with available transcripts
+      def initialize(video_id, requested_language_codes, transcript_data)
+        @requested_language_codes = requested_language_codes
+        @transcript_data = transcript_data
+        super(video_id)
+      end
+
+      def cause_message
+        format(
+          CAUSE_MESSAGE,
+          requested_language_codes: @requested_language_codes.inspect,
+          transcript_data: @transcript_data.to_s
+        )
+      end
+    end
+
+    # Raised when no transcripts are available for a video
+    class NoTranscriptAvailable < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "No transcripts are available for this video"
+    end
+
+    # Raised when a PO token is required to fetch the transcript
+    class PoTokenRequired < CouldNotRetrieveTranscript
+      CAUSE_MESSAGE = "The requested video cannot be retrieved without a PO Token. " \
+                      "If this happens, please open a GitHub issue!"
+    end
+  end
+end