m3u8 0.8.2 → 1.8.1

data/lib/m3u8/playlist_item.rb

@@ -1,14 +1,45 @@
 # frozen_string_literal: true
+
 module M3u8
   # PlaylistItem represents a set of EXT-X-STREAM-INF or
   # EXT-X-I-FRAME-STREAM-INF attributes
   class PlaylistItem
-    include M3u8
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] program ID
+    # @return [Integer, nil] horizontal resolution in pixels
+    # @return [Integer, nil] vertical resolution in pixels
+    # @return [String, nil] codec string or computed codecs
+    # @return [Integer, nil] peak bandwidth in bits/s
+    # @return [String, nil] audio codec hint for codecs generation
+    # @return [String, Integer, Float, nil] H.264/HEVC/AV1 level
+    # @return [String, nil] H.264/HEVC/AV1 profile name
+    # @return [String, nil] VIDEO rendition group ID
+    # @return [String, nil] AUDIO rendition group ID
+    # @return [String, nil] stream URI
+    # @return [Integer, nil] average bandwidth in bits/s
+    # @return [String, nil] SUBTITLES rendition group ID
+    # @return [String, nil] CLOSED-CAPTIONS value or 'NONE'
+    # @return [Boolean] whether this is an I-frame stream
+    # @return [BigDecimal, nil] frame rate
+    # @return [String, nil] stream name
+    # @return [String, nil] HDCP level (TYPE-0, TYPE-1, NONE)
+    # @return [String, nil] stable variant ID
+    # @return [String, nil] video range (SDR, HLG, PQ)
+    # @return [String, nil] allowed CPC value
+    # @return [String, nil] content steering pathway ID
+    # @return [String, nil] required video layout
+    # @return [String, nil] supplemental codecs string
+    # @return [Float, nil] stream score
     attr_accessor :program_id, :width, :height, :codecs, :bandwidth,
                   :audio_codec, :level, :profile, :video, :audio, :uri,
                   :average_bandwidth, :subtitles, :closed_captions, :iframe,
-                  :frame_rate, :name, :hdcp_level
+                  :frame_rate, :name, :hdcp_level, :stable_variant_id,
+                  :video_range, :allowed_cpc, :pathway_id,
+                  :req_video_layout, :supplemental_codecs, :score
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
       self.iframe = false
       params.each do |key, value|
@@ -16,69 +47,105 @@ module M3u8
       end
     end
 
+    # Parse an EXT-X-STREAM-INF or EXT-X-I-FRAME-STREAM-INF tag.
+    # @param text [String] raw tag line
+    # @return [PlaylistItem]
     def self.parse(text)
-      item = PlaylistItem.new
-      item.parse(text)
-      item
-    end
-
-    def parse(text)
       attributes = parse_attributes(text)
       options = options_from_attributes(attributes)
-      initialize(options)
+      PlaylistItem.new(options)
     end
 
+    # Format the resolution as a WIDTHxHEIGHT string.
+    # @return [String, nil]
     def resolution
       return if width.nil?
+
       "#{width}x#{height}"
     end
 
+    # Return or compute the codecs string.
+    # @return [String, nil]
     def codecs
       return @codecs unless @codecs.nil?
 
-      video_codec_string = video_codec(profile, level)
+      video = Codecs.video_codec(profile, level)
 
-      # profile and/or level were specified but not recognized,
-      # do not specify any codecs
-      return nil if !(profile.nil? && level.nil?) && video_codec_string.nil?
+      # profile and/or level were specified but not recognized
+      return nil if !(profile.nil? && level.nil?) && video.nil?
 
-      audio_codec_string = audio_codec_code
+      audio = Codecs.audio_codec(@audio_codec)
 
-      # audio codec was specified but not recognized,
-      # do not specify any codecs
-      return nil if !@audio_codec.nil? && audio_codec_string.nil?
+      # audio codec was specified but not recognized
+      return nil if !@audio_codec.nil? && audio.nil?
 
-      codec_strings = [video_codec_string, audio_codec_string].compact
-      codec_strings.empty? ? nil : codec_strings.join(',')
+      strings = [video, audio].compact
+      strings.empty? ? nil : strings.join(',')
     end
 
+    # Render as an m3u8 tag string.
+    # @return [String]
     def to_s
       m3u8_format
     end
 
-    private
+    def self.options_from_attributes(attributes)
+      parse_stream_attrs(attributes)
+        .merge(parse_media_attrs(attributes))
+    end
+    private_class_method :options_from_attributes
 
