m3u8 0.8.2 → 1.8.1

data/lib/m3u8/writer.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
+
 module M3u8
   # Writer provides generation of text output of playlists in m3u8 format
   class Writer
+    # @return [IO] output stream
     attr_accessor :io
 
+    # @param io [IO] writable IO object
     def initialize(io)
       @io = io
     end
 
+    # Write a playlist to the output stream.
+    # @param playlist [Playlist] playlist to write
+    # @return [void]
     def write(playlist)
       validate(playlist)
       write_header(playlist)
@@ -21,6 +27,7 @@ module M3u8
 
     def write_footer(playlist)
       return if playlist.live? || playlist.master?
+
       io.puts '#EXT-X-ENDLIST'
     end
 
@@ -41,7 +48,9 @@ module M3u8
 
     def validate(playlist)
       return if playlist.valid?
-      raise PlaylistTypeError, 'Playlist is invalid.'
+
+      raise PlaylistTypeError,
+            "Playlist is invalid: #{playlist.errors.join('; ')}"
     end
 
     def write_cache_tag(cache)
@@ -76,6 +85,20 @@ module M3u8
       write_discontinuity_sequence_tag(playlist.discontinuity_sequence)
       write_cache_tag(playlist.cache)
       io.puts target_duration_format(playlist)
+      write_server_control_tag(playlist.server_control)
+      write_part_inf_tag(playlist.part_inf)
+    end
+
+    def write_server_control_tag(server_control)
+      return if server_control.nil?
+
+      io.puts server_control.to_s
+    end
+
+    def write_part_inf_tag(part_inf)
+      return if part_inf.nil?
+
+      io.puts part_inf.to_s
     end
 
     def write_version_tag(version)

data/lib/m3u8.rb

@@ -1,30 +1,54 @@
 # frozen_string_literal: true
+
 require 'bigdecimal'
 require 'stringio'
-Dir[File.dirname(__FILE__) + '/m3u8/*.rb'].sort.each { |file| require file }
+Dir["#{File.dirname(__FILE__)}/m3u8/*.rb"].each { |file| require file }
 
 # M3u8 provides parsing, generation, and validation of m3u8 playlists
 module M3u8
-  def intialize_with_byterange(params = {})
+  # Initialize attributes from a params hash, converting any Hash
+  # values for :byterange into ByteRange instances.
+  # @param params [Hash] attribute key-value pairs
+  # @return [void]
+  def initialize_with_byterange(params = {})
     params.each do |key, value|
       value = ByteRange.new(value) if value.is_a?(Hash)
       instance_variable_set("@#{key}", value)
     end
   end
 
+  # Parse an HLS attribute list string into a Hash.
+  # @param line [String] raw attribute list (e.g. 'KEY="val",NUM=1')
+  # @return [Hash<String, String>] attribute name-value pairs
   def parse_attributes(line)
-    array = line.delete("\n").scan(/([A-z0-9-]+)\s*=\s*("[^"]*"|[^,]*)/)
-    Hash[array.map { |key, value| [key, value.delete('"')] }]
+    line.delete("\n").scan(/([A-Za-z0-9-]+)\s*=\s*("[^"]*"|[^,]*)/)
+        .to_h { |key, value| [key, value.delete('"')] }
   end
 
+  # Convert a string value to Float, returning nil when nil.
+  # @param value [String, nil] numeric string
+  # @return [Float, nil]
   def parse_float(value)
-    value.nil? ? nil : value.to_f
+    value&.to_f
+  end
+
+  # Convert a string value to Integer, returning nil when nil.
+  # @param value [String, nil] numeric string
+  # @return [Integer, nil]
+  def parse_int(value)
+    value&.to_i
   end
 
+  # Parse an HLS YES/NO attribute into a boolean.
+  # @param value [String] 'YES' or 'NO'
+  # @return [Boolean]
   def parse_yes_no(value)
-    value == 'YES' ? true : false
+    value == 'YES'
   end
 
+  # Convert a boolean into an HLS YES/NO string.
+  # @param boolean [Boolean] value to convert
+  # @return [String] 'YES' or 'NO'
   def to_yes_no(boolean)
     boolean == true ? 'YES' : 'NO'
   end

data/m3u8.gemspec

@@ -1,5 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'm3u8/version'
 
@@ -8,21 +7,22 @@ Gem::Specification.new do |spec|
   spec.version       = M3u8::VERSION
   spec.authors       = ['Seth Deckard']
   spec.email         = ['seth@deckard.me']
-  spec.summary       = %q{Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).}
-  spec.description   = %q{Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).}
+  spec.summary       = 'Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).'
+  spec.description   = 'Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).'
   spec.homepage      = 'https://github.com/sethdeckard/m3u8'
   spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/sethdeckard/m3u8',
