m3u8 1.8.0 → 1.9.0

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

@@ -13,7 +13,7 @@ describe M3u8::CLI::ValidateCommand do
         )
         code = described_class.new(playlist, stdout).run
         expect(code).to eq(0)
-        expect(stdout.string.strip).to eq('Valid')
+        expect(stdout.string).to start_with('Valid')
       end
     end
 
@@ -35,5 +35,21 @@ describe M3u8::CLI::ValidateCommand do
         )
       end
     end
+
+    context 'when playlist has warnings' do
+      it 'prints warnings after the validity result' do
+        playlist = M3u8::Playlist.read(
+          File.read('spec/fixtures/map_playlist.m3u8')
+        )
+        code = described_class.new(playlist, stdout).run
+        expect(code).to eq(0)
+        lines = stdout.string.split("\n")
+        expect(lines).to include('Valid')
+        expect(lines).to include('Warnings:')
+        expect(lines).to include(
+          '  - EXT-X-MAP requires version 6 (version 5)'
+        )
+      end
+    end
   end
 end

data/spec/lib/m3u8/cli_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'json'
 
 describe M3u8::CLI do
   let(:stdout) { StringIO.new }
@@ -24,6 +25,7 @@ describe M3u8::CLI do
       expect(stdout.string).to include('Usage: m3u8')
       expect(stdout.string).to include('inspect')
       expect(stdout.string).to include('validate')
+      expect(stdout.string).to include('diff')
     end
   end
 
@@ -64,7 +66,7 @@ describe M3u8::CLI do
     it 'reads a playlist from a file for validate' do
       code = run(['validate', 'spec/fixtures/master.m3u8'])
       expect(code).to eq(0)
-      expect(stdout.string.strip).to eq('Valid')
+      expect(stdout.string).to start_with('Valid')
     end
   end
 
@@ -79,6 +81,50 @@ describe M3u8::CLI do
     end
   end
 
+  describe 'inspect --json' do
+    it 'prints the playlist as JSON and exits 0' do
+      code = run(['inspect', '--json', 'spec/fixtures/master.m3u8'])
+      expect(code).to eq(0)
+      expect(JSON.parse(stdout.string)['master']).to be(true)
+    end
+  end
+
+  describe 'validate --json' do
+    it 'rejects the flag and exits 2' do
+      code = run(['validate', '--json', 'spec/fixtures/master.m3u8'])
+      expect(code).to eq(2)
+      expect(stderr.string).to include('--json is only supported for inspect')
+    end
+  end
+
+  describe 'diff' do
+    it 'reports identical playlists and exits 0' do
+      code = run(['diff', 'spec/fixtures/master.m3u8',
+                  'spec/fixtures/master.m3u8'])
+      expect(code).to eq(0)
+      expect(stdout.string.strip).to eq('Identical')
+    end
+
+    it 'reports differences and exits 1' do
+      code = run(['diff', 'spec/fixtures/playlist.m3u8',
+                  'spec/fixtures/event_playlist.m3u8'])
+      expect(code).to eq(1)
+      expect(stdout.string).to include('=>')
+    end
+
+    it 'requires two files and exits 2' do
+      code = run(['diff', 'spec/fixtures/master.m3u8'])
+      expect(code).to eq(2)
+      expect(stderr.string).to include('diff requires two files')
+    end
+
+    it 'reports a missing file and exits 2' do
+      code = run(['diff', 'spec/fixtures/master.m3u8', 'nope.m3u8'])
+      expect(code).to eq(2)
+      expect(stderr.string).to include('no such file')
+    end
+  end
+
   describe 'stdin input' do
     it 'reads a playlist from stdin' do
       content = File.read('spec/fixtures/master.m3u8')

