m3u8 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac7ba85dc1681fda7ba574fd13afc5a2a644726beb03cd10d80862a62d996a76
-  data.tar.gz: 8ec9e60e8ca0a7c81f4fdea78aae937bde641d37baa6984aef90da1c97f6c068
+  metadata.gz: bbf61a694bdc2daf585ad9f405be821f09ba53289ef075e4342f267e674eb21b
+  data.tar.gz: d599367f1344f9b1ad91c20590bc0b4c57a6d0369c71e3a34fd69325ae0c7f44
 SHA512:
-  metadata.gz: ede5d1bfd13f64815f5777485bd1a744ce0e13cecf0b51c9d657b7c2890b34f69e70dfba66f707b66007ca176308d99dba14f7a259dfdab2553e2f35e1199bba
-  data.tar.gz: fb035f0a70f3f675d1c53b5ef46af63e4dd0fc88dad66666b0010eb66210b48eb7ad3b0748a81f55d8b95f0a8af1fb4492a0467bd8f0469fce5ef93b9cdb2b10
+  metadata.gz: 9574b7ac1a95fe6b2fabe0bd28576b2b21713a1bed68e2a18d4ea9f644920a91a08e4696df69a19d7b8392eda87fc8fa14b090338ffebe31524cd5f3f4235539
+  data.tar.gz: 2f34f676d931929f6671b4e3b3ba3efc0e49e73fc2dc54f6c3a64f499e8d2c1a20b974fcad3febcb0f17252d6aef1f9fb612b1c1ec9ad1911e41aa28314f8ea1

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+**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.
+
+***
+
 **1.1.0**
 
 * Added convenience accessor methods to `Playlist` for filtering items by type: `segments`, `playlists`, `media_items`, `keys`, `maps`, `date_ranges`, `parts`, `session_data`.

data/README.md

@@ -30,6 +30,127 @@ 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:
+
+```ruby
+# instance_eval form (clean DSL)
+playlist = M3u8::Playlist.build(version: 4, target: 12) do
+  segment duration: 11.34, segment: '1080-7mbps00000.ts'
+  segment duration: 11.26, segment: '1080-7mbps00001.ts'
+end
+
+# yielded builder form (access outer scope)
+playlist = M3u8::Playlist.build(version: 4) do |b|
+  files.each { |f| b.segment duration: 10.0, segment: f }
+end
+```
+
+Build a master playlist:
+
+```ruby
+playlist = M3u8::Playlist.build(independent_segments: true) do
+  media type: 'AUDIO', group_id: 'audio', name: 'English',
+        default: true, uri: 'eng/index.m3u8'
+  playlist bandwidth: 5_042_000, width: 1920, height: 1080,
+           profile: 'high', level: 4.1, audio_codec: 'aac-lc',
+           uri: 'hls/1080.m3u8'
+  playlist bandwidth: 2_387_000, width: 1280, height: 720,
+           profile: 'main', level: 3.1, audio_codec: 'aac-lc',
+           uri: 'hls/720.m3u8'
+end
+```
+
+Build a media playlist:
+
+```ruby
+playlist = M3u8::Playlist.build(version: 4, target: 12,
+                                sequence: 1, type: 'VOD') do
+  key method: 'AES-128', uri: 'https://example.com/key.bin'
+  map uri: 'init.mp4'
+  segment duration: 11.34, segment: '00000.ts'
+  discontinuity
+  segment duration: 11.26, segment: '00001.ts'
+end
+```
+
+Build an LL-HLS playlist:
+
+```ruby
+sc = M3u8::ServerControlItem.new(
+  can_skip_until: 24.0, part_hold_back: 1.0,
+  can_block_reload: true
+)
+pi = M3u8::PartInfItem.new(part_target: 0.5)
+
+playlist = M3u8::Playlist.build(
+  version: 9, target: 4, sequence: 100,
+  server_control: sc, part_inf: pi, live: true
+) do
+  map uri: 'init.mp4'
+  segment duration: 4.0, segment: 'seg100.mp4'
+  part duration: 0.5, uri: 'seg101.0.mp4', independent: true
+  preload_hint type: 'PART', uri: 'seg101.1.mp4'
+  rendition_report uri: '../alt/index.m3u8',
+                   last_msn: 101, last_part: 0
+end
+```
+
+All DSL methods correspond to item classes: `segment`, `playlist`, `media`, `session_data`, `session_key`, `content_steering`, `key`, `map`, `date_range`, `discontinuity`, `gap`, `time`, `bitrate`, `part`, `preload_hint`, `rendition_report`, `skip`, `define`, `playback_start`.
+
 ## Usage (creating playlists)
 
 Create a master playlist and add child playlists for adaptive bitrate streaming:

data/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/builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Builder provides a block-based DSL for constructing playlists
+  class Builder
+    ITEMS = {
+      segment: 'SegmentItem',
+      playlist: 'PlaylistItem',
+      media: 'MediaItem',
+      session_data: 'SessionDataItem',
+      session_key: 'SessionKeyItem',
+      content_steering: 'ContentSteeringItem',
+      key: 'KeyItem',
+      map: 'MapItem',
+      date_range: 'DateRangeItem',
+      time: 'TimeItem',
+      bitrate: 'BitrateItem',
+      part: 'PartItem',
+      preload_hint: 'PreloadHintItem',
+      rendition_report: 'RenditionReportItem',
+      skip: 'SkipItem',
+      define: 'DefineItem',
+      playback_start: 'PlaybackStart'
+    }.freeze
+
+    ZERO_ARG_ITEMS = {
+      discontinuity: 'DiscontinuityItem',
+      gap: 'GapItem'
+    }.freeze
+
+    def initialize(playlist)
+      @playlist = playlist
+    end
+
+    ITEMS.each do |method_name, class_name|
+      define_method(method_name) do |params = {}|
+        @playlist.items << M3u8.const_get(class_name).new(params)
+      end
+    end
+
+    ZERO_ARG_ITEMS.each do |method_name, class_name|
+      define_method(method_name) do
+        @playlist.items << M3u8.const_get(class_name).new
+      end
+    end
+  end
+end

data/lib/m3u8/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

@@ -14,6 +14,17 @@ module M3u8
       @items = []
     end
 
+    def self.build(options = {}, &block)
+      playlist = new(options)
+      builder = Builder.new(playlist)
+      if block.arity == 1
+        yield builder
+      else
+        builder.instance_eval(&block)
+      end
+      playlist
+    end
+
     def self.codecs(options = {})
       item = PlaylistItem.new(options)
       item.codecs
@@ -55,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.1.0'
+  VERSION = '1.3.0'
 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)