m3u8 1.8.1 → 1.9.0

data/lib/m3u8/playlist.rb

@@ -4,6 +4,8 @@ module M3u8
   # Playlist represents an m3u8 playlist, it can be a master playlist
   # or a set of media segments
   class Playlist
+    include Serializable
+
     # @return [Array] list of items in the playlist
     # @return [Integer, nil] EXT-X-VERSION value
     # @return [Boolean, nil] EXT-X-ALLOW-CACHE value
@@ -21,10 +23,14 @@ module M3u8
                   :independent_segments, :live, :part_inf,
                   :server_control
 
+    # @return [Array<String>] unrecognized #EXT tags found while parsing
+    attr_reader :unknown_tags
+
     # @param options [Hash] playlist attributes
     def initialize(options = {})
       assign_options(options)
       @items = []
+      @unknown_tags = []
     end
 
     # Build a playlist using a DSL block.
@@ -52,12 +58,63 @@ module M3u8
 
     # Parse an m3u8 playlist from a String or IO.
     # @param input [String, IO] playlist content
+    # @param strict [Boolean] raise on unsupported tags when true
     # @return [Playlist] frozen playlist
-    def self.read(input)
-      reader = Reader.new
+    def self.read(input, strict: false)
+      reader = Reader.new(strict: strict)
       reader.read(input)
     end
 
+    # Reconstruct a playlist from a Hash produced by #to_h.
+    # @param hash [Hash] playlist attributes and items
+    # @return [Playlist]
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_sym)
+      items = hash.delete(:items) || []
+      part_inf = hash.delete(:part_inf)
+      server_control = hash.delete(:server_control)
+      playlist = new(hash)
+      playlist.part_inf = nested(PartInfItem, part_inf)
+      playlist.server_control = nested(ServerControlItem, server_control)
+      items.each { |attributes| playlist.items << item_from_h(attributes) }
+      playlist
+    end
+
+    def self.nested(klass, attributes)
+      return if attributes.nil?
+
+      klass.new(attributes.transform_keys(&:to_sym))
+    end
+    private_class_method :nested
+
+    def self.item_from_h(attributes)
+      attributes = attributes.transform_keys(&:to_sym)
+      klass = item_class(attributes.delete(:item_type))
+      return klass.new if attributes.empty?
+
+      klass.new(attributes)
+    end
+    private_class_method :item_from_h
+
+    def self.item_class(type)
+      klass = serializable_item_classes[type.to_s]
+      return klass unless klass.nil?
+
+      raise InvalidPlaylistError, "Unknown item type: #{type.inspect}"
+    end
+    private_class_method :item_class
+
+    def self.serializable_item_classes
+      @serializable_item_classes ||=
+        M3u8.constants.each_with_object({}) do |name, map|
+          const = M3u8.const_get(name)
+          next unless const.is_a?(Class) && const.include?(Serializable)
+
+          map[name.to_s] = const
+        end
+    end
+    private_class_method :serializable_item_classes
+
     # Write the playlist to an IO object.
     # @param output [IO] writable IO object
     # @return [void]
@@ -66,6 +123,14 @@ module M3u8
       writer.write(self)
     end
 
+    # Resolve EXT-X-DEFINE variable references into a new Playlist.
+    # @param imported [Hash] values for IMPORT definitions
+    # @param query [Hash] values for QUERYPARAM definitions
+    # @return [Playlist]
+    def resolve_variables(imported: {}, query: {})
+      VariableResolver.new(self, imported: imported, query: query).resolve
+    end
+
     # Whether this is a live (non-VOD) media playlist.
     # @return [Boolean]
     def live?
@@ -88,6 +153,7 @@ module M3u8
     def freeze
       items.each { |item| freeze_item(item) }
       items.freeze
+      unknown_tags.freeze
       part_inf&.freeze
       server_control&.freeze
       super
@@ -101,6 +167,27 @@ module M3u8
       output.string
     end
 
