m3u8 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fb7826061b077f6e56712067f673393591d628e4e35a895af1910ff7fae859d
-  data.tar.gz: 8e0298d7fb9806e4fa2d3bc66b522a6f7bf7d0bbad1a57fcefeafeac7255a1f4
+  metadata.gz: c38180f01d16f00854720acaf6fc8359f2362417e19b8e45248a1573597716ca
+  data.tar.gz: b5192ed27a57a1f3a06d32f09d5d1fdbcd3c1e788d6bf515c68f739531ba8f23
 SHA512:
-  metadata.gz: 20c066c9f250d0d7948c3211f958bf553d8385d07f8715274b2738d3c497cf8cf450790489f80ccca88a1e09a67fc43411f055efcc16bf6f9fa07efed43ed407
-  data.tar.gz: 515ba07430d27872130625dc1d5eac52ebd68a76c20306ff4443b9829f74b3d3a7ceee8d63f118a7e832c6f48a7742e6157eb5bff05e26c198f262566f443c78
+  metadata.gz: be03dc5ca38934401073972dfab62b7ec35e4733eda199a91320b1b668e4046f04eae8518a720795d945bf7439da70ebe2d15d9bb53db3cd65cffedd3f70c0d9
+  data.tar.gz: a4faf2090ab7d3cd6c5788723a842d795903748e42a8ced6726af626ae81dc4373262074c2eeff70baae56c3b73c02d5a4a93d6caf84646d530092202c54dda1

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+**1.7.0**
+
+* Added HLS Interstitials first-class `DateRangeItem` accessors:
+  `asset_uri`, `asset_list`, `resume_offset`, `playout_limit`,
+  `restrict`, `snap`, `timeline_occupies`, `timeline_style`, and
+  `content_may_vary`.
+* Promoted supported interstitial `X-` attributes out of
+  `client_attributes` into typed fields during parsing and formatting.
+* Refactored `DateRangeItem` attribute formatting helpers to reduce
+  duplication while preserving output behavior.
+
+***
+
 **1.6.0**
 
 * Added SCTE-35 parsing with `M3u8::Scte35` for `splice_info_section`

data/README.md

@@ -253,12 +253,43 @@ Insert a timed metadata date range:
 ```ruby
 item = M3u8::DateRangeItem.new(
   id: 'ad-break-1', start_date: '2024-06-01T12:00:00Z',
-  planned_duration: 30.0,
+  planned_duration: 30.0, cue: 'PRE',
   client_attributes: { 'X-AD-ID' => '"foo"' }
 )
 playlist.items << item
 ```
 
