m3u8 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a9a7d6e157afd5fd7028323544bf9d851bd898890f90c66af6f64e672d7e456
-  data.tar.gz: ee452e25dfb96ee9634e9a00c287a87ac4640dceb2d965550e31199e0c0b4e26
+  metadata.gz: 7112d267f1f0b5e6f89f4c5b54392b02dc3d37d39d9cbda88d2125b69b89ca37
+  data.tar.gz: 6755f10b8de1fbb8d06f881b29973623fa48e53347b54f3093c37ff794817090
 SHA512:
-  metadata.gz: f6b458aaf9a1a1060d19dca456020b54813f0c1f011615593e088a512a87ed32120cd5d509fb66dd3b12f85fe11a255304eede7852a00197cfd9513c918a33eb
-  data.tar.gz: 7c543fd8e6004adaf275adfe95c231b42fe0549805436f8dea3e77f2731f273084c99887781d0b69daf05ec1e53218fb8711be895fc0c14e9f0687f983a611b1
+  metadata.gz: 635a0727ca10232fd961568d72210bbf96ed1a52c64ed0326a98f275ed1948f2d6016abd1edc774972365f459508e92bd0048e5fa511e4864683d196a2eaddbe
+  data.tar.gz: 6afceffd0ce2b396737e1963ce89b7d1e31177d12d1226c4f705feff4e3625110de05fb108973eac0203566e018f9aa8ac470a0825ee7c581b86753687320009

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+**1.3.1**
+
+* Excluded CLAUDE.md and AGENTS.md from gem package.
+
+***
+
+**1.3.0**
+
+* Added CLI tool (`bin/m3u8`) with `inspect` and `validate` subcommands for inspecting playlist metadata and checking validity from the command line. Supports file arguments and stdin piping.
+* Added `session_keys` convenience accessor to `Playlist`.
+
+***
+
 **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.

data/README.md

@@ -30,6 +30,58 @@ Or install it yourself as:
 
     $ gem install m3u8
 
+## CLI
+
+The gem includes a command-line tool for inspecting and validating playlists.
+
+### Inspect
+
+Display playlist metadata and item summary:
+
+```
+$ m3u8 inspect master.m3u8
+Type:                  Master
+Independent Segments:  Yes
+
+Variants:              6
+  1920x1080  5042000 bps  hls/1080/1080.m3u8
+  640x360    861000 bps   hls/360/360.m3u8
+Media:                 2
+Session Keys:          1
+Session Data:          0
+
+$ m3u8 inspect media.m3u8
+Type:       Media
+Version:    4
+Sequence:   1
+Target:     12
+Duration:   1371.99s
+Playlist:   VOD
+Cache:      No
+
+Segments:   138
+Keys:       0
+Maps:       0
+```
+
+Reads from stdin when no file is given:
+
+```
+$ cat playlist.m3u8 | m3u8 inspect
+```
+
+### Validate
+
+Check playlist validity (exit 0 for valid, 1 for invalid):
+
+```
+$ m3u8 validate playlist.m3u8
+Valid
+
+$ m3u8 validate bad.m3u8
+Invalid: mixed playlist and segment items
+```
+
 ## Usage (Builder DSL)
 
 `Playlist.build` provides a block-based DSL for concise playlist construction. It supports two forms:

data/bin/m3u8

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'm3u8'
+
+exit M3u8::CLI.run(ARGV, $stdin, $stdout, $stderr)

