youtube-transcript-rb 0.1.0 → 0.2.1

data/lib/youtube_rb/transcript/formatters.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "json"
+
+module YoutubeRb
+  module Transcript
+    # Module containing all transcript formatters
+    module Formatters
+      # Base formatter class. All formatters should inherit from this class
+      # and implement their own format_transcript and format_transcripts methods.
+      class Formatter
+        # Format a single transcript
+        #
+        # @param transcript [FetchedTranscript] The transcript to format
+        # @param options [Hash] Additional formatting options
+        # @return [String] The formatted transcript
+        def format_transcript(transcript, **options)
+          raise NotImplementedError, "Subclass must implement #format_transcript"
+        end
+
+        # Format multiple transcripts
+        #
+        # @param transcripts [Array<FetchedTranscript>] The transcripts to format
+        # @param options [Hash] Additional formatting options
+        # @return [String] The formatted transcripts
+        def format_transcripts(transcripts, **options)
+          raise NotImplementedError, "Subclass must implement #format_transcripts"
+        end
+      end
+
+      # Formats transcript as pretty-printed Ruby data structures
+      class PrettyPrintFormatter < Formatter
+        # Format a single transcript as pretty-printed output
+        #
+        # @param transcript [FetchedTranscript] The transcript to format
+        # @param options [Hash] Options passed to PP.pp
+        # @return [String] Pretty-printed transcript data
+        def format_transcript(transcript, **options)
+          require "pp"
+          PP.pp(transcript.to_raw_data, +"", options[:width] || 79)
+        end
+
+        # Format multiple transcripts as pretty-printed output
+        #
+        # @param transcripts [Array<FetchedTranscript>] The transcripts to format
+        # @param options [Hash] Options passed to PP.pp
+        # @return [String] Pretty-printed transcripts data
+        def format_transcripts(transcripts, **options)
+          require "pp"
+          data = transcripts.map(&:to_raw_data)
+          PP.pp(data, +"", options[:width] || 79)
+        end
+      end
+
+      # Formats transcript as JSON
+      class JSONFormatter < Formatter
+        # Format a single transcript as JSON
+        #
+        # @param transcript [FetchedTranscript] The transcript to format
+        # @param options [Hash] Options passed to JSON.generate (e.g., :indent, :space)
+        # @return [String] JSON representation of the transcript
+        def format_transcript(transcript, **options)
+          JSON.generate(transcript.to_raw_data, options)
+        end
+
+        # Format multiple transcripts as JSON array
+        #
+        # @param transcripts [Array<FetchedTranscript>] The transcripts to format
+        # @param options [Hash] Options passed to JSON.generate
+        # @return [String] JSON array representation of the transcripts
+        def format_transcripts(transcripts, **options)
+          data = transcripts.map(&:to_raw_data)
+          JSON.generate(data, options)
+        end
+      end
+
+      # Formats transcript as plain text (text only, no timestamps)
+      class TextFormatter < Formatter
+        # Format a single transcript as plain text
+        #
+        # @param transcript [FetchedTranscript] The transcript to format
+        # @param options [Hash] Unused options
+        # @return [String] Plain text with each line separated by newlines
+        def format_transcript(transcript, **options)
+          transcript.map(&:text).join("\n")
+        end
+
+        # Format multiple transcripts as plain text
+        #
+        # @param transcripts [Array<FetchedTranscript>] The transcripts to format
+        # @param options [Hash] Unused options
+        # @return [String] Plain text with transcripts separated by triple newlines
+        def format_transcripts(transcripts, **options)
+          transcripts.map { |t| format_transcript(t, **options) }.join("\n\n\n")
+        end
+      end
+
+      # Base class for timestamp-based formatters (SRT, WebVTT)
+      class TextBasedFormatter < TextFormatter
+        # Format a single transcript with timestamps
+        #
+        # @param transcript [FetchedTranscript] The transcript to format
+        # @param options [Hash] Unused options
+        # @return [String] Formatted transcript with timestamps
+        def format_transcript(transcript, **options)
+          lines = []
+          snippets = transcript.to_a
+
+          snippets.each_with_index do |snippet, i|
+            end_time = snippet.start + snippet.duration
+
+            # Use next snippet's start time if it starts before current end time
+            if i < snippets.length - 1 && snippets[i + 1].start < end_time
+              end_time = snippets[i + 1].start
+            end
+
+            time_text = "#{seconds_to_timestamp(snippet.start)} --> #{seconds_to_timestamp(end_time)}"
+            lines << format_transcript_helper(i, time_text, snippet)
+          end
+
+          format_transcript_header(lines)
+        end
+
+        protected
+
+        # Format a timestamp from components
+        #
+        # @param hours [Integer] Hours component
+        # @param mins [Integer] Minutes component
+        # @param secs [Integer] Seconds component
+        # @param ms [Integer] Milliseconds component
+        # @return [String] Formatted timestamp
+        def format_timestamp(hours, mins, secs, ms)
+          raise NotImplementedError, "Subclass must implement #format_timestamp"
+        end
+
+        # Format the transcript header/wrapper
+        #
+        # @param lines [Array<String>] The formatted lines
+        # @return [String] The complete formatted transcript
+        def format_transcript_header(lines)
+          raise NotImplementedError, "Subclass must implement #format_transcript_header"
+        end
+
+        # Format a single transcript entry
+        #
+        # @param index [Integer] The entry index (0-based)
+        # @param time_text [String] The formatted time range
+        # @param snippet [TranscriptSnippet] The snippet to format
+        # @return [String] The formatted entry
+        def format_transcript_helper(index, time_text, snippet)
+          raise NotImplementedError, "Subclass must implement #format_transcript_helper"
+        end
+
+        private
+
+        # Convert seconds to timestamp string
+        #
+        # @param time [Float] Time in seconds
+        # @return [String] Formatted timestamp
+        def seconds_to_timestamp(time)
+          time = time.to_f
+          hours, remainder = time.divmod(3600)
+          mins, secs_float = remainder.divmod(60)
+          secs = secs_float.to_i
+          ms = ((time - time.to_i) * 1000).round
+
+          format_timestamp(hours.to_i, mins.to_i, secs, ms)
+        end
+      end
+
+      # Formats transcript as SRT (SubRip) subtitle format
+      #
+      # @example SRT format
+      #   1
+      #   00:00:00,000 --> 00:00:02,500
+      #   Hello world
+      #
+      #   2
+      #   00:00:02,500 --> 00:00:05,000
+      #   This is a test
+      #
+      class SRTFormatter < TextBasedFormatter
+        protected
+
+        def format_timestamp(hours, mins, secs, ms)
+          format("%02d:%02d:%02d,%03d", hours, mins, secs, ms)
+        end
+
+        def format_transcript_header(lines)
+          lines.join("\n\n") + "\n"
+        end
+
+        def format_transcript_helper(index, time_text, snippet)
+          "#{index + 1}\n#{time_text}\n#{snippet.text}"
+        end
+      end
+
+      # Formats transcript as WebVTT (Web Video Text Tracks) format
+      #
+      # @example WebVTT format
+      #   WEBVTT
+      #
+      #   00:00:00.000 --> 00:00:02.500
+      #   Hello world
+      #
+      #   00:00:02.500 --> 00:00:05.000
+      #   This is a test
+      #
+      class WebVTTFormatter < TextBasedFormatter
+        protected
+
+        def format_timestamp(hours, mins, secs, ms)
+          format("%02d:%02d:%02d.%03d", hours, mins, secs, ms)
+        end
+
+        def format_transcript_header(lines)
+          "WEBVTT\n\n" + lines.join("\n\n") + "\n"
+        end
+
+        def format_transcript_helper(index, time_text, snippet)
+          "#{time_text}\n#{snippet.text}"
+        end
+      end
+
+      # Utility class to load formatters by type name
+      class FormatterLoader
+        # Mapping of format names to formatter classes
+        TYPES = {
+          "json" => JSONFormatter,
+          "pretty" => PrettyPrintFormatter,
+          "text" => TextFormatter,
+          "webvtt" => WebVTTFormatter,
+          "srt" => SRTFormatter
+        }.freeze
+
+        # Error raised when an unknown formatter type is requested
+        class UnknownFormatterType < StandardError
+          def initialize(formatter_type)
+            super(
+              "The format '#{formatter_type}' is not supported. " \
+              "Choose one of the following formats: #{TYPES.keys.join(", ")}"
+            )
+          end
+        end
+
+        # Load a formatter by type name
+        #
+        # @param formatter_type [String] The formatter type (json, pretty, text, webvtt, srt)
+        # @return [Formatter] An instance of the requested formatter
+        # @raise [UnknownFormatterType] If the formatter type is not supported
+        #
+        # @example
+        #   loader = FormatterLoader.new
+        #   formatter = loader.load("json")
+        #   output = formatter.format_transcript(transcript)
+        #
+        def load(formatter_type = "pretty")
+          formatter_type = formatter_type.to_s
+          raise UnknownFormatterType, formatter_type unless TYPES.key?(formatter_type)
+
+          TYPES[formatter_type].new
+        end
+      end
+    end
+  end
+end