data/spec/lib/m3u8/conformance_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'M3u8::Playlist#warnings' do
+  def low_latency(part_target:, hold_back:, skip_until: nil, target: 10)
+    playlist = M3u8::Playlist.new(version: 9, target: target)
+    playlist.part_inf = M3u8::PartInfItem.new(part_target: part_target)
+    playlist.server_control = M3u8::ServerControlItem.new(
+      part_hold_back: hold_back, can_skip_until: skip_until
+    )
+    playlist
+  end
+
+  context 'version compatibility' do
+    it 'warns when a feature requires a higher version' do
+      playlist = M3u8::Playlist.read(
+        File.read('spec/fixtures/map_playlist.m3u8')
+      )
+      expect(playlist.warnings)
+        .to include('EXT-X-MAP requires version 6 (version 5)')
+    end
+
+    it 'warns about floating-point EXTINF below version 3' do
+      playlist = M3u8::Playlist.new(version: 1, target: 10)
+      playlist.items << M3u8::SegmentItem.new(duration: 4.0, segment: 'a.ts')
+      expect(playlist.warnings)
+        .to include('floating-point EXTINF requires version 3 (version 1)')
+    end
+
+    it 'does not warn about integer EXTINF durations' do
+      playlist = M3u8::Playlist.new(version: 1, target: 10)
+      playlist.items << M3u8::SegmentItem.new(duration: 4, segment: 'a.ts')
+      expect(playlist.warnings).to be_empty
+    end
+
+    it 'warns about LL-HLS tags below version 9' do
+      playlist = M3u8::Playlist.new(version: 6, target: 4)
+      playlist.part_inf = M3u8::PartInfItem.new(part_target: 0.5)
+      playlist.server_control =
+        M3u8::ServerControlItem.new(part_hold_back: 1.5)
+      expect(playlist.warnings)
+        .to include('EXT-X-PART-INF requires version 9 (version 6)')
+    end
+
+    it 'warns when a SERVICE INSTREAM-ID needs a higher version' do
+      playlist = M3u8::Playlist.new
+      playlist.items << M3u8::MediaItem.new(
+        type: 'CLOSED-CAPTIONS', group_id: 'cc', name: 'CC',
+        instream_id: 'SERVICE1'
+      )
+      expect(playlist.warnings).to include(
+        'SERVICE INSTREAM-ID requires version 7 (no EXT-X-VERSION tag)'
+      )
+    end
+
+    it 'warns when EXT-X-SESSION-KEY needs a higher version' do
+      playlist = M3u8::Playlist.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
+      expect(playlist.warnings).to include(
+        'EXT-X-SESSION-KEY requires version 7 (no EXT-X-VERSION tag)'
+      )
+    end
+
+    it 'is empty when the version is sufficient' do
+      playlist = M3u8::Playlist.read(
+        File.read('spec/fixtures/master_full.m3u8')
+      )
+      expect(playlist.warnings).to be_empty
+    end
+  end
+
+  context 'low-latency HLS' do
+    it 'warns when EXT-X-PART lacks EXT-X-PART-INF' do
+      playlist = M3u8::Playlist.new(version: 9, target: 4)
+      playlist.items << M3u8::PartItem.new(uri: 'p.m4s', duration: 0.5)
+      expect(playlist.warnings)
+        .to include('EXT-X-PART requires EXT-X-PART-INF')
+    end
+
+    it 'does not require PART-HOLD-BACK when it is omitted' do
+      playlist = M3u8::Playlist.new(version: 9, target: 4)
+      playlist.part_inf = M3u8::PartInfItem.new(part_target: 0.5)
+      expect(playlist.warnings).to be_empty
+    end
+
+    it 'warns when PART-HOLD-BACK is below twice PART-TARGET' do
+      playlist = low_latency(part_target: 1.0, hold_back: 1.5)
+      expect(playlist.warnings)
+        .to include('PART-HOLD-BACK should be at least twice PART-TARGET')
+    end
+
+    it 'warns when PART-HOLD-BACK is below three times PART-TARGET' do
+      playlist = low_latency(part_target: 1.0, hold_back: 2.5)
+      expect(playlist.warnings).to include(
+        'PART-HOLD-BACK should be at least three times PART-TARGET'
+      )
+    end
+
+    it 'warns when CAN-SKIP-UNTIL is below six times TARGETDURATION' do
+      playlist = low_latency(part_target: 1.0, hold_back: 3.0,
+                             skip_until: 10.0, target: 4)
+      expect(playlist.warnings).to include(
+        'CAN-SKIP-UNTIL should be at least six times TARGETDURATION'
+      )
+    end
+
+    it 'is empty when LL-HLS thresholds are met' do
+      playlist = low_latency(part_target: 1.0, hold_back: 3.0,
+                             skip_until: 24.0, target: 4)
+      expect(playlist.warnings).to be_empty
+    end
+
+    it 'skips the PART-HOLD-BACK check without a PART-TARGET' do
+      playlist = M3u8::Playlist.new(version: 9, target: 4)
+      playlist.part_inf = M3u8::PartInfItem.new
+      playlist.server_control =
+        M3u8::ServerControlItem.new(part_hold_back: 1.0)
+      expect(playlist.warnings).to be_empty
+    end
+  end
+end

