m3u8 0.8.2 → 1.8.1

data/lib/m3u8/date_range_item.rb

@@ -1,113 +1,184 @@
 # frozen_string_literal: true
+
 module M3u8
   # DateRangeItem represents a #EXT-X-DATERANGE tag
   class DateRangeItem
-    include M3u8
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] unique date range identifier
+    # @return [String, nil] CLASS attribute
+    # @return [String, nil] start date (ISO 8601)
+    # @return [String, nil] end date (ISO 8601)
+    # @return [Float, nil] duration in seconds
+    # @return [Float, nil] planned duration in seconds
+    # @return [String, nil] SCTE-35 command hex string
+    # @return [String, nil] SCTE-35 out hex string
+    # @return [String, nil] SCTE-35 in hex string
+    # @return [String, nil] CUE attribute
+    # @return [Boolean, nil] END-ON-NEXT flag
+    # @return [Hash, nil] client-defined X- attributes
+    # @return [String, nil] interstitial asset URI
+    # @return [String, nil] interstitial asset list URI
+    # @return [Float, nil] interstitial resume offset
+    # @return [Float, nil] interstitial playout limit
+    # @return [String, nil] interstitial restrict value
+    # @return [String, nil] interstitial snap value
+    # @return [String, nil] interstitial timeline occupies
+    # @return [String, nil] interstitial timeline style
+    # @return [String, nil] content may vary flag
     attr_accessor :id, :class_name, :start_date, :end_date, :duration,
                   :planned_duration, :scte35_cmd, :scte35_out, :scte35_in,
-                  :end_on_next, :client_attributes
-
+                  :cue, :end_on_next, :client_attributes,
+                  :asset_uri, :asset_list, :resume_offset,
+                  :playout_limit, :restrict, :snap,
+                  :timeline_occupies, :timeline_style,
+                  :content_may_vary
+
+    INTERSTITIAL_KEYS = %w[
+      X-ASSET-URI X-ASSET-LIST X-RESUME-OFFSET X-PLAYOUT-LIMIT
+      X-RESTRICT X-SNAP X-TIMELINE-OCCUPIES X-TIMELINE-STYLE
+      X-CONTENT-MAY-VARY
+    ].freeze
+
+    # @param options [Hash] attribute key-value pairs
     def initialize(options = {})
       options.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
-    def parse(text)
+    # Parse an EXT-X-DATERANGE tag.
+    # @param text [String] raw tag line
+    # @return [DateRangeItem]
+    def self.parse(text)
       attributes = parse_attributes(text)
-      @id = attributes['ID']
-      @class_name = attributes['CLASS']
-      @start_date = attributes['START-DATE']
-      @end_date = attributes['END-DATE']
-      @duration = parse_float(attributes['DURATION'])
-      @planned_duration = parse_float(attributes['PLANNED-DURATION'])
-      @scte35_cmd = attributes['SCTE35-CMD']
-      @scte35_out = attributes['SCTE35-OUT']
-      @scte35_in = attributes['SCTE35-IN']
-      @end_on_next = attributes.key?('END-ON-NEXT') ? true : false
-      @client_attributes = parse_client_attributes(attributes)
+      options = parse_base_attributes(attributes)
+                .merge(parse_interstitials(attributes))
+                .merge(client_attributes:
+                         parse_client_attributes(attributes))
+      DateRangeItem.new(options)
     end
 
+    def self.parse_base_attributes(attributes)
+      { id: attributes['ID'],
+        class_name: attributes['CLASS'],
+        start_date: attributes['START-DATE'],
+        end_date: attributes['END-DATE'],
+        duration: parse_float(attributes['DURATION']),
+        planned_duration:
+          parse_float(attributes['PLANNED-DURATION']),
+        scte35_cmd: attributes['SCTE35-CMD'],
+        scte35_out: attributes['SCTE35-OUT'],
+        scte35_in: attributes['SCTE35-IN'],
+        cue: attributes['CUE'],
+        end_on_next: attributes.key?('END-ON-NEXT') }
+    end
+    private_class_method :parse_base_attributes
+
+    def self.parse_interstitials(attributes)
+      { asset_uri: attributes['X-ASSET-URI'],
+        asset_list: attributes['X-ASSET-LIST'],
+        resume_offset:
+          parse_float(attributes['X-RESUME-OFFSET']),
+        playout_limit:
+          parse_float(attributes['X-PLAYOUT-LIMIT']),
+        restrict: attributes['X-RESTRICT'],
+        snap: attributes['X-SNAP'],
+        timeline_occupies:
+          attributes['X-TIMELINE-OCCUPIES'],
+        timeline_style: attributes['X-TIMELINE-STYLE'],
+        content_may_vary:
+          attributes['X-CONTENT-MAY-VARY'] }
+    end
+    private_class_method :parse_interstitials
+
+    # Render as an m3u8 EXT-X-DATERANGE tag.
+    # @return [String]
     def to_s
       "#EXT-X-DATERANGE:#{formatted_attributes}"
     end
 
