m3u8 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2be533f088c62f6247e71b571a4481c92e56f8d575511ecae16be472dd90006a
-  data.tar.gz: 3d6de6bef331beefea33a156f6129dbcb30c89b195d807440acd740b53027a1b
+  metadata.gz: ac7ba85dc1681fda7ba574fd13afc5a2a644726beb03cd10d80862a62d996a76
+  data.tar.gz: 8ec9e60e8ca0a7c81f4fdea78aae937bde641d37baa6984aef90da1c97f6c068
 SHA512:
-  metadata.gz: edd32a67f619c6fd6b234163cbd16837cd92100f9d84f3729dd1ab09d6fdb1467f8cdab9e89cf64db344d4bb4359620c7aaad3d8532cb33195734a8c22833874
-  data.tar.gz: c24310d02ff3f844640618cf73fba927fd06bdf2f24e0c20d65166b459092f605d59f1ad408853342c3196e3eceed9535ef08a71c7c75bed8024d5f6383d2f8e
+  metadata.gz: ede5d1bfd13f64815f5777485bd1a744ce0e13cecf0b51c9d657b7c2890b34f69e70dfba66f707b66007ca176308d99dba14f7a259dfdab2553e2f35e1199bba
+  data.tar.gz: fb035f0a70f3f675d1c53b5ef46af63e4dd0fc88dad66666b0010eb66210b48eb7ad3b0748a81f55d8b95f0a8af1fb4492a0467bd8f0469fce5ef93b9cdb2b10

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,9 @@
+**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/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).
@@ -75,6 +75,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 +104,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 +231,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 +336,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/playlist.rb

@@ -54,12 +54,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 +120,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.1.0'
 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Seth Deckard