data/spec/lib/m3u8/date_range_item_spec.rb

@@ -172,6 +172,26 @@ describe M3u8::DateRangeItem do
       expect(item.to_s).to eq(expected)
     end
 
+    it 'should render small float values as floating-point number instead of scientific notation' do
+      options = { id: 'test_id', start_date: '2014-03-05T11:15:00Z',
+                  duration: 0.00001,
+                  planned_duration: 0.00002,
+                  resume_offset: 0.00003,
+                  playout_limit: 0.00004,
+                  client_attributes: { 'X-CUSTOM' => 0.00005 } }
+      item = described_class.new(options)
+
+      expected = '#EXT-X-DATERANGE:ID="test_id",' \
+                 'START-DATE="2014-03-05T11:15:00Z",' \
+                 'DURATION=0.00001,' \
+                 'PLANNED-DURATION=0.00002,' \
+                 'X-CUSTOM=0.00005,' \
+                 'X-RESUME-OFFSET=0.00003,' \
+                 'X-PLAYOUT-LIMIT=0.00004'
+
+      expect(item.to_s).to eq(expected)
+    end
+
     it 'should ignore optional attributes' do
       options = { id: 'test_id', start_date: '2014-03-05T11:15:00Z' }
       item = described_class.new(options)

data/spec/lib/m3u8/part_item_spec.rb

@@ -56,5 +56,12 @@ describe M3u8::PartItem do
       expected = '#EXT-X-PART:DURATION=1.5,URI="part1.ts"'
       expect(item.to_s).to eq(expected)
     end
+
+    it 'should render small float values as floating-point number instead of scientific notation' do
+      options = { duration: 0.00001, uri: 'part1.ts' }
+      item = described_class.new(options)
+      expected = '#EXT-X-PART:DURATION=0.00001,URI="part1.ts"'
+      expect(item.to_s).to eq(expected)
+    end
   end
 end

data/spec/lib/m3u8/reader_spec.rb

@@ -612,5 +612,40 @@ describe M3u8::Reader do
           .to raise_error(M3u8::InvalidPlaylistError, message)
       end
     end
+
+    context 'with unsupported tags' do
+      let(:content) do
+        "#EXTM3U\n#EXT-X-VERSION:4\n#EXT-X-FUTURE-TAG:1\n" \
+          "#EXT-X-TARGETDURATION:10\n#EXTINF:5.0,\nseg.ts\n" \
+          "#EXT-X-ENDLIST\n"
+      end
+
+      it 'records unknown tags by default' do
+        playlist = M3u8::Playlist.read(content)
+        expect(playlist.unknown_tags).to eq(['#EXT-X-FUTURE-TAG:1'])
+        expect(playlist.segments.first.segment).to eq('seg.ts')
+      end
+
+      it 'raises in strict mode' do
+        expect { M3u8::Playlist.read(content, strict: true) }
+          .to raise_error(M3u8::InvalidPlaylistError, /Unsupported tag/)
+      end
+
+      it 'ignores plain comment lines' do
+        commented = "#EXTM3U\n# a comment\n#EXT-X-TARGETDURATION:10\n" \
+                    "#EXTINF:5.0,\nseg.ts\n#EXT-X-ENDLIST\n"
+        playlist = M3u8::Playlist.read(commented)
+        expect(playlist.unknown_tags).to be_empty
+        expect(playlist.segments.first.segment).to eq('seg.ts')
+      end
+
+      it 'does not treat an unknown tag as a segment URI' do
+        open_case = "#EXTM3U\n#EXT-X-TARGETDURATION:10\n#EXTINF:5.0,\n" \
+                    "#EXT-X-WAT:1\nseg.ts\n#EXT-X-ENDLIST\n"
+        playlist = M3u8::Playlist.read(open_case)
+        expect(playlist.segments.first.segment).to eq('seg.ts')
+        expect(playlist.unknown_tags).to eq(['#EXT-X-WAT:1'])
+      end
+    end
   end
 end