+#### HLS Interstitials
+
+`DateRangeItem` supports [HLS Interstitials](https://developer.apple.com/documentation/http-live-streaming/providing-an-hls-interstitial) attributes as first-class accessors for ad insertion, pre/post-rolls, and timeline integration:
+
+```ruby
+item = M3u8::DateRangeItem.new(
+  id: 'ad-break-1',
+  class_name: 'com.apple.hls.interstitial',
+  start_date: '2024-06-01T12:00:00Z',
+  asset_uri: 'http://example.com/ad.m3u8',
+  resume_offset: 0.0,
+  playout_limit: 30.0,
+  restrict: 'SKIP,JUMP',
+  snap: 'OUT',
+  content_may_vary: 'YES'
+)
+playlist.items << item
+```
+
+| HLS Attribute        | Accessor            | Type   |
+|----------------------|---------------------|--------|
+| X-ASSET-URI          | `asset_uri`         | String |
+| X-ASSET-LIST         | `asset_list`        | String |
+| X-RESUME-OFFSET      | `resume_offset`     | Float  |
+| X-PLAYOUT-LIMIT      | `playout_limit`     | Float  |
+| X-RESTRICT           | `restrict`          | String |
+| X-SNAP               | `snap`              | String |
+| X-TIMELINE-OCCUPIES  | `timeline_occupies` | String |
+| X-TIMELINE-STYLE     | `timeline_style`    | String |
+| X-CONTENT-MAY-VARY   | `content_may_vary`  | String |
+
 Signal an encoding discontinuity:
 
 ```ruby

data/lib/m3u8/date_range_item.rb

@@ -7,7 +7,17 @@ module M3u8
 
     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
 
     def initialize(options = {})
       options.each do |key, value|
@@ -26,7 +36,9 @@ module M3u8
       @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')
+      parse_interstitials(attributes)
       @client_attributes = parse_client_attributes(attributes)
     end
 
@@ -56,34 +68,28 @@ module M3u8
        duration_format,
        planned_duration_format,
        client_attributes_format,
+       interstitial_formats,
        scte35_cmd_format,
        scte35_out_format,
        scte35_in_format,
-       end_on_next_format].compact.join(',')
+       cue_format,
+       end_on_next_format].flatten.compact.join(',')
     end
 
     def class_name_format
-      return if class_name.nil?
-
-      %(CLASS="#{class_name}")
+      quoted_format('CLASS', class_name)
     end
 
     def end_date_format
-      return if end_date.nil?
-
-      %(END-DATE="#{end_date}")
+      quoted_format('END-DATE', end_date)
     end
 
     def duration_format
-      return if duration.nil?
-
-      "DURATION=#{duration}"
+      unquoted_format('DURATION', duration)
     end
 
     def planned_duration_format
-      return if planned_duration.nil?
-
-      "PLANNED-DURATION=#{planned_duration}"
+      unquoted_format('PLANNED-DURATION', planned_duration)
     end
 
     def client_attributes_format
@@ -107,22 +113,76 @@ module M3u8
       end
     end
 
-    def scte35_cmd_format
-      return if scte35_cmd.nil?
+    def 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
 
-      "SCTE35-CMD=#{scte35_cmd}"
+    def interstitial_formats
+      [asset_uri_format, asset_list_format,
+       resume_offset_format, playout_limit_format,
+       restrict_format, snap_format,
+       timeline_occupies_format, timeline_style_format,
+       content_may_vary_format]
     end
 
-    def scte35_out_format
-      return if scte35_out.nil?
+    def asset_uri_format
+      quoted_format('X-ASSET-URI', asset_uri)
+    end
+
+    def asset_list_format
+      quoted_format('X-ASSET-LIST', asset_list)
+    end
+
+    def resume_offset_format
+      unquoted_format('X-RESUME-OFFSET', resume_offset)
+    end
+
+    def playout_limit_format
+      unquoted_format('X-PLAYOUT-LIMIT', playout_limit)
+    end
+
+    def restrict_format
+      quoted_format('X-RESTRICT', restrict)
+    end
+
+    def snap_format
+      quoted_format('X-SNAP', snap)
+    end
+
+    def timeline_occupies_format
+      quoted_format('X-TIMELINE-OCCUPIES', timeline_occupies)
+    end
+
+    def timeline_style_format
+      quoted_format('X-TIMELINE-STYLE', timeline_style)
+    end
 
-      "SCTE35-OUT=#{scte35_out}"
+    def content_may_vary_format
+      quoted_format('X-CONTENT-MAY-VARY', content_may_vary)
+    end
+
+    def scte35_cmd_format
+      unquoted_format('SCTE35-CMD', scte35_cmd)
+    end
+
+    def scte35_out_format
+      unquoted_format('SCTE35-OUT', scte35_out)
     end
 
     def scte35_in_format
-      return if scte35_in.nil?
+      unquoted_format('SCTE35-IN', scte35_in)
+    end
 
-      "SCTE35-IN=#{scte35_in}"
+    def cue_format
+      quoted_format('CUE', cue)
     end
 
     def end_on_next_format
@@ -131,8 +191,18 @@ module M3u8
       'END-ON-NEXT=YES'
     end
 
+    def quoted_format(key, value)
+      %(#{key}="#{value}") unless value.nil?
+    end
+
+    def unquoted_format(key, value)
+      "#{key}=#{value}" unless value.nil?
+    end
+
     def parse_client_attributes(attributes)
-      attributes.select { |key| key.start_with?('X-') }
+      attributes.select do |key|
+        key.start_with?('X-') && !INTERSTITIAL_KEYS.include?(key)
+      end
     end
   end
 end

data/lib/m3u8/version.rb

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

data/spec/lib/m3u8/date_range_item_spec.rb

@@ -11,7 +11,17 @@ describe M3u8::DateRangeItem do
                   planned_duration: 59.993,
                   scte35_out: '0xFC002F0000000000FF0',
                   scte35_in: '0xFC002F0000000000FF1',
-                  scte35_cmd: '0xFC002F0000000000FF2', end_on_next: true,
+                  scte35_cmd: '0xFC002F0000000000FF2',
+                  cue: 'PRE', end_on_next: true,
+                  asset_uri: 'http://example.com/ad.m3u8',
+                  asset_list: 'http://example.com/ads.json',
+                  resume_offset: 10.5,
+                  playout_limit: 30.0,
+                  restrict: 'SKIP,JUMP',
+                  snap: 'OUT',
+                  timeline_occupies: 'RANGE',
+                  timeline_style: 'HIGHLIGHT',
+                  content_may_vary: 'YES',
                   client_attributes: { 'X-CUSTOM' => 45.3 } }
       item = described_class.new(options)
 
@@ -24,7 +34,17 @@ describe M3u8::DateRangeItem do
       expect(item.scte35_out).to eq('0xFC002F0000000000FF0')
       expect(item.scte35_in).to eq('0xFC002F0000000000FF1')
       expect(item.scte35_cmd).to eq('0xFC002F0000000000FF2')
+      expect(item.cue).to eq('PRE')
       expect(item.end_on_next).to be true
+      expect(item.asset_uri).to eq('http://example.com/ad.m3u8')
+      expect(item.asset_list).to eq('http://example.com/ads.json')
+      expect(item.resume_offset).to eq(10.5)
+      expect(item.playout_limit).to eq(30.0)
+      expect(item.restrict).to eq('SKIP,JUMP')
+      expect(item.snap).to eq('OUT')
+      expect(item.timeline_occupies).to eq('RANGE')
+      expect(item.timeline_style).to eq('HIGHLIGHT')
+      expect(item.content_may_vary).to eq('YES')
       expect(item.client_attributes.empty?).to be false
       expect(item.client_attributes['X-CUSTOM']).to eq(45.3)
     end
@@ -33,12 +53,22 @@ describe M3u8::DateRangeItem do
   describe '#parse' do
     it 'should parse m3u8 tag into instance' do
       item = described_class.new
-      line = '#EXT-X-DATERANGE:ID="splice-6FFFFFF0",CLASS="test_class"' \
+      line = '#EXT-X-DATERANGE:ID="splice-6FFFFFF0",CLASS="test_class",' \
              'START-DATE="2014-03-05T11:15:00Z",' \
              'END-DATE="2014-03-05T11:16:00Z",DURATION=60.1,' \
              'PLANNED-DURATION=59.993,SCTE35-OUT=0xFC002F0000000000FF0,' \
              'SCTE35-IN=0xFC002F0000000000FF1,' \
              'SCTE35-CMD=0xFC002F0000000000FF2,' \
+             'X-ASSET-URI="http://example.com/ad.m3u8",' \
+             'X-ASSET-LIST="http://example.com/ads.json",' \
+             'X-RESUME-OFFSET=10.5,' \
+             'X-PLAYOUT-LIMIT=30.0,' \
+             'X-RESTRICT="SKIP,JUMP",' \
+             'X-SNAP="OUT",' \
+             'X-TIMELINE-OCCUPIES="RANGE",' \
+             'X-TIMELINE-STYLE="HIGHLIGHT",' \
+             'X-CONTENT-MAY-VARY="YES",' \
+             'CUE="PRE",' \
              'END-ON-NEXT=YES'
       item.parse(line)
 
@@ -51,6 +81,16 @@ describe M3u8::DateRangeItem do
       expect(item.scte35_out).to eq('0xFC002F0000000000FF0')
       expect(item.scte35_in).to eq('0xFC002F0000000000FF1')
       expect(item.scte35_cmd).to eq('0xFC002F0000000000FF2')
+      expect(item.asset_uri).to eq('http://example.com/ad.m3u8')
+      expect(item.asset_list).to eq('http://example.com/ads.json')
+      expect(item.resume_offset).to eq(10.5)
+      expect(item.playout_limit).to eq(30.0)
+      expect(item.restrict).to eq('SKIP,JUMP')
+      expect(item.snap).to eq('OUT')
+      expect(item.timeline_occupies).to eq('RANGE')
+      expect(item.timeline_style).to eq('HIGHLIGHT')
+      expect(item.content_may_vary).to eq('YES')
+      expect(item.cue).to eq('PRE')
       expect(item.end_on_next).to be true
       expect(item.client_attributes.empty?).to be true
     end
@@ -93,20 +133,43 @@ describe M3u8::DateRangeItem do
                   planned_duration: 59.993,
                   scte35_out: '0xFC002F0000000000FF0',
                   scte35_in: '0xFC002F0000000000FF1',
-                  scte35_cmd: '0xFC002F0000000000FF2', end_on_next: true,
+                  scte35_cmd: '0xFC002F0000000000FF2',
+                  asset_uri: 'http://example.com/ad.m3u8',
+                  asset_list: 'http://example.com/ads.json',
+                  resume_offset: 10.5,
+                  playout_limit: 30.0,
+                  restrict: 'SKIP,JUMP',
+                  snap: 'OUT',
+                  timeline_occupies: 'RANGE',
+                  timeline_style: 'HIGHLIGHT',
+                  content_may_vary: 'YES',
+                  cue: 'POST,ONCE', end_on_next: true,
                   client_attributes: { 'X-CUSTOM' => 45.3,
-                                       'X-CUSTOM-TEXT' => 'test_value' } }
+                                       'X-CUSTOM-TEXT' =>
+                                         'test_value' } }
       item = described_class.new(options)
 
-      expected = '#EXT-X-DATERANGE:ID="test_id",CLASS="test_class",' \
+      expected = '#EXT-X-DATERANGE:ID="test_id",' \
+                 'CLASS="test_class",' \
                  'START-DATE="2014-03-05T11:15:00Z",' \
-                 'END-DATE="2014-03-05T11:16:00Z",DURATION=60.1,' \
+                 'END-DATE="2014-03-05T11:16:00Z",' \
+                 'DURATION=60.1,' \
                  'PLANNED-DURATION=59.993,' \
                  'X-CUSTOM=45.3,' \
                  'X-CUSTOM-TEXT="test_value",' \
+                 'X-ASSET-URI="http://example.com/ad.m3u8",' \
+                 'X-ASSET-LIST="http://example.com/ads.json",' \
+                 'X-RESUME-OFFSET=10.5,' \
+                 'X-PLAYOUT-LIMIT=30.0,' \
+                 'X-RESTRICT="SKIP,JUMP",' \
+                 'X-SNAP="OUT",' \
+                 'X-TIMELINE-OCCUPIES="RANGE",' \
+                 'X-TIMELINE-STYLE="HIGHLIGHT",' \
+                 'X-CONTENT-MAY-VARY="YES",' \
                  'SCTE35-CMD=0xFC002F0000000000FF2,' \
                  'SCTE35-OUT=0xFC002F0000000000FF0,' \
                  'SCTE35-IN=0xFC002F0000000000FF1,' \
+                 'CUE="POST,ONCE",' \
                  'END-ON-NEXT=YES'
 
       expect(item.to_s).to eq(expected)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Seth Deckard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-01 00:00:00.000000000 Z
+date: 2026-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler