m3u8 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df37c1a4cc89e0bd918c6137c5bc86682d61638b407697240e76f40acb8983e7
-  data.tar.gz: e19fd10c1b3f732057285247f08bb235573fa6434085295b53a76be22f1a53aa
+  metadata.gz: 1fb7826061b077f6e56712067f673393591d628e4e35a895af1910ff7fae859d
+  data.tar.gz: 8e0298d7fb9806e4fa2d3bc66b522a6f7bf7d0bbad1a57fcefeafeac7255a1f4
 SHA512:
-  metadata.gz: c4ff8a727525925718fcb0ff7fed0b8bb758556d8e262c97ebacaca4fe96550b4494817ce5d8f4a0525d961a274a1905b16af6b5a85b8ac57235254f54392f8a
-  data.tar.gz: 19ae07aa8cd202846254983b823973c4b7d0a9d4bde50e5cc8be7e1e4d91182205bec84731f628298f2659085434716120135a074656e1c9c2aa2c1988415b4f
+  metadata.gz: 20c066c9f250d0d7948c3211f958bf553d8385d07f8715274b2738d3c497cf8cf450790489f80ccca88a1e09a67fc43411f055efcc16bf6f9fa07efed43ed407
+  data.tar.gz: 515ba07430d27872130625dc1d5eac52ebd68a76c20306ff4443b9829f74b3d3a7ceee8d63f118a7e832c6f48a7742e6157eb5bff05e26c198f262566f443c78

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+**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.

data/README.md

@@ -365,6 +365,62 @@ 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/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.5.0'
+  VERSION = '1.6.0'
 end

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

data/spec/lib/m3u8/scte35_bit_reader_spec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35BitReader do
+  describe '#read_bits' do
+    it 'should read 8-bit values' do
+      reader = described_class.new("\xAB")
+      expect(reader.read_bits(8)).to eq(0xAB)
+    end
+
+    it 'should read 1-bit values' do
+      reader = described_class.new("\xA0")
+      expect(reader.read_bits(1)).to eq(1)
+      expect(reader.read_bits(1)).to eq(0)
+      expect(reader.read_bits(1)).to eq(1)
+      expect(reader.read_bits(1)).to eq(0)
+    end
+
+    it 'should read 12-bit values' do
+      reader = described_class.new("\xAB\xCD")
+      expect(reader.read_bits(12)).to eq(0xABC)
+    end
+
+    it 'should read 16-bit values' do
+      reader = described_class.new("\xAB\xCD")
+      expect(reader.read_bits(16)).to eq(0xABCD)
+    end
+
+    it 'should read 32-bit values' do
+      reader = described_class.new("\x12\x34\x56\x78")
+      expect(reader.read_bits(32)).to eq(0x12345678)
+    end
+
+    it 'should read 33-bit values' do
+      # 1 followed by 32 zeros = 2^32
+      reader = described_class.new("\x80\x00\x00\x00\x00")
+      expect(reader.read_bits(33)).to eq(2**32)
+    end
+
+    it 'should read 33-bit values after partial byte reads' do
+      # Simulates: time_specified(1), reserved(6), pts_time(33)
+      # 1_111111_0 00000000 00000000 00000000 00000001
+      reader = described_class.new("\xFE\x00\x00\x00\x01")
+      expect(reader.read_bits(1)).to eq(1)
+      expect(reader.read_bits(6)).to eq(0x3F)
+      expect(reader.read_bits(33)).to eq(1)
+    end
+
+    it 'should read values across byte boundaries' do
+      reader = described_class.new("\xF0\x0F")
+      expect(reader.read_bits(4)).to eq(0xF)
+      expect(reader.read_bits(8)).to eq(0x00)
+      expect(reader.read_bits(4)).to eq(0xF)
+    end
+  end
+
+  describe '#read_flag' do
+    it 'should return true for 1' do
+      reader = described_class.new("\x80")
+      expect(reader.read_flag).to be true
+    end
+
+    it 'should return false for 0' do
+      reader = described_class.new("\x00")
+      expect(reader.read_flag).to be false
+    end
+  end
+
+  describe '#read_bytes' do
+    it 'should read raw bytes' do
+      reader = described_class.new("\xDE\xAD\xBE\xEF")
+      expect(reader.read_bytes(2)).to eq("\xDE\xAD".b)
+      expect(reader.read_bytes(2)).to eq("\xBE\xEF".b)
+    end
+  end
+
+  describe '#skip_bits' do
+    it 'should advance the position' do
+      reader = described_class.new("\xFF\x42")
+      reader.skip_bits(8)
+      expect(reader.read_bits(8)).to eq(0x42)
+    end
+
+    it 'should skip sub-byte amounts' do
+      reader = described_class.new("\xF5")
+      reader.skip_bits(4)
+      expect(reader.read_bits(4)).to eq(0x5)
+    end
+  end
+
+  describe '#bytes_remaining' do
+    it 'should return remaining bytes' do
+      reader = described_class.new("\x01\x02\x03\x04")
+      expect(reader.bytes_remaining).to eq(4)
+      reader.read_bits(8)
+      expect(reader.bytes_remaining).to eq(3)
+    end
+
+    it 'should account for partial byte reads' do
+      reader = described_class.new("\x01\x02")
+      reader.read_bits(4)
+      expect(reader.bytes_remaining).to eq(1)
+    end
+  end
+end