data/spec/lib/m3u8/round_trip_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'json'
 
 describe 'Round-trip serialization' do
   def read_fixture(name)
@@ -149,4 +150,113 @@ describe 'Round-trip serialization' do
       expect(item.data_id).to eq('com.example.lyrics')
     end
   end
+
+  # Canonical output (the result of rendering a parsed playlist) must be a
+  # fixed point of parse-then-render, regardless of whether the original
+  # input was canonical. This guards the reader/writer against asymmetries.
+  context 'idempotent canonical output (all fixtures)' do
+    Dir['spec/fixtures/*.m3u8'].each do |path|
+      fixture = File.basename(path)
+
+      it "produces stable canonical output for #{fixture}" do
+        canonical = parse(read_fixture(fixture)).to_s
+        expect(parse(canonical).to_s).to eq(canonical)
+      end
+    end
+  end
+
+  context 'idempotent canonical output (generated playlists)' do
+    def random_time(rng)
+      Time.at(rng.rand(1_500_000_000..1_700_000_000)).utc
+    end
+
+    def random_byterange(rng)
+      M3u8::ByteRange.new(length: rng.rand(200..900), start: rng.rand(0..50))
+    end
+
+    def build_segment(rng, index)
+      segment = M3u8::SegmentItem.new(
+        duration: ((rng.rand * 12) + 0.5).round(3),
+        segment: "segment#{index}.ts"
+      )
+      segment.byterange = random_byterange(rng) if rng.rand < 0.4
+      segment.program_date_time = random_time(rng) if rng.rand < 0.3
+      segment
+    end
+
+    def build_segments(rng)
+      [].tap do |items|
+        rng.rand(1..5).times do |index|
+          items << M3u8::DiscontinuityItem.new if rng.rand < 0.2
+          items << build_segment(rng, index)
+        end
+      end
+    end
+
+    def random_media_playlist(rng)
+      segments = build_segments(rng)
+      target = segments.grep(M3u8::SegmentItem)
+                       .map { |s| s.duration.round }.max
+      playlist = M3u8::Playlist.new(version: rng.rand(3..7),
+                                    target: target, sequence: rng.rand(0..9))
+      playlist.type = %w[VOD EVENT].sample(random: rng) if rng.rand < 0.5
+      playlist.independent_segments = true if rng.rand < 0.5
+      playlist.items.concat(segments)
+      key = M3u8::KeyItem.new(method: 'AES-128', uri: 'key.bin')
+      playlist.items.unshift(key) if rng.rand < 0.3
+      playlist
+    end
+
+    def build_variant(rng, index)
+      M3u8::PlaylistItem.new(uri: "variant#{index}.m3u8",
+                             bandwidth: rng.rand(100_000..9_000_000),
+                             width: 1920, height: 1080,
+                             codecs: 'avc1.640028,mp4a.40.2')
+    end
+
+    def random_master_playlist(rng)
+      playlist = M3u8::Playlist.new(version: rng.rand(4..7))
+      playlist.independent_segments = true if rng.rand < 0.5
+      rng.rand(1..4).times do |index|
+        playlist.items << build_variant(rng, index)
+      end
+      rendition = M3u8::MediaItem.new(type: 'AUDIO', group_id: 'audio',
+                                      name: 'English', uri: 'audio.m3u8')
+      playlist.items << rendition if rng.rand < 0.6
+      playlist
+    end
+
+    it 'produces stable canonical output across generated playlists' do
+      rng = Random.new(90_125)
+      100.times do |iteration|
+        playlist = if iteration.even?
+                     random_media_playlist(rng)
+                   else
+                     random_master_playlist(rng)
+                   end
+        canonical = parse(playlist.to_s).to_s
+        message = "drift on iteration #{iteration}:\n#{canonical}"
+        expect(parse(canonical).to_s).to eq(canonical), message
+        rebuilt = M3u8::Playlist.from_h(parse(canonical).to_h)
+        expect(rebuilt.to_s).to eq(canonical), message
+      end
+    end
+  end
+
+  # A playlist rebuilt from its Hash (or its JSON) must render identically
+  # to the canonical output, exercising Playlist.from_h across every item.
+  context 'Hash and JSON round-trip (all fixtures)' do
+    Dir['spec/fixtures/*.m3u8'].each do |path|
+      fixture = File.basename(path)
+
+      it "rebuilds #{fixture} from its Hash and JSON" do
+        canonical = parse(read_fixture(fixture)).to_s
+        playlist = parse(canonical)
+        from_hash = M3u8::Playlist.from_h(playlist.to_h)
+        expect(from_hash.to_s).to eq(canonical)
+        from_json = M3u8::Playlist.from_h(JSON.parse(playlist.to_json))
+        expect(from_json.to_s).to eq(canonical)
+      end
+    end
+  end
 end