-    private
-
-    def formatted_attributes
-      [%(ID="#{id}"),
-       class_name_format,
-       %(START-DATE="#{start_date}"),
-       end_date_format,
-       duration_format,
-       planned_duration_format,
-       client_attributes_format,
-       scte35_cmd_format,
-       scte35_out_format,
-       scte35_in_format,
-       end_on_next_format].compact.join(',')
+    # Parse SCTE-35 command data.
+    # @return [Scte35, nil]
+    def scte35_cmd_info
+      Scte35.parse(scte35_cmd) unless scte35_cmd.nil?
     end
 
-    def class_name_format
-      return if class_name.nil?
-      %(CLASS="#{class_name}")
+    # Parse SCTE-35 out data.
+    # @return [Scte35, nil]
+    def scte35_out_info
+      Scte35.parse(scte35_out) unless scte35_out.nil?
     end
 
-    def end_date_format
-      return if end_date.nil?
-      %(END-DATE="#{end_date}")
+    # Parse SCTE-35 in data.
+    # @return [Scte35, nil]
+    def scte35_in_info
+      Scte35.parse(scte35_in) unless scte35_in.nil?
     end
 
-    def duration_format
-      return if duration.nil?
-      "DURATION=#{duration}"
+    def self.parse_client_attributes(attributes)
+      attributes.select do |key|
+        key.start_with?('X-') && !INTERSTITIAL_KEYS.include?(key)
+      end
     end
+    private_class_method :parse_client_attributes
+
+    private
 
-    def planned_duration_format
-      return if planned_duration.nil?
-      "PLANNED-DURATION=#{planned_duration}"
+    def formatted_attributes
+      [%(ID="#{id}"),
+       quoted_format('CLASS', class_name),
+       %(START-DATE="#{start_date}"),
+       quoted_format('END-DATE', end_date),
+       unquoted_format('DURATION', decimal_format(duration)),
+       unquoted_format('PLANNED-DURATION', decimal_format(planned_duration)),
+       client_attributes_format,
+       interstitial_formats,
+       unquoted_format('SCTE35-CMD', scte35_cmd),
+       unquoted_format('SCTE35-OUT', scte35_out),
+       unquoted_format('SCTE35-IN', scte35_in),
+       quoted_format('CUE', cue),
+       end_on_next_format].flatten.compact.join(',')
     end
 
     def client_attributes_format
-      return if client_attributes.nil?
+      return if client_attributes.nil? || client_attributes.empty?
+
       client_attributes.map do |attribute|
         value = attribute.last
-        value_format = decimal?(value) ? value : %("#{value}")
-        "#{attribute.first}=#{value_format}"
+        fmt = decimal?(value) ? decimal_format(value) : %("#{value}")
+        "#{attribute.first}=#{fmt}"
       end
     end
 
     def decimal?(value)
-      return true if value =~ /\A\d+\Z/
+      val = value.to_s
+      return true if val =~ /\A\d+\Z/
+
       begin
-        return true if Float(value)
-      rescue
+        true if Float(val)
+      rescue StandardError
         false
       end
     end
 
-    def scte35_cmd_format
-      return if scte35_cmd.nil?
-      "SCTE35-CMD=#{scte35_cmd}"
-    end
-
-    def scte35_out_format
-      return if scte35_out.nil?
-      "SCTE35-OUT=#{scte35_out}"
-    end
-
-    def scte35_in_format
-      return if scte35_in.nil?
-      "SCTE35-IN=#{scte35_in}"
+    def interstitial_formats
+      [quoted_format('X-ASSET-URI', asset_uri),
+       quoted_format('X-ASSET-LIST', asset_list),
+       unquoted_format('X-RESUME-OFFSET', decimal_format(resume_offset)),
+       unquoted_format('X-PLAYOUT-LIMIT', decimal_format(playout_limit)),
+       quoted_format('X-RESTRICT', restrict),
+       quoted_format('X-SNAP', snap),
+       quoted_format('X-TIMELINE-OCCUPIES', timeline_occupies),
+       quoted_format('X-TIMELINE-STYLE', timeline_style),
+       quoted_format('X-CONTENT-MAY-VARY', content_may_vary)]
     end
 
     def end_on_next_format
       return unless end_on_next