-    def options_from_attributes(attributes)
+    def self.parse_stream_attrs(attributes)
       resolution = parse_resolution(attributes['RESOLUTION'])
       { program_id: attributes['PROGRAM-ID'],
         codecs: attributes['CODECS'],
         width: resolution[:width],
         height: resolution[:height],
-        bandwidth: attributes['BANDWIDTH'].to_i,
+        bandwidth:
+          parse_bandwidth(attributes['BANDWIDTH']),
         average_bandwidth:
-          parse_average_bandwidth(attributes['AVERAGE-BANDWIDTH']),
-        frame_rate: parse_frame_rate(attributes['FRAME-RATE']),
-        video: attributes['VIDEO'], audio: attributes['AUDIO'],
-        uri: attributes['URI'], subtitles: attributes['SUBTITLES'],
+          parse_average_bandwidth(
+            attributes['AVERAGE-BANDWIDTH']
+          ),
+        frame_rate:
+          parse_frame_rate(attributes['FRAME-RATE']),
+        hdcp_level: attributes['HDCP-LEVEL'],
+        video_range: attributes['VIDEO-RANGE'],
+        supplemental_codecs:
+          attributes['SUPPLEMENTAL-CODECS'],
+        score: parse_float(attributes['SCORE']) }
+    end
+    private_class_method :parse_stream_attrs
+
+    def self.parse_media_attrs(attributes)
+      { video: attributes['VIDEO'],
+        audio: attributes['AUDIO'],
+        uri: attributes['URI'],
+        subtitles: attributes['SUBTITLES'],
         closed_captions: attributes['CLOSED-CAPTIONS'],
-        name: attributes['NAME'], hdcp_level: attributes['HDCP-LEVEL'] }
+        name: attributes['NAME'],
+        stable_variant_id:
+          attributes['STABLE-VARIANT-ID'],
+        allowed_cpc: attributes['ALLOWED-CPC'],
+        pathway_id: attributes['PATHWAY-ID'],
+        req_video_layout:
+          attributes['REQ-VIDEO-LAYOUT'] }
     end
+    private_class_method :parse_media_attrs
 
-    def parse_average_bandwidth(value)
-      value.to_i unless value.nil?
+    def self.parse_average_bandwidth(value)
+      value&.to_i
     end
+    private_class_method :parse_average_bandwidth
 
-    def parse_resolution(resolution)
+    def self.parse_bandwidth(value)
+      return if value.nil?
+
+      value.to_i
+    end
+    private_class_method :parse_bandwidth
+
+    def self.parse_resolution(resolution)
       return { width: nil, height: nil } if resolution.nil?
 
       values = resolution.split('x')
@@ -86,13 +153,17 @@ module M3u8
       height = values[1].to_i
       { width: width, height: height }
     end
+    private_class_method :parse_resolution
 
-    def parse_frame_rate(frame_rate)
+    def self.parse_frame_rate(frame_rate)
       return if frame_rate.nil?
 
       value = BigDecimal(frame_rate)
-      value if value > 0
+      value if value.positive?
     end
+    private_class_method :parse_frame_rate
+
+    private
 
     def m3u8_format
       return %(#EXT-X-I-FRAME-STREAM-INF:#{attributes},URI="#{uri}") if iframe
@@ -101,116 +172,49 @@ module M3u8
     end
 
     def attributes
-      [program_id_format,
-       resolution_format,
-       codecs_format,
-       bandwidth_format,
-       average_bandwidth_format,
-       frame_rate_format,
-       hdcp_level_format,
-       audio_format,
-       video_format,
-       subtitles_format,
-       closed_captions_format,
-       name_format].compact.join(',')
+      (stream_attributes + media_attributes).compact.join(',')
     end
 
-    def program_id_format
-      return if program_id.nil?
-      "PROGRAM-ID=#{program_id}"
+    def stream_attributes
+      [unquoted_format('PROGRAM-ID', program_id),
+       unquoted_format('RESOLUTION', resolution),
+       quoted_format('CODECS', codecs),
+       quoted_format('SUPPLEMENTAL-CODECS', supplemental_codecs),
+       "BANDWIDTH=#{bandwidth}",
+       unquoted_format('AVERAGE-BANDWIDTH', average_bandwidth),
+       unquoted_format('SCORE', score),
+       frame_rate_format,
+       unquoted_format('HDCP-LEVEL', hdcp_level),
+       unquoted_format('VIDEO-RANGE', video_range)]
     end
 
-    def resolution_format
-      return if resolution.nil?
-      "RESOLUTION=#{resolution}"
+    def media_attributes
+      [quoted_format('ALLOWED-CPC', allowed_cpc),
+       quoted_format('AUDIO', audio),
+       quoted_format('VIDEO', video),
+       quoted_format('SUBTITLES', subtitles),
+       closed_captions_format,
+       quoted_format('NAME', name),
+       quoted_format('STABLE-VARIANT-ID', stable_variant_id),
+       quoted_format('PATHWAY-ID', pathway_id),
+       quoted_format('REQ-VIDEO-LAYOUT',
+                     req_video_layout)]
     end
 
     def frame_rate_format
       return if frame_rate.nil?
-      "FRAME-RATE=#{format('%.3f', frame_rate)}"
-    end
-
-    def hdcp_level_format
-      return if hdcp_level.nil?
-      "HDCP-LEVEL=#{hdcp_level}"
-    end
-
-    def codecs_format
-      return if codecs.nil?
-      %(CODECS="#{codecs}")
-    end
-
-    def bandwidth_format
-      "BANDWIDTH=#{bandwidth}"
-    end
-
-    def average_bandwidth_format
-      return if average_bandwidth.nil?
-      "AVERAGE-BANDWIDTH=#{average_bandwidth}"
-    end
 
-    def audio_format
-      return if audio.nil?
-      %(AUDIO="#{audio}")
-    end
-
-    def video_format
-      return if video.nil?
-      %(VIDEO="#{video}")
-    end
-
-    def subtitles_format
-      return if subtitles.nil?
-      %(SUBTITLES="#{subtitles}")
+      "FRAME-RATE=#{format('%.3f', frame_rate)}"
     end
 
     def closed_captions_format
       return if closed_captions.nil?
 
       if closed_captions == 'NONE'
-        %(CLOSED-CAPTIONS=NONE)
+        'CLOSED-CAPTIONS=NONE'
       else
         %(CLOSED-CAPTIONS="#{closed_captions}")
       end
     end
-
-    def name_format
-      return if name.nil?
-      %(NAME="#{name}")
-    end
-
-    def audio_codec_code
-      return if @audio_codec.nil?
-      return 'mp4a.40.2' if @audio_codec.casecmp('aac-lc').zero?
-      return 'mp4a.40.5' if @audio_codec.casecmp('he-aac').zero?
-      return 'mp4a.40.34' if @audio_codec.casecmp('mp3').zero?
-    end
-
-    def video_codec(profile, level)
-      return if profile.nil? || level.nil?
-
-      return baseline_codec_string(level) if profile.casecmp('baseline').zero?
-      return main_codec_string(level) if profile.casecmp('main').zero?
-      return high_codec_string(level) if profile.casecmp('high').zero?
-    end
-
-    def baseline_codec_string(level)
-      return 'avc1.66.30' if level == 3.0
-      return 'avc1.42001f' if level == 3.1
-    end
-
-    def main_codec_string(level)
-      return 'avc1.77.30' if level == 3.0
-      return 'avc1.4d001f' if level == 3.1
-      return 'avc1.4d0028' if level == 4.0
-      return 'avc1.4d0029' if level == 4.1
-    end
-
-    def high_codec_string(level)
-      return nil unless [3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2].include?(level)
-
-      level_hex_string = level.to_s.sub('.', '').to_i.to_s(16)
-      return "avc1.6400#{level_hex_string}"
-    end
   end
 end

data/lib/m3u8/preload_hint_item.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module M3u8
+  # PreloadHintItem represents an EXT-X-PRELOAD-HINT tag which allows
+  # a server to indicate a resource that will be needed soon.
+  class PreloadHintItem
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] hint type (PART or MAP)
+    # @return [String, nil] hint resource URI
+    # @return [Integer, nil] byte range start offset
+    # @return [Integer, nil] byte range length
+    attr_accessor :type, :uri, :byterange_start, :byterange_length
+
+    # @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-PRELOAD-HINT tag.
+    # @param text [String] raw tag line
+    # @return [PreloadHintItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      PreloadHintItem.new(
+        type: attributes['TYPE'],
+        uri: attributes['URI'],
+        byterange_start:
+          parse_int(attributes['BYTERANGE-START']),
+        byterange_length:
+          parse_int(attributes['BYTERANGE-LENGTH'])
+      )
+    end
+
+    # Render as an m3u8 EXT-X-PRELOAD-HINT tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-PRELOAD-HINT:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [unquoted_format('TYPE', type),
+       quoted_format('URI', uri),
+       unquoted_format('BYTERANGE-START', byterange_start),
+       unquoted_format('BYTERANGE-LENGTH',
+                       byterange_length)].compact.join(',')
+    end
+  end
+end

data/lib/m3u8/reader.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+
 module M3u8
   # Reader provides parsing of m3u8 playlists
   class Reader
-    include M3u8
     attr_accessor :playlist, :item, :open, :master, :tags
 
     def initialize(*)