data/lib/youtube_rb/transcript/settings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module YoutubeRb
+  module Transcript
+    # YouTube watch URL template
+    # @example
+    #   format(WATCH_URL, video_id: "abc123")
+    #   # => "https://www.youtube.com/watch?v=abc123"
+    WATCH_URL = "https://www.youtube.com/watch?v=%<video_id>s"
+
+    # YouTube Innertube API URL template
+    # @example
+    #   format(INNERTUBE_API_URL, api_key: "key123")
+    #   # => "https://www.youtube.com/youtubei/v1/player?key=key123"
+    INNERTUBE_API_URL = "https://www.youtube.com/youtubei/v1/player?key=%<api_key>s"
+
+    # Innertube API context for Android client
+    # Used in POST requests to the Innertube API
+    INNERTUBE_CONTEXT = {
+      "client" => {
+        "clientName" => "ANDROID",
+        "clientVersion" => "20.10.38"
+      }
+    }.freeze
+  end
+end

data/lib/youtube_rb/transcript/transcript.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module YoutubeRb
+  module Transcript
+    # Represents a language available for translation
+    class TranslationLanguage
+      # @return [String] the language name (e.g., "Spanish")
+      attr_reader :language
+
+      # @return [String] the language code (e.g., "es")
+      attr_reader :language_code
+
+      # @param language [String] the language name
+      # @param language_code [String] the language code
+      def initialize(language:, language_code:)
+        @language = language
+        @language_code = language_code
+      end
+    end
+
+    # Represents a single transcript snippet/segment
+    class TranscriptSnippet
+      # @return [String] the text content of the snippet
+      attr_reader :text
+
+      # @return [Float] the start time in seconds
+      attr_reader :start
+
+      # @return [Float] the duration in seconds
+      attr_reader :duration
+
+      # @param text [String] the text content
+      # @param start [Float] the start time in seconds
+      # @param duration [Float] the duration in seconds
+      def initialize(text:, start:, duration:)
+        @text = text
+        @start = start.to_f
+        @duration = duration.to_f
+      end
+
+      # Convert to hash representation
+      # @return [Hash] hash with text, start, and duration keys
+      def to_h
+        {
+          "text" => @text,
+          "start" => @start,
+          "duration" => @duration
+        }
+      end
+    end
+
+    # Represents a fetched transcript containing multiple snippets
+    # This class is Enumerable, allowing iteration over snippets
+    class FetchedTranscript
+      include Enumerable
+
+      # @return [String] the video ID
+      attr_reader :video_id
+
+      # @return [String] the language name (e.g., "English")
+      attr_reader :language
+
+      # @return [String] the language code (e.g., "en")
+      attr_reader :language_code
+
+      # @return [Boolean] whether the transcript was auto-generated
+      attr_reader :is_generated
+
+      # @return [Array<TranscriptSnippet>] the transcript snippets
+      attr_reader :snippets
+
+      # @param video_id [String] the YouTube video ID
+      # @param language [String] the language name
+      # @param language_code [String] the language code
+      # @param is_generated [Boolean] whether auto-generated
+      # @param snippets [Array<TranscriptSnippet>] the snippets (optional)
+      def initialize(video_id:, language:, language_code:, is_generated:, snippets: [])
+        @video_id = video_id
+        @language = language
+        @language_code = language_code
+        @is_generated = is_generated
+        @snippets = snippets
+      end
+
+      # Add a snippet to the transcript
+      # @param snippet [TranscriptSnippet] the snippet to add
+      # @return [self]
+      def add_snippet(snippet)
+        @snippets << snippet
+        self
+      end
+
+      # Iterate over each snippet
+      # @yield [TranscriptSnippet] each snippet in the transcript
+      def each(&block)
+        @snippets.each(&block)
+      end
+
+      # Get a snippet by index
+      # @param index [Integer] the index
+      # @return [TranscriptSnippet] the snippet at the given index
+      def [](index)
+        @snippets[index]
+      end
+
+      # Get the number of snippets
+      # @return [Integer] the count of snippets
+      def length
+        @snippets.length
+      end
+      alias size length
+
+      # Convert to raw data (array of hashes)
+      # @return [Array<Hash>] array of snippet hashes
+      def to_raw_data
+        @snippets.map(&:to_h)
+      end
+
+      # Check if transcript was auto-generated
+      # @return [Boolean]
+      def generated?
+        @is_generated
+      end
+    end
+
+    # Represents transcript metadata and provides fetch/translate capabilities
+    class TranscriptMetadata
+      # @return [String] the video ID
+      attr_reader :video_id
+
+      # @return [String] the language name
+      attr_reader :language
+
+      # @return [String] the language code
+      attr_reader :language_code
+
+      # @return [Boolean] whether auto-generated
+      attr_reader :is_generated
+
+      # @return [Array<TranslationLanguage>] available translation languages
+      attr_reader :translation_languages
+
+      # @param http_client [Faraday::Connection] the HTTP client
+      # @param video_id [String] the YouTube video ID
+      # @param url [String] the transcript URL
+      # @param language [String] the language name
+      # @param language_code [String] the language code
+      # @param is_generated [Boolean] whether auto-generated
+      # @param translation_languages [Array<TranslationLanguage>] available translations
+      def initialize(http_client:, video_id:, url:, language:, language_code:, is_generated:, translation_languages:)
+        @http_client = http_client
+        @video_id = video_id
+        @url = url
+        @language = language
+        @language_code = language_code
+        @is_generated = is_generated
+        @translation_languages = translation_languages
+        @translation_languages_dict = translation_languages.each_with_object({}) do |tl, hash|
+          hash[tl.language_code] = tl.language
+        end
+      end
+
+      # Fetch the actual transcript data
+      # @param preserve_formatting [Boolean] whether to preserve HTML formatting
+      # @return [FetchedTranscript] the fetched transcript
+      # @raise [PoTokenRequired] if a PO token is required
+      def fetch(preserve_formatting: false)
+        raise PoTokenRequired, @video_id if @url.include?("&exp=xpe")
+
+        response = @http_client.get(@url)
+        raise_http_errors(response)
+
+        parser = TranscriptParser.new(preserve_formatting: preserve_formatting)
+        snippets = parser.parse(response.body)
+
+        FetchedTranscript.new(
+          video_id: @video_id,
+          language: @language,
+          language_code: @language_code,
+          is_generated: @is_generated,
+          snippets: snippets
+        )
+      end
+
+      # Check if this transcript can be translated
+      # @return [Boolean]
+      def translatable?
+        !@translation_languages.empty?
+      end
+      alias is_translatable translatable?
+
+      # Translate this transcript to another language
+      # @param language_code [String] the target language code
+      # @return [TranscriptMetadata] a new TranscriptMetadata object for the translated version
+      # @raise [NotTranslatable] if the transcript cannot be translated
+      # @raise [TranslationLanguageNotAvailable] if the language is not available
+      def translate(language_code)
+        raise NotTranslatable, @video_id unless translatable?
+        raise TranslationLanguageNotAvailable, @video_id unless @translation_languages_dict.key?(language_code)
+
+        TranscriptMetadata.new(
+          http_client: @http_client,
+          video_id: @video_id,
+          url: "#{@url}&tlang=#{language_code}",
+          language: @translation_languages_dict[language_code],
+          language_code: language_code,
+          is_generated: true,
+          translation_languages: []
+        )
+      end
+
+      # Check if transcript was auto-generated
+      # @return [Boolean]
+      def generated?
+        @is_generated
+      end
+
+      # String representation of the transcript
+      # @return [String]
+      def to_s
+        translation_desc = translatable? ? "[TRANSLATABLE]" : ""
+        "#{@language_code} (\"#{@language}\")#{translation_desc}"
+      end
+
+      private
+
+      def raise_http_errors(response)
+        case response.status
+        when 429
+          raise IpBlocked, @video_id
+        when 400..599
+          raise YouTubeRequestFailed.new(@video_id, StandardError.new("HTTP #{response.status}"))
+        end
+      end
+    end
+  end
+end

