m3u8 0.8.2 → 1.8.1

data/lib/m3u8/bitrate_item.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module M3u8
+  # BitrateItem represents an EXT-X-BITRATE tag that indicates the
+  # approximate bitrate of the following media segments in kbps.
+  class BitrateItem
+    # @return [Integer, nil] approximate bitrate in kbps
+    attr_accessor :bitrate
+
+    # @param params [Hash] attribute key-value pairs
+    def initialize(params = {})
+      params.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Parse an EXT-X-BITRATE tag.
+    # @param text [String] raw tag line
+    # @return [BitrateItem]
+    def self.parse(text)
+      value = text.gsub('#EXT-X-BITRATE:', '').strip
+      BitrateItem.new(bitrate: value.to_i)
+    end
+
+    # Render as an m3u8 EXT-X-BITRATE tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-BITRATE:#{bitrate}"
+    end
+  end
+end

data/lib/m3u8/builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Builder provides a block-based DSL for constructing playlists
+  class Builder
+    ITEMS = {
+      segment: 'SegmentItem',
+      playlist: 'PlaylistItem',
+      media: 'MediaItem',
+      session_data: 'SessionDataItem',
+      session_key: 'SessionKeyItem',
+      content_steering: 'ContentSteeringItem',
+      key: 'KeyItem',
+      map: 'MapItem',
+      date_range: 'DateRangeItem',
+      time: 'TimeItem',
+      bitrate: 'BitrateItem',
+      part: 'PartItem',
+      preload_hint: 'PreloadHintItem',
+      rendition_report: 'RenditionReportItem',
+      skip: 'SkipItem',
+      define: 'DefineItem',
+      playback_start: 'PlaybackStart'
+    }.freeze
+
+    ZERO_ARG_ITEMS = {
+      discontinuity: 'DiscontinuityItem',
+      gap: 'GapItem'
+    }.freeze
+
+    # @param playlist [Playlist] playlist to build into
+    def initialize(playlist)
+      @playlist = playlist
+    end
+
+    ITEMS.each do |method_name, class_name|
+      define_method(method_name) do |params = {}|
+        @playlist.items << M3u8.const_get(class_name).new(params)
+      end
+    end
+
+    ZERO_ARG_ITEMS.each do |method_name, class_name|
+      define_method(method_name) do
+        @playlist.items << M3u8.const_get(class_name).new
+      end
+    end
+  end
+end

data/lib/m3u8/byte_range.rb

@@ -1,15 +1,22 @@
 # frozen_string_literal: true
+
 module M3u8
   # ByteRange represents sub range of a resource
   class ByteRange
+    # @return [Integer, nil] number of bytes
+    # @return [Integer, nil] start offset in bytes
     attr_accessor :length, :start
 
+    # @param params [Hash] :length and optional :start
     def initialize(params = {})
       params.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
+    # Parse a byte range string (e.g. "4500@600").
+    # @param text [String] byte range string
+    # @return [ByteRange]
     def self.parse(text)
       values = text.split('@')
       length_value = values[0].to_i
@@ -18,6 +25,8 @@ module M3u8
       ByteRange.new(options)
     end
 
+    # Render as a byte range string (e.g. "4500@600").
+    # @return [String]
     def to_s
       "#{length}#{start_format}"
     end
@@ -26,6 +35,7 @@ module M3u8
 
     def start_format
       return if start.nil?
+
       "@#{start}"
     end
   end