data/spec/lib/m3u8/scte35_segmentation_descriptor_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35SegmentationDescriptor do
+  # Builds a full SCTE-35 hex string with a time_signal command and descriptors
+  def build_hex_with_descriptors(descriptor_bytes)
+    # time_signal with pts=90000: FE 00 01 5F 90 (5 bytes, type 0x06)
+    cmd_bytes = 'FE00015F90'
+    cmd_len = 5
+    desc_loop_length = descriptor_bytes.length
+    desc_hex = descriptor_bytes.map { |b| format('%02X', b) }.join
+    desc_loop_hex = format('%04X', desc_loop_length)
+
+    # section_length = 11(header) + cmd_len + 2(desc_loop_len) + desc_loop + 4(CRC)
+    section_length = 11 + cmd_len + 2 + desc_loop_length + 4
+    header = splice_info_header(section_length, cmd_len)
+
+    "0x#{header}06#{cmd_bytes}#{desc_loop_hex}#{desc_hex}DEADBEEF"
+  end
+
+  def splice_info_header(section_length, cmd_length)
+    section_header = format('%04X', 0x3000 | section_length)
+    tier_cmd = format('%06X', (0xFFF << 12) | cmd_length)
+    "FC#{section_header}00000000000000#{tier_cmd}"
+  end
+
+  # Builds segmentation_descriptor bytes (tag=0x02, identifier=CUEI)
+  def segmentation_descriptor(fields)
+    # descriptor_tag(8): 0x02
+    # descriptor_length(8): computed
+    # identifier(32): CUEI = 0x43554549
+    # segmentation_event_id(32)
+    # segmentation_event_cancel_indicator(1) + reserved(7)
+    # if not cancelled:
+    #   program_segmentation_flag(1)=1 + segmentation_duration_flag(1)
+    #   + delivery_not_restricted_flag(1)=1 + reserved(5)=11111
+    #   if duration_flag: segmentation_duration(40)
+    #   segmentation_upid_type(8) + segmentation_upid_length(8)
+    #   + upid data
+    #   segmentation_type_id(8) + segment_num(8) + segments_expected(8)
+    bytes = [0x43, 0x55, 0x45, 0x49] # CUEI identifier
+    bytes += to_bytes(fields[:event_id], 4)
+
+    if fields[:cancel]
+      bytes += [0xFF] # cancel=1, reserved=1111111
+    else
+      bytes << 0x7F # cancel=0, reserved=1111111
+      duration_flag = fields[:duration] ? 1 : 0
+      # program_seg=1, duration_flag, delivery_not_restricted=1, reserved=11111
+      flags = (1 << 7) | (duration_flag << 6) | (1 << 5) | 0x1F
+      bytes << flags
+
+      if fields[:duration]
+        bytes += to_bytes(fields[:duration], 5) # 40-bit duration
+      end
+
+      upid = fields[:upid] || ''
+      bytes << (fields[:upid_type] || 0)
+      bytes << upid.length
+      bytes += upid.bytes if upid.length.positive?
+
+      bytes << fields[:type_id]
+      bytes << (fields[:segment_num] || 0)
+      bytes << (fields[:segments_expected] || 0)
+    end
+
+    # Prepend tag and length
+    [0x02, bytes.length] + bytes
+  end
+
+  def to_bytes(value, count)
+    count.times.map { |i| (value >> (8 * (count - 1 - i))) & 0xFF }
+  end
+
+  describe 'parsing via Scte35.parse' do
+    it 'should parse a segmentation descriptor with ad-start type' do
+      desc = segmentation_descriptor(
+        event_id: 0x00000001, type_id: 0x30,
+        segment_num: 0, segments_expected: 0
+      )
+      hex = build_hex_with_descriptors(desc)
+      result = M3u8::Scte35.parse(hex)
+
+      expect(result.descriptors.length).to eq(1)
+      seg = result.descriptors.first
+      expect(seg).to be_a(described_class)
+      expect(seg.segmentation_event_id).to eq(1)
+      expect(seg.segmentation_type_id).to eq(0x30)
+      expect(seg.segment_num).to eq(0)
+      expect(seg.segments_expected).to eq(0)
+    end
+
+    it 'should parse a segmentation descriptor with duration' do
+      desc = segmentation_descriptor(
+        event_id: 0x00000002, type_id: 0x34,
+        duration: 2_700_000, segment_num: 1, segments_expected: 2
+      )
+      hex = build_hex_with_descriptors(desc)
+      result = M3u8::Scte35.parse(hex)
+      seg = result.descriptors.first
+
+      expect(seg.segmentation_duration).to eq(2_700_000)
+      expect(seg.segmentation_type_id).to eq(0x34)
+      expect(seg.segment_num).to eq(1)
+      expect(seg.segments_expected).to eq(2)
+    end
+
+    it 'should parse a segmentation descriptor with UPID' do
+      desc = segmentation_descriptor(
+        event_id: 0x00000003, type_id: 0x30,
+        upid_type: 0x09, upid: 'SIGNAL123'
+      )
+      hex = build_hex_with_descriptors(desc)
+      result = M3u8::Scte35.parse(hex)
+      seg = result.descriptors.first
+
+      expect(seg.segmentation_upid_type).to eq(0x09)
+      expect(seg.segmentation_upid).to eq('SIGNAL123')
+    end
+
+    it 'should parse a cancelled segmentation descriptor' do
+      desc = segmentation_descriptor(event_id: 0x00000004, cancel: true)
+      hex = build_hex_with_descriptors(desc)
+      result = M3u8::Scte35.parse(hex)
+      seg = result.descriptors.first
+
+      expect(seg.segmentation_event_id).to eq(4)
+      expect(seg.segmentation_event_cancel_indicator).to be true
+      expect(seg.segmentation_type_id).to be_nil
+    end
+
+    it 'should store raw bytes for unknown descriptor tags' do
+      # Unknown tag 0xFF with 4 bytes of identifier + 2 bytes data
+      unknown_desc = [0xFF, 0x06, 0x43, 0x55, 0x45, 0x49, 0xAA, 0xBB]
+      hex = build_hex_with_descriptors(unknown_desc)
+      result = M3u8::Scte35.parse(hex)
+
+      expect(result.descriptors.length).to eq(1)
+      expect(result.descriptors.first).to be_a(String)
+    end
+  end
+end