data/lib/m3u8/cli/inspect_command.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module M3u8
+  class CLI
+    # InspectCommand displays metadata about a playlist
+    class InspectCommand
+      MEDIA_WIDTH = 12
+      MASTER_WIDTH = 23
+
+      def initialize(playlist, stdout)
+        @playlist = playlist
+        @stdout = stdout
+      end
+
+      def run
+        if @playlist.master?
+          print_master
+        else
+          print_media
+        end
+        0
+      end
+
+      private
+
+      def print_media
+        field 'Type', 'Media', MEDIA_WIDTH
+        field 'Version', @playlist.version, MEDIA_WIDTH
+        field 'Sequence', @playlist.sequence, MEDIA_WIDTH
+        field 'Target', @playlist.target, MEDIA_WIDTH
+        field 'Duration', duration_value, MEDIA_WIDTH
+        field 'Playlist', @playlist.type, MEDIA_WIDTH
+        field 'Cache', cache_value, MEDIA_WIDTH
+        @stdout.puts
+        field 'Segments', @playlist.segments.size, MEDIA_WIDTH
+        field 'Keys', @playlist.keys.size, MEDIA_WIDTH
+        field 'Maps', @playlist.maps.size, MEDIA_WIDTH
+      end
+
+      def print_master
+        field 'Type', 'Master', MASTER_WIDTH
+        field 'Independent Segments',
+              independent_segments_value, MASTER_WIDTH
+        @stdout.puts
+        print_variants
+        print_media_items
+        field 'Session Keys',
+              @playlist.session_keys.size, MASTER_WIDTH
+        field 'Session Data',
+              @playlist.session_data.size, MASTER_WIDTH
+      end
+
+      def print_variants
+        variants = @playlist.playlists
+        field 'Variants', variants.size, MASTER_WIDTH
+        variants.each { |v| @stdout.puts variant_line(v) }
+      end
+
+      def print_media_items
+        items = @playlist.media_items
+        field 'Media', items.size, MASTER_WIDTH
+        items.each do |m|
+          @stdout.puts "  #{m.type}  #{m.group_id}  #{m.name}"
+        end
+      end
+
+      def variant_line(variant)
+        res = variant.resolution || ''
+        format('  %-11<res>s%<bw>s bps  %<uri>s',
+               res: res, bw: variant.bandwidth, uri: variant.uri)
+      end
+
+      def independent_segments_value
+        return unless @playlist.independent_segments
+
+        'Yes'
+      end
+
+      def duration_value
+        format('%<s>gs', s: @playlist.duration)
+      end
+
+      def cache_value
+        return unless @playlist.cache == false
+
+        'No'
+      end
+
+      def field(label, value, width)
+        return if value.nil?
+
+        @stdout.puts format("%-#{width}<label>s%<value>s",
+                            label: "#{label}:", value: value)
+      end
+    end
+  end
+end

data/lib/m3u8/cli/validate_command.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module M3u8
+  class CLI
+    # ValidateCommand checks playlist validity
+    class ValidateCommand
+      def initialize(playlist, stdout)
+        @playlist = playlist
+        @stdout = stdout
+      end
+
+      def run
+        if @playlist.valid?
+          @stdout.puts 'Valid'
+          0
+        else
+          @stdout.puts 'Invalid: mixed playlist and segment items'
+          1
+        end
+      end
+    end
+  end
+end

data/lib/m3u8/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'cli/inspect_command'
+require_relative 'cli/validate_command'
+
+module M3u8
+  # CLI provides a command-line interface for inspecting and validating
+  # m3u8 playlists
+  class CLI
+    COMMANDS = %w[inspect validate].freeze
+
+    def self.run(argv, stdin, stdout, stderr)
+      new(argv, stdin, stdout, stderr).run
+    end
+
+    def initialize(argv, stdin, stdout, stderr)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      parse_global_options
+      dispatch
+    rescue OptionParser::InvalidOption => e
+      @stderr.puts e.message
+      2
+    end
+
+    private
+
+    def parse_global_options
+      @parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: m3u8 <command> [options] [file]'
+        opts.separator ''
+        opts.separator 'Commands:'
+        opts.separator '  inspect    Show playlist metadata'
+        opts.separator '  validate   Check playlist validity'
+        opts.separator ''
+        opts.on('-v', '--version', 'Show version') do
+          @stdout.puts M3u8::VERSION
+          throw :exit, 0
+        end
+        opts.on('-h', '--help', 'Show help') do
+          @stdout.puts opts
+          throw :exit, 0
+        end
+      end
+
+      @exit_code = catch(:exit) do
+        @parser.order!(@argv)
+        nil
+      end
+    end
+
+    def dispatch
+      return @exit_code if @exit_code
+
+      command = @argv.shift
+      return usage_error if command.nil?
+      return usage_error("unknown command: #{command}") \
+        unless COMMANDS.include?(command)
+
+      input = resolve_input
+      return 2 unless input
+
+      playlist = parse_playlist(input)
+      return 2 unless playlist
+
+      execute_command(command, playlist)
+    end
+
+    def execute_command(command, playlist)
+      case command
+      when 'inspect'
+        InspectCommand.new(playlist, @stdout).run
+      when 'validate'
+        ValidateCommand.new(playlist, @stdout).run
+      end
+    end
+
+    def resolve_input
+      file = @argv.shift
+      if file
+        read_file(file)
+      elsif !@stdin.tty?
+        @stdin.read
+      else
+        usage_error
+        nil
+      end
+    end
+
+    def read_file(path)
+      File.read(path)
+    rescue Errno::ENOENT
+      @stderr.puts "no such file: #{path}"
+      nil
+    end
+
+    def parse_playlist(input)
+      Playlist.read(input)
+    rescue StandardError => e
+      @stderr.puts "parse error: #{e.message}"
+      nil
+    end
+
+    def usage_error(message = nil)
+      @stderr.puts message if message
+      @stderr.puts @parser.to_s
+      2
+    end
+  end
+end