+      @has_endlist = false
       @tags = [basic_tags,
                media_segment_tags,
                media_playlist_tags,
@@ -13,13 +14,19 @@ module M3u8
                universal_tags].inject(:merge)
     end
 
+    # Parse an m3u8 playlist from a String or IO.
+    # @param input [String, IO] playlist content
+    # @return [Playlist] frozen playlist
     def read(input)
       @playlist = Playlist.new
-      input.each_line.with_index do |line, index|
+      @has_endlist = false
+      lines = input.is_a?(String) ? input : input.read
+      lines.split(/\r\n|\r|\n/).each_with_index do |line, index|
         validate_file_format(line) if index.zero?
         parse_line(line)
       end
-      playlist
+      playlist.live = !@has_endlist unless master
+      playlist.freeze
     end
 
     private
@@ -36,7 +43,10 @@ module M3u8
         '#EXT-X-KEY' => ->(line) { parse_key(line) },
         '#EXT-X-MAP' => ->(line) { parse_map(line) },
         '#EXT-X-PROGRAM-DATE-TIME' => ->(line) { parse_time(line) },
-        '#EXT-X-DATERANGE' => ->(line) { parse_date_range(line) }
+        '#EXT-X-DATERANGE' => ->(line) { parse_date_range(line) },
+        '#EXT-X-GAP' => ->(_line) { parse_gap },
+        '#EXT-X-BITRATE' => ->(line) { parse_bitrate(line) },
+        '#EXT-X-PART' => ->(line) { parse_part(line) }
       }
     end
 
@@ -48,8 +58,14 @@ module M3u8
         end,
         '#EXT-X-ALLOW-CACHE' => ->(line) { parse_cache(line) },
         '#EXT-X-TARGETDURATION' => ->(line) { parse_target(line) },
-        '#EXT-X-I-FRAMES-ONLY' => proc { playlist.iframes_only = true },
-        '#EXT-X-PLAYLIST-TYPE' => ->(line) { parse_playlist_type(line) }
+        '#EXT-X-I-FRAMES-ONLY' => ->(_line) { playlist.iframes_only = true },
+        '#EXT-X-PLAYLIST-TYPE' => ->(line) { parse_playlist_type(line) },
+        '#EXT-X-PART-INF' => ->(line) { parse_part_inf(line) },
+        '#EXT-X-SERVER-CONTROL' => ->(line) { parse_server_control(line) },
+        '#EXT-X-SKIP' => ->(line) { parse_skip(line) },
+        '#EXT-X-PRELOAD-HINT' => ->(line) { parse_preload_hint(line) },
+        '#EXT-X-RENDITION-REPORT' => ->(line) { parse_rendition_report(line) },
+        '#EXT-X-ENDLIST' => ->(_line) { @has_endlist = true }
       }
     end
 
@@ -59,21 +75,24 @@ module M3u8
         '#EXT-X-SESSION-DATA' => ->(line) { parse_session_data(line) },
         '#EXT-X-SESSION-KEY' => ->(line) { parse_session_key(line) },
         '#EXT-X-STREAM-INF' => ->(line) { parse_stream(line) },
-        '#EXT-X-I-FRAME-STREAM-INF' => ->(line) { parse_iframe_stream(line) }
+        '#EXT-X-I-FRAME-STREAM-INF' => ->(line) { parse_iframe_stream(line) },
+        '#EXT-X-CONTENT-STEERING' => ->(line) { parse_content_steering(line) }
       }
     end
 
     def universal_tags
       {
         '#EXT-X-START' => ->(line) { parse_start(line) },
-        '#EXT-X-INDEPENDENT-SEGMENTS' => proc do
+        '#EXT-X-INDEPENDENT-SEGMENTS' => lambda do |_line|
           playlist.independent_segments = true
-        end
+        end,
+        '#EXT-X-DEFINE' => ->(line) { parse_define(line) }
       }
     end
 
     def parse_line(line)
       return if match_tag(line)
+
       parse_next_line(line) if !item.nil? && open
     end
 
@@ -83,29 +102,33 @@ module M3u8
       end
 
       return unless tag.values.first
+
       tag.values.first.call(line)
       true
     end
 
+    def tag_value(line)
+      line.split(':', 2).last.strip
+    end
+
     def parse_playlist_type(line)
-      playlist.type = line.gsub('#EXT-X-PLAYLIST-TYPE:', '').delete!("\n")
+      playlist.type = tag_value(line)
     end
 
     def parse_version(line)
-      playlist.version = line.gsub('#EXT-X-VERSION:', '').to_i
+      playlist.version = tag_value(line).to_i
     end
 
     def parse_sequence(line)
