m3u8 1.3.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7112d267f1f0b5e6f89f4c5b54392b02dc3d37d39d9cbda88d2125b69b89ca37
-  data.tar.gz: 6755f10b8de1fbb8d06f881b29973623fa48e53347b54f3093c37ff794817090
+  metadata.gz: df37c1a4cc89e0bd918c6137c5bc86682d61638b407697240e76f40acb8983e7
+  data.tar.gz: e19fd10c1b3f732057285247f08bb235573fa6434085295b53a76be22f1a53aa
 SHA512:
-  metadata.gz: 635a0727ca10232fd961568d72210bbf96ed1a52c64ed0326a98f275ed1948f2d6016abd1edc774972365f459508e92bd0048e5fa511e4864683d196a2eaddbe
-  data.tar.gz: 6afceffd0ce2b396737e1963ce89b7d1e31177d12d1226c4f705feff4e3625110de05fb108973eac0203566e018f9aa8ac470a0825ee7c581b86753687320009
+  metadata.gz: c4ff8a727525925718fcb0ff7fed0b8bb758556d8e262c97ebacaca4fe96550b4494817ce5d8f4a0525d961a274a1905b16af6b5a85b8ac57235254f54392f8a
+  data.tar.gz: 19ae07aa8cd202846254983b823973c4b7d0a9d4bde50e5cc8be7e1e4d91182205bec84731f628298f2659085434716120135a074656e1c9c2aa2c1988415b4f

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+**1.5.0**
+
+* Added `Playlist#freeze` for deep-freezing playlists, items, nested objects, and playlist-level objects. `Playlist.build` and `Playlist.read` now return frozen playlists. `Playlist.new` remains mutable until `freeze` is called explicitly.
+
+***
+
+**1.4.0**
+
+* Added `Playlist#errors` method returning an array of validation error messages. `Playlist#valid?` now delegates to `errors.empty?`. Validates mixed item types, target duration, segment items, playlist items, media items, encryption keys, session keys, session data, and LL-HLS part items.
+* Updated CLI `validate` command to display specific error messages.
+* Updated `Writer` to include specific errors in the exception message.
+
+***
+
 **1.3.1**
 
 * Excluded CLAUDE.md and AGENTS.md from gem package.

data/README.md

@@ -79,7 +79,8 @@ $ m3u8 validate playlist.m3u8
 Valid
 
 $ m3u8 validate bad.m3u8
-Invalid: mixed playlist and segment items
+Invalid
+  - Playlist contains both master and media items
 ```
 
 ## Usage (Builder DSL)
@@ -343,6 +344,62 @@ options = { width: 1920, height: 1080, codecs: 'avc1.66.30,mp4a.40.2',
 item = M3u8::PlaylistItem.new(options)
 ```
 