data/lib/m3u8/playlist.rb

@@ -66,35 +66,39 @@ module M3u8
     end
 
     def segments
-      items.select { |item| item.is_a?(SegmentItem) }
+      items.grep(SegmentItem)
     end
 
     def playlists
-      items.select { |item| item.is_a?(PlaylistItem) }
+      items.grep(PlaylistItem)
     end
 
     def media_items
-      items.select { |item| item.is_a?(MediaItem) }
+      items.grep(MediaItem)
     end
 
     def keys
-      items.select { |item| item.is_a?(KeyItem) }
+      items.grep(KeyItem)
     end
 
     def maps
-      items.select { |item| item.is_a?(MapItem) }
+      items.grep(MapItem)
     end
 
     def date_ranges
-      items.select { |item| item.is_a?(DateRangeItem) }
+      items.grep(DateRangeItem)
     end
 
     def parts
-      items.select { |item| item.is_a?(PartItem) }
+      items.grep(PartItem)
     end
 
     def session_data
-      items.select { |item| item.is_a?(SessionDataItem) }
+      items.grep(SessionDataItem)
+    end
+
+    def session_keys
+      items.grep(SessionKeyItem)
     end
 
     def duration

data/lib/m3u8/version.rb

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

data/lib/m3u8.rb

@@ -14,10 +14,8 @@ module M3u8
   end
 
   def parse_attributes(line)