+    # Convert the playlist into a Hash of its attributes and items.
+    # Each item Hash carries an :item_type key identifying its class.
+    # @return [Hash<Symbol, Object>]
+    def to_h
+      {
+        master: master?,
+        live: live?,
+        version: version,
+        independent_segments: independent_segments,
+        iframes_only: iframes_only,
+        type: type,
+        target: target,
+        sequence: sequence,
+        discontinuity_sequence: discontinuity_sequence,
+        cache: cache,
+        part_inf: part_inf&.to_h,
+        server_control: server_control&.to_h,
+        items: items.map { |item| item_to_h(item) }
+      }
+    end
+
     # Collect validation errors for the playlist.
     # @return [Array<String>] list of error messages
     def errors
@@ -123,6 +210,16 @@ module M3u8
       errors.empty?
     end
 
+    # Collect non-fatal conformance warnings (version compatibility and
+    # Low-Latency HLS recommendations).
+    # @return [Array<String>] list of warning messages
+    def warnings
+      [].tap do |list|
+        version_warnings(list)
+        low_latency_warnings(list)
+      end
+    end
+
     # @return [Array<SegmentItem>]
     def segments
       items.grep(SegmentItem)
@@ -176,6 +273,10 @@ module M3u8
 
     private
 
+    def item_to_h(item)
+      item.to_h.merge(item_type: item.class.name.split('::').last)
+    end
+
     def freeze_item(item)
       item.byterange&.freeze if item.respond_to?(:byterange)
       item.program_date_time&.freeze if item.respond_to?(:program_date_time)
@@ -292,6 +393,139 @@ module M3u8
       errors << 'Playlist contains both master and media items'
     end
 
+    VERSION_FEATURES = [
+      [2, 'EXT-X-KEY IV', :encryption_iv?],
+      [3, 'floating-point EXTINF', :float_durations?],
+      [4, 'EXT-X-BYTERANGE', :byterange_segments?],
+      [4, 'EXT-X-I-FRAMES-ONLY', :iframes_only],
+      [5, 'KEYFORMAT', :key_format?],
+      [5, 'EXT-X-MAP', :iframe_map?],
+      [6, 'EXT-X-MAP', :media_map?],
+      [7, 'SERVICE INSTREAM-ID', :service_instream_id?],
+      [7, 'EXT-X-SESSION-KEY', :session_keys?],
+      [8, 'EXT-X-DEFINE', :defines?],
+      [9, 'EXT-X-SERVER-CONTROL', :server_control?],
+      [9, 'EXT-X-PART-INF', :part_inf?],
+      [9, 'EXT-X-PART', :parts?],
+      [9, 'EXT-X-SKIP', :skips?],
+      [9, 'EXT-X-PRELOAD-HINT', :preload_hints?],
+      [9, 'EXT-X-RENDITION-REPORT', :rendition_reports?]
+    ].freeze
+    private_constant :VERSION_FEATURES
+
+    def version_warnings(list)
+      VERSION_FEATURES.each do |required, feature, predicate|
+        next unless send(predicate)
+        next if effective_version >= required
+
+        list << "#{feature} requires version #{required} (#{declared_version})"
+      end
+    end
+
+    def effective_version
+      version || 1
+    end
+
+    def declared_version
+      version.nil? ? 'no EXT-X-VERSION tag' : "version #{version}"
+    end
+
+    def encryption_iv?
+      (keys + session_keys).any?(&:iv)
+    end
+
+    def key_format?
+      (keys + session_keys).any? do |item|
+        item.key_format || item.key_format_versions
+      end
+    end
+
+    def float_durations?
+      segments.any? { |item| item.duration.is_a?(Float) }
+    end
+
+    def byterange_segments?
+      segments.any?(&:byterange)
+    end
+
+    def iframe_map?
+      maps.any? && iframes_only
+    end
+
+    def media_map?
+      maps.any? && !iframes_only
+    end
+
+    def defines?
+      items.grep(DefineItem).any?
+    end
+
+    def service_instream_id?
+      media_items.any? { |item| item.instream_id&.start_with?('SERVICE') }
+    end
+
+    def session_keys?
+      session_keys.any?
+    end
+
+    def server_control?
+      !server_control.nil?
+    end
+
+    def part_inf?
+      !part_inf.nil?
+    end
+
+    def parts?
+      parts.any?
+    end
+
+    def skips?
+      items.grep(SkipItem).any?
+    end
+
+    def preload_hints?
+      items.grep(PreloadHintItem).any?
+    end
+
+    def rendition_reports?
+      items.grep(RenditionReportItem).any?
+    end
+
+    def low_latency_warnings(list)
+      if parts.any? && part_inf.nil?
+        list << 'EXT-X-PART requires EXT-X-PART-INF'
+      end
+      part_hold_back_warnings(list) unless part_inf.nil?
+      skip_warnings(list)
+    end
+
+    def part_hold_back_warnings(list)
+      hold_back = server_control&.part_hold_back
+      return if hold_back.nil?
+
+      target = part_inf.part_target
+      return if target.nil?
+
+      compare_part_hold_back(list, hold_back, target)
+    end
+
+    def compare_part_hold_back(list, hold_back, target)
+      if hold_back < target * 2
+        list << 'PART-HOLD-BACK should be at least twice PART-TARGET'
+      elsif hold_back < target * 3
+        list << 'PART-HOLD-BACK should be at least three times PART-TARGET'
+      end
+    end
+
+    def skip_warnings(list)
+      skip = server_control&.can_skip_until
+      return if skip.nil?
+      return if skip >= target * 6
+
+      list << 'CAN-SKIP-UNTIL should be at least six times TARGETDURATION'
+    end
+
     def playlist_size
       playlists.size
     end