-      playlist.sequence = line.gsub('#EXT-X-MEDIA-SEQUENCE:', '').to_i
+      playlist.sequence = tag_value(line).to_i
     end
 
     def parse_cache(line)
-      line = line.gsub('#EXT-X-ALLOW-CACHE:', '')
-      playlist.cache = parse_yes_no(line)
+      playlist.cache = tag_value(line) == 'YES'
     end
 
     def parse_target(line)
-      playlist.target = line.gsub('#EXT-X-TARGETDURATION:', '').to_i
+      playlist.target = tag_value(line).to_i
     end
 
     def parse_stream(line)
@@ -133,8 +156,7 @@ module M3u8
     end
 
     def parse_discontinuity_sequence(line)
-      value = line.gsub('#EXT-X-DISCONTINUITY-SEQUENCE:', '').strip
-      playlist.discontinuity_sequence = Integer(value)
+      playlist.discontinuity_sequence = Integer(tag_value(line))
     end
 
     def parse_key(line)
@@ -148,11 +170,7 @@ module M3u8
     end
 
     def parse_segment(line)
-      self.item = M3u8::SegmentItem.new
-      values = line.gsub('#EXTINF:', '').tr("\n", ',').split(',')
-      item.duration = values[0].to_f
-      item.comment = values[1] unless values[1].nil?
-
+      self.item = M3u8::SegmentItem.parse(line)
       self.master = false
       self.open = true
     end
@@ -179,9 +197,7 @@ module M3u8
     end
 
     def parse_start(line)
-      item = M3u8::PlaybackStart.new
-      item.parse(line)
-      playlist.items << item
+      playlist.items << M3u8::PlaybackStart.parse(line)
     end
 
     def parse_time(line)
@@ -194,9 +210,50 @@ module M3u8
     end
 
     def parse_date_range(line)
-      item = M3u8::DateRangeItem.new
-      item.parse(line)
-      playlist.items << item
+      playlist.items << M3u8::DateRangeItem.parse(line)
+    end
+
+    def parse_define(line)
+      playlist.items << M3u8::DefineItem.parse(line)
+    end
+
+    def parse_content_steering(line)
+      playlist.items << M3u8::ContentSteeringItem.parse(line)
+    end
+
+    def parse_part(line)
+      self.open = false
+      playlist.items << M3u8::PartItem.parse(line)
+    end
+
+    def parse_part_inf(line)
+      playlist.part_inf = M3u8::PartInfItem.parse(line)
+    end
+
+    def parse_server_control(line)
+      playlist.server_control = M3u8::ServerControlItem.parse(line)
+    end
+
+    def parse_skip(line)
+      playlist.items << M3u8::SkipItem.parse(line)
+    end
+
+    def parse_preload_hint(line)
+      playlist.items << M3u8::PreloadHintItem.parse(line)
+    end
+
+    def parse_rendition_report(line)
+      playlist.items << M3u8::RenditionReportItem.parse(line)
+    end
+
+    def parse_gap(*)
+      self.open = false
+      playlist.items << M3u8::GapItem.new
+    end
+
+    def parse_bitrate(line)
+      self.open = false
+      playlist.items << M3u8::BitrateItem.parse(line)
     end
 
     def parse_next_line(line)
@@ -212,6 +269,7 @@ module M3u8
 
     def validate_file_format(line)
       return if line.rstrip == '#EXTM3U'
+
       message = 'Playlist must start with a #EXTM3U tag, line read ' \
                 "contained the value: #{line}"
       raise InvalidPlaylistError, message

data/lib/m3u8/rendition_report_item.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module M3u8
+  # RenditionReportItem represents an EXT-X-RENDITION-REPORT tag which
+  # carries information about associated renditions in LL-HLS.
+  class RenditionReportItem
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] rendition URI
+    # @return [Integer, nil] last media sequence number
+    # @return [Integer, nil] last partial segment index
+    attr_accessor :uri, :last_msn, :last_part
+
+    # @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-RENDITION-REPORT tag.
+    # @param text [String] raw tag line
+    # @return [RenditionReportItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      RenditionReportItem.new(
+        uri: attributes['URI'],
+        last_msn: parse_int(attributes['LAST-MSN']),
+        last_part: parse_int(attributes['LAST-PART'])
+      )
+    end
+
+    # Render as an m3u8 EXT-X-RENDITION-REPORT tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-RENDITION-REPORT:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [quoted_format('URI', uri),
+       unquoted_format('LAST-MSN', last_msn),
+       unquoted_format('LAST-PART', last_part)].compact.join(',')
+    end
+  end
+end