-      'END-ON-NEXT=YES'
-    end
 
-    def parse_client_attributes(attributes)
-      attributes.select { |key| key.start_with?('X-') }
+      'END-ON-NEXT=YES'
     end
   end
 end

data/lib/m3u8/define_item.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module M3u8
+  # DefineItem represents an EXT-X-DEFINE tag which provides variable
+  # definitions for variable substitution. Supports three mutually
+  # exclusive modes: NAME/VALUE, IMPORT, or QUERYPARAM.
+  class DefineItem
+    extend M3u8
+
+    # @return [String, nil] variable name
+    # @return [String, nil] variable value
+    # @return [String, nil] imported variable name
+    # @return [String, nil] query parameter name
+    attr_accessor :name, :value, :import, :queryparam
+
+    # @param params [Hash] attribute key-value pairs
+    def initialize(params = {})
+      params.each do |key, val|
+        instance_variable_set("@#{key}", val)
+      end
+    end
+
+    # Parse an EXT-X-DEFINE tag.
+    # @param text [String] raw tag line
+    # @return [DefineItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      DefineItem.new(
+        name: attributes['NAME'],
+        value: attributes['VALUE'],
+        import: attributes['IMPORT'],
+        queryparam: attributes['QUERYPARAM']
+      )
+    end
+
+    # Render as an m3u8 EXT-X-DEFINE tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-DEFINE:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      if import
+        %(IMPORT="#{import}")
+      elsif queryparam
+        %(QUERYPARAM="#{queryparam}")
+      else
+        %(NAME="#{name}",VALUE="#{value}")
+      end
+    end
+  end
+end

data/lib/m3u8/discontinuity_item.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
+
 module M3u8
   # DiscontinuityItem represents a EXT-X-DISCONTINUITY tag to indicate a
   # discontinuity between the SegmentItems that proceed and follow it.
   class DiscontinuityItem
+    # Render as an m3u8 EXT-X-DISCONTINUITY tag.
+    # @return [String]
     def to_s
       "#EXT-X-DISCONTINUITY\n"
     end

data/lib/m3u8/encryptable.rb

@@ -1,7 +1,22 @@
 # frozen_string_literal: true
+
 module M3u8
-  # Encapsulates logic common to encryption key tags
+  # Encapsulates logic common to encryption key tags.
+  # Adds :method, :uri, :iv, :key_format, and
+  # :key_format_versions accessors when included.
   module Encryptable
+    include AttributeFormatter
+
+    # @!attribute [rw] method
+    #   @return [String, nil] encryption method
+    # @!attribute [rw] uri
+    #   @return [String, nil] key URI
+    # @!attribute [rw] iv
+    #   @return [String, nil] initialization vector
+    # @!attribute [rw] key_format
+    #   @return [String, nil] KEYFORMAT value
+    # @!attribute [rw] key_format_versions
+    #   @return [String, nil] KEYFORMATVERSIONS value
     def self.included(base)
       base.send :attr_accessor, :method
       base.send :attr_accessor, :uri
@@ -10,42 +25,24 @@ module M3u8
       base.send :attr_accessor, :key_format_versions
     end
 
+    # Render encryption attributes as a comma-separated string.
+    # @return [String]
     def attributes_to_s
-      [method_format,
-       uri_format,
-       iv_format,
-       key_format_format,
-       key_format_versions_format].compact.join(',')
+      [unquoted_format('METHOD', method),
+       quoted_format('URI', uri),
+       unquoted_format('IV', iv),
+       quoted_format('KEYFORMAT', key_format),
+       quoted_format('KEYFORMATVERSIONS',
+                     key_format_versions)].compact.join(',')
     end
 
+    # Map HLS attribute names to Ruby symbol keys.
+    # @param attributes [Hash] raw attribute hash
+    # @return [Hash] symbolized options
     def convert_key_names(attributes)
       { method: attributes['METHOD'], uri: attributes['URI'],
         iv: attributes['IV'], key_format: attributes['KEYFORMAT'],
         key_format_versions: attributes['KEYFORMATVERSIONS'] }
     end