-    # rubocop:disable Style/HashTransformValues
     line.delete("\n").scan(/([A-Za-z0-9-]+)\s*=\s*("[^"]*"|[^,]*)/)
         .to_h { |key, value| [key, value.delete('"')] }
-    # rubocop:enable Style/HashTransformValues
   end
 
   def parse_float(value)

data/m3u8.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.0'
 
   spec.files         = `git ls-files -z`.split("\x0")
+                                        .grep_v(/\A(CLAUDE|AGENTS)\.md\z/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::CLI::InspectCommand do
+  let(:stdout) { StringIO.new }
+
+  def inspect_fixture(name)
+    playlist = M3u8::Playlist.read(
+      File.read("spec/fixtures/#{name}")
+    )
+    described_class.new(playlist, stdout).run
+  end
+
+  describe 'media playlist' do
+    it 'displays metadata for a VOD playlist' do
+      code = inspect_fixture('playlist.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:       Media')
+      expect(lines).to include('Version:    4')
+      expect(lines).to include('Sequence:   1')
+      expect(lines).to include('Target:     12')
+      expect(lines).to include('Duration:   1371.99s')
+      expect(lines).to include('Playlist:   VOD')
+      expect(lines).to include('Cache:      No')
+      expect(lines).to include('Segments:   138')
+      expect(lines).to include('Keys:       0')
+      expect(lines).to include('Maps:       0')
+    end
+
+    it 'displays metadata for an encrypted playlist' do
+      code = inspect_fixture('encrypted.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:       Media')
+      expect(lines).to include('Version:    3')
+      expect(lines).to include('Sequence:   7794')
+      expect(lines).to include('Target:     15')
+      expect(lines).to include('Segments:   4')
+      expect(lines).to include('Keys:       2')
+      expect(lines).not_to include('Playlist:')
+      expect(lines).not_to include('Cache:')
+    end
+
+    it 'displays metadata for an LL-HLS playlist' do
+      code = inspect_fixture('ll_hls_playlist.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:       Media')
+      expect(lines).to include('Version:    9')
+      expect(lines).to include('Segments:   2')
+      expect(lines).to include('Maps:       1')
+    end
+  end
+
+  describe 'master playlist' do
+    it 'displays metadata for a master playlist' do
+      code = inspect_fixture('master.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:                  Master')
+      expect(lines).to include(
+        'Independent Segments:  Yes'
+      )
+      expect(lines).to include('Variants:              6')
+      expect(lines).to include('1920x1080  5042000 bps')
+      expect(lines).to include(
+        'hls/1080-7mbps/1080-7mbps.m3u8'
+      )
+      expect(lines).to include('6400 bps')
+      expect(lines).to include('hls/64k/64k.m3u8')
+      expect(lines).to include('Media:                 0')
+      expect(lines).to include('Session Keys:          1')
+      expect(lines).to include('Session Data:          0')
+    end
+
+    it 'displays metadata for a variant audio playlist' do
+      code = inspect_fixture('variant_audio.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:                  Master')
+      expect(lines).to include('Variants:              4')
+      expect(lines).to include('Media:                 6')
+      expect(lines).to include('AUDIO  audio-lo  English')
+      expect(lines).to include(
+        "AUDIO  audio-hi  Fran\xC3\xA7ais"
+      )
+      expect(lines).to include('Session Keys:          0')
+      expect(lines).to include('Session Data:          0')
+      expect(lines).not_to include('Independent Segments:')
+    end
+
+    it 'displays session data for a session data playlist' do
+      code = inspect_fixture('session_data.m3u8')
+      expect(code).to eq(0)
+      lines = stdout.string
+      expect(lines).to include('Type:       Media')
+      expect(lines).to include('Segments:   0')
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::CLI::ValidateCommand do
+  let(:stdout) { StringIO.new }
+
+  describe '#run' do
+    context 'when playlist is valid' do
+      it 'prints Valid and returns 0' do
+        playlist = M3u8::Playlist.read(
+          File.read('spec/fixtures/master.m3u8')
+        )
+        code = described_class.new(playlist, stdout).run
+        expect(code).to eq(0)
+        expect(stdout.string.strip).to eq('Valid')
+      end
+    end
+
+    context 'when playlist is invalid' do
+      it 'prints Invalid and returns 1' do
+        playlist = M3u8::Playlist.new
+        playlist.items << M3u8::PlaylistItem.new(
+          bandwidth: 540, uri: 'test.url'
+        )
+        playlist.items << M3u8::SegmentItem.new(
+          duration: 10.0, segment: 'test.ts'
+        )
+        code = described_class.new(playlist, stdout).run
+        expect(code).to eq(1)
+        expect(stdout.string.strip).to include('Invalid')
+      end
+    end
+  end
+end

data/spec/lib/m3u8/cli_spec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe M3u8::CLI do
+  let(:stdout) { StringIO.new }
+  let(:stderr) { StringIO.new }
+  let(:stdin) { StringIO.new }
+
+  def run(argv)
+    described_class.run(argv, stdin, stdout, stderr)
+  end
+
+  describe '--version' do
+    it 'prints the version and exits 0' do
+      expect(run(['--version'])).to eq(0)
+      expect(stdout.string.strip).to eq(M3u8::VERSION)
+    end
+  end
+
+  describe '--help' do
+    it 'prints usage and exits 0' do
+      expect(run(['--help'])).to eq(0)
+      expect(stdout.string).to include('Usage: m3u8')
+      expect(stdout.string).to include('inspect')
+      expect(stdout.string).to include('validate')
+    end
+  end
+
+  describe 'no command' do
+    it 'prints usage to stderr and exits 2' do
+      expect(run([])).to eq(2)
+      expect(stderr.string).to include('Usage: m3u8')
+    end
+  end
+
+  describe 'unknown command' do
+    it 'prints error and usage to stderr and exits 2' do
+      expect(run(['bogus'])).to eq(2)
+      expect(stderr.string).to include('unknown command: bogus')
+    end
+  end
+
+  describe 'invalid option' do
+    it 'prints error to stderr and exits 2' do
+      expect(run(['--bogus'])).to eq(2)
+      expect(stderr.string).to include('invalid option')
+    end
+  end
+
+  describe 'file not found' do
+    it 'prints error to stderr and exits 2' do
+      expect(run(['inspect', 'nonexistent.m3u8'])).to eq(2)
+      expect(stderr.string).to include('no such file')
+    end
+  end
+
+  describe 'file input' do
+    it 'reads a playlist from a file for inspect' do
+      code = run(['inspect', 'spec/fixtures/master.m3u8'])
+      expect(code).to eq(0)
+    end
+
+    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')
+    end
+  end
+
+  describe 'parse error' do
+    it 'prints error to stderr and exits 2' do
+      stdin = StringIO.new('not a playlist')
+      code = described_class.run(
+        ['inspect'], stdin, stdout, stderr
+      )
+      expect(code).to eq(2)
+      expect(stderr.string).to include('parse error')
+    end
+  end
+
+  describe 'stdin input' do
+    it 'reads a playlist from stdin' do
+      content = File.read('spec/fixtures/master.m3u8')
+      stdin = StringIO.new(content)
+      code = described_class.run(
+        ['inspect'], stdin, stdout, stderr
+      )
+      expect(code).to eq(0)
+    end
+  end
+
+  describe 'command with no input on a tty' do
+    it 'prints usage to stderr and exits 2' do
+      tty = StringIO.new
+      allow(tty).to receive(:tty?).and_return(true)
+      code = described_class.run(
+        ['inspect'], tty, stdout, stderr
+      )
+      expect(code).to eq(2)
+      expect(stderr.string).to include('Usage: m3u8')
+    end
+  end
+end

data/spec/lib/m3u8/playlist_spec.rb

@@ -60,8 +60,9 @@ describe M3u8::Playlist do
 
   describe '.read' do
     it 'returns new playlist from content' do
-      file = File.open('spec/fixtures/master.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
       expect(playlist.master?).to be true
       expect(playlist.items.size).to eq(8)
     end
@@ -238,8 +239,9 @@ describe M3u8::Playlist do
 
   describe '#segments' do
     it 'returns only segment items' do
-      file = File.open('spec/fixtures/playlist.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/playlist.m3u8')
+      )
       expect(playlist.segments).to all be_a(M3u8::SegmentItem)
       expect(playlist.segments.size).to eq(138)
     end
@@ -247,8 +249,9 @@ describe M3u8::Playlist do
 
   describe '#playlists' do
     it 'returns only playlist items' do
-      file = File.open('spec/fixtures/master.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
       expect(playlist.playlists).to all be_a(M3u8::PlaylistItem)
       expect(playlist.playlists.size).to eq(6)
     end
@@ -256,8 +259,9 @@ describe M3u8::Playlist do
 
   describe '#media_items' do
     it 'returns only media items' do
-      file = File.open('spec/fixtures/variant_audio.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/variant_audio.m3u8')
+      )
       expect(playlist.media_items).to all be_a(M3u8::MediaItem)
       expect(playlist.media_items.size).to eq(6)
     end
@@ -265,8 +269,9 @@ describe M3u8::Playlist do
 
   describe '#keys' do
     it 'returns only key items' do
-      file = File.open('spec/fixtures/encrypted.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/encrypted.m3u8')
+      )
       expect(playlist.keys).to all be_a(M3u8::KeyItem)
       expect(playlist.keys.size).to eq(2)
     end
@@ -274,8 +279,9 @@ describe M3u8::Playlist do
 
   describe '#maps' do
     it 'returns only map items' do
-      file = File.open('spec/fixtures/map_playlist.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/map_playlist.m3u8')
+      )
       expect(playlist.maps).to all be_a(M3u8::MapItem)
       expect(playlist.maps.size).to eq(1)
     end
