m3u8 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a4ef59c0103a519f686f38d7eb24e99286f698bfbee43d7e8ad48827dfd00e5
-  data.tar.gz: b776355294c670836ecc6598ad169d71eedc40e017a686c28042828bf724e805
+  metadata.gz: 1fb7826061b077f6e56712067f673393591d628e4e35a895af1910ff7fae859d
+  data.tar.gz: 8e0298d7fb9806e4fa2d3bc66b522a6f7bf7d0bbad1a57fcefeafeac7255a1f4
 SHA512:
-  metadata.gz: e2f761adbf62244f9f175fc28f7f00f0d77d78acb5af19906f70fff656777e97bbbe787454ce47accd0e72f4e702baeda20dde763a72ac87174cb9ccd24dca15
-  data.tar.gz: bf19a4de08cc5216b939c77eedc147e93e134bc284a90464f138f3a31f0d679d88e5bd6e306db63dbf0e26ce7a40fba618bb67d41c15443899a2824b6fd4776c
+  metadata.gz: 20c066c9f250d0d7948c3211f958bf553d8385d07f8715274b2738d3c497cf8cf450790489f80ccca88a1e09a67fc43411f055efcc16bf6f9fa07efed43ed407
+  data.tar.gz: 515ba07430d27872130625dc1d5eac52ebd68a76c20306ff4443b9829f74b3d3a7ceee8d63f118a7e832c6f48a7742e6157eb5bff05e26c198f262566f443c78

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+**1.6.0**
+
+* Added SCTE-35 parsing with `M3u8::Scte35` for `splice_info_section`
+  payloads, including `splice_null` (0x00), `splice_insert` (0x05),
+  `time_signal` (0x06), and descriptor loop parsing.
+* Added `DateRangeItem` SCTE-35 convenience methods:
+  `scte35_cmd_info`, `scte35_out_info`, and `scte35_in_info`.
+* Added parsing support for SCTE-35 segmentation descriptors
+  (`segmentation_descriptor`, tag 0x02 with `CUEI` identifier).
+* Added `M3u8::Scte35::ParseError` for malformed SCTE-35 payloads.
+* Documented SCTE-35 usage and parsed fields in README.
+
+***
+
+**1.5.0**
+
+* Added `Playlist#freeze` for deep-freezing playlists, items, nested objects, and playlist-level objects. `Playlist.build` and `Playlist.read` now return frozen playlists. `Playlist.new` remains mutable until `freeze` is called explicitly.
+
+***
+
 **1.4.0**
 
 * Added `Playlist#errors` method returning an array of validation error messages. `Playlist#valid?` now delegates to `errors.empty?`. Validates mixed item types, target duration, segment items, playlist items, media items, encryption keys, session keys, session data, and LL-HLS part items.

data/README.md