+    'changelog_uri' => 'https://github.com/sethdeckard/m3u8/blob/master/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/sethdeckard/m3u8/issues'
+  }
 
   spec.files         = `git ls-files -z`.split("\x0")
+                                        .grep_v(/\A(CLAUDE|AGENTS)\.md\z/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.add_dependency 'bigdecimal'
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec', '>=3.0'
-  spec.add_development_dependency 'coveralls'
-  spec.add_development_dependency 'guard'
-  spec.add_development_dependency 'guard-rspec'
-  spec.add_development_dependency 'simplecov'
 end

data/spec/fixtures/content_steering.m3u8

@@ -0,0 +1,10 @@
+#EXTM3U
+#EXT-X-VERSION:13
+#EXT-X-INDEPENDENT-SEGMENTS
+#EXT-X-DEFINE:NAME="base_url",VALUE="https://example.com"
+#EXT-X-DEFINE:IMPORT="token"
+#EXT-X-CONTENT-STEERING:SERVER-URI="https://example.com/steering",PATHWAY-ID="CDN-A"
+#EXT-X-STREAM-INF:BANDWIDTH=2000000,CODECS="avc1.640028,mp4a.40.2",RESOLUTION=1280x720
+720p.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=5000000,CODECS="avc1.640028,mp4a.40.2",RESOLUTION=1920x1080
+1080p.m3u8

data/spec/fixtures/daterange_playlist.m3u8

@@ -0,0 +1,14 @@
+#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-TARGETDURATION:10
+#EXT-X-DATERANGE:ID="ad-1",CLASS="com.example.ad",START-DATE="2024-01-01T00:00:00Z",END-DATE="2024-01-01T00:00:30Z",DURATION=30.0,X-AD-ID="ad-123",X-AD-URL="https://example.com/ad"
+#EXTINF:10.0,
+segment0.ts
+#EXT-X-DATERANGE:ID="ad-2",CLASS="com.example.ad",START-DATE="2024-01-01T00:00:30Z",PLANNED-DURATION=15.0,X-AD-ID="ad-456"
+#EXTINF:10.0,
+segment1.ts
+#EXT-X-DATERANGE:ID="ch-1",START-DATE="2024-01-01T00:01:00Z",END-ON-NEXT=YES
+#EXTINF:10.0,
+segment2.ts
+#EXT-X-ENDLIST

data/spec/fixtures/encrypted_discontinuity.m3u8

@@ -0,0 +1,17 @@
+#EXTM3U
+#EXT-X-VERSION:6
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-TARGETDURATION:10
+#EXT-X-KEY:METHOD=AES-128,URI="https://example.com/key1.bin",IV=0x00000000000000000000000000000001
+#EXTINF:10.0,
+segment0.ts
+#EXTINF:10.0,
+segment1.ts
+#EXT-X-DISCONTINUITY
+#EXT-X-KEY:METHOD=AES-128,URI="https://example.com/key2.bin",IV=0x00000000000000000000000000000002
+#EXTINF:10.0,
+segment2.ts
+#EXT-X-KEY:METHOD=NONE
+#EXTINF:10.0,
+segment3.ts
+#EXT-X-ENDLIST

data/spec/fixtures/event_playlist.m3u8

@@ -0,0 +1,18 @@
+#EXTM3U
+#EXT-X-PLAYLIST-TYPE:EVENT
+#EXT-X-VERSION:7
+#EXT-X-INDEPENDENT-SEGMENTS
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-TARGETDURATION:6
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:6.0,
+#EXT-X-BYTERANGE:75232@0
+segment0.mp4
+#EXTINF:6.0,
+#EXT-X-BYTERANGE:82112@75232
+segment1.mp4
+#EXT-X-DISCONTINUITY
+#EXT-X-MAP:URI="init2.mp4"
+#EXTINF:5.0,
+segment2.mp4
+#EXT-X-ENDLIST

data/spec/fixtures/gap_playlist.m3u8

@@ -0,0 +1,14 @@
+#EXTM3U
+#EXT-X-VERSION:6
+#EXT-X-TARGETDURATION:10
+#EXT-X-MEDIA-SEQUENCE:1
+#EXT-X-BITRATE:128
+#EXTINF:10.0,
+segment1.ts
+#EXT-X-GAP
+#EXTINF:10.0,
+gap_segment.ts
+#EXT-X-BITRATE:256
+#EXTINF:10.0,
+segment3.ts
+#EXT-X-ENDLIST

data/spec/fixtures/ll_hls_advanced.m3u8

@@ -0,0 +1,18 @@
+#EXTM3U
+#EXT-X-VERSION:9
+#EXT-X-MEDIA-SEQUENCE:100
+#EXT-X-TARGETDURATION:4
+#EXT-X-SERVER-CONTROL:CAN-SKIP-UNTIL=24.0,CAN-SKIP-DATERANGES=YES,HOLD-BACK=12.0,PART-HOLD-BACK=1.0,CAN-BLOCK-RELOAD=YES
+#EXT-X-PART-INF:PART-TARGET=0.5
+#EXT-X-SKIP:SKIPPED-SEGMENTS=10,RECENTLY-REMOVED-DATERANGES="dr-1"
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:4.0,
+segment100.mp4
+#EXT-X-DISCONTINUITY
+#EXT-X-PART:DURATION=0.5,URI="segment101.0.mp4",INDEPENDENT=YES
+#EXT-X-PART:DURATION=0.5,URI="segment101.1.mp4",BYTERANGE="1024@0",GAP=YES
+#EXT-X-PART:DURATION=0.5,URI="segment101.2.mp4"
+#EXTINF:4.0,
+segment101.mp4
+#EXT-X-PRELOAD-HINT:TYPE=MAP,URI="init2.mp4"
+#EXT-X-RENDITION-REPORT:URI="../720p/stream.m3u8",LAST-MSN=101,LAST-PART=2

data/spec/fixtures/ll_hls_playlist.m3u8

@@ -0,0 +1,20 @@
+#EXTM3U
+#EXT-X-VERSION:9
+#EXT-X-TARGETDURATION:4
+#EXT-X-MEDIA-SEQUENCE:100
+#EXT-X-SERVER-CONTROL:CAN-SKIP-UNTIL=24.0,CAN-BLOCK-RELOAD=YES,PART-HOLD-BACK=1.0
+#EXT-X-PART-INF:PART-TARGET=0.5
+#EXT-X-SKIP:SKIPPED-SEGMENTS=5
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:4.0,
+segment100.mp4
+#EXT-X-PART:DURATION=0.5,URI="segment101.0.mp4",INDEPENDENT=YES
+#EXT-X-PART:DURATION=0.5,URI="segment101.1.mp4"
+#EXT-X-PART:DURATION=0.5,URI="segment101.2.mp4"
+#EXT-X-PART:DURATION=0.5,URI="segment101.3.mp4"
+#EXTINF:4.0,
+segment101.mp4
+#EXT-X-PART:DURATION=0.5,URI="segment102.0.mp4",INDEPENDENT=YES
+#EXT-X-PRELOAD-HINT:TYPE=PART,URI="segment102.1.mp4"
+#EXT-X-RENDITION-REPORT:URI="../720p/stream.m3u8",LAST-MSN=101,LAST-PART=3
+#EXT-X-RENDITION-REPORT:URI="../480p/stream.m3u8",LAST-MSN=101,LAST-PART=3

data/spec/fixtures/master_full.m3u8

@@ -0,0 +1,14 @@
+#EXTM3U
+#EXT-X-VERSION:13
+#EXT-X-INDEPENDENT-SEGMENTS
+#EXT-X-DEFINE:QUERYPARAM="token"
+#EXT-X-START:TIME-OFFSET=10.5,PRECISE=YES
+#EXT-X-SESSION-KEY:METHOD=SAMPLE-AES,URI="https://example.com/key.bin",KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1"
+#EXT-X-SESSION-DATA:DATA-ID="com.example.title",VALUE="Example Stream",LANGUAGE="en"
+#EXT-X-CONTENT-STEERING:SERVER-URI="https://example.com/steering",PATHWAY-ID="CDN-A"
+#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="audio/en.m3u8",FORCED=NO
+#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",LANGUAGE="es",NAME="Spanish",AUTOSELECT=YES,DEFAULT=NO,URI="audio/es.m3u8",FORCED=NO
+#EXT-X-STREAM-INF:CODECS="avc1.640028,mp4a.40.2",BANDWIDTH=5000000,AVERAGE-BANDWIDTH=4500000,FRAME-RATE=29.970,AUDIO="aac"
+video/1080.m3u8
+#EXT-X-STREAM-INF:CODECS="avc1.4d001f,mp4a.40.2",BANDWIDTH=2000000,AVERAGE-BANDWIDTH=1800000,FRAME-RATE=29.970,AUDIO="aac"
+video/720.m3u8

data/spec/fixtures/master_v13.m3u8

@@ -0,0 +1,8 @@
+#EXTM3U
+#EXT-X-VERSION:13
+#EXT-X-INDEPENDENT-SEGMENTS
+#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",NAME="English",LANGUAGE="en",DEFAULT=YES,AUTOSELECT=YES,CHANNELS="2",STABLE-RENDITION-ID="audio-en",BIT-DEPTH=16,SAMPLE-RATE=44100,URI="audio/en.m3u8"
+#EXT-X-STREAM-INF:BANDWIDTH=5000000,AVERAGE-BANDWIDTH=4500000,CODECS="avc1.640028,mp4a.40.2",RESOLUTION=1920x1080,FRAME-RATE=29.970,HDCP-LEVEL=TYPE-0,VIDEO-RANGE=SDR,AUDIO="aac",STABLE-VARIANT-ID="hd-1080",PATHWAY-ID="CDN-A",SCORE=12.5,SUPPLEMENTAL-CODECS="dvh1.05.06/db4g",ALLOWED-CPC="com.example.drm:SMART-TV/PC",REQ-VIDEO-LAYOUT="CH-MONO"
+1080p.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2000000,AVERAGE-BANDWIDTH=1800000,CODECS="avc1.4d001f,mp4a.40.2",RESOLUTION=1280x720,FRAME-RATE=29.970,VIDEO-RANGE=SDR,AUDIO="aac",STABLE-VARIANT-ID="hd-720"
+720p.m3u8

data/spec/lib/m3u8/bitrate_item_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::BitrateItem do
+  describe '.new' do
+    it 'assigns attributes from options' do
+      item = described_class.new(bitrate: 128)
+      expect(item.bitrate).to eq(128)
+    end
+  end
+
+  describe '.parse' do
+    it 'returns instance from parsed tag' do
+      item = described_class.parse('#EXT-X-BITRATE:128')
+      expect(item.bitrate).to eq(128)
+    end
+  end
+
+  describe '#to_s' do
+    it 'returns m3u8 format representation' do
+      item = described_class.new(bitrate: 128)
+      expect(item.to_s).to eq('#EXT-X-BITRATE:128')
+    end
+  end
+end

data/spec/lib/m3u8/builder_spec.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::Builder do
+  shared_examples 'a builder method' do |method, klass, params, checks|
+    it "adds a #{klass} to the playlist" do
+      pl = M3u8::Playlist.build { send(method, **params) }
+
+      item = pl.items.first
+      expect(item).to be_a(klass)
+      checks.each do |attr, value|
+        expect(item.public_send(attr)).to eq(value)
+      end
+    end
+  end
+
+  shared_examples 'a zero-arg builder method' do |method, klass|
+    it "adds a #{klass} to the playlist" do
+      pl = M3u8::Playlist.build { send(method) }
+      expect(pl.items.first).to be_a(klass)
+    end
+  end
+
+  describe '#segment' do
+    include_examples 'a builder method',
+                     :segment, M3u8::SegmentItem,
+                     { duration: 11.34,
+                       segment: '1080-7mbps00000.ts' },
+                     { duration: 11.34,
+                       segment: '1080-7mbps00000.ts' }
+  end
+
+  describe '#playlist' do
+    include_examples 'a builder method',
+                     :playlist, M3u8::PlaylistItem,
+                     { bandwidth: 540, uri: 'test.url' },
+                     { bandwidth: 540, uri: 'test.url' }
+  end
+
+  describe '#media' do
+    include_examples 'a builder method',
+                     :media, M3u8::MediaItem,
+                     { type: 'AUDIO', group_id: 'audio-lo',
+                       name: 'English', default: true,
+                       uri: 'eng/prog_index.m3u8' },
+                     { type: 'AUDIO', group_id: 'audio-lo',
+                       name: 'English' }
+  end
+
+  describe '#session_data' do
+    include_examples 'a builder method',
+                     :session_data, M3u8::SessionDataItem,
+                     { data_id: 'com.example.title',
+                       value: 'My Video', language: 'en' },
+                     { data_id: 'com.example.title',
+                       value: 'My Video' }
+  end
+
+  describe '#session_key' do
+    include_examples 'a builder method',
+                     :session_key, M3u8::SessionKeyItem,
+                     { method: 'AES-128',
+                       uri: 'https://example.com/key.bin' },
+                     { method: 'AES-128' }
+  end
+
+  describe '#content_steering' do
+    include_examples 'a builder method',
+                     :content_steering,
+                     M3u8::ContentSteeringItem,
+                     { server_uri: 'https://example.com/s',
+                       pathway_id: 'CDN-A' },
+                     { server_uri: 'https://example.com/s',
+                       pathway_id: 'CDN-A' }
+  end
+
+  describe '#key' do
+    include_examples 'a builder method',
+                     :key, M3u8::KeyItem,
+                     { method: 'AES-128',
+                       uri: 'https://example.com/key.bin' },
+                     { method: 'AES-128' }
+  end
+
+  describe '#map' do
+    it 'adds a MapItem to the playlist' do
+      pl = M3u8::Playlist.build do
+        map uri: 'init.mp4',
+            byterange: { length: 812, start: 0 }
+      end
+
+      item = pl.items.first
+      expect(item).to be_a(M3u8::MapItem)
+      expect(item.uri).to eq('init.mp4')
+      expect(item.byterange.length).to eq(812)
+    end
+  end
+
+  describe '#date_range' do
+    include_examples 'a builder method',
+                     :date_range, M3u8::DateRangeItem,
+                     { id: 'ad-break-1',
+                       start_date: '2024-06-01T12:00:00Z',
+                       planned_duration: 30.0 },
+                     { id: 'ad-break-1',
+                       planned_duration: 30.0 }
+  end
+
+  describe '#discontinuity' do
+    include_examples 'a zero-arg builder method',
+                     :discontinuity, M3u8::DiscontinuityItem
+  end
+
+  describe '#gap' do
+    include_examples 'a zero-arg builder method',
+                     :gap, M3u8::GapItem
+  end
+
+  describe '#time' do
+    include_examples 'a builder method',
+                     :time, M3u8::TimeItem,
+                     { time: '2024-06-01T12:00:00Z' },
+                     { time: '2024-06-01T12:00:00Z' }
+  end
+
+  describe '#bitrate' do
+    include_examples 'a builder method',
+                     :bitrate, M3u8::BitrateItem,
+                     { bitrate: 1500 },
+                     { bitrate: 1500 }
+  end
+
+  describe '#part' do
+    include_examples 'a builder method',
+                     :part, M3u8::PartItem,
+                     { duration: 0.5, uri: 'seg101.0.mp4',
+                       independent: true },
+                     { duration: 0.5, uri: 'seg101.0.mp4' }
+  end
+
+  describe '#preload_hint' do
+    include_examples 'a builder method',
+                     :preload_hint, M3u8::PreloadHintItem,
+                     { type: 'PART', uri: 'seg101.1.mp4' },
+                     { type: 'PART', uri: 'seg101.1.mp4' }
+  end
+
+  describe '#rendition_report' do
+    include_examples 'a builder method',
+                     :rendition_report,
+                     M3u8::RenditionReportItem,
+                     { uri: '../alt/index.m3u8',
+                       last_msn: 101, last_part: 0 },
+                     { uri: '../alt/index.m3u8',
+                       last_msn: 101 }
+  end
+
+  describe '#skip' do
+    include_examples 'a builder method',
+                     :skip, M3u8::SkipItem,
+                     { skipped_segments: 10 },
+                     { skipped_segments: 10 }
+  end
+
+  describe '#define' do
+    include_examples 'a builder method',
+                     :define, M3u8::DefineItem,
+                     { name: 'base',
+                       value: 'https://example.com' },
+                     { name: 'base',
+                       value: 'https://example.com' }
+  end
+
+  describe '#playback_start' do
+    include_examples 'a builder method',
+                     :playback_start, M3u8::PlaybackStart,
+                     { time_offset: 10.0, precise: true },
+                     { time_offset: 10.0 }
+  end
+
+  describe 'Playlist.build' do
+    it 'returns a Playlist with options' do
+      playlist = M3u8::Playlist.build(version: 4,
+                                      target: 12) do
+        segment duration: 11.34, segment: 'test.ts'
+      end
+
+      expect(playlist).to be_a(M3u8::Playlist)
+      expect(playlist.version).to eq(4)
+      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|
+        files.each do |f|
+          b.segment duration: 10.0, segment: f
+        end
+      end
+
+      expect(playlist.items.size).to eq(2)
+      expect(playlist.items[0].segment).to eq('seg1.ts')
+      expect(playlist.items[1].segment).to eq('seg2.ts')
+    end
+  end
+
+  describe 'integration' do
+    it 'produces identical output to imperative API ' \
+       'for a master playlist' do
+      imperative = M3u8::Playlist.new(
+        independent_segments: true
+      )
+      imperative.items << M3u8::PlaylistItem.new(
+        program_id: '1', bandwidth: 6400,
+        audio_codec: 'mp3', uri: 'lo/index.m3u8'
+      )
+      imperative.items << M3u8::PlaylistItem.new(
+        program_id: '2', bandwidth: 50_000,
+        width: 1920, height: 1080,
+        profile: 'high', level: 4.1,
+        audio_codec: 'aac-lc', uri: 'hi/index.m3u8'
+      )
+      imperative.items << M3u8::SessionDataItem.new(
+        data_id: 'com.test.title', value: 'Test',
+        language: 'en'
+      )
+
+      built = M3u8::Playlist.build(
+        independent_segments: true
+      ) do
+        playlist program_id: '1', bandwidth: 6400,
+                 audio_codec: 'mp3', uri: 'lo/index.m3u8'
+        playlist program_id: '2', bandwidth: 50_000,
+                 width: 1920, height: 1080,
+                 profile: 'high', level: 4.1,
+                 audio_codec: 'aac-lc',
+                 uri: 'hi/index.m3u8'
+        session_data data_id: 'com.test.title',
+                     value: 'Test', language: 'en'
+      end
+
+      expect(built.to_s).to eq(imperative.to_s)
+    end
+
+    it 'produces identical output to imperative API ' \
+       'for a media playlist' do
+      imperative = M3u8::Playlist.new(
+        version: 7, cache: false, target: 12,
+        sequence: 1, type: 'VOD'
+      )
+      imperative.items << M3u8::KeyItem.new(
+        method: 'AES-128', uri: 'http://test.key',
+        iv: 'D512BBF', key_format: 'identity',
+        key_format_versions: '1/3'
+      )
+      imperative.items << M3u8::SegmentItem.new(
+        duration: 11.344644, segment: '00000.ts'
+      )
+      imperative.items << M3u8::DiscontinuityItem.new
+      imperative.items << M3u8::TimeItem.new(
+        time: '2024-06-01T12:00:00Z'
+      )
+      imperative.items << M3u8::SegmentItem.new(
+        duration: 11.261233, segment: '00001.ts'
+      )
+      imperative.items << M3u8::MapItem.new(
+        uri: 'init.mp4',
+        byterange: { length: 812, start: 0 }
+      )
+      imperative.items << M3u8::SegmentItem.new(
+        duration: 7.5, segment: '00002.ts'
+      )
+
+      built = M3u8::Playlist.build(
+        version: 7, cache: false, target: 12,
+        sequence: 1, type: 'VOD'
+      ) do
+        key method: 'AES-128', uri: 'http://test.key',
+            iv: 'D512BBF', key_format: 'identity',
+            key_format_versions: '1/3'
+        segment duration: 11.344644, segment: '00000.ts'
+        discontinuity
+        time time: '2024-06-01T12:00:00Z'
+        segment duration: 11.261233, segment: '00001.ts'
+        map uri: 'init.mp4',
+            byterange: { length: 812, start: 0 }
+        segment duration: 7.5, segment: '00002.ts'
+      end
+
+      expect(built.to_s).to eq(imperative.to_s)
+    end
+
+    it 'produces identical output to imperative API ' \
+       'for an LL-HLS playlist' do
+      sc = M3u8::ServerControlItem.new(
+        can_skip_until: 24.0, part_hold_back: 1.0,
+        can_block_reload: true
+      )
+      pi = M3u8::PartInfItem.new(part_target: 0.5)
+      opts = {
+        version: 9, target: 4, sequence: 100,
+        server_control: sc, part_inf: pi, live: true
+      }
+
+      imperative = M3u8::Playlist.new(opts)
+      imperative.items << M3u8::MapItem.new(
+        uri: 'init.mp4'
+      )
+      imperative.items << M3u8::SegmentItem.new(
+        duration: 4.0, segment: 'seg100.mp4'
+      )
+      imperative.items << M3u8::PartItem.new(
+        duration: 0.5, uri: 'seg101.0.mp4',
+        independent: true
+      )
+      imperative.items << M3u8::PreloadHintItem.new(
+        type: 'PART', uri: 'seg101.1.mp4'
+      )
+      imperative.items << M3u8::RenditionReportItem.new(
+        uri: '../alt/index.m3u8',
+        last_msn: 101, last_part: 0
+      )
+
+      built = M3u8::Playlist.build(opts) do
+        map uri: 'init.mp4'
+        segment duration: 4.0, segment: 'seg100.mp4'
+        part duration: 0.5, uri: 'seg101.0.mp4',
+             independent: true
+        preload_hint type: 'PART', uri: 'seg101.1.mp4'
+        rendition_report uri: '../alt/index.m3u8',
+                         last_msn: 101, last_part: 0
+      end
+
+      expect(built.to_s).to eq(imperative.to_s)
+    end
+  end
+end