data/lib/m3u8/playlist_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # EXT-X-I-FRAME-STREAM-INF attributes
   class PlaylistItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] program ID

data/lib/m3u8/preload_hint_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # a server to indicate a resource that will be needed soon.
   class PreloadHintItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] hint type (PART or MAP)

data/lib/m3u8/reader.rb

@@ -5,7 +5,8 @@ module M3u8
   class Reader
     attr_accessor :playlist, :item, :open, :master, :tags
 
-    def initialize(*)
+    def initialize(strict: false)
+      @strict = strict
       @has_endlist = false
       @tags = [basic_tags,
                media_segment_tags,
@@ -22,7 +23,10 @@ module M3u8
       @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?
+        if index.zero?
+          validate_file_format(line)
+          next
+        end
         parse_line(line)
       end
       playlist.live = !@has_endlist unless master
@@ -92,10 +96,19 @@ module M3u8
 
     def parse_line(line)
       return if match_tag(line)
+      return handle_unmatched(line) if line.start_with?('#')
 
       parse_next_line(line) if !item.nil? && open
     end
 
+    def handle_unmatched(line)
+      return unless line.start_with?('#EXT')
+
+      raise InvalidPlaylistError, "Unsupported tag: #{line}" if @strict
+
+      playlist.unknown_tags << line
+    end
+
     def match_tag(line)
       tag = @tags.select do |key|
         line.start_with?(key) && !line.start_with?("#{key}-")

data/lib/m3u8/rendition_report_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # carries information about associated renditions in LL-HLS.
   class RenditionReportItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] rendition URI

data/lib/m3u8/segment_item.rb

@@ -6,6 +6,7 @@ module M3u8
   class SegmentItem
     include M3u8
     include AttributeFormatter
+    include Serializable
 
     # @return [Float, nil] segment duration in seconds
     # @return [String, nil] segment URI