@@ -283,8 +289,9 @@ describe M3u8::Playlist do
 
   describe '#date_ranges' do
     it 'returns only date range items' do
-      file = File.open('spec/fixtures/daterange_playlist.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/daterange_playlist.m3u8')
+      )
       expect(playlist.date_ranges)
         .to all be_a(M3u8::DateRangeItem)
       expect(playlist.date_ranges.size).to eq(3)
@@ -293,8 +300,9 @@ describe M3u8::Playlist do
 
   describe '#parts' do
     it 'returns only part items' do
-      file = File.open('spec/fixtures/ll_hls_playlist.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/ll_hls_playlist.m3u8')
+      )
       expect(playlist.parts).to all be_a(M3u8::PartItem)
       expect(playlist.parts.size).to eq(5)
     end
@@ -302,14 +310,26 @@ describe M3u8::Playlist do
 
   describe '#session_data' do
     it 'returns only session data items' do
-      file = File.open('spec/fixtures/session_data.m3u8')
-      playlist = described_class.read(file)
+      playlist = described_class.read(
+        File.read('spec/fixtures/session_data.m3u8')
+      )
       expect(playlist.session_data)
         .to all be_a(M3u8::SessionDataItem)
       expect(playlist.session_data.size).to eq(3)
     end
   end
 
