m3u8 0.8.2 → 1.8.1

data/lib/m3u8/scte35.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Parses SCTE-35 splice_info_section binary payloads from hex strings
+  class Scte35
+    class ParseError < StandardError; end
+
+    attr_reader :table_id, :pts_adjustment, :tier,
+                :splice_command_type, :splice_command, :descriptors
+
+    def initialize(options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse(hex_string)
+      raw = hex_string.sub(/\A0x/i, '')
+      data = [raw].pack('H*')
+      reader = Scte35BitReader.new(data)
+
+      header = parse_header(reader)
+      command = parse_command(reader, header)
+      descriptors = parse_descriptors(reader, header)
+
+      args = header.merge(splice_command: command,
+                          descriptors: descriptors, raw: hex_string)
+      new(**args)
+    rescue NoMethodError, ArgumentError => e
+      raise ParseError, "invalid SCTE-35 data: #{e.message}"
+    end
+
+    def to_s
+      @raw
+    end
+
+    def self.parse_header(reader)
+      table_id = reader.read_bits(8)
+      reader.skip_bits(4) # section_syntax_indicator, private, reserved
+      section_length = reader.read_bits(12)
+      reader.read_bits(8) # protocol_version
+      reader.read_flag    # encrypted_packet
+      reader.read_bits(6) # encryption_algorithm
+      pts_adjustment = reader.read_bits(33)
+      reader.read_bits(8) # cw_index
+      tier = reader.read_bits(12)
+      splice_command_length = reader.read_bits(12)
+      splice_command_type = reader.read_bits(8)
+
+      { table_id: table_id, pts_adjustment: pts_adjustment,
+        tier: tier, splice_command_type: splice_command_type,
+        splice_command_length: splice_command_length,
+        section_length: section_length }
+    end
+
+    def self.parse_command(reader, header)
+      cmd_length = command_data_length(reader, header)
+
+      case header[:splice_command_type]
+      when 0x00 then Scte35SpliceNull.new
+      when 0x05 then Scte35SpliceInsert.parse_from(reader, cmd_length)
+      when 0x06 then Scte35TimeSignal.parse_from(reader, cmd_length)
+      else reader.read_bytes(cmd_length)
+      end
+    end
+
+    def self.parse_splice_time(reader)
+      unless reader.read_flag # time_specified
+        reader.skip_bits(7) # reserved
+        return nil
+      end
+
+      reader.skip_bits(6) # reserved
+      reader.read_bits(33)
+    end
+
+    def self.parse_descriptors(reader, header)
+      # For unknown commands with 0xFFF, command consumed all
+      # remaining bytes (per spec), so no descriptors to parse
+      return [] if unknown_command_with_unspecified_length?(header)
+
+      desc_loop_length = reader.read_bits(16)
+      parse_descriptor_loop(reader, desc_loop_length)
+    end
+
+    def self.unknown_command_with_unspecified_length?(header)
+      header[:splice_command_length] == 0xFFF &&
+        ![0x00, 0x05, 0x06].include?(header[:splice_command_type])
+    end
+
+    def self.parse_descriptor_loop(reader, remaining)
+      descriptors = []
+      while remaining.positive?
+        tag = reader.read_bits(8)
+        length = reader.read_bits(8)
+        remaining -= 2 + length
+        descriptors << parse_single_descriptor(reader, tag, length)
+      end
+      descriptors
+    end
+
+    def self.parse_single_descriptor(reader, tag, length)
+      identifier = reader.read_bits(32)
+      if tag == Scte35SegmentationDescriptor::DESCRIPTOR_TAG &&
+         identifier == Scte35SegmentationDescriptor::CUEI_IDENTIFIER
+        Scte35SegmentationDescriptor.parse_from(reader, length)
+      else
+        reader.read_bytes(length - 4)
+      end
+    end
+
+    def self.command_data_length(reader, header)
+      length = header[:splice_command_length]
+      return length unless length == 0xFFF
+
+      if unknown_command_with_unspecified_length?(header)
+        # Unknown command: consume everything up to CRC
+        reader.bytes_remaining - 4
+      else
+        # Known command types parse their own fields; length unused
+        0
+      end
+    end
+
+    private_class_method :parse_header, :parse_command,
+                         :parse_descriptors, :command_data_length,
+                         :parse_descriptor_loop, :parse_single_descriptor,
+                         :unknown_command_with_unspecified_length?
+  end
+end

data/lib/m3u8/scte35_bit_reader.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Reads sub-byte bit fields from binary data for SCTE-35 parsing
+  class Scte35BitReader
+    def initialize(data)
+      @data = data.b
+      @byte_pos = 0
+      @bit_pos = 0
+    end
+
+    def read_bits(count)
+      value = 0
+      count.times do
+        value = (value << 1) | current_bit
+        advance_bit
+      end
+      value
+    end
+
+    def read_flag
+      read_bits(1) == 1
+    end
+
+    def read_bytes(count)
+      @data[@byte_pos, count].tap { @byte_pos += count }
+    end
+
+    def skip_bits(count)
+      count.times { advance_bit }
+    end
+
+    def bytes_remaining
+      @data.length - @byte_pos - (@bit_pos.positive? ? 1 : 0)
+    end
+
+    private
+
+    def current_bit
+      (@data.getbyte(@byte_pos) >> (7 - @bit_pos)) & 1
+    end
+
+    def advance_bit
+      @bit_pos += 1
+      return unless @bit_pos >= 8
+
+      @bit_pos = 0
+      @byte_pos += 1
+    end
+  end
+end

data/lib/m3u8/scte35_segmentation_descriptor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Represents a segmentation_descriptor (tag 0x02) in SCTE-35
+  class Scte35SegmentationDescriptor
+    CUEI_IDENTIFIER = 0x43554549
+    DESCRIPTOR_TAG = 0x02
+
+    attr_reader :segmentation_event_id, :segmentation_event_cancel_indicator,
+                :segmentation_type_id, :segmentation_duration,
+                :segmentation_upid_type, :segmentation_upid,
+                :segment_num, :segments_expected
+
+    def initialize(options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse_from(reader, _length)
+      attrs = { segmentation_event_id: reader.read_bits(32) }
+      attrs[:segmentation_event_cancel_indicator] = reader.read_flag
+      reader.skip_bits(7) # reserved
+      return new(**attrs) if attrs[:segmentation_event_cancel_indicator]
+
+      parse_segmentation_detail(reader, attrs)
+    end
+
+    def self.parse_segmentation_detail(reader, attrs)
+      reader.read_flag # program_segmentation_flag
+      duration_flag = reader.read_flag
+      reader.skip_bits(6) # delivery_not_restricted + reserved/flags
+
+      attrs[:segmentation_duration] = reader.read_bits(40) if duration_flag
+      parse_upid(reader, attrs)
+      attrs[:segmentation_type_id] = reader.read_bits(8)
+      attrs[:segment_num] = reader.read_bits(8)
+      attrs[:segments_expected] = reader.read_bits(8)
+      new(**attrs)
+    end
+
+    def self.parse_upid(reader, attrs)
+      attrs[:segmentation_upid_type] = reader.read_bits(8)
+      upid_length = reader.read_bits(8)
+      return if upid_length.zero?
+
+      attrs[:segmentation_upid] =
+        reader.read_bytes(upid_length)
+              .force_encoding('UTF-8')
+    end
+
+    private_class_method :parse_segmentation_detail, :parse_upid
+  end
+end

data/lib/m3u8/scte35_splice_insert.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Represents a splice_insert SCTE-35 command (type 0x05)
+  class Scte35SpliceInsert
+    attr_reader :splice_event_id, :splice_event_cancel_indicator,
+                :out_of_network_indicator, :pts_time,
+                :break_duration, :break_auto_return,
+                :unique_program_id, :avail_num, :avails_expected
+
+    def initialize(options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse_from(reader, _length)
+      attrs = { splice_event_id: reader.read_bits(32) }
+      attrs[:splice_event_cancel_indicator] = reader.read_flag
+      reader.skip_bits(7) # reserved
+      return new(**attrs) if attrs[:splice_event_cancel_indicator]
+
+      parse_splice_detail(reader, attrs)
+    end
+
+    def self.parse_splice_detail(reader, attrs)
+      attrs[:out_of_network_indicator] = reader.read_flag
+      program_splice = reader.read_flag
+      duration_flag = reader.read_flag
+      immediate = reader.read_flag
+      reader.skip_bits(4) # reserved
+
+      if program_splice
+        attrs[:pts_time] = Scte35.parse_splice_time(reader) unless immediate
+      else
+        parse_components(reader, immediate)
+      end
+      parse_break_duration(reader, attrs) if duration_flag
+      attrs[:unique_program_id] = reader.read_bits(16)
+      attrs[:avail_num] = reader.read_bits(8)
+      attrs[:avails_expected] = reader.read_bits(8)
+      new(**attrs)
+    end
+
+    def self.parse_components(reader, immediate)
+      component_count = reader.read_bits(8)
+      component_count.times do
+        reader.read_bits(8) # component_tag
+        Scte35.parse_splice_time(reader) unless immediate
+      end
+    end
+
+    def self.parse_break_duration(reader, attrs)
+      attrs[:break_auto_return] = reader.read_flag
+      reader.skip_bits(6) # reserved
+      attrs[:break_duration] = reader.read_bits(33)
+    end
+
+    private_class_method :parse_splice_detail, :parse_break_duration,
+                         :parse_components
+  end
+end

data/lib/m3u8/scte35_splice_null.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Represents a splice_null SCTE-35 command (type 0x00).
+  # Contains no data fields.
+  class Scte35SpliceNull # rubocop:disable Lint/EmptyClass
+  end
+end

data/lib/m3u8/scte35_time_signal.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Represents a time_signal SCTE-35 command (type 0x06)
+  class Scte35TimeSignal
+    attr_reader :pts_time
+
+    def initialize(options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse_from(reader, _length)
+      pts_time = Scte35.parse_splice_time(reader)
+      new(pts_time: pts_time)
+    end
+  end
+end

data/lib/m3u8/segment_item.rb

@@ -1,24 +1,58 @@
 # frozen_string_literal: true
+
 module M3u8
   # SegmentItem represents EXTINF attributes with the URI that follows,
   # optionally allowing an EXT-X-BYTERANGE tag to be set.
   class SegmentItem
     include M3u8
+    include AttributeFormatter
+
+    # @return [Float, nil] segment duration in seconds
+    # @return [String, nil] segment URI
+    # @return [String, nil] human-readable comment after duration
+    # @return [TimeItem, Time, nil] program date-time
+    # @return [ByteRange, nil] byte range
     attr_accessor :duration, :segment, :comment, :program_date_time, :byterange
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
-      intialize_with_byterange(params)
+      initialize_with_byterange(params)
+    end
+
+    # Parse an EXTINF tag line.
+    # @param text [String] raw tag line
+    # @return [SegmentItem]
+    def self.parse(text)
+      values = text.gsub('#EXTINF:', '')
+                   .tr("\n", ',').split(',')
+      options = { duration: values[0].to_f }
+      options[:comment] = values[1] unless values[1].nil?
+      SegmentItem.new(options)
     end
 
+    # Render as an m3u8 EXTINF tag with segment URI.
+    # @return [String]
     def to_s
-      date = "#{program_date_time}\n" unless program_date_time.nil?
-      "#EXTINF:#{duration},#{comment}#{byterange_format}\n#{date}#{segment}"
+      "#EXTINF:#{decimal_format(duration)},#{comment}#{byterange_format}" \
+        "\n#{date_format}#{segment}"
+    end
+
+    def date_format
+      return if program_date_time.nil?
+
+      pdt = if program_date_time.is_a?(TimeItem)
+              program_date_time
+            else
+              TimeItem.new(time: program_date_time)
+            end
+      "#{pdt}\n"
     end
 
     private
 
     def byterange_format
       return if byterange.nil?
+
       "\n#EXT-X-BYTERANGE:#{byterange}"
     end
   end

data/lib/m3u8/server_control_item.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module M3u8
+  # ServerControlItem represents an EXT-X-SERVER-CONTROL tag which
+  # provides directives for Low-Latency HLS delivery.
+  class ServerControlItem
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [Float, nil] skip threshold in seconds
+    # @return [Boolean, nil] whether dateranges can be skipped
+    # @return [Float, nil] hold-back duration in seconds
+    # @return [Float, nil] part hold-back duration in seconds
+    # @return [Boolean, nil] whether blocking reload is supported
+    attr_accessor :can_skip_until, :can_skip_dateranges, :hold_back,
+                  :part_hold_back, :can_block_reload
+
+    # @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-SERVER-CONTROL tag.
+    # @param text [String] raw tag line
+    # @return [ServerControlItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      ServerControlItem.new(
+        can_skip_until: parse_float(attributes['CAN-SKIP-UNTIL']),
+        can_skip_dateranges:
+          parse_yes_no(attributes['CAN-SKIP-DATERANGES']),
+        hold_back: parse_float(attributes['HOLD-BACK']),
+        part_hold_back: parse_float(attributes['PART-HOLD-BACK']),
+        can_block_reload:
+          parse_yes_no(attributes['CAN-BLOCK-RELOAD'])
+      )
+    end
+
+    # Render as an m3u8 EXT-X-SERVER-CONTROL tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-SERVER-CONTROL:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [unquoted_format('CAN-SKIP-UNTIL', can_skip_until),
+       can_skip_dateranges_format,
+       unquoted_format('HOLD-BACK', hold_back),
+       unquoted_format('PART-HOLD-BACK', part_hold_back),
+       can_block_reload_format].compact.join(',')
+    end
+
+    def can_skip_dateranges_format
+      return unless can_skip_dateranges
+
+      'CAN-SKIP-DATERANGES=YES'
+    end
+
+    def can_block_reload_format
+      return unless can_block_reload
+
+      'CAN-BLOCK-RELOAD=YES'
+    end
+  end
+end

data/lib/m3u8/session_data_item.rb

@@ -1,16 +1,27 @@
 # frozen_string_literal: true
+
 module M3u8
   # SessionDataItem represents a set of EXT-X-SESSION-DATA attributes
   class SessionDataItem
     extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] DATA-ID value
+    # @return [String, nil] VALUE attribute
+    # @return [String, nil] URI attribute
+    # @return [String, nil] LANGUAGE attribute
     attr_accessor :data_id, :value, :uri, :language
 
+    # @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-SESSION-DATA tag.
+    # @param text [String] raw tag line
+    # @return [SessionDataItem]
     def self.parse(text)
       attributes = parse_attributes text
       options = { data_id: attributes['DATA-ID'], value: attributes['VALUE'],
@@ -18,36 +29,14 @@ module M3u8
       M3u8::SessionDataItem.new options
     end
 
+    # Render as an m3u8 EXT-X-SESSION-DATA tag.
+    # @return [String]
     def to_s
-      attributes = [data_id_format,
-                    value_format,
-                    uri_format,
-                    language_format].compact.join(',')
+      attributes = [quoted_format('DATA-ID', data_id),
+                    quoted_format('VALUE', value),
+                    quoted_format('URI', uri),
+                    quoted_format('LANGUAGE', language)].compact.join(',')
       "#EXT-X-SESSION-DATA:#{attributes}"
     end
-
-    private
-
-    def data_id_format
-      %(DATA-ID="#{data_id}")
-    end
-
-    def value_format
-      return if value.nil?
-
-      %(VALUE="#{value}")
-    end
-
-    def uri_format
-      return if uri.nil?
-
-      %(URI="#{uri}")
-    end
-
-    def language_format
-      return if language.nil?
-
-      %(LANGUAGE="#{language}")
-    end
   end
 end

data/lib/m3u8/session_key_item.rb

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

data/lib/m3u8/skip_item.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module M3u8
+  # SkipItem represents an EXT-X-SKIP tag used in Playlist Delta
+  # Updates for Low-Latency HLS.
+  class SkipItem
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [Integer, nil] number of skipped segments
+    # @return [String, nil] recently removed dateranges
+    attr_accessor :skipped_segments, :recently_removed_dateranges
+
+    # @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-SKIP tag.
+    # @param text [String] raw tag line
+    # @return [SkipItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      SkipItem.new(
+        skipped_segments:
+          attributes['SKIPPED-SEGMENTS'].to_i,
+        recently_removed_dateranges:
+          attributes['RECENTLY-REMOVED-DATERANGES']
+      )
+    end
+
+    # Render as an m3u8 EXT-X-SKIP tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-SKIP:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [unquoted_format('SKIPPED-SEGMENTS', skipped_segments),
+       quoted_format('RECENTLY-REMOVED-DATERANGES',
+                     recently_removed_dateranges)].compact.join(',')
+    end
+  end
+end

data/lib/m3u8/time_item.rb

@@ -1,22 +1,31 @@
 # frozen_string_literal: true
+
 module M3u8
   # TimeItem represents EXT-X-PROGRAM-DATE-TIME
   class TimeItem
     extend M3u8
+
+    # @return [Time, String, nil] program date-time value
     attr_accessor :time
 
+    # @param params [Hash] :time value
     def initialize(params = {})
       params.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
+    # Parse an EXT-X-PROGRAM-DATE-TIME tag.
+    # @param text [String] raw tag line
+    # @return [TimeItem]
     def self.parse(text)
       time = text.gsub('#EXT-X-PROGRAM-DATE-TIME:', '')
       options = { time: Time.parse(time) }
       TimeItem.new(options)
     end
 
+    # Render as an m3u8 EXT-X-PROGRAM-DATE-TIME tag.
+    # @return [String]
     def to_s
       %(#EXT-X-PROGRAM-DATE-TIME:#{time_format})
     end
@@ -25,6 +34,7 @@ module M3u8
 
     def time_format
       return time if time.is_a?(String)
+
       time.iso8601
     end
   end

data/lib/m3u8/version.rb

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