data/lib/m3u8/serializable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Serializable provides a Hash representation of an item by converting
+  # its instance variables into JSON-compatible values.
+  module Serializable
+    # Convert the item into a Hash of its attributes.
+    # @return [Hash<Symbol, Object>]
+    def to_h
+      instance_variables.each_with_object({}) do |ivar, result|
+        key = ivar.to_s.delete_prefix('@').to_sym
+        result[key] = Serializable.serialize(instance_variable_get(ivar))
+      end
+    end
+
+    # Convert the item into a JSON-ready Hash (alias of #to_h).
+    # @return [Hash]
+    def as_json(*)
+      to_h
+    end
+
+    # Render the item as a JSON string.
+    # @return [String]
+    def to_json(*args)
+      require 'json'
+      to_h.to_json(*args)
+    end
+
+    # Recursively convert a value into a JSON-compatible form.
+    # @param value [Object] value to convert
+    # @return [Object]
+    def self.serialize(value)
+      case value
+      when TimeItem then serialize(value.time)
+      when Time then value.iso8601
+      when BigDecimal then value.to_f
+      when Serializable then value.to_h
+      when Hash then value.transform_values { |item| serialize(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/m3u8/server_control_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # provides directives for Low-Latency HLS delivery.
   class ServerControlItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [Float, nil] skip threshold in seconds

data/lib/m3u8/session_data_item.rb

@@ -4,6 +4,7 @@ module M3u8
   # SessionDataItem represents a set of EXT-X-SESSION-DATA attributes
   class SessionDataItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] DATA-ID value

data/lib/m3u8/session_key_item.rb

@@ -5,14 +5,7 @@ module M3u8
   class SessionKeyItem
     include Encryptable
     extend M3u8
-
-    # @param params [Hash] attribute key-value pairs
-    def initialize(params = {})
-      options = convert_key_names(params)
-      options.merge(params).each do |key, value|
-        instance_variable_set("@#{key}", value)
-      end
-    end
+    include Serializable
 
     # Parse an EXT-X-SESSION-KEY tag.
     # @param text [String] raw tag line

data/lib/m3u8/skip_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # Updates for Low-Latency HLS.
   class SkipItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [Integer, nil] number of skipped segments

data/lib/m3u8/time_item.rb

@@ -4,6 +4,7 @@ module M3u8
   # TimeItem represents EXT-X-PROGRAM-DATE-TIME
   class TimeItem
     extend M3u8
+    include Serializable
 
     # @return [Time, String, nil] program date-time value
     attr_accessor :time

data/lib/m3u8/variable_resolver.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module M3u8
+  # VariableResolver applies EXT-X-DEFINE variable substitution to a
+  # playlist, replacing {$NAME} references in URIs and string attribute
+  # values with their defined values per RFC 8216bis section 4.2. A
+  # definition must appear before any reference that uses it.
+  class VariableResolver
+    VARIABLE_REFERENCE = /\{\$([a-zA-Z0-9_-]+)\}/
+
+    # @param playlist [Playlist] playlist to resolve
+    # @param imported [Hash] values for IMPORT definitions
+    # @param query [Hash] values for QUERYPARAM definitions
+    def initialize(playlist, imported: {}, query: {})
+      @playlist = playlist
+      @imported = imported
+      @query = query
+    end
+
+    # Resolve variable references into a new Playlist.
+    # @return [Playlist]
+    def resolve
+      hash = @playlist.to_h
+      hash[:items] = resolve_items(hash[:items])
+      Playlist.from_h(hash)
+    end
+
+    private
+
+    def resolve_items(items)
+      defined = {}
+      items.map do |item|
+        if item[:item_type] == 'DefineItem'
+          register(item, defined)
+          item
+        else
+          substitute(item, defined)
+        end
+      end
+    end
+
+    def register(item, defined)
+      name, value = binding_for(item)
+      defined[name] = value
+    end
+
+    def binding_for(define)
+      if define[:import]
+        external(define[:import], @imported, 'IMPORT')
+      elsif define[:queryparam]
+        external(define[:queryparam], @query, 'QUERYPARAM')
+      else
+        [define[:name], define[:value]]
+      end
+    end
+
+    def external(name, source, kind)
+      unless source.key?(name)
+        raise InvalidPlaylistError, "#{kind} variable not found: #{name}"
+      end
+
+      [name, source[name]]
+    end
+
+    def substitute(value, defined)
+      case value
+      when String then expand(value, defined)
+      when Hash
+        value.transform_values { |item| substitute(item, defined) }
+      else value
+      end
+    end
+
+    def expand(string, defined)
+      string.gsub(VARIABLE_REFERENCE) do
+        name = Regexp.last_match(1)
+        defined.fetch(name) do
+          raise InvalidPlaylistError, "Undefined variable: #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/m3u8/version.rb

@@ -2,5 +2,5 @@
 
 # M3u8 provides parsing, generation, and validation of m3u8 playlists
 module M3u8
-  VERSION = '1.8.1'
+  VERSION = '1.9.0'
 end

data/lib/m3u8.rb

@@ -2,6 +2,8 @@
 
 require 'bigdecimal'
 require 'stringio'
+require 'time'
+require_relative 'm3u8/serializable'
 Dir["#{File.dirname(__FILE__)}/m3u8/*.rb"].each { |file| require file }
 
 # M3u8 provides parsing, generation, and validation of m3u8 playlists

data/spec/lib/m3u8/cli/diff_command_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::CLI::DiffCommand do
+  let(:stdout) { StringIO.new }
+
+  def diff(first, second)
+    described_class.new(first, second, stdout).run
+  end
+
+  def media(version: 3, durations: [5.0])
+    playlist = M3u8::Playlist.new(version: version, target: 10)
+    durations.each do |duration|
+      playlist.items << M3u8::SegmentItem.new(duration: duration,
+                                              segment: 'segment.ts')
+    end
+    playlist
+  end
+
+  it 'reports identical playlists and exits 0' do
+    expect(diff(media, media)).to eq(0)
+    expect(stdout.string.strip).to eq('Identical')
+  end
+
+  it 'reports a changed top-level attribute' do
+    code = diff(media(version: 3), media(version: 4))
+    expect(code).to eq(1)
+    expect(stdout.string).to include('version: 3 => 4')
+  end
+
+  it 'reports a changed item attribute' do
+    code = diff(media(durations: [5.0]), media(durations: [6.0]))
+    expect(code).to eq(1)
+    expect(stdout.string).to include('items[0].duration: 5.0 => 6.0')
+  end
+
+  it 'reports an added item' do
+    code = diff(media(durations: [5.0]), media(durations: [5.0, 6.0]))
+    expect(code).to eq(1)
+    expect(stdout.string).to include('items[1]: added SegmentItem')
+  end
+
+  it 'reports a removed item' do
+    code = diff(media(durations: [5.0, 6.0]), media(durations: [5.0]))
+    expect(code).to eq(1)
+    expect(stdout.string).to include('items[1]: removed SegmentItem')
+  end
+end

data/spec/lib/m3u8/cli/inspect_command_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'json'
 
 describe M3u8::CLI::InspectCommand do
   let(:stdout) { StringIO.new }
@@ -12,6 +13,17 @@ describe M3u8::CLI::InspectCommand do
     described_class.new(playlist, stdout).run
   end
 
+  describe 'json output' do
+    it 'prints the playlist as JSON when json is true' do
+      playlist = M3u8::Playlist.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
+      code = described_class.new(playlist, stdout, json: true).run
+      expect(code).to eq(0)
+      expect(JSON.parse(stdout.string)['master']).to be(true)
+    end
+  end
+
   describe 'media playlist' do
     it 'displays metadata for a VOD playlist' do
       code = inspect_fixture('playlist.m3u8')

data/spec/lib/m3u8/cli/validate_command_spec.rb

@@ -13,7 +13,7 @@ describe M3u8::CLI::ValidateCommand do
         )
         code = described_class.new(playlist, stdout).run
         expect(code).to eq(0)
-        expect(stdout.string.strip).to eq('Valid')
+        expect(stdout.string).to start_with('Valid')
       end
     end
 
@@ -35,5 +35,21 @@ describe M3u8::CLI::ValidateCommand do
         )
       end
     end
+
+    context 'when playlist has warnings' do
+      it 'prints warnings after the validity result' do
+        playlist = M3u8::Playlist.read(
+          File.read('spec/fixtures/map_playlist.m3u8')
+        )
+        code = described_class.new(playlist, stdout).run
+        expect(code).to eq(0)
+        lines = stdout.string.split("\n")
+        expect(lines).to include('Valid')
+        expect(lines).to include('Warnings:')
+        expect(lines).to include(
+          '  - EXT-X-MAP requires version 6 (version 5)'
+        )
+      end
+    end
   end
 end