+  describe '#session_keys' do
+    it 'returns only session key items' do
+      playlist = described_class.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
+      expect(playlist.session_keys)
+        .to all be_a(M3u8::SessionKeyItem)
+      expect(playlist.session_keys.size).to eq(1)
+    end
+  end
+
   describe '#write' do
     context 'when playlist is valid' do
       it 'returns playlist text' do

data/spec/lib/m3u8/reader_spec.rb

@@ -7,9 +7,10 @@ describe M3u8::Reader do
 
   describe '#read' do
     it 'parses master playlist' do
-      file = File.open('spec/fixtures/master.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
       expect(playlist.master?).to be true
       expect(playlist.discontinuity_sequence).to be_nil
       expect(playlist.independent_segments).to be true
@@ -54,9 +55,10 @@ describe M3u8::Reader do
     end
 
     it 'parses master playlist with I-Frames' do
-      file = File.open('spec/fixtures/master_iframes.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/master_iframes.m3u8')
+      )
       expect(playlist.master?).to be true
 
       expect(playlist.items.size).to eq(7)
@@ -69,9 +71,10 @@ describe M3u8::Reader do
     end
 
     it 'parses media playlist' do
-      file = File.open('spec/fixtures/playlist.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/playlist.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.version).to eq(4)
       expect(playlist.sequence).to eq(1)
@@ -94,9 +97,10 @@ describe M3u8::Reader do
     end
 
     it 'parses I-Frame playlist' do
-      file = File.open('spec/fixtures/iframes.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/iframes.m3u8')
+      )
 
       expect(playlist.iframes_only).to be true
       expect(playlist.items.size).to eq(3)
@@ -114,9 +118,10 @@ describe M3u8::Reader do
     end
 
     it 'parses segment playlist with comments' do
-      file = File.open('spec/fixtures/playlist_with_comments.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/playlist_with_comments.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.version).to eq(4)
       expect(playlist.sequence).to eq(1)
@@ -136,9 +141,10 @@ describe M3u8::Reader do
     end
 
     it 'parses variant playlist with audio options and groups' do
-      file = File.open('spec/fixtures/variant_audio.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/variant_audio.m3u8')
+      )
 
       expect(playlist.master?).to be true
       expect(playlist.items.size).to eq(10)
@@ -157,9 +163,10 @@ describe M3u8::Reader do
     end
 
     it 'parses variant playlist with camera angles' do
-      file = File.open('spec/fixtures/variant_angles.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/variant_angles.m3u8')
+      )
 
       expect(playlist.master?).to be true
       expect(playlist.items.size).to eq(11)