data/spec/lib/m3u8/segment_item_spec.rb

@@ -89,4 +89,15 @@ describe M3u8::SegmentItem do
                'segment.aac'
     expect(output).to eq expected
   end
+
+  it 'converts very small durations to floating point' do
+    time = Time.iso8601('2020-11-25T20:27:00Z')
+    hash = { duration: 0.000001, segment: 'test.ts', program_date_time: time }
+    item = M3u8::SegmentItem.new(hash)
+    output = item.to_s
+    expected = "#EXTINF:0.000001,\n" \
+               "#EXT-X-PROGRAM-DATE-TIME:2020-11-25T20:27:00Z\n" \
+               'test.ts'
+    expect(output).to eq expected
+  end
 end

data/spec/lib/m3u8/serializable_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+
+describe M3u8::Serializable do
+  describe '.serialize' do
+    it 'converts a Time to an iso8601 string' do
+      time = Time.utc(2020, 1, 2, 3, 4, 5)
+      expect(described_class.serialize(time)).to eq('2020-01-02T03:04:05Z')
+    end
+
+    it 'converts a TimeItem to its time value' do
+      item = M3u8::TimeItem.new(time: Time.utc(2020, 1, 2, 3, 4, 5))
+      expect(described_class.serialize(item)).to eq('2020-01-02T03:04:05Z')
+    end
+
+    it 'converts a BigDecimal to a Float' do
+      expect(described_class.serialize(BigDecimal('29.97'))).to eq(29.97)
+    end
+
+    it 'converts a nested Serializable to a Hash' do
+      range = M3u8::ByteRange.new(length: 100, start: 5)
+      expect(described_class.serialize(range)).to eq(length: 100, start: 5)
+    end
+
+    it 'recursively serializes Hash values' do
+      result = described_class.serialize('X-A' => BigDecimal('1.5'))
+      expect(result).to eq('X-A' => 1.5)
+    end
+
+    it 'returns scalar values unchanged' do
+      expect(described_class.serialize('plain')).to eq('plain')
+    end
+  end
+
+  describe '#to_h' do
+    it 'maps instance variables to symbol keys' do
+      item = M3u8::ByteRange.new(length: 300, start: 12)
+      expect(item.to_h).to eq(length: 300, start: 12)
+    end
+
+    it 'returns an empty Hash when there are no attributes' do
+      expect(M3u8::GapItem.new.to_h).to eq({})
+    end
+
+    it 'serializes a segment program date time to a string' do
+      segment = M3u8::SegmentItem.new(duration: 5.0, segment: 'a.ts')
+      segment.program_date_time =
+        M3u8::TimeItem.new(time: Time.utc(2020, 1, 1))
+      expect(segment.to_h[:program_date_time]).to eq('2020-01-01T00:00:00Z')
+    end
+
+    it 'serializes a byte range to a nested Hash' do
+      segment = M3u8::SegmentItem.new(duration: 5.0, segment: 'a.ts',
+                                      byterange: { length: 50, start: 2 })
+      expect(segment.to_h[:byterange]).to eq(length: 50, start: 2)
+    end
+
+    it 'serializes client attributes as a Hash' do
+      item = M3u8::DateRangeItem.new(id: 'x',
+                                     client_attributes: { 'X-A' => 'b' })
+      expect(item.to_h[:client_attributes]).to eq('X-A' => 'b')
+    end
+
+    it 'omits raw HLS attribute names for parsed keys' do
+      key = M3u8::KeyItem.parse(
+        '#EXT-X-KEY:METHOD=AES-128,URI="k.key",IV=0x1234'
+      )
+      expect(key.to_h.keys).to contain_exactly(
+        :method, :uri, :iv, :key_format, :key_format_versions
+      )
+    end
+  end
+
+  describe 'M3u8::Playlist#to_h' do
+    def read_fixture(name)
+      M3u8::Playlist.read(File.read("spec/fixtures/#{name}"))
+    end
+
+    it 'includes top-level attributes and typed items for a master' do
+      hash = read_fixture('master.m3u8').to_h
+      expect(hash[:master]).to be(true)
+      expect(hash[:part_inf]).to be_nil
+      expect(hash[:items]).to all(include(:item_type))
+      types = hash[:items].map { |item| item[:item_type] }
+      expect(types).to include('PlaylistItem')
+    end
+
+    it 'serializes part_inf and server_control for LL-HLS' do
+      hash = read_fixture('ll_hls_playlist.m3u8').to_h
+      expect(hash[:master]).to be(false)
+      expect(hash[:server_control][:can_skip_until]).to eq(24.0)
+      expect(hash[:part_inf][:part_target]).to eq(0.5)
+    end
+  end
+
+  describe '#as_json and #to_json' do
+    it 'as_json returns the same Hash as to_h' do
+      item = M3u8::ByteRange.new(length: 10, start: 2)
+      expect(item.as_json).to eq(item.to_h)
+    end
+
+    it 'to_json renders the attributes as JSON' do
+      item = M3u8::ByteRange.new(length: 10, start: 2)
+      expect(JSON.parse(item.to_json)).to eq('length' => 10, 'start' => 2)
+    end
+  end
+
+  describe 'M3u8::Playlist.from_h' do
+    def read_fixture(name)
+      M3u8::Playlist.read(File.read("spec/fixtures/#{name}"))
+    end
+
+    it 'round-trips a playlist through to_h' do
+      original = read_fixture('encrypted.m3u8')
+      rebuilt = M3u8::Playlist.from_h(original.to_h)
+      expect(rebuilt.to_s).to eq(original.to_s)
+    end
+
+    it 'round-trips a playlist through JSON' do
+      original = read_fixture('master.m3u8')
+      rebuilt = M3u8::Playlist.from_h(JSON.parse(original.to_json))
+      expect(rebuilt.to_s).to eq(original.to_s)
+    end
+
+    it 'raises for an unknown item type' do
+      expect do
+        M3u8::Playlist.from_h(items: [{ item_type: 'Bogus' }])
+      end.to raise_error(M3u8::InvalidPlaylistError, /Bogus/)
+    end
+  end
+end

data/spec/lib/m3u8/time_item_spec.rb

@@ -1,8 +1,21 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'open3'
 
 describe M3u8::TimeItem do
+  it 'parses program date time after only requiring m3u8' do
+    lib = File.expand_path('../../../lib', __dir__)
+    script = <<~'RUBY'
+      require 'm3u8'
+      lines = ['#EXTM3U',
+               '#EXT-X-PROGRAM-DATE-TIME:2010-02-19T14:54:23Z']
+      M3u8::Playlist.read(lines.join("\n") + "\n")
+    RUBY
+    output, status = Open3.capture2e('ruby', '-I', lib, '-e', script)
+    expect(status).to be_success, output
+  end
+
   it 'should provide m3u8 format representation' do
     options = { time: '2010-02-19T14:54:23.031' }
     item = M3u8::TimeItem.new(options)