+## Frozen playlists
+
+Playlists returned by `Playlist.build` and `Playlist.read` are frozen (deeply immutable). Items, nested objects, and the items array are all frozen, preventing accidental mutation after construction:
+
+```ruby
+playlist = M3u8::Playlist.read(File.open('master.m3u8'))
+playlist.frozen?          # => true
+playlist.items.frozen?    # => true
+playlist.items.first.frozen? # => true
+```
+
+Playlists created with `Playlist.new` remain mutable. Call `freeze` explicitly when ready:
+
+```ruby
+playlist = M3u8::Playlist.new
+playlist.items << M3u8::SegmentItem.new(duration: 10.0, segment: 'test.ts')
+playlist.freeze
+```
+
+Frozen playlists still support `to_s` and `write` for output.
+
+## Validation
+
+Check whether a playlist is valid and inspect specific errors:
+
+```ruby
+playlist.valid?
+# => true
+
+playlist.errors
+# => []
+```
+
+When a playlist has issues, `errors` returns descriptive messages:
+
+```ruby
+playlist.valid?
+# => false
+
+playlist.errors
+# => ["Playlist contains both master and media items"]
+```
+
+The following validations are performed:
+
+* Mixed item types (both master and media items in one playlist)
+* Target duration less than any segment's rounded duration
+* Segment items missing a URI or having a negative duration
+* Playlist items missing a URI or valid bandwidth
+* Media items missing type, group ID, or name
+* Key and session key items missing a URI when method is not NONE
+* Session data items missing data ID, or having both/neither value and URI
+* Part items missing a URI or duration
+
+`valid?` delegates to `errors.empty?` and both are recomputed on each call.
+
 ## Usage (parsing playlists)
 
 ```ruby

data/lib/m3u8/cli/validate_command.rb

@@ -14,7 +14,8 @@ module M3u8
           @stdout.puts 'Valid'
           0
         else
-          @stdout.puts 'Invalid: mixed playlist and segment items'
+          @stdout.puts 'Invalid'
+          @playlist.errors.each { |e| @stdout.puts "  - #{e}" }
           1
         end
       end

data/lib/m3u8/playlist.rb

@@ -22,7 +22,7 @@ module M3u8
       else
         builder.instance_eval(&block)
       end
-      playlist
+      playlist.freeze
     end
 
     def self.codecs(options = {})
@@ -53,16 +53,36 @@ module M3u8
       playlist_size.positive?
     end
 
+    def freeze
+      items.each { |item| freeze_item(item) }
+      items.freeze
+      part_inf&.freeze
+      server_control&.freeze
+      super
+    end
+
     def to_s
       output = StringIO.open
       write(output)
       output.string
     end
 
-    def valid?
-      return false if playlist_size.positive? && segment_size.positive?
+    def errors
+      [].tap do |errors|
+        validate_mixed_items(errors)
+        validate_target_duration(errors)
+        validate_segment_items(errors)
+        validate_playlist_items(errors)
+        validate_media_items(errors)
+        validate_key_items(errors)
+        validate_session_key_items(errors)
+        validate_session_data_items(errors)
+        validate_part_items(errors)
+      end
+    end
 
-      true
+    def valid?
+      errors.empty?
     end
 
     def segments
@@ -107,6 +127,13 @@ module M3u8
 
     private
 
+    def freeze_item(item)
+      item.byterange&.freeze if item.respond_to?(:byterange)
+      item.program_date_time&.freeze if item.respond_to?(:program_date_time)
+      item.client_attributes&.freeze if item.respond_to?(:client_attributes)
+      item.freeze
+    end
+
     def assign_options(options)
       options = defaults.merge(options)
 
@@ -134,6 +161,78 @@ module M3u8
       }
     end
 
+    def validate_part_items(errors)
+      parts.each do |item|
+        errors << 'Part item requires a URI' if item.uri.nil?
+        errors << 'Part item requires a duration' if item.duration.nil?
+      end
+    end
+
+    def validate_session_data_items(errors)
+      session_data.each do |item|
+        errors << 'Session data item requires a data ID' if item.data_id.nil?
+        if !item.value.nil? && !item.uri.nil?
+          errors << 'Session data item cannot have both value and URI'
+        elsif item.value.nil? && item.uri.nil?
+          errors << 'Session data item requires a value or URI'
+        end
+      end
+    end
+
+    def validate_key_items(errors)
+      keys.each do |item|
+        next if item.method == 'NONE'
+
+        errors << 'Key item requires a URI when method is not NONE' if item.uri.nil?
+      end
+    end
+
+    def validate_session_key_items(errors)
+      session_keys.each do |item|
+        next if item.method == 'NONE'
+
+        errors << 'Session key item requires a URI when method is not NONE' if item.uri.nil?
+      end
+    end
+
+    def validate_playlist_items(errors)
+      playlists.each do |item|
+        errors << 'Playlist item requires a bandwidth' unless item.bandwidth&.positive?
+        errors << 'Playlist item requires a URI' if item.uri.nil?
+      end
+    end
+
+    def validate_media_items(errors)
+      media_items.each do |item|
+        errors << 'Media item requires a type' if item.type.nil?
+        errors << 'Media item requires a group ID' if item.group_id.nil?
+        errors << 'Media item requires a name' if item.name.nil?
+      end
+    end
+
+    def validate_segment_items(errors)
+      segments.each do |segment|
+        errors << 'Segment item requires a segment URI' if segment.segment.nil?
+        errors << 'Segment item has negative duration' if segment.duration&.negative?
+      end
+    end
+
+    def validate_target_duration(errors)
+      return if master?
+
+      max = segments.filter_map { |s| s.duration&.round }.max
+      return if max.nil? || target >= max
+
+      errors << "Target duration #{target} is less than " \
+                "segment duration of #{max}"
+    end
+
+    def validate_mixed_items(errors)
+      return unless playlist_size.positive? && segment_size.positive?
+
+      errors << 'Playlist contains both master and media items'
+    end
+
     def playlist_size
       playlists.size
     end

data/lib/m3u8/playlist_item.rb

@@ -69,7 +69,7 @@ module M3u8
         codecs: attributes['CODECS'],
         width: resolution[:width],
         height: resolution[:height],
-        bandwidth: attributes['BANDWIDTH'].to_i,
+        bandwidth: parse_bandwidth(attributes['BANDWIDTH']),
         average_bandwidth:
           parse_average_bandwidth(attributes['AVERAGE-BANDWIDTH']),
         frame_rate: parse_frame_rate(attributes['FRAME-RATE']),
@@ -90,6 +90,12 @@ module M3u8
       value&.to_i
     end
 
+    def parse_bandwidth(value)
+      return if value.nil?
+
+      value.to_i
+    end
+
     def parse_resolution(resolution)
       return { width: nil, height: nil } if resolution.nil?
 

data/lib/m3u8/reader.rb

@@ -25,7 +25,7 @@ module M3u8
         parse_line(line)
       end
       playlist.live = !@has_endlist unless master
-      playlist
+      playlist.freeze
     end
 
     private

data/lib/m3u8/version.rb

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

data/lib/m3u8/writer.rb

@@ -44,7 +44,8 @@ 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)

data/spec/lib/m3u8/builder_spec.rb

@@ -191,6 +191,20 @@ describe M3u8::Builder do
       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|

data/spec/lib/m3u8/cli/validate_command_spec.rb

@@ -18,7 +18,7 @@ describe M3u8::CLI::ValidateCommand do
     end
 
     context 'when playlist is invalid' do
-      it 'prints Invalid and returns 1' do
+      it 'prints Invalid with specific errors and returns 1' do
         playlist = M3u8::Playlist.new
         playlist.items << M3u8::PlaylistItem.new(
           bandwidth: 540, uri: 'test.url'
@@ -28,7 +28,11 @@ describe M3u8::CLI::ValidateCommand do
         )
         code = described_class.new(playlist, stdout).run
         expect(code).to eq(1)
-        expect(stdout.string.strip).to include('Invalid')
+        lines = stdout.string.split("\n")
+        expect(lines[0]).to eq('Invalid')
+        expect(lines[1]).to eq(
+          '  - Playlist contains both master and media items'
+        )
       end
     end
   end

data/spec/lib/m3u8/playlist_item_spec.rb

@@ -94,6 +94,12 @@ describe M3u8::PlaylistItem do
       expect(item.supplemental_codecs).to eq('dvh1.05.06/db4g')
       expect(item.req_video_layout).to eq('CH-MONO')
     end
+
+    it 'keeps bandwidth nil when BANDWIDTH is missing' do
+      input = '#EXT-X-STREAM-INF:CODECS="avc",URI="test.url"'
+      item = M3u8::PlaylistItem.parse(input)
+      expect(item.bandwidth).to be_nil
+    end
   end
 
   describe '#to_s' do

data/spec/lib/m3u8/playlist_spec.rb

@@ -182,6 +182,7 @@ describe M3u8::Playlist do
     end
 
     it 'returns media playlist text' do
+      playlist = described_class.new(target: 12)
       options = { duration: 11.344644, segment: '1080-7mbps00000.ts' }
       item =  M3u8::SegmentItem.new(options)
       playlist.items << item
@@ -192,7 +193,7 @@ describe M3u8::Playlist do
 
       expected = "#EXTM3U\n" \
                  "#EXT-X-MEDIA-SEQUENCE:0\n" \
-                 "#EXT-X-TARGETDURATION:10\n" \
+                 "#EXT-X-TARGETDURATION:12\n" \
                  "#EXTINF:11.344644,\n" \
                  "1080-7mbps00000.ts\n" \
                  "#EXTINF:11.261233,\n" \
@@ -237,6 +238,329 @@ describe M3u8::Playlist do
     end
   end
 
+  describe '#errors' do
+    context 'when playlist is empty' do
+      it 'returns no errors' do
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when playlist has only master items' do
+      it 'returns no errors' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when playlist has only media items' do
+      it 'returns no errors' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.0, segment: 'test.ts'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when segment duration exceeds target duration' do
+      it 'returns target duration error' do
+        playlist = described_class.new(target: 10)
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 12.1, segment: 'test.ts'
+        )
+        expect(playlist.errors).to include(
+          'Target duration 10 is less than segment duration of 12'
+        )
+      end
+    end
+
+    context 'when segment duration rounds to target' do
+      it 'returns no errors' do
+        playlist = described_class.new(target: 11)
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.5, segment: 'test.ts'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when playlist is master' do
+      it 'skips target duration check' do
+        playlist = described_class.new(master: true)
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when segment has no URI' do
+      it 'returns missing segment error' do
+        playlist.items << M3u8::SegmentItem.new(duration: 10.0)
+        expect(playlist.errors).to include(
+          'Segment item requires a segment URI'
+        )
+      end
+    end
+
+    context 'when segment has negative duration' do
+      it 'returns negative duration error' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: -1.0, segment: 'test.ts'
+        )
+        expect(playlist.errors).to include(
+          'Segment item has negative duration'
+        )
+      end
+    end
+
+    context 'when segment has zero duration' do
+      it 'returns no errors' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 0.0, segment: 'test.ts'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when multiple segments are invalid' do
+      it 'accumulates errors' do
+        playlist.items << M3u8::SegmentItem.new(duration: 10.0)
+        playlist.items << M3u8::SegmentItem.new(
+          duration: -1.0, segment: 'test.ts'
+        )
+        errors = playlist.errors
+        expect(errors).to include(
+          'Segment item requires a segment URI'
+        )
+        expect(errors).to include(
+          'Segment item has negative duration'
+        )
+      end
+    end
+
+    context 'when playlist item has no bandwidth' do
+      it 'returns missing bandwidth error' do
+        playlist.items << M3u8::PlaylistItem.new(uri: 'test.url')
+        expect(playlist.errors).to include(
+          'Playlist item requires a bandwidth'
+        )
+      end
+    end
+
+    context 'when playlist item has no URI and is not iframe' do
+      it 'returns missing URI error' do
+        playlist.items << M3u8::PlaylistItem.new(bandwidth: 540)
+        expect(playlist.errors).to include(
+          'Playlist item requires a URI'
+        )
+      end
+    end
+
+    context 'when playlist item has zero bandwidth' do
+      it 'returns missing bandwidth error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 0, uri: 'test.url'
+        )
+        expect(playlist.errors).to include(
+          'Playlist item requires a bandwidth'
+        )
+      end
+    end
+
+    context 'when iframe playlist item has no URI' do
+      it 'returns missing URI error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, iframe: true
+        )
+        expect(playlist.errors).to include(
+          'Playlist item requires a URI'
+        )
+      end
+    end
+
+    context 'when media item is missing type' do
+      it 'returns missing type error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::MediaItem.new(
+          group_id: 'audio', name: 'English'
+        )
+        expect(playlist.errors).to include(
+          'Media item requires a type'
+        )
+      end
+    end
+
+    context 'when media item is missing group_id' do
+      it 'returns missing group_id error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::MediaItem.new(
+          type: 'AUDIO', name: 'English'
+        )
+        expect(playlist.errors).to include(
+          'Media item requires a group ID'
+        )
+      end
+    end
+
+    context 'when media item is missing name' do
+      it 'returns missing name error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::MediaItem.new(
+          type: 'AUDIO', group_id: 'audio'
+        )
+        expect(playlist.errors).to include(
+          'Media item requires a name'
+        )
+      end
+    end
+
+    context 'when key item has method but no URI' do
+      it 'returns missing URI error' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.0, segment: 'test.ts'
+        )
+        playlist.items << M3u8::KeyItem.new(method: 'AES-128')
+        expect(playlist.errors).to include(
+          'Key item requires a URI when method is not NONE'
+        )
+      end
+    end
+
+    context 'when key item method is NONE' do
+      it 'returns no errors' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.0, segment: 'test.ts'
+        )
+        playlist.items << M3u8::KeyItem.new(method: 'NONE')
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when session key item has method but no URI' do
+      it 'returns missing URI error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SessionKeyItem.new(
+          method: 'AES-128'
+        )
+        expect(playlist.errors).to include(
+          'Session key item requires a URI when method is not NONE'
+        )
+      end
+    end
+
+    context 'when session data item has no data_id' do
+      it 'returns missing data_id error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SessionDataItem.new(
+          value: 'Test'
+        )
+        expect(playlist.errors).to include(
+          'Session data item requires a data ID'
+        )
+      end
+    end
+
+    context 'when session data item has both value and uri' do
+      it 'returns conflict error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SessionDataItem.new(
+          data_id: 'com.test', value: 'Test',
+          uri: 'http://test'
+        )
+        expect(playlist.errors).to include(
+          'Session data item cannot have both value and URI'
+        )
+      end
+    end
+
+    context 'when session data item has neither value nor uri' do
+      it 'returns missing value error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SessionDataItem.new(
+          data_id: 'com.test'
+        )
+        expect(playlist.errors).to include(
+          'Session data item requires a value or URI'
+        )
+      end
+    end
+
+    context 'when session data item has only value' do
+      it 'returns no session data errors' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SessionDataItem.new(
+          data_id: 'com.test', value: 'Test'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when part item has no URI' do
+      it 'returns missing URI error' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 4.0, segment: 'seg.mp4'
+        )
+        playlist.items << M3u8::PartItem.new(duration: 0.5)
+        expect(playlist.errors).to include(
+          'Part item requires a URI'
+        )
+      end
+    end
+
+    context 'when part item has no duration' do
+      it 'returns missing duration error' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 4.0, segment: 'seg.mp4'
+        )
+        playlist.items << M3u8::PartItem.new(uri: 'seg.0.mp4')
+        expect(playlist.errors).to include(
+          'Part item requires a duration'
+        )
+      end
+    end
+
+    context 'when part item is valid' do
+      it 'returns no part errors' do
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 4.0, segment: 'seg.mp4'
+        )
+        playlist.items << M3u8::PartItem.new(
+          duration: 0.5, uri: 'seg.0.mp4'
+        )
+        expect(playlist.errors).to be_empty
+      end
+    end
+
+    context 'when playlist has mixed items' do
+      it 'returns mixed items error' do
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.0, segment: 'test.ts'
+        )
+        expect(playlist.errors).to include(
+          'Playlist contains both master and media items'
+        )
+      end
+    end
+  end
+
   describe '#segments' do
     it 'returns only segment items' do
       playlist = described_class.read(
@@ -330,6 +654,108 @@ describe M3u8::Playlist do
     end
   end
 
+  describe '#freeze' do
+    it 'freezes the playlist' do
+      playlist.freeze
+      expect(playlist).to be_frozen
+    end
+
+    it 'freezes the items array' do
+      playlist.freeze
+      expect(playlist.items).to be_frozen
+    end
+
+    it 'freezes each item' do
+      item = M3u8::SegmentItem.new(duration: 10.0, segment: 'test.ts')
+      playlist.items << item
+      playlist.freeze
+      expect(item).to be_frozen
+    end
+
+    it 'freezes nested byterange on items' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts',
+        byterange: { length: 4500, start: 600 }
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.byterange).to be_frozen
+    end
+
+    it 'freezes nested program_date_time on items' do
+      time = M3u8::TimeItem.new(time: '2024-06-01T12:00:00Z')
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts',
+        program_date_time: time
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.program_date_time).to be_frozen
+    end
+
+    it 'freezes nested client_attributes on items' do
+      item = M3u8::DateRangeItem.new(
+        id: 'ad-1', start_date: '2024-01-01T00:00:00Z',
+        client_attributes: { 'X-AD-ID' => '"foo"' }
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.client_attributes).to be_frozen
+    end
+
+    it 'freezes part_inf' do
+      playlist.part_inf = M3u8::PartInfItem.new(part_target: 0.5)
+      playlist.freeze
+      expect(playlist.part_inf).to be_frozen
+    end
+
+    it 'freezes server_control' do
+      playlist.server_control = M3u8::ServerControlItem.new(
+        can_skip_until: 24.0
+      )
+      playlist.freeze
+      expect(playlist.server_control).to be_frozen
+    end
+
+    it 'raises FrozenError on attribute set' do
+      playlist.freeze
+      expect { playlist.version = 7 }
+        .to raise_error(FrozenError)
+    end
+
+    it 'raises FrozenError on items append' do
+      playlist.freeze
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      expect { playlist.items << item }
+        .to raise_error(FrozenError)
+    end
+
+    it 'raises FrozenError on item mutation' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      playlist.items << item
+      playlist.freeze
+      expect { item.duration = 5.0 }
+        .to raise_error(FrozenError)
+    end
+
+    it 'still supports to_s' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(playlist.to_s).to include('#EXTM3U')
+    end
+
+    it 'returns self' do
+      expect(playlist.freeze).to equal(playlist)
+    end
+  end
+
   describe '#write' do
     context 'when playlist is valid' do
       it 'returns playlist text' do
@@ -356,7 +782,8 @@ describe M3u8::Playlist do
         item = M3u8::SegmentItem.new(options)
         playlist.items << item
 
-        message = 'Playlist is invalid.'
+        message = 'Playlist is invalid: Playlist contains both ' \
+                  'master and media items'
         io = StringIO.new
         expect { playlist.write(io) }
           .to raise_error(M3u8::PlaylistTypeError, message)

data/spec/lib/m3u8/reader_spec.rb

@@ -590,6 +590,20 @@ describe M3u8::Reader do
       expect(item.segment).to eq('segment0.ts')
     end
 
+    it 'returns a frozen master playlist' do
+      playlist = reader.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
+      expect(playlist).to be_frozen
+    end
+
+    it 'returns a frozen media playlist' do
+      playlist = reader.read(
+        File.read('spec/fixtures/playlist.m3u8')
+      )
+      expect(playlist).to be_frozen
+    end
+
     context 'when playlist source is invalid' do
       it 'raises error with message' do
         message = 'Playlist must start with a #EXTM3U tag, line read ' \

data/spec/lib/m3u8/writer_spec.rb

@@ -17,7 +17,7 @@ describe M3u8::Writer do
         item = M3u8::PlaylistItem.new(options)
         playlist.items << item
         options = { data_id: 'com.test.movie.title', value: 'Test',
-                    uri: 'http://test', language: 'en' }
+                    language: 'en' }
         item = M3u8::SessionDataItem.new(options)
         playlist.items << item
 
@@ -28,7 +28,7 @@ describe M3u8::Writer do
                    %(RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2") +
                    ",BANDWIDTH=50000\nplaylist_url\n" +
                    %(#EXT-X-SESSION-DATA:DATA-ID="com.test.movie.title",) +
-                   %(VALUE="Test",URI="http://test",LANGUAGE="en"\n)
+                   %(VALUE="Test",LANGUAGE="en"\n)
 
         io = StringIO.open
         writer = described_class.new(io)
@@ -101,7 +101,7 @@ describe M3u8::Writer do
 
     context 'when playlist is a media playlist' do
       it 'writes playlist to io' do
-        options = { version: 4, cache: false, target: 6.2, sequence: 1,
+        options = { version: 4, cache: false, target: 12, sequence: 1,
                     discontinuity_sequence: 10, type: 'EVENT',
                     iframes_only: true }
         playlist = M3u8::Playlist.new(options)
@@ -116,7 +116,7 @@ describe M3u8::Writer do
                    "#EXT-X-MEDIA-SEQUENCE:1\n" \
                    "#EXT-X-DISCONTINUITY-SEQUENCE:10\n" \
                    "#EXT-X-ALLOW-CACHE:NO\n" \
-                   "#EXT-X-TARGETDURATION:6\n" \
+                   "#EXT-X-TARGETDURATION:12\n" \
                    "#EXTINF:11.344644,\n" \
                    "1080-7mbps00000.ts\n" \
                    "#EXT-X-ENDLIST\n"
@@ -132,7 +132,7 @@ describe M3u8::Writer do
       it 'writes playlist to io' do
         options = { duration: 11.344644, segment: '1080-7mbps00000.ts' }
         item =  M3u8::SegmentItem.new(options)
-        playlist = M3u8::Playlist.new(version: 7)
+        playlist = M3u8::Playlist.new(version: 7, target: 12)
         playlist.items << item
 
         options = { method: 'AES-128', uri: 'http://test.key',
@@ -148,7 +148,7 @@ describe M3u8::Writer do
         expected = "#EXTM3U\n" \
                    "#EXT-X-VERSION:7\n" \
                    "#EXT-X-MEDIA-SEQUENCE:0\n" \
-                   "#EXT-X-TARGETDURATION:10\n" \
+                   "#EXT-X-TARGETDURATION:12\n" \
                    "#EXTINF:11.344644,\n" \
                    "1080-7mbps00000.ts\n" +
                    %(#EXT-X-KEY:METHOD=AES-128,URI="http://test.key",) +
@@ -204,10 +204,10 @@ describe M3u8::Writer do
       end
     end
 
-    it 'raises error if item types are mixed' do
+    it 'raises error with specific messages if item types are mixed' do
       playlist = M3u8::Playlist.new
-      options = { program_id: 1, width: 1920, height: 1080, codecs: 'avc',
-                  bandwidth: 540, playlist: 'test.url' }
+      options = { program_id: 1, width: 1920, height: 1080,
+                  codecs: 'avc', bandwidth: 540, uri: 'test.url' }
       item = M3u8::PlaylistItem.new(options)
       playlist.items << item
 
@@ -215,7 +215,8 @@ describe M3u8::Writer do
       item = M3u8::SegmentItem.new(options)
       playlist.items << item
 
-      message = 'Playlist is invalid.'
+      message = 'Playlist is invalid: Playlist contains both ' \
+                'master and media items'
       io = StringIO.new
       writer = described_class.new(io)
       expect { writer.write(playlist) }

metadata

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