@@ -183,22 +190,22 @@ describe M3u8::Reader do
     end
 
     it 'processes multiple reads as separate playlists' do
-      file = File.open('spec/fixtures/master.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      content = File.read('spec/fixtures/master.m3u8')
+      playlist = reader.read(content)
 
       expect(playlist.items.size).to eq(8)
 
-      file = File.open('spec/fixtures/master.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(content)
 
       expect(playlist.items.size).to eq(8)
     end
 
     it 'parses playlist with session data' do
-      file = File.open('spec/fixtures/session_data.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/session_data.m3u8')
+      )
 
       expect(playlist.items.size).to eq(3)
 
@@ -209,9 +216,10 @@ describe M3u8::Reader do
     end
 
     it 'parses encrypted playlist' do
-      file = File.open('spec/fixtures/encrypted.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/encrypted.m3u8')
+      )
 
       expect(playlist.items.size).to eq(6)
 
@@ -222,9 +230,10 @@ describe M3u8::Reader do
     end
 
     it 'parses map (media intialization section) playlists' do
-      file = File.open('spec/fixtures/map_playlist.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/map_playlist.m3u8')
+      )
 
       expect(playlist.items.size).to eq(1)
 
@@ -236,9 +245,10 @@ describe M3u8::Reader do
     end
 
     it 'reads segment with timestamp' do
-      file = File.open('spec/fixtures/timestamp_playlist.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/timestamp_playlist.m3u8')
+      )
       expect(playlist.items.count).to eq(6)
 
       item_date_time = playlist.items.first.program_date_time
@@ -247,9 +257,10 @@ describe M3u8::Reader do
     end
 
     it 'parses playlist with daterange' do
-      file = File.open('spec/fixtures/date_range_scte35.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/date_range_scte35.m3u8')
+      )
       expect(playlist.items.count).to eq(5)
 
       item = playlist.items[0]
@@ -260,9 +271,10 @@ describe M3u8::Reader do
     end
 
     it 'parses master playlist with v13 attributes' do
-      file = File.open('spec/fixtures/master_v13.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/master_v13.m3u8')
+      )
       expect(playlist.master?).to be true
       expect(playlist.version).to eq(13)
 
@@ -288,9 +300,10 @@ describe M3u8::Reader do
     end
 
     it 'parses playlist with content steering and defines' do
-      file = File.open('spec/fixtures/content_steering.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/content_steering.m3u8')
+      )
       expect(playlist.master?).to be true
       expect(playlist.items.size).to eq(5)
 
@@ -310,9 +323,10 @@ describe M3u8::Reader do
     end
 
     it 'parses LL-HLS playlist' do
-      file = File.open('spec/fixtures/ll_hls_playlist.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/ll_hls_playlist.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.live?).to be true
       expect(playlist.version).to eq(9)
@@ -361,9 +375,10 @@ describe M3u8::Reader do
     end
 
     it 'parses playlist with gap and bitrate tags' do
-      file = File.open('spec/fixtures/gap_playlist.m3u8')
       reader = M3u8::Reader.new
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/gap_playlist.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.items.size).to eq(6)
 
@@ -383,8 +398,9 @@ describe M3u8::Reader do
     end
 
     it 'parses event playlist with byterange and map change' do