data/spec/lib/m3u8/scte35_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35 do
+  describe '.parse' do
+    it 'should parse a splice_null command' do
+      # splice_info_section with splice_null (type 0x00):
+      #   table_id=0xFC, section_length=17, protocol=0, pts_adjustment=0
+      #   cw_index=0, tier=0xFFF, command_length=0, command_type=0x00
+      #   descriptor_loop_length=0, crc=0xDEADBEEF
+      hex = '0xFC301100000000000000FFF000000000DEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.table_id).to eq(0xFC)
+      expect(result.pts_adjustment).to eq(0)
+      expect(result.tier).to eq(0xFFF)
+      expect(result.splice_command_type).to eq(0x00)
+      expect(result.splice_command).to be_a(M3u8::Scte35SpliceNull)
+      expect(result.descriptors).to eq([])
+    end
+
+    it 'should round-trip hex string via to_s' do
+      hex = '0xFC301100000000000000FFF000000000DEADBEEF'
+      result = described_class.parse(hex)
+      expect(result.to_s).to eq(hex)
+    end
+
+    it 'should store raw bytes for unknown command types' do
+      # command_type=0xFF with 2 bytes of command data (0xAABB)
+      # section_length=19 to accommodate extra 2 bytes
+      hex = '0xFC301300000000000000FFF002FFAABB0000DEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.splice_command_type).to eq(0xFF)
+      expect(result.splice_command).to eq("\xAA\xBB".b)
+    end
+
+    it 'should parse nonzero pts_adjustment' do
+      # pts_adjustment=300 (0x12C): encrypted=0, algo=0, pts=300
+      # 0_000000_0_00000000_00000000_00000001_00101100
+      # bytes: 00 00 00 01 2C
+      hex = '0xFC301100000000012C00FFF000000000DEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.pts_adjustment).to eq(300)
+    end
+
+    it 'should handle hex strings without 0x prefix' do
+      hex = 'FC301100000000000000FFF000000000DEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.table_id).to eq(0xFC)
+      expect(result.splice_command_type).to eq(0x00)
+    end
+
+    it 'should parse descriptors with 0xFFF command length' do
+      # time_signal (type 0x06) with splice_command_length=0xFFF
+      # and a descriptor present
+      # time_signal: time_specified=1, pts=90000 (5 bytes)
+      # descriptor: tag=0xFF, length=6, identifier=CUEI, data=0xAABB
+      hex = '0xFC301E00000000000000FFFFFF06FE00015F900008FF0643554549AABBDEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.splice_command_type).to eq(0x06)
+      expect(result.splice_command.pts_time).to eq(90_000)
+      expect(result.descriptors.length).to eq(1)
+      expect(result.descriptors.first).to be_a(String)
+    end
+
+    it 'should consume remaining bytes for unknown type with 0xFFF' do
+      # unknown command type 0xFF with 0xFFF length
+      # command data is everything up to CRC (no descriptors per spec)
+      # section_length = 11(header) + 3(command) + 4(CRC) = 18
+      hex = '0xFC301200000000000000FFFFFFFFAABBCCDEADBEEF'
+      result = described_class.parse(hex)
+
+      expect(result.splice_command_type).to eq(0xFF)
+      expect(result.splice_command).to eq("\xAA\xBB\xCC".b)
+      expect(result.descriptors).to eq([])
+    end
+
+    it 'should raise ParseError for truncated data' do
+      hex = '0xFC30'
+      expect { described_class.parse(hex) }
+        .to raise_error(M3u8::Scte35::ParseError, /invalid SCTE-35 data/)
+    end
+
+    it 'should raise ParseError for empty hex string' do
+      expect { described_class.parse('0x') }
+        .to raise_error(M3u8::Scte35::ParseError, /invalid SCTE-35 data/)
+    end
+  end
+end