@@ -344,6 +344,83 @@ options = { width: 1920, height: 1080, codecs: 'avc1.66.30,mp4a.40.2',
 item = M3u8::PlaylistItem.new(options)
 ```
 
+## Frozen playlists
+
+Playlists returned by `Playlist.build` and `Playlist.read` are frozen (deeply immutable). Items, nested objects, and the items array are all frozen, preventing accidental mutation after construction:
+
+```ruby
+playlist = M3u8::Playlist.read(File.open('master.m3u8'))
+playlist.frozen?          # => true
+playlist.items.frozen?    # => true
+playlist.items.first.frozen? # => true
+```
+
+Playlists created with `Playlist.new` remain mutable. Call `freeze` explicitly when ready:
+
+```ruby
+playlist = M3u8::Playlist.new
+playlist.items << M3u8::SegmentItem.new(duration: 10.0, segment: 'test.ts')
+playlist.freeze
+```
+
+Frozen playlists still support `to_s` and `write` for output.
+
+## SCTE-35 parsing
+
+`DateRangeItem` stores SCTE-35 values (`scte35_cmd`, `scte35_out`, `scte35_in`) as raw hex strings. Convenience methods parse them into structured objects:
+
+```ruby
+playlist = M3u8::Playlist.read(file)
+date_range = playlist.date_ranges.first
+
+info = date_range.scte35_out_info
+info.table_id             # => 252 (0xFC)
+info.pts_adjustment        # => 0
+info.tier                  # => 4095
+info.splice_command_type   # => 5
+
+cmd = info.splice_command  # => Scte35SpliceInsert
+cmd.splice_event_id        # => 1
+cmd.out_of_network_indicator # => true
+cmd.pts_time               # => 90000
+cmd.break_duration         # => 2700000
+cmd.break_auto_return      # => true
+```
+
+Parse any SCTE-35 hex string directly:
+
+```ruby
+info = M3u8::Scte35.parse('0xFC301100...')
+info.to_s  # => original hex string
+```
+
+### Command types
+
+| Type | Class | Key attributes |
+|------|-------|----------------|
+| 0x00 | `Scte35SpliceNull` | *(none)* |
+| 0x05 | `Scte35SpliceInsert` | `splice_event_id`, `out_of_network_indicator`, `pts_time`, `break_duration`, `break_auto_return`, `unique_program_id`, `avail_num`, `avails_expected` |
+| 0x06 | `Scte35TimeSignal` | `pts_time` |
+
+Unknown command types store raw bytes in `splice_command`.
+
+### Descriptors
+
+Segmentation descriptors (tag 0x02, identifier `CUEI`) are parsed as `Scte35SegmentationDescriptor`:
+
+```ruby
+desc = info.descriptors.first
+desc.segmentation_event_id    # => 1
+desc.segmentation_type_id     # => 0x30
+desc.segmentation_duration    # => 2700000
+desc.segmentation_upid_type   # => 9
+desc.segmentation_upid        # => "SIGNAL123"
+desc.segment_num              # => 0
+desc.segments_expected         # => 0
+```
+
+Unknown descriptor tags store raw bytes.
+
 ## Validation
 
 Check whether a playlist is valid and inspect specific errors:

data/lib/m3u8/date_range_item.rb

@@ -34,6 +34,18 @@ module M3u8
       "#EXT-X-DATERANGE:#{formatted_attributes}"
     end
 
+    def scte35_cmd_info
+      Scte35.parse(scte35_cmd) unless scte35_cmd.nil?
+    end
+
+    def scte35_out_info
+      Scte35.parse(scte35_out) unless scte35_out.nil?
+    end
+
+    def scte35_in_info
+      Scte35.parse(scte35_in) unless scte35_in.nil?
+    end
+
     private
 
     def formatted_attributes

data/lib/m3u8/playlist.rb

@@ -22,7 +22,7 @@ module M3u8
       else
         builder.instance_eval(&block)
       end
-      playlist
+      playlist.freeze
     end
 
     def self.codecs(options = {})
@@ -53,6 +53,14 @@ module M3u8
       playlist_size.positive?
     end
 
+    def freeze
+      items.each { |item| freeze_item(item) }
+      items.freeze
+      part_inf&.freeze
+      server_control&.freeze
+      super
+    end
+
     def to_s
       output = StringIO.open
       write(output)
@@ -119,6 +127,13 @@ module M3u8
 
     private
 
+    def freeze_item(item)
+      item.byterange&.freeze if item.respond_to?(:byterange)
+      item.program_date_time&.freeze if item.respond_to?(:program_date_time)
+      item.client_attributes&.freeze if item.respond_to?(:client_attributes)
+      item.freeze
+    end
+
     def assign_options(options)
       options = defaults.merge(options)
 

data/lib/m3u8/reader.rb

@@ -25,7 +25,7 @@ module M3u8
         parse_line(line)
       end
       playlist.live = !@has_endlist unless master
-      playlist
+      playlist.freeze
     end
 
     private

data/lib/m3u8/scte35.rb

@@ -0,0 +1,129 @@
+# 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)
+      return header[:splice_command_length] unless header[:splice_command_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,52 @@
+# 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/version.rb

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

data/spec/lib/m3u8/builder_spec.rb

@@ -191,6 +191,20 @@ describe M3u8::Builder do
       expect(playlist.target).to eq(12)
     end
 
+    it 'returns a frozen playlist' do
+      playlist = M3u8::Playlist.build do
+        segment duration: 10.0, segment: 'test.ts'
+      end
+      expect(playlist).to be_frozen
+    end
+
+    it 'returns a frozen playlist with yielded form' do
+      playlist = M3u8::Playlist.build do |b|
+        b.segment duration: 10.0, segment: 'test.ts'
+      end
+      expect(playlist).to be_frozen
+    end
+
     it 'supports yielded builder form' do
       files = %w[seg1.ts seg2.ts]
       playlist = M3u8::Playlist.build(version: 4) do |b|

data/spec/lib/m3u8/date_range_item_spec.rb

@@ -122,4 +122,51 @@ describe M3u8::DateRangeItem do
       expect(item.to_s).to eq(expected)
     end
   end
+
+  describe '#scte35_out_info' do
+    it 'should return parsed Scte35 when scte35_out is set' do
+      hex = '0xFC301100000000000000FFF000000000DEADBEEF'
+      item = described_class.new(scte35_out: hex)
+      result = item.scte35_out_info
+
+      expect(result).to be_a(M3u8::Scte35)
+      expect(result.table_id).to eq(0xFC)
+      expect(result.to_s).to eq(hex)
+    end
+
+    it 'should return nil when scte35_out is nil' do
+      item = described_class.new
+      expect(item.scte35_out_info).to be_nil
+    end
+  end
+
+  describe '#scte35_in_info' do
+    it 'should return parsed Scte35 when scte35_in is set' do
+      hex = '0xFC301100000000000000FFF000000000DEADBEEF'
+      item = described_class.new(scte35_in: hex)
+      result = item.scte35_in_info
+
+      expect(result).to be_a(M3u8::Scte35)
+    end
+
+    it 'should return nil when scte35_in is nil' do
+      item = described_class.new
+      expect(item.scte35_in_info).to be_nil
+    end
+  end
+
+  describe '#scte35_cmd_info' do
+    it 'should return parsed Scte35 when scte35_cmd is set' do
+      hex = '0xFC301100000000000000FFF000000000DEADBEEF'
+      item = described_class.new(scte35_cmd: hex)
+      result = item.scte35_cmd_info
+
+      expect(result).to be_a(M3u8::Scte35)
+    end
+
+    it 'should return nil when scte35_cmd is nil' do
+      item = described_class.new
+      expect(item.scte35_cmd_info).to be_nil
+    end
+  end
 end