m3u8 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2be533f088c62f6247e71b571a4481c92e56f8d575511ecae16be472dd90006a
-  data.tar.gz: 3d6de6bef331beefea33a156f6129dbcb30c89b195d807440acd740b53027a1b
+  metadata.gz: 7a9a7d6e157afd5fd7028323544bf9d851bd898890f90c66af6f64e672d7e456
+  data.tar.gz: ee452e25dfb96ee9634e9a00c287a87ac4640dceb2d965550e31199e0c0b4e26
 SHA512:
-  metadata.gz: edd32a67f619c6fd6b234163cbd16837cd92100f9d84f3729dd1ab09d6fdb1467f8cdab9e89cf64db344d4bb4359620c7aaad3d8532cb33195734a8c22833874
-  data.tar.gz: c24310d02ff3f844640618cf73fba927fd06bdf2f24e0c20d65166b459092f605d59f1ad408853342c3196e3eceed9535ef08a71c7c75bed8024d5f6383d2f8e
+  metadata.gz: f6b458aaf9a1a1060d19dca456020b54813f0c1f011615593e088a512a87ed32120cd5d509fb66dd3b12f85fe11a255304eede7852a00197cfd9513c918a33eb
+  data.tar.gz: 7c543fd8e6004adaf275adfe95c231b42fe0549805436f8dea3e77f2731f273084c99887781d0b69daf05ec1e53218fb8711be895fc0c14e9f0687f983a611b1

data/AGENTS.md

@@ -2,8 +2,9 @@
 
 ## Development Workflow
 
-- Small commits that can each be deployed independently
-- Each commit must not break production (CI/CD safe)
+- Git workflow: GitHub flow
+- Small (but logical) commits that can each be deployed independently
+- Each commit must not break CI
 - Prefer incremental changes over large feature branches
 
 ### Commit Messages
@@ -12,13 +13,15 @@
 
 **Body:** Wrap at 72 chars, explain what/why not how, blank line after subject
 
-**Leading verbs:** Add, Remove, Fix, Upgrade, Refactor, Reformat, Start, Stop, Document, Reword
+**Leading verbs:** Add, Remove, Fix, Upgrade, Refactor, Reformat, Document, Reword
 
 ## Development Standards
 
+- README updated with API changes
 - **Tests must cover all behavior** - check with `coverage/index.html` after running specs
 - RuboCop enforces 80-char line limit and other style
 
 ## Deployment
 
-Never deploy anything.
+- Kicking off PR: `ghprcw`
+- Never deploy anything

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+**1.2.0**
+
+* Added `Playlist.build` with block-based Builder DSL for concise playlist construction. Supports both `instance_eval` (clean DSL) and yielded builder (outer scope access) forms. All 19 item types have corresponding DSL methods.
+
+***
+
+**1.1.0**
+
+* Added convenience accessor methods to `Playlist` for filtering items by type: `segments`, `playlists`, `media_items`, `keys`, `maps`, `date_ranges`, `parts`, `session_data`.
+
+***
+
 **1.0.0**
 
 * Full HLS spec compliance with draft-pantos-hls-rfc8216bis-19 (Protocol Version 13).

data/CLAUDE.md

@@ -1 +1 @@
-AGENTS.md
+./AGENTS.md

data/README.md