-      file = File.open('spec/fixtures/event_playlist.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/event_playlist.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.live?).to be false
       expect(playlist.type).to eq('EVENT')
@@ -417,8 +433,9 @@ describe M3u8::Reader do
     end
 
     it 'parses daterange playlist' do
-      file = File.open('spec/fixtures/daterange_playlist.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/daterange_playlist.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.items.size).to eq(6)
 
@@ -445,8 +462,9 @@ describe M3u8::Reader do
     end
 
     it 'parses full master playlist' do
-      file = File.open('spec/fixtures/master_full.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/master_full.m3u8')
+      )
       expect(playlist.master?).to be true
       expect(playlist.version).to eq(13)
       expect(playlist.independent_segments).to be true
@@ -489,8 +507,9 @@ describe M3u8::Reader do
     end
 
     it 'parses encrypted playlist with discontinuities' do
-      file = File.open('spec/fixtures/encrypted_discontinuity.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/encrypted_discontinuity.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.live?).to be false
       expect(playlist.items.size).to eq(8)
@@ -515,8 +534,9 @@ describe M3u8::Reader do
     end
 
     it 'parses advanced LL-HLS playlist' do
-      file = File.open('spec/fixtures/ll_hls_advanced.m3u8')
-      playlist = reader.read(file)
+      playlist = reader.read(
+        File.read('spec/fixtures/ll_hls_advanced.m3u8')
+      )
       expect(playlist.master?).to be false
       expect(playlist.live?).to be true
       expect(playlist.version).to eq(9)

data/spec/lib/m3u8/round_trip_spec.rb

@@ -76,9 +76,7 @@ describe 'Round-trip serialization' do
       second = parse(first.to_s)
 
       expect(second.items.size).to eq(first.items.size)
-      defines = second.items.select do |i|
-        i.is_a?(M3u8::DefineItem)
-      end
+      defines = second.items.grep(M3u8::DefineItem)
       expect(defines.size).to eq(2)
 
       steering = second.items.find do |i|
@@ -106,9 +104,7 @@ describe 'Round-trip serialization' do
       second = parse(first.to_s)
 
       expect(second.items.size).to eq(first.items.size)
-      media = second.items.select do |i|
-        i.is_a?(M3u8::MediaItem)
-      end
+      media = second.items.grep(M3u8::MediaItem)
       expect(media.size).to eq(6)
       expect(media.first.group_id).to eq('audio-lo')
     end
@@ -119,9 +115,7 @@ describe 'Round-trip serialization' do
       second = parse(first.to_s)
 
       expect(second.items.size).to eq(first.items.size)
-      media = second.items.select do |i|
-        i.is_a?(M3u8::MediaItem)
-      end
+      media = second.items.grep(M3u8::MediaItem)
       expect(media.size).to eq(9)
       types = media.map(&:type).uniq.sort
       expect(types).to eq(%w[AUDIO CLOSED-CAPTIONS

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Seth Deckard
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2026-02-28 00:00:00.000000000 Z
@@ -125,7 +125,8 @@ dependencies:
 description: Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).
 email:
 - seth@deckard.me
-executables: []
+executables:
+- m3u8
 extensions: []
 extra_rdoc_files: []
 files:
@@ -134,18 +135,20 @@ files:
 - ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
-- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
 - Gemfile
 - Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/m3u8
 - lib/m3u8.rb
 - lib/m3u8/bitrate_item.rb
 - lib/m3u8/builder.rb
 - lib/m3u8/byte_range.rb
+- lib/m3u8/cli.rb
+- lib/m3u8/cli/inspect_command.rb
+- lib/m3u8/cli/validate_command.rb
 - lib/m3u8/content_steering_item.rb
 - lib/m3u8/date_range_item.rb
 - lib/m3u8/define_item.rb
@@ -197,6 +200,9 @@ files:
 - spec/lib/m3u8/bitrate_item_spec.rb
 - spec/lib/m3u8/builder_spec.rb
 - spec/lib/m3u8/byte_range_spec.rb
+- spec/lib/m3u8/cli/inspect_command_spec.rb
+- spec/lib/m3u8/cli/validate_command_spec.rb
+- spec/lib/m3u8/cli_spec.rb
 - spec/lib/m3u8/content_steering_item_spec.rb
 - spec/lib/m3u8/date_range_item_spec.rb
 - spec/lib/m3u8/define_item_spec.rb
@@ -227,7 +233,7 @@ homepage: https://github.com/sethdeckard/m3u8
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -242,8 +248,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Generate and parse m3u8 playlists for HTTP Live Streaming (HLS).
 test_files: []

data/AGENTS.md

@@ -1,27 +0,0 @@
-# AGENTS.md
-
-## Development Workflow
-
-- 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
-
-**Subject:** Max 50 chars, capitalized, no period, imperative mood ("Add" not "Added")
-
-**Body:** Wrap at 72 chars, explain what/why not how, blank line after subject
-
-**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
-
-- Kicking off PR: `ghprcw`
-- Never deploy anything

data/CLAUDE.md

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