data/lib/m3u8/cli/inspect_command.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module M3u8
+  class CLI
+    # InspectCommand displays metadata about a playlist
+    class InspectCommand
+      MEDIA_WIDTH = 12
+      MASTER_WIDTH = 23
+
+      def initialize(playlist, stdout)
+        @playlist = playlist
+        @stdout = stdout
+      end
+
+      def run
+        if @playlist.master?
+          print_master
+        else
+          print_media
+        end
+        0
+      end
+
+      private
+
+      def print_media
+        field 'Type', 'Media', MEDIA_WIDTH
+        field 'Version', @playlist.version, MEDIA_WIDTH
+        field 'Sequence', @playlist.sequence, MEDIA_WIDTH
+        field 'Target', @playlist.target, MEDIA_WIDTH
+        field 'Duration', duration_value, MEDIA_WIDTH
+        field 'Playlist', @playlist.type, MEDIA_WIDTH
+        field 'Cache', cache_value, MEDIA_WIDTH
+        @stdout.puts
+        field 'Segments', @playlist.segments.size, MEDIA_WIDTH
+        field 'Keys', @playlist.keys.size, MEDIA_WIDTH
+        field 'Maps', @playlist.maps.size, MEDIA_WIDTH
+      end
+
+      def print_master
+        field 'Type', 'Master', MASTER_WIDTH
+        field 'Independent Segments',
+              independent_segments_value, MASTER_WIDTH
+        @stdout.puts
+        print_variants
+        print_media_items
+        field 'Session Keys',
+              @playlist.session_keys.size, MASTER_WIDTH
+        field 'Session Data',
+              @playlist.session_data.size, MASTER_WIDTH
+      end
+
+      def print_variants
+        variants = @playlist.playlists
+        field 'Variants', variants.size, MASTER_WIDTH
+        variants.each { |v| @stdout.puts variant_line(v) }
+      end
+
+      def print_media_items
+        items = @playlist.media_items
+        field 'Media', items.size, MASTER_WIDTH
+        items.each do |m|
+          @stdout.puts "  #{m.type}  #{m.group_id}  #{m.name}"
+        end
+      end
+
+      def variant_line(variant)
+        res = variant.resolution || ''
+        format('  %-11<res>s%<bw>s bps  %<uri>s',
+               res: res, bw: variant.bandwidth, uri: variant.uri)
+      end
+
+      def independent_segments_value
+        return unless @playlist.independent_segments
+
+        'Yes'
+      end
+
+      def duration_value
+        format('%<s>gs', s: @playlist.duration)
+      end
+
+      def cache_value
+        return unless @playlist.cache == false
+
+        'No'
+      end
+
+      def field(label, value, width)
+        return if value.nil?
+
+        @stdout.puts format("%-#{width}<label>s%<value>s",
+                            label: "#{label}:", value: value)
+      end
+    end
+  end
+end

data/lib/m3u8/cli/validate_command.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module M3u8
+  class CLI
+    # ValidateCommand checks playlist validity
+    class ValidateCommand
+      def initialize(playlist, stdout)
+        @playlist = playlist
+        @stdout = stdout
+      end
+
+      def run
+        if @playlist.valid?
+          @stdout.puts 'Valid'
+          0
+        else
+          @stdout.puts 'Invalid'
+          @playlist.errors.each { |e| @stdout.puts "  - #{e}" }
+          1
+        end
+      end
+    end
+  end
+end

data/lib/m3u8/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'cli/inspect_command'
+require_relative 'cli/validate_command'
+
+module M3u8
+  # CLI provides a command-line interface for inspecting and validating
+  # m3u8 playlists
+  class CLI
+    COMMANDS = %w[inspect validate].freeze
+
+    def self.run(argv, stdin, stdout, stderr)
+      new(argv, stdin, stdout, stderr).run
+    end
+
+    def initialize(argv, stdin, stdout, stderr)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      parse_global_options
+      dispatch
+    rescue OptionParser::InvalidOption => e
+      @stderr.puts e.message
+      2
+    end
+
+    private
+
+    def parse_global_options
+      @parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: m3u8 <command> [options] [file]'
+        opts.separator ''
+        opts.separator 'Commands:'
+        opts.separator '  inspect    Show playlist metadata'
+        opts.separator '  validate   Check playlist validity'
+        opts.separator ''
+        opts.on('-v', '--version', 'Show version') do
+          @stdout.puts M3u8::VERSION
+          throw :exit, 0
+        end
+        opts.on('-h', '--help', 'Show help') do
+          @stdout.puts opts
+          throw :exit, 0
+        end
+      end
+
+      @exit_code = catch(:exit) do
+        @parser.order!(@argv)
+        nil
+      end
+    end
+
+    def dispatch
+      return @exit_code if @exit_code
+
+      command = @argv.shift
+      return usage_error if command.nil?
+      return usage_error("unknown command: #{command}") \
+        unless COMMANDS.include?(command)
+
+      input = resolve_input
+      return 2 unless input
+
+      playlist = parse_playlist(input)
+      return 2 unless playlist
+
+      execute_command(command, playlist)
+    end
+
+    def execute_command(command, playlist)
+      case command
+      when 'inspect'
+        InspectCommand.new(playlist, @stdout).run
+      when 'validate'
+        ValidateCommand.new(playlist, @stdout).run
+      end
+    end
+
+    def resolve_input
+      file = @argv.shift
+      if file
+        read_file(file)
+      elsif !@stdin.tty?
+        @stdin.read
+      else
+        usage_error
+        nil
+      end
+    end
+
+    def read_file(path)
+      File.read(path)
+    rescue Errno::ENOENT
+      @stderr.puts "no such file: #{path}"
+      nil
+    end
+
+    def parse_playlist(input)
+      Playlist.read(input)
+    rescue StandardError => e
+      @stderr.puts "parse error: #{e.message}"
+      nil
+    end
+
+    def usage_error(message = nil)
+      @stderr.puts message if message
+      @stderr.puts @parser.to_s
+      2
+    end
+  end
+end