data/spec/lib/m3u8/scte35_splice_insert_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35SpliceInsert do
+  def build_splice_insert_hex(command_bytes, command_length: nil)
+    cmd_len = command_length || command_bytes.length
+    # section_length = 11(header) + cmd_len + 2(desc_loop) + 4(CRC)
+    section_length = 11 + cmd_len + 6
+    header = splice_info_header(section_length, cmd_len)
+    command_hex = command_bytes.map { |b| format('%02X', b) }.join
+    desc_and_crc = '0000DEADBEEF'
+    "0x#{header}05#{command_hex}#{desc_and_crc}"
+  end
+
+  def splice_info_header(section_length, cmd_length)
+    table_id = 'FC'
+    section_header = format('%04X', 0x3000 | section_length)
+    proto_and_pts = '000000000000'
+    cw_index = '00'
+    tier_cmd = format('%06X', (0xFFF << 12) | cmd_length)
+    "#{table_id}#{section_header}#{proto_and_pts}#{cw_index}#{tier_cmd}"
+  end
+
+  describe '.parse_from' do
+    it 'should parse an ad-start splice_insert' do
+      # splice_event_id(32): 0x00000001
+      # splice_event_cancel_indicator(1): 0
+      # reserved(7): 1111111
+      # out_of_network_indicator(1): 1
+      # program_splice_flag(1): 1
+      # duration_flag(1): 0
+      # splice_immediate_flag(1): 0
+      # reserved(4): 1111
+      # splice_time: time_specified(1)=1, reserved(6)=111111, pts(33)=90000
+      # unique_program_id(16): 0x0001
+      # avail_num(8): 0
+      # avails_expected(8): 0
+      #
+      # pts_time 90000 = 0x15F90:
+      # time_specified(1)=1, reserved(6)=111111, pts(33)=0x00015F90
+      # 1_111111_0_00000000_00000000_00010101_11111001_0000...
+      # Wait, 33 bits of 90000 = 0x15F90:
+      # binary: 0_00000000_00000001_01011111_10010000
+      # with prefix: 1_111111_0_00000000_00000001_01011111_10010000
+      # bytes: FE 00 00 01 5F 90 ... but that's 6 bytes (48 bits) for 40 bits
+      #
+      # Actually: 1+6+33 = 40 bits = 5 bytes:
+      # 1_111111_0 00000000 00000001 01011111 10010000
+      # = FE 00 01 5F 90
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x01, # splice_event_id = 1
+        0x7F,                   # cancel=0, reserved=1111111
+        0xCF,                   # out=1, program=1, duration=0, immediate=0, reserved=1111
+        0xFE, 0x00, 0x01, 0x5F, 0x90, # splice_time: specified=1, pts=90000
+        0x00, 0x01,             # unique_program_id = 1
+        0x00,                   # avail_num = 0
+        0x00                    # avails_expected = 0
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd).to be_a(described_class)
+      expect(cmd.splice_event_id).to eq(1)
+      expect(cmd.out_of_network_indicator).to be true
+      expect(cmd.pts_time).to eq(90_000)
+      expect(cmd.unique_program_id).to eq(1)
+      expect(cmd.avail_num).to eq(0)
+      expect(cmd.avails_expected).to eq(0)
+    end
+
+    it 'should parse a cancelled splice event' do
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x02, # splice_event_id = 2
+        0xFF                    # cancel=1, reserved=1111111
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd.splice_event_id).to eq(2)
+      expect(cmd.splice_event_cancel_indicator).to be true
+      expect(cmd.out_of_network_indicator).to be_nil
+      expect(cmd.pts_time).to be_nil
+    end
+
+    it 'should parse splice_insert with break duration' do
+      # out=1, program=1, duration=1, immediate=0, reserved=1111
+      # splice_time: specified=1, pts=90000
+      # break_duration: auto_return(1)=1, reserved(6)=111111, duration(33)=2700000
+      # 2700000 = 0x293370
+      # 1_111111_0_00000000_00000000_00101001_00110011_01110000
+      # Wait, 33 bits: 0_00000000_00101001_00110011_01110000
+      # = 00 29 33 70 in the last 4 bytes, first byte has auto_return+reserved+MSB
+      # 1_111111_0 00000000 00101001 00110011 01110000
+      # = FE 00 29 33 70
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x03, # splice_event_id = 3
+        0x7F,                   # cancel=0, reserved=1111111
+        0xEF,                   # out=1, program=1, duration=1, immediate=0, reserved=1111
+        0xFE, 0x00, 0x01, 0x5F, 0x90, # splice_time: specified=1, pts=90000
+        0xFE, 0x00, 0x29, 0x32, 0xE0, # break_duration: auto=1, dur=2700000
+        0x00, 0x01,             # unique_program_id = 1
+        0x00,                   # avail_num = 0
+        0x02                    # avails_expected = 2
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd.break_duration).to eq(2_700_000)
+      expect(cmd.break_auto_return).to be true
+      expect(cmd.avails_expected).to eq(2)
+    end
+
+    it 'should parse an immediate splice (no PTS)' do
+      # out=1, program=1, duration=0, immediate=1, reserved=1111
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x04, # splice_event_id = 4
+        0x7F,                   # cancel=0, reserved=1111111
+        0xDF,                   # out=1, program=1, duration=0, immediate=1, reserved=1111
+        0x00, 0x01,             # unique_program_id = 1
+        0x00,                   # avail_num = 0
+        0x00                    # avails_expected = 0
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd.pts_time).to be_nil
+      expect(cmd.out_of_network_indicator).to be true
+      expect(cmd.splice_event_id).to eq(4)
+    end
+
+    it 'should parse component mode splice_insert' do
+      # out=1, program=0, duration=0, immediate=0, reserved=1111
+      # 1_0_0_0_1111 = 0x8F
+      # component_count=1, component_tag=0x22,
+      # splice_time: specified=1, pts=90000
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x01, # splice_event_id = 1
+        0x7F,                   # cancel=0, reserved=1111111
+        0x8F,                   # out=1, program=0, duration=0, immediate=0, reserved=1111
+        0x01,                   # component_count = 1
+        0x22,                   # component_tag = 0x22
+        0xFE, 0x00, 0x01, 0x5F, 0x90, # splice_time: specified=1, pts=90000
+        0x00, 0x01,             # unique_program_id = 1
+        0x00,                   # avail_num = 0
+        0x00                    # avails_expected = 0
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd).to be_a(described_class)
+      expect(cmd.splice_event_id).to eq(1)
+      expect(cmd.out_of_network_indicator).to be true
+      expect(cmd.pts_time).to be_nil
+      expect(cmd.unique_program_id).to eq(1)
+    end
+
+    it 'should parse component mode with immediate flag' do
+      # out=1, program=0, duration=0, immediate=1, reserved=1111
+      # 1_0_0_1_1111 = 0x9F
+      command_bytes = [
+        0x00, 0x00, 0x00, 0x05, # splice_event_id = 5
+        0x7F,                   # cancel=0, reserved=1111111
+        0x9F,                   # out=1, program=0, duration=0, immediate=1, reserved=1111
+        0x02,                   # component_count = 2
+        0x10,                   # component_tag = 0x10
+        0x20,                   # component_tag = 0x20
+        0x00, 0x01,             # unique_program_id = 1
+        0x00,                   # avail_num = 0
+        0x00                    # avails_expected = 0
+      ]
+      hex = build_splice_insert_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd.splice_event_id).to eq(5)
+      expect(cmd.unique_program_id).to eq(1)
+    end
+  end
+end