-
-    private
-
-    def method_format
-      "METHOD=#{method}"
-    end
-
-    def uri_format
-      %(URI="#{uri}") unless uri.nil?
-    end
-
-    def iv_format
-      "IV=#{iv}" unless iv.nil?
-    end
-
-    def key_format_format
-      %(KEYFORMAT="#{key_format}") unless key_format.nil?
-    end
-
-    def key_format_versions_format
-      return if key_format_versions.nil?
-
-      %(KEYFORMATVERSIONS="#{key_format_versions}")
-    end
   end
 end

data/lib/m3u8/error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   class InvalidPlaylistError < StandardError
   end

data/lib/m3u8/gap_item.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module M3u8
+  # GapItem represents an EXT-X-GAP tag to indicate that the segment URI
+  # to which it applies does not contain media data and should not be
+  # loaded by clients.
+  class GapItem
+    # Render as an m3u8 EXT-X-GAP tag.
+    # @return [String]
+    def to_s
+      '#EXT-X-GAP'
+    end
+  end
+end

data/lib/m3u8/key_item.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
+
 module M3u8
   # KeyItem represents a set of EXT-X-KEY attributes
   class KeyItem
     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|
@@ -12,11 +14,16 @@ module M3u8
       end
     end
 
+    # Parse an EXT-X-KEY tag.
+    # @param text [String] raw tag line
+    # @return [KeyItem]
     def self.parse(text)
       attributes = parse_attributes(text)
       KeyItem.new(attributes)
     end
 
+    # Render as an m3u8 EXT-X-KEY tag.
+    # @return [String]
     def to_s
       "#EXT-X-KEY:#{attributes_to_s}"
     end

data/lib/m3u8/map_item.rb

@@ -1,16 +1,25 @@
 # frozen_string_literal: true
+
 module M3u8
   # MapItem represents a EXT-X-MAP tag which specifies how to obtain the Media
   # Initialization Section
   class MapItem
     extend M3u8
     include M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] URI of the initialization section
+    # @return [ByteRange, nil] byte range within the resource
     attr_accessor :uri, :byterange
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
-      intialize_with_byterange(params)
+      initialize_with_byterange(params)
     end
 
+    # Parse an EXT-X-MAP tag.
+    # @param text [String] raw tag line
+    # @return [MapItem]
     def self.parse(text)
       attributes = parse_attributes(text)
       range_value = attributes['BYTERANGE']
@@ -19,15 +28,17 @@ module M3u8
       MapItem.new(options)
     end
 
+    # Render as an m3u8 EXT-X-MAP tag.
+    # @return [String]
     def to_s
-      %(#EXT-X-MAP:URI="#{uri}"#{byterange_format})
+      "#EXT-X-MAP:#{formatted_attributes.compact.join(',')}"
     end
 
     private
 
-    def byterange_format
-      return if byterange.nil?
-      %(,BYTERANGE="#{byterange}")
+    def formatted_attributes
+      [%(URI="#{uri}"),
+       quoted_format('BYTERANGE', byterange)]
     end
   end
 end

data/lib/m3u8/media_item.rb

@@ -1,21 +1,45 @@
 # frozen_string_literal: true
+
 module M3u8
   # MediaItem represents a set of EXT-X-MEDIA attributes
   class MediaItem
     extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] media type (AUDIO, VIDEO, etc.)
+    # @return [String, nil] group ID
+    # @return [String, nil] language tag (RFC 5646)
+    # @return [String, nil] associated language tag
+    # @return [String, nil] rendition name
+    # @return [Boolean, nil] AUTOSELECT flag
+    # @return [Boolean, nil] DEFAULT flag
+    # @return [String, nil] rendition URI
+    # @return [Boolean, nil] FORCED flag
+    # @return [String, nil] instream ID for CC
+    # @return [String, nil] media characteristics
+    # @return [String, nil] audio channels
+    # @return [String, nil] stable rendition ID
+    # @return [Integer, nil] audio bit depth
+    # @return [Integer, nil] audio sample rate
     attr_accessor :type, :group_id, :language, :assoc_language, :name,
                   :autoselect, :default, :uri, :forced, :instream_id,
-                  :characteristics, :channels
+                  :characteristics, :channels, :stable_rendition_id,
+                  :bit_depth, :sample_rate
 
+    # @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-MEDIA tag.
+    # @param text [String] raw tag line
+    # @return [MediaItem]
     def self.parse(text)
       attributes = parse_attributes(text)