data/lib/m3u8/codecs.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Codec lookup tables for HLS playlist items
+  module Codecs
+    AUDIO_CODECS = {
+      'aac-lc' => 'mp4a.40.2',
+      'he-aac' => 'mp4a.40.5',
+      'mp3' => 'mp4a.40.34',
+      'ac-3' => 'ac-3',
+      'ec-3' => 'ec-3',
+      'e-ac-3' => 'ec-3',
+      'flac' => 'fLaC',
+      'opus' => 'Opus'
+    }.freeze
+
+    BASELINE_CODECS = {
+      3.0 => 'avc1.66.30',
+      3.1 => 'avc1.42001f'
+    }.freeze
+
+    MAIN_CODECS = {
+      3.0 => 'avc1.77.30',
+      3.1 => 'avc1.4d001f',
+      4.0 => 'avc1.4d0028',
+      4.1 => 'avc1.4d0029'
+    }.freeze
+
+    HIGH_LEVELS = [3.0, 3.1, 3.2, 4.0, 4.1, 4.2,
+                   5.0, 5.1, 5.2].freeze
+
+    HEVC_CODECS = {
+      ['hevc-main', 3.1] => 'hvc1.1.6.L93.B0',
+      ['hevc-main', 4.0] => 'hvc1.1.6.L120.B0',
+      ['hevc-main', 5.0] => 'hvc1.1.6.L150.B0',
+      ['hevc-main', 5.1] => 'hvc1.1.6.L153.B0',
+      ['hevc-main-10', 3.1] => 'hvc1.2.4.L93.B0',
+      ['hevc-main-10', 4.0] => 'hvc1.2.4.L120.B0',
+      ['hevc-main-10', 5.0] => 'hvc1.2.4.L150.B0',
+      ['hevc-main-10', 5.1] => 'hvc1.2.4.L153.B0'
+    }.freeze
+
+    AV1_CODECS = {
+      ['av1-main', 3.1] => 'av01.0.04M.08',
+      ['av1-main', 4.0] => 'av01.0.08M.08',
+      ['av1-main', 5.0] => 'av01.0.12M.08',
+      ['av1-main', 5.1] => 'av01.0.13M.08',
+      ['av1-high', 3.1] => 'av01.1.04H.10',
+      ['av1-high', 4.0] => 'av01.1.08H.10',
+      ['av1-high', 5.0] => 'av01.1.12H.10',
+      ['av1-high', 5.1] => 'av01.1.13H.10'
+    }.freeze
+
+    # Look up the codec string for an audio codec name.
+    # @param codec [String, nil] audio codec name
+    # @return [String, nil] codec string
+    def self.audio_codec(codec)
+      return if codec.nil?
+
+      AUDIO_CODECS[codec.downcase]
+    end
+
+    # Look up the codec string for a video profile and level.
+    # @param profile [String, nil] video profile name
+    # @param level [Float, Integer, nil] video level
+    # @return [String, nil] codec string
+    def self.video_codec(profile, level)
+      return if profile.nil? || level.nil?
+
+      level = level.to_f
+      name = profile.downcase
+      return BASELINE_CODECS[level] if name == 'baseline'
+      return MAIN_CODECS[level] if name == 'main'
+      return high_codec_string(level) if name == 'high'
+      return HEVC_CODECS[[profile, level]] if name.start_with?('hevc-')
+
+      AV1_CODECS[[profile, level]] if name.start_with?('av1-')
+    end
+
+    def self.high_codec_string(level)
+      return nil unless HIGH_LEVELS.include?(level)
+
+      hex = level.to_s.sub('.', '').to_i.to_s(16)
+      "avc1.6400#{hex}"
+    end
+
+    private_class_method :high_codec_string
+  end
+end

data/lib/m3u8/content_steering_item.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module M3u8
+  # ContentSteeringItem represents an EXT-X-CONTENT-STEERING tag which
+  # indicates a Content Steering Manifest for dynamic pathway selection.
+  class ContentSteeringItem
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] steering manifest server URI
+    # @return [String, nil] default pathway ID
+    attr_accessor :server_uri, :pathway_id
+
+    # @param params [Hash] attribute key-value pairs
+    def initialize(params = {})
+      params.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Parse an EXT-X-CONTENT-STEERING tag.
+    # @param text [String] raw tag line
+    # @return [ContentSteeringItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      ContentSteeringItem.new(
+        server_uri: attributes['SERVER-URI'],
+        pathway_id: attributes['PATHWAY-ID']
+      )
+    end
+
+    # Render as an m3u8 EXT-X-CONTENT-STEERING tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-CONTENT-STEERING:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [quoted_format('SERVER-URI', server_uri),
+       quoted_format('PATHWAY-ID', pathway_id)].compact.join(',')
+    end
+  end
+end