@@ -2,9 +2,9 @@
 [![CI](https://github.com/sethdeckard/m3u8/actions/workflows/ci.yml/badge.svg)](https://github.com/sethdeckard/m3u8/actions/workflows/ci.yml)
 # m3u8
 
-m3u8 provides easy generation and parsing of m3u8 playlists defined in the [HTTP Live Streaming (HLS)](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis) Internet Draft published by Apple.
+m3u8 provides easy generation and parsing of m3u8 playlists defined in [RFC 8216 HTTP Live Streaming](https://www.rfc-editor.org/rfc/rfc8216) and its proposed successor [draft-pantos-hls-rfc8216bis](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis).
 
-* Full coverage of [draft-pantos-hls-rfc8216bis-19](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-19) (Protocol Version 13), including Low-Latency HLS and Content Steering.
+* Full coverage of [RFC 8216](https://www.rfc-editor.org/rfc/rfc8216) and [draft-pantos-hls-rfc8216bis-19](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-19) (Protocol Version 13), including Low-Latency HLS and Content Steering.
 * Provides parsing of an m3u8 playlist into an object model from any File, StringIO, or string.
 * Provides ability to write playlist to a File or StringIO or expose as string via to_s.
 * Distinction between a master and media playlist is handled automatically (single Playlist class).
@@ -30,6 +30,75 @@ Or install it yourself as:
 
     $ gem install m3u8
 
+## Usage (Builder DSL)
+
+`Playlist.build` provides a block-based DSL for concise playlist construction. It supports two forms:
+
+```ruby
+# instance_eval form (clean DSL)
+playlist = M3u8::Playlist.build(version: 4, target: 12) do
+  segment duration: 11.34, segment: '1080-7mbps00000.ts'
+  segment duration: 11.26, segment: '1080-7mbps00001.ts'
+end
+
+# yielded builder form (access outer scope)
+playlist = M3u8::Playlist.build(version: 4) do |b|
+  files.each { |f| b.segment duration: 10.0, segment: f }
+end
+```
+
+Build a master playlist:
+
+```ruby
+playlist = M3u8::Playlist.build(independent_segments: true) do
+  media type: 'AUDIO', group_id: 'audio', name: 'English',
+        default: true, uri: 'eng/index.m3u8'
+  playlist bandwidth: 5_042_000, width: 1920, height: 1080,
+           profile: 'high', level: 4.1, audio_codec: 'aac-lc',
+           uri: 'hls/1080.m3u8'
+  playlist bandwidth: 2_387_000, width: 1280, height: 720,
+           profile: 'main', level: 3.1, audio_codec: 'aac-lc',
+           uri: 'hls/720.m3u8'
+end
+```
+
+Build a media playlist:
+
+```ruby
+playlist = M3u8::Playlist.build(version: 4, target: 12,
+                                sequence: 1, type: 'VOD') do
+  key method: 'AES-128', uri: 'https://example.com/key.bin'
+  map uri: 'init.mp4'
+  segment duration: 11.34, segment: '00000.ts'
+  discontinuity
+  segment duration: 11.26, segment: '00001.ts'
+end
+```
+
+Build an LL-HLS playlist:
+
+```ruby
+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)
+
+playlist = M3u8::Playlist.build(
+  version: 9, target: 4, sequence: 100,
+  server_control: sc, part_inf: pi, live: true
+) 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
+```
+
+All DSL methods correspond to item classes: `segment`, `playlist`, `media`, `session_data`, `session_key`, `content_steering`, `key`, `map`, `date_range`, `discontinuity`, `gap`, `time`, `bitrate`, `part`, `preload_hint`, `rendition_report`, `skip`, `define`, `playback_start`.
+
 ## Usage (creating playlists)
 
 Create a master playlist and add child playlists for adaptive bitrate streaming:
@@ -75,6 +144,25 @@ item = M3u8::DefineItem.new(name: 'base', value: 'https://example.com')
 playlist.items << item
 ```
 
+Add a session-level encryption key (master playlists):
+
+```ruby
+item = M3u8::SessionKeyItem.new(
+  method: 'AES-128', uri: 'https://example.com/key.bin'
+)
+playlist.items << item
+```
+
+Add session-level data (master playlists):
+
+```ruby
+item = M3u8::SessionDataItem.new(
+  data_id: 'com.example.title', value: 'My Video',
+  language: 'en'
+)
+playlist.items << item
+```
+
 Create a standard playlist and add MPEG-TS segments via SegmentItem:
 
 ```ruby
@@ -85,6 +173,65 @@ item = M3u8::SegmentItem.new(duration: 11, segment: 'test.ts')
 playlist.items << item
 ```
 
+### Media segment tags
+
+Add an encryption key for subsequent segments:
+
+```ruby
+item = M3u8::KeyItem.new(
+  method: 'AES-128',
+  uri: 'https://example.com/key.bin',
+  iv: '0x1234567890abcdef1234567890abcdef'
+)
+playlist.items << item
+```
+
+Specify an initialization segment (e.g. fMP4 header):
+
+```ruby
+item = M3u8::MapItem.new(
+  uri: 'init.mp4', byterange: { length: 812, start: 0 }
+)
+playlist.items << item
+```
+
+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,
+  client_attributes: { 'X-AD-ID' => '"foo"' }
+)
+playlist.items << item
+```
+
+Signal an encoding discontinuity:
+
+```ruby
+playlist.items << M3u8::DiscontinuityItem.new
+```
+
+Attach a program date/time to the next segment:
+
+```ruby
+item = M3u8::TimeItem.new(time: Time.iso8601('2024-06-01T12:00:00Z'))
+playlist.items << item
+```
+
+Mark a gap in segment availability:
+
+```ruby
+playlist.items << M3u8::GapItem.new
+```
+
+Add a bitrate hint for upcoming segments:
+
+```ruby
+item = M3u8::BitrateItem.new(bitrate: 1500)
+playlist.items << item
+```
+
 ### Low-Latency HLS
 
 Create an LL-HLS playlist with server control, partial segments, and preload hints:
@@ -153,11 +300,50 @@ playlist.master?
 # => true
 ```
 
-Access items in playlist:
+Query playlist properties:
+
+```ruby
+playlist.master?
+# => true (contains variant streams)
+playlist.live?
+# => false (master playlists are never live)
+```
+
+For media playlists, `duration` returns total segment duration:
+
+```ruby
+media = M3u8::Playlist.read(
+  File.open('spec/fixtures/event_playlist.m3u8')
+)
+media.live?
+# => false
+media.duration
+# => 17.0 (sum of all segment durations)
+```
+
+Access items and their attributes:
 
 ```ruby
 playlist.items.first
 #  => #<M3u8::PlaylistItem ...>
+
+media.segments.first.duration
+# => 6.0
+media.segments.first.segment
+# => "segment0.mp4"
+```
+
+Convenience methods filter items by type:
+
+```ruby
+playlist.playlists    # => [PlaylistItem, ...]
+playlist.segments     # => [SegmentItem, ...]
+playlist.media_items  # => [MediaItem, ...]
+playlist.keys         # => [KeyItem, ...]
+playlist.maps         # => [MapItem, ...]
+playlist.date_ranges  # => [DateRangeItem, ...]
+playlist.parts        # => [PartItem, ...]
+playlist.session_data # => [SessionDataItem, ...]
 ```
 
 Parse an LL-HLS playlist:
@@ -219,6 +405,7 @@ codecs = M3u8::Playlist.codecs(options)
 * `EXT-X-PLAYLIST-TYPE`
 * `EXT-X-I-FRAMES-ONLY`
 * `EXT-X-ALLOW-CACHE`
+* `EXT-X-ENDLIST`
 
 ### Media segment tags
 * `EXTINF`

data/lib/m3u8/builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Builder provides a block-based DSL for constructing playlists
+  class Builder
+    ITEMS = {
+      segment: 'SegmentItem',
+      playlist: 'PlaylistItem',
+      media: 'MediaItem',
+      session_data: 'SessionDataItem',
+      session_key: 'SessionKeyItem',
+      content_steering: 'ContentSteeringItem',
+      key: 'KeyItem',
+      map: 'MapItem',
+      date_range: 'DateRangeItem',
+      time: 'TimeItem',
+      bitrate: 'BitrateItem',
+      part: 'PartItem',
+      preload_hint: 'PreloadHintItem',
+      rendition_report: 'RenditionReportItem',
+      skip: 'SkipItem',
+      define: 'DefineItem',
+      playback_start: 'PlaybackStart'
+    }.freeze
+
+    ZERO_ARG_ITEMS = {
+      discontinuity: 'DiscontinuityItem',
+      gap: 'GapItem'
+    }.freeze
+
+    def initialize(playlist)
+      @playlist = playlist
+    end
+
+    ITEMS.each do |method_name, class_name|
+      define_method(method_name) do |params = {}|
+        @playlist.items << M3u8.const_get(class_name).new(params)
+      end
+    end
+
+    ZERO_ARG_ITEMS.each do |method_name, class_name|
+      define_method(method_name) do
+        @playlist.items << M3u8.const_get(class_name).new
+      end
+    end
+  end
+end

data/lib/m3u8/playlist.rb

@@ -14,6 +14,17 @@ module M3u8
       @items = []
     end
 
+    def self.build(options = {}, &block)
+      playlist = new(options)
+      builder = Builder.new(playlist)
+      if block.arity == 1
+        yield builder
+      else
+        builder.instance_eval(&block)
+      end
+      playlist
+    end
+
     def self.codecs(options = {})
       item = PlaylistItem.new(options)
       item.codecs
@@ -54,12 +65,40 @@ module M3u8
       true
     end
 
+    def segments
+      items.select { |item| item.is_a?(SegmentItem) }
+    end
+
+    def playlists
+      items.select { |item| item.is_a?(PlaylistItem) }
+    end
+
+    def media_items
+      items.select { |item| item.is_a?(MediaItem) }
+    end
+
+    def keys
+      items.select { |item| item.is_a?(KeyItem) }
+    end
+
+    def maps
+      items.select { |item| item.is_a?(MapItem) }
+    end
+
+    def date_ranges
+      items.select { |item| item.is_a?(DateRangeItem) }
+    end
+
+    def parts
+      items.select { |item| item.is_a?(PartItem) }
+    end
+
+    def session_data
+      items.select { |item| item.is_a?(SessionDataItem) }
+    end
+
     def duration
-      duration = 0.0
-      items.each do |item|
-        duration += item.duration if item.is_a?(M3u8::SegmentItem)
-      end
-      duration
+      segments.sum(&:duration)
     end
 
     private
@@ -92,11 +131,11 @@ module M3u8
     end
 
     def playlist_size
-      items.count { |item| item.is_a?(PlaylistItem) }
+      playlists.size
     end
 
     def segment_size
-      items.count { |item| item.is_a?(SegmentItem) }
+      segments.size
     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.0.0'
+  VERSION = '1.2.0'
 end

data/spec/lib/m3u8/builder_spec.rb

@@ -0,0 +1,338 @@
+# 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 '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

data/spec/lib/m3u8/playlist_spec.rb

@@ -236,6 +236,80 @@ describe M3u8::Playlist do
     end
   end
 
+  describe '#segments' do
+    it 'returns only segment items' do
+      file = File.open('spec/fixtures/playlist.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.segments).to all be_a(M3u8::SegmentItem)
+      expect(playlist.segments.size).to eq(138)
+    end
+  end
+
+  describe '#playlists' do
+    it 'returns only playlist items' do
+      file = File.open('spec/fixtures/master.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.playlists).to all be_a(M3u8::PlaylistItem)
+      expect(playlist.playlists.size).to eq(6)
+    end
+  end
+
+  describe '#media_items' do
+    it 'returns only media items' do
+      file = File.open('spec/fixtures/variant_audio.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.media_items).to all be_a(M3u8::MediaItem)
+      expect(playlist.media_items.size).to eq(6)
+    end
+  end
+
+  describe '#keys' do
+    it 'returns only key items' do
+      file = File.open('spec/fixtures/encrypted.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.keys).to all be_a(M3u8::KeyItem)
+      expect(playlist.keys.size).to eq(2)
+    end
+  end
+
+  describe '#maps' do
+    it 'returns only map items' do
+      file = File.open('spec/fixtures/map_playlist.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.maps).to all be_a(M3u8::MapItem)
+      expect(playlist.maps.size).to eq(1)
+    end
+  end
+
+  describe '#date_ranges' do
+    it 'returns only date range items' do
+      file = File.open('spec/fixtures/daterange_playlist.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.date_ranges)
+        .to all be_a(M3u8::DateRangeItem)
+      expect(playlist.date_ranges.size).to eq(3)
+    end
+  end
+
+  describe '#parts' do
+    it 'returns only part items' do
+      file = File.open('spec/fixtures/ll_hls_playlist.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.parts).to all be_a(M3u8::PartItem)
+      expect(playlist.parts.size).to eq(5)
+    end
+  end
+
+  describe '#session_data' do
+    it 'returns only session data items' do
+      file = File.open('spec/fixtures/session_data.m3u8')
+      playlist = described_class.read(file)
+      expect(playlist.session_data)
+        .to all be_a(M3u8::SessionDataItem)
+      expect(playlist.session_data.size).to eq(3)
+    end
+  end
+
   describe '#write' do
     context 'when playlist is valid' do
       it 'returns playlist text' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Seth Deckard
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-02-07 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -144,6 +144,7 @@ files:
 - Rakefile
 - lib/m3u8.rb
 - lib/m3u8/bitrate_item.rb
+- lib/m3u8/builder.rb
 - lib/m3u8/byte_range.rb
 - lib/m3u8/content_steering_item.rb
 - lib/m3u8/date_range_item.rb
@@ -194,6 +195,7 @@ files:
 - spec/fixtures/variant_angles.m3u8
 - spec/fixtures/variant_audio.m3u8
 - spec/lib/m3u8/bitrate_item_spec.rb
+- spec/lib/m3u8/builder_spec.rb
 - spec/lib/m3u8/byte_range_spec.rb
 - spec/lib/m3u8/content_steering_item_spec.rb
 - spec/lib/m3u8/date_range_item_spec.rb
@@ -225,7 +227,7 @@ homepage: https://github.com/sethdeckard/m3u8
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -240,8 +242,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).
 test_files: []