-      options = { type: attributes['TYPE'], group_id: attributes['GROUP-ID'],
+      options = { type: attributes['TYPE'],
+                  group_id: attributes['GROUP-ID'],
                   language: attributes['LANGUAGE'],
                   assoc_language: attributes['ASSOC-LANGUAGE'],
                   name: attributes['NAME'],
@@ -25,10 +49,16 @@ module M3u8
                   uri: attributes['URI'],
                   instream_id: attributes['INSTREAM-ID'],
                   characteristics: attributes['CHARACTERISTICS'],
-                  channels: attributes['CHANNELS'] }
+                  channels: attributes['CHANNELS'],
+                  stable_rendition_id:
+                    attributes['STABLE-RENDITION-ID'],
+                  bit_depth: parse_int(attributes['BIT-DEPTH']),
+                  sample_rate: parse_int(attributes['SAMPLE-RATE']) }
       MediaItem.new(options)
     end
 
+    # Render as an m3u8 EXT-X-MEDIA tag.
+    # @return [String]
     def to_s
       "#EXT-X-MEDIA:#{formatted_attributes.join(',')}"
     end
@@ -36,79 +66,21 @@ module M3u8
     private
 
     def formatted_attributes
-      [type_format,
-       group_id_format,
-       language_format,
-       assoc_language_format,
-       name_format,
-       autoselect_format,
-       default_format,
-       uri_format,
-       forced_format,
-       instream_id_format,
-       characteristics_format,
-       channels_format].compact
-    end
-
-    def type_format
-      "TYPE=#{type}"
-    end
-
-    def group_id_format
-      %(GROUP-ID="#{group_id}")
-    end
-
-    def language_format
-      return if language.nil?
-      %(LANGUAGE="#{language}")
-    end
-
-    def assoc_language_format
-      return if assoc_language.nil?
-      %(ASSOC-LANGUAGE="#{assoc_language}")
-    end
-
-    def name_format
-      %(NAME="#{name}")
-    end
-
-    def autoselect_format
-      return if autoselect.nil?
-      "AUTOSELECT=#{to_yes_no autoselect}"
-    end
-
-    def default_format
-      return if default.nil?
-      "DEFAULT=#{to_yes_no default}"
-    end
-
-    def uri_format
-      return if uri.nil?
-      %(URI="#{uri}")
-    end
-
-    def forced_format
-      return if forced.nil?
-      "FORCED=#{to_yes_no forced}"
-    end
-
-    def instream_id_format
-      return if instream_id.nil?
-      %(INSTREAM-ID="#{instream_id}")
-    end
-
-    def characteristics_format
-      return if characteristics.nil?
-      %(CHARACTERISTICS="#{characteristics}")
-    end
-
-    def channels_format
-      return if channels.nil?
-      %(CHANNELS="#{channels}")
-    end
-
-    def to_yes_no(boolean)
-      boolean == true ? 'YES' : 'NO'
+      ["TYPE=#{type}",
+       %(GROUP-ID="#{group_id}"),
+       quoted_format('LANGUAGE', language),
+       quoted_format('ASSOC-LANGUAGE', assoc_language),
+       %(NAME="#{name}"),
+       boolean_format('AUTOSELECT', autoselect),
+       boolean_format('DEFAULT', default),
+       quoted_format('URI', uri),
+       boolean_format('FORCED', forced),
+       quoted_format('INSTREAM-ID', instream_id),
+       quoted_format('CHARACTERISTICS', characteristics),
+       quoted_format('CHANNELS', channels),
+       quoted_format('STABLE-RENDITION-ID', stable_rendition_id),
+       unquoted_format('BIT-DEPTH', bit_depth),
+       unquoted_format('SAMPLE-RATE', sample_rate)].compact
     end
   end
 end

data/lib/m3u8/part_inf_item.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module M3u8
+  # PartInfItem represents an EXT-X-PART-INF tag which provides
+  # information about partial segments in the playlist.
+  class PartInfItem
+    extend M3u8
+
+    # @return [Float, nil] partial segment target duration
+    attr_accessor :part_target
+
+    # @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-PART-INF tag.
+    # @param text [String] raw tag line
+    # @return [PartInfItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      PartInfItem.new(
+        part_target: attributes['PART-TARGET'].to_f
+      )
+    end
+
+    # Render as an m3u8 EXT-X-PART-INF tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-PART-INF:PART-TARGET=#{part_target}"
+    end
+  end
+end