m3u8 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac7ba85dc1681fda7ba574fd13afc5a2a644726beb03cd10d80862a62d996a76
-  data.tar.gz: 8ec9e60e8ca0a7c81f4fdea78aae937bde641d37baa6984aef90da1c97f6c068
+  metadata.gz: 7a9a7d6e157afd5fd7028323544bf9d851bd898890f90c66af6f64e672d7e456
+  data.tar.gz: ee452e25dfb96ee9634e9a00c287a87ac4640dceb2d965550e31199e0c0b4e26
 SHA512:
-  metadata.gz: ede5d1bfd13f64815f5777485bd1a744ce0e13cecf0b51c9d657b7c2890b34f69e70dfba66f707b66007ca176308d99dba14f7a259dfdab2553e2f35e1199bba
-  data.tar.gz: fb035f0a70f3f675d1c53b5ef46af63e4dd0fc88dad66666b0010eb66210b48eb7ad3b0748a81f55d8b95f0a8af1fb4492a0467bd8f0469fce5ef93b9cdb2b10
+  metadata.gz: f6b458aaf9a1a1060d19dca456020b54813f0c1f011615593e088a512a87ed32120cd5d509fb66dd3b12f85fe11a255304eede7852a00197cfd9513c918a33eb
+  data.tar.gz: 7c543fd8e6004adaf275adfe95c231b42fe0549805436f8dea3e77f2731f273084c99887781d0b69daf05ec1e53218fb8711be895fc0c14e9f0687f983a611b1

data/CHANGELOG.md

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

data/CLAUDE.md

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

data/README.md

@@ -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:

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

data/lib/m3u8/version.rb

@@ -2,5 +2,5 @@
 
 # M3u8 provides parsing, generation, and validation of m3u8 playlists
 module M3u8
-  VERSION = '1.1.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.1.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: []