data/lib/youtube_rb/transcript/transcript_list.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module YoutubeRb
+  module Transcript
+    # Represents a list of available transcripts for a YouTube video.
+    # This class is Enumerable, allowing iteration over all available transcripts.
+    # It provides functionality to search for transcripts in specific languages.
+    class TranscriptList
+      include Enumerable
+
+      # @return [String] the video ID this TranscriptList is for
+      attr_reader :video_id
+
+      # Build a TranscriptList from captions JSON data
+      #
+      # @param http_client [Faraday::Connection] the HTTP client for fetching transcripts
+      # @param video_id [String] the YouTube video ID
+      # @param captions_json [Hash] the captions JSON parsed from YouTube
+      # @return [TranscriptList] the created TranscriptList
+      def self.build(http_client:, video_id:, captions_json:)
+        translation_languages = (captions_json["translationLanguages"] || []).map do |tl|
+          TranslationLanguage.new(
+            language: tl.dig("languageName", "runs", 0, "text") || "",
+            language_code: tl["languageCode"]
+          )
+        end
+
+        manually_created_transcripts = {}
+        generated_transcripts = {}
+
+        (captions_json["captionTracks"] || []).each do |caption|
+          is_generated = caption.fetch("kind", "") == "asr"
+          target_dict = is_generated ? generated_transcripts : manually_created_transcripts
+
+          language_code = caption["languageCode"]
+          transcript_translation_languages = caption.fetch("isTranslatable", false) ? translation_languages : []
+
+          target_dict[language_code] = TranscriptMetadata.new(
+            http_client: http_client,
+            video_id: video_id,
+            url: caption["baseUrl"].to_s.gsub("&fmt=srv3", ""),
+            language: caption.dig("name", "runs", 0, "text") || "",
+            language_code: language_code,
+            is_generated: is_generated,
+            translation_languages: transcript_translation_languages
+          )
+        end
+
+        new(
+          video_id: video_id,
+          manually_created_transcripts: manually_created_transcripts,
+          generated_transcripts: generated_transcripts,
+          translation_languages: translation_languages
+        )
+      end
+
+      # @param video_id [String] the YouTube video ID
+      # @param manually_created_transcripts [Hash<String, TranscriptMetadata>] manually created transcripts by language code
+      # @param generated_transcripts [Hash<String, TranscriptMetadata>] auto-generated transcripts by language code
+      # @param translation_languages [Array<TranslationLanguage>] available translation languages
+      def initialize(video_id:, manually_created_transcripts:, generated_transcripts:, translation_languages:)
+        @video_id = video_id
+        @manually_created_transcripts = manually_created_transcripts
+        @generated_transcripts = generated_transcripts
+        @translation_languages = translation_languages
+      end
+
+      # Iterate over all transcripts (manually created first, then generated)
+      #
+      # @yield [TranscriptMetadata] each available transcript
+      # @return [Enumerator] if no block given
+      def each(&block)
+        return to_enum(:each) unless block_given?
+
+        @manually_created_transcripts.each_value(&block)
+        @generated_transcripts.each_value(&block)
+      end
+
+      # Find a transcript for the given language codes.
+      # Manually created transcripts are preferred over generated ones.
+      #
+      # @param language_codes [Array<String>] language codes in descending priority
+      # @return [TranscriptMetadata] the found transcript
+      # @raise [NoTranscriptFound] if no transcript matches the requested languages
+      def find_transcript(language_codes)
+        find_transcript_in(
+          language_codes,
+          [@manually_created_transcripts, @generated_transcripts]
+        )
+      end
+
+      # Find an automatically generated transcript for the given language codes.
+      #
+      # @param language_codes [Array<String>] language codes in descending priority
+      # @return [TranscriptMetadata] the found transcript
+      # @raise [NoTranscriptFound] if no generated transcript matches
+      def find_generated_transcript(language_codes)
+        find_transcript_in(language_codes, [@generated_transcripts])
+      end
+
+      # Find a manually created transcript for the given language codes.
+      #
+      # @param language_codes [Array<String>] language codes in descending priority
+      # @return [TranscriptMetadata] the found transcript
+      # @raise [NoTranscriptFound] if no manually created transcript matches
+      def find_manually_created_transcript(language_codes)
+        find_transcript_in(language_codes, [@manually_created_transcripts])
+      end
+
+      # String representation of the transcript list
+      #
+      # @return [String] human-readable description of available transcripts
+      def to_s
+        <<~DESC
+          For this video (#{@video_id}) transcripts are available in the following languages:
+
+          (MANUALLY CREATED)
+          #{format_language_list(@manually_created_transcripts.values)}
+
+          (GENERATED)
+          #{format_language_list(@generated_transcripts.values)}
+
+          (TRANSLATION LANGUAGES)
+          #{format_translation_languages}
+        DESC
+      end
+
+      private
+
+      # Find a transcript from the given dictionaries
+      #
+      # @param language_codes [Array<String>] language codes to search for
+      # @param transcript_dicts [Array<Hash>] transcript dictionaries to search
+      # @return [TranscriptMetadata] the found transcript
+      # @raise [NoTranscriptFound] if no transcript matches
+      def find_transcript_in(language_codes, transcript_dicts)
+        language_codes.each do |language_code|
+          transcript_dicts.each do |dict|
+            return dict[language_code] if dict.key?(language_code)
+          end
+        end
+
+        raise NoTranscriptFound.new(@video_id, language_codes, self)
+      end
+
+      # Format a list of transcripts for display
+      #
+      # @param transcripts [Array<TranscriptMetadata>] transcripts to format
+      # @return [String] formatted list or "None"
+      def format_language_list(transcripts)
+        return "None" if transcripts.empty?
+
+        transcripts.map { |t| " - #{t}" }.join("\n")
+      end
+
+      # Format translation languages for display
+      #
+      # @return [String] formatted list or "None"
+      def format_translation_languages
+        return "None" if @translation_languages.empty?
+
+        @translation_languages.map do |tl|
+          " - #{tl.language_code} (\"#{tl.language}\")"
+        end.join("\n")
+      end
+    end
+  end
+end