data/spec/lib/m3u8/scte35_splice_null_spec.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35SpliceNull do
+  describe '#new' do
+    it 'should create an empty splice null command' do
+      command = described_class.new
+      expect(command).to be_a(described_class)
+    end
+  end
+end

data/spec/lib/m3u8/scte35_time_signal_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Scte35TimeSignal do
+  def build_time_signal_hex(command_bytes, command_length: nil)
+    cmd_len = command_length || command_bytes.length
+    section_length = 11 + cmd_len + 6
+    header = splice_info_header(section_length, cmd_len)
+    command_hex = command_bytes.map { |b| format('%02X', b) }.join
+    "0x#{header}06#{command_hex}0000DEADBEEF"
+  end
+
+  def splice_info_header(section_length, cmd_length)
+    table_id = 'FC'
+    section_header = format('%04X', 0x3000 | section_length)
+    proto_and_pts = '000000000000'
+    cw_index = '00'
+    tier_cmd = format('%06X', (0xFFF << 12) | cmd_length)
+    "#{table_id}#{section_header}#{proto_and_pts}#{cw_index}#{tier_cmd}"
+  end
+
+  describe '.parse_from' do
+    it 'should parse time_signal with PTS time' do
+      # splice_time: time_specified(1)=1, reserved(6)=111111, pts(33)=90000
+      # 90000 = 0x15F90
+      # 1_111111_0_00000000_00000001_01011111_10010000
+      # = FE 00 01 5F 90
+      command_bytes = [0xFE, 0x00, 0x01, 0x5F, 0x90]
+      hex = build_time_signal_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd).to be_a(described_class)
+      expect(cmd.pts_time).to eq(90_000)
+    end
+
+    it 'should parse time_signal without time_specified' do
+      # time_specified(1)=0, reserved(7)=1111111
+      # = 0x7F (1 byte)
+      command_bytes = [0x7F]
+      hex = build_time_signal_hex(command_bytes)
+      result = M3u8::Scte35.parse(hex)
+      cmd = result.splice_command
+
+      expect(cmd).to be_a(described_class)
+      expect(cmd.pts_time).to be_nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Seth Deckard
@@ -167,6 +167,12 @@ files:
 - lib/m3u8/preload_hint_item.rb
 - lib/m3u8/reader.rb
 - lib/m3u8/rendition_report_item.rb
+- lib/m3u8/scte35.rb
+- lib/m3u8/scte35_bit_reader.rb
+- lib/m3u8/scte35_segmentation_descriptor.rb
+- lib/m3u8/scte35_splice_insert.rb
+- lib/m3u8/scte35_splice_null.rb
+- lib/m3u8/scte35_time_signal.rb
 - lib/m3u8/segment_item.rb
 - lib/m3u8/server_control_item.rb
 - lib/m3u8/session_data_item.rb
@@ -220,6 +226,12 @@ files:
 - spec/lib/m3u8/reader_spec.rb
 - spec/lib/m3u8/rendition_report_item_spec.rb
 - spec/lib/m3u8/round_trip_spec.rb
+- spec/lib/m3u8/scte35_bit_reader_spec.rb
+- spec/lib/m3u8/scte35_segmentation_descriptor_spec.rb
+- spec/lib/m3u8/scte35_spec.rb
+- spec/lib/m3u8/scte35_splice_insert_spec.rb
+- spec/lib/m3u8/scte35_splice_null_spec.rb
+- spec/lib/m3u8/scte35_time_signal_spec.rb
 - spec/lib/m3u8/segment_item_spec.rb
 - spec/lib/m3u8/server_control_item_spec.rb
 - spec/lib/m3u8/session_data_item_spec.rb