m3u8 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00157be29743342bb6156539b9fca6a1e67ae9ae60e74cab04eebeda10a888ec
-  data.tar.gz: f82b069b8fef0ce72694b11640431b25ea04caa7616ee69ab6c56e9f9029fdc3
+  metadata.gz: 6aa8d6835f0eba8dae6c9cd066c09c184e9a940cd4623dc6a8820b3ca3194c03
+  data.tar.gz: 372db49600b9957e662a061d3458a28a992c0050f13488db1ad621b6f2e9181e
 SHA512:
-  metadata.gz: 659a5a703d0a00887b9dc724bb252aeb56fb44010756772f8667b62ebd77b34b6b3a4f647c0c6aaf46cdfbfafbdf5173b59db2f1a84efa34fd4c5b4aafbab732
-  data.tar.gz: 07a539694c4231895fd0f7eebfb18f860c0dbbcbdd0f63e31b50ce7485937dc84fcac198ad443f9f6591bed7c17d32839bae7aba3904e452781e98520f21153c
+  metadata.gz: bc706ed5149e62a8dbdfc57fc351a8c2fcadbefc91731621446ec08d958a3f22e56490e48f5e2dc983d829d0c208fec38ca504f8f1d76334fd0387730b7be634
+  data.tar.gz: 1779b54ffacfe7ca0a25a4091ed837f3c7c3c40b6ff7dd8bd8e780614bf714e036434fa537db35dbc653f69e8b980e64a52055c90de61f66730ead28561d1321

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+**1.9.0**
+
+* Added `to_h`, `as_json`, and `to_json` to `Playlist` and all item
+  classes, with `Playlist.from_h` to rebuild a playlist from a Hash or
+  parsed JSON. Each serialized item carries an `item_type` key.
+* Added a strict parsing mode via `Playlist.read(input, strict: true)`,
+  plus a `Playlist#unknown_tags` accessor that collects unrecognized
+  `#EXT` tags instead of silently dropping them.
+* Added `Playlist#resolve_variables` to apply `EXT-X-DEFINE` variable
+  substitution (`NAME`/`VALUE`, `IMPORT`, and `QUERYPARAM`).
+* Added `Playlist#warnings` reporting non-fatal conformance advisories:
+  protocol-version compatibility and Low-Latency HLS recommendations.
+  The `validate` CLI command prints them under a `Warnings:` heading.
+* Added a `--json` option to the `inspect` CLI command and a new `diff`
+  command for comparing two playlists.
+* Fixed a missing `require 'time'` that raised `NoMethodError` when
+  parsing a playlist containing `EXT-X-PROGRAM-DATE-TIME` without the
+  `time` library already loaded.
+
+***
+
 **1.8.1**
 
 * Merged pull request #59 from [marocchino](https://github.com/marocchino).

data/README.md

@@ -70,6 +70,13 @@ Reads from stdin when no file is given:
 $ cat playlist.m3u8 | m3u8 inspect
 ```
 
+Pass `--json` to emit the playlist as JSON instead of the summary:
+
+```
+$ m3u8 inspect --json master.m3u8
+{"master":true,"version":null,...}
+```
+
 ### Validate
 
 Check playlist validity (exit 0 for valid, 1 for invalid):
@@ -83,6 +90,19 @@ Invalid
   - Playlist contains both master and media items
 ```
 
+### Diff
+
+Show structural differences between two playlists (exit 0 when identical,
+1 when they differ):
+
+```
+$ m3u8 diff old.m3u8 new.m3u8
+  version: 4 => 7
+  target: 12 => 6
+  items[2].duration: 5.0 => 6.0
+  items[5]: added SegmentItem
+```
+
 ## Usage (Builder DSL)
 
 `Playlist.build` provides a block-based DSL for concise playlist construction. It supports two forms:
@@ -487,6 +507,19 @@ The following validations are performed:
 
 `valid?` delegates to `errors.empty?` and both are recomputed on each call.
 
+Separately, `warnings` returns non-fatal conformance advisories that do not
+affect `valid?`: protocol-version compatibility (e.g. `EXT-X-MAP` requires
+version 6) and Low-Latency HLS recommendations (`PART-HOLD-BACK` and
+`CAN-SKIP-UNTIL` thresholds, required `EXT-X-PART-INF`):
+
+```ruby
+playlist.warnings
+# => ["EXT-X-MAP requires version 6 (version 5)"]
+```
+
+The `m3u8 validate` command prints these under a `Warnings:` heading after
+the validity result.
+
 ## Usage (parsing playlists)
 
 ```ruby
@@ -496,6 +529,34 @@ playlist.master?
 # => true
 ```
 
+By default, unrecognized `#EXT` tags are ignored and collected in
+`unknown_tags`. Pass `strict: true` to raise on the first one instead:
+
+```ruby
+playlist = M3u8::Playlist.read(file)
+playlist.unknown_tags
+# => ["#EXT-X-FUTURE-TAG:1"]
+
+M3u8::Playlist.read(file, strict: true)
+# => raises M3u8::InvalidPlaylistError on an unsupported tag
+```
+
+`EXT-X-DEFINE` variables are preserved verbatim on parse. Call
+`resolve_variables` to expand `{$NAME}` references (in URIs and string
+attribute values) into a new playlist:
+
+```ruby
+resolved = playlist.resolve_variables
+# IMPORT and QUERYPARAM definitions take their values from arguments:
+resolved = playlist.resolve_variables(
+  imported: { 'host' => 'https://cdn.example.com' },
+  query: { 'token' => 'abc123' }
+)
+```
+
+Resolving raises `M3u8::InvalidPlaylistError` for an undefined reference
+or a missing IMPORT/QUERYPARAM value.
+
 Query playlist properties:
 
 ```ruby
@@ -555,6 +616,34 @@ playlist.part_inf.part_target
 
 M3u8::Reader is the class that handles parsing if you want more control over the process.
 
+## Serialization (Hash and JSON)
+
+Convert a playlist (and every item) to a plain Hash or JSON for interop with
+other tooling, and rebuild a playlist from that Hash or JSON:
+
+```ruby
+playlist = M3u8::Playlist.read(File.open('spec/fixtures/master.m3u8'))
+
+hash = playlist.to_h
+# => { master: true, version: nil, ..., items: [{ ..., item_type: "PlaylistItem" }] }
+
+json = playlist.to_json
+# => "{\"master\":true,...}"
+
+# Each item also responds to to_h / as_json / to_json
+playlist.playlists.first.to_h
+# => { program_id: "1", codecs: "avc1.640028,mp4a.40.2", bandwidth: 5_042_000, ... }
+
+# Rebuild from a Hash or from parsed JSON
+M3u8::Playlist.from_h(hash)
+M3u8::Playlist.from_h(JSON.parse(json))
+```
+
+Each item Hash carries an `:item_type` key identifying its class, which
+`from_h` uses to reconstruct the correct item. Defining `to_json`/`as_json`
+overrides the generic implementations that the `json` library and
+ActiveSupport otherwise provide for these objects.
+
 ## Codec string generation
 
 Generate the codec string based on audio and video codec options without dealing with a playlist instance:

data/lib/m3u8/bitrate_item.rb

@@ -4,6 +4,8 @@ module M3u8
   # BitrateItem represents an EXT-X-BITRATE tag that indicates the
   # approximate bitrate of the following media segments in kbps.
   class BitrateItem
+    include Serializable
+
     # @return [Integer, nil] approximate bitrate in kbps
     attr_accessor :bitrate
 

data/lib/m3u8/byte_range.rb

@@ -3,6 +3,8 @@
 module M3u8
   # ByteRange represents sub range of a resource
   class ByteRange
+    include Serializable
+
     # @return [Integer, nil] number of bytes
     # @return [Integer, nil] start offset in bytes
     attr_accessor :length, :start

data/lib/m3u8/cli/diff_command.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module M3u8
+  class CLI
+    # DiffCommand reports structural differences between two playlists
+    # by comparing their normalized Hash representations.
+    class DiffCommand
+      def initialize(first, second, stdout)
+        @first = first.to_h
+        @second = second.to_h
+        @stdout = stdout
+      end
+
+      def run
+        if @first == @second
+          @stdout.puts 'Identical'
+          return 0
+        end
+
+        diff_hash('', without_items(@first), without_items(@second))
+        diff_items
+        1
+      end
+
+      private
+
+      def without_items(hash)
+        hash.except(:items)
+      end
+
+      def diff_items
+        first = @first[:items]
+        second = @second[:items]
+        (0...[first.size, second.size].max).each do |index|
+          diff_item(index, first[index], second[index])
+        end
+      end
+
+      def diff_item(index, first, second)
+        return if first == second
+
+        if first.nil?
+          @stdout.puts "  items[#{index}]: added #{second[:item_type]}"
+        elsif second.nil?
+          @stdout.puts "  items[#{index}]: removed #{first[:item_type]}"
+        else
+          diff_hash("items[#{index}].", first, second)
+        end
+      end
+
+      def diff_hash(prefix, first, second)
+        (first.keys | second.keys).each do |key|
+          next if first[key] == second[key]
+
+          @stdout.puts "  #{prefix}#{key}: " \
+                       "#{first[key].inspect} => #{second[key].inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/m3u8/cli/inspect_command.rb

@@ -7,12 +7,15 @@ module M3u8
       MEDIA_WIDTH = 12
       MASTER_WIDTH = 23
 
-      def initialize(playlist, stdout)
+      def initialize(playlist, stdout, json: false)
         @playlist = playlist
         @stdout = stdout
+        @json = json
       end
 
       def run
+        return print_json if @json
+
         if @playlist.master?
           print_master
         else
@@ -23,6 +26,11 @@ module M3u8
 
       private
 
+      def print_json
+        @stdout.puts @playlist.to_json
+        0
+      end
+
       def print_media
         field 'Type', 'Media', MEDIA_WIDTH
         field 'Version', @playlist.version, MEDIA_WIDTH

data/lib/m3u8/cli/validate_command.rb

@@ -10,6 +10,14 @@ module M3u8
       end
 
       def run
+        code = report_validity
+        report_warnings
+        code
+      end
+
+      private
+
+      def report_validity
         if @playlist.valid?
           @stdout.puts 'Valid'
           0
@@ -19,6 +27,14 @@ module M3u8
           1
         end
       end
+
+      def report_warnings
+        warnings = @playlist.warnings
+        return if warnings.empty?
+
+        @stdout.puts 'Warnings:'
+        warnings.each { |warning| @stdout.puts "  - #{warning}" }
+      end
     end
   end
 end

data/lib/m3u8/cli.rb

@@ -3,12 +3,13 @@
 require 'optparse'
 require_relative 'cli/inspect_command'
 require_relative 'cli/validate_command'
+require_relative 'cli/diff_command'
 
 module M3u8
   # CLI provides a command-line interface for inspecting and validating
   # m3u8 playlists
   class CLI
-    COMMANDS = %w[inspect validate].freeze
+    COMMANDS = %w[inspect validate diff].freeze
 
     def self.run(argv, stdin, stdout, stderr)
       new(argv, stdin, stdout, stderr).run
@@ -32,12 +33,21 @@ module M3u8
     private
 
     def parse_global_options
-      @parser = OptionParser.new do |opts|
+      @parser = build_parser
+      @exit_code = catch(:exit) do
+        @parser.order!(@argv)
+        nil
+      end
+    end
+
+    def build_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 '  inspect    Show playlist metadata (--json for JSON)'
         opts.separator '  validate   Check playlist validity'
+        opts.separator '  diff       Show differences between two playlists'
         opts.separator ''
         opts.on('-v', '--version', 'Show version') do
           @stdout.puts M3u8::VERSION
@@ -48,11 +58,6 @@ module M3u8
           throw :exit, 0
         end
       end
-
-      @exit_code = catch(:exit) do
-        @parser.order!(@argv)
-        nil
-      end
     end
 
     def dispatch
@@ -63,24 +68,53 @@ module M3u8
       return usage_error("unknown command: #{command}") \
         unless COMMANDS.include?(command)
 
+      return run_diff if command == 'diff'
+
+      run_single(command)
+    end
+
+    def run_single(command)
+      json = !@argv.delete('--json').nil?
+      if json && command != 'inspect'
+        return usage_error('--json is only supported for inspect')
+      end
+
       input = resolve_input
       return 2 unless input
 
       playlist = parse_playlist(input)
       return 2 unless playlist
 
-      execute_command(command, playlist)
+      execute_command(command, playlist, json)
     end
 
-    def execute_command(command, playlist)
+    def execute_command(command, playlist, json)
       case command
       when 'inspect'
-        InspectCommand.new(playlist, @stdout).run
+        InspectCommand.new(playlist, @stdout, json: json).run
       when 'validate'
         ValidateCommand.new(playlist, @stdout).run
       end
     end
 
+    def run_diff
+      first = @argv.shift
+      second = @argv.shift
+      return usage_error('diff requires two files') if first.nil? || second.nil?
+
+      playlists = [parse_file(first), parse_file(second)]
+      return 2 if playlists.any?(&:nil?)
+
+      DiffCommand.new(playlists[0], playlists[1], @stdout).run
+    end
+
+    def parse_file(path)
+      input = read_file(path)
+      return if input.nil?
+
+      parse_playlist(input)
+    end
+
     def resolve_input
       file = @argv.shift
       if file

data/lib/m3u8/content_steering_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # indicates a Content Steering Manifest for dynamic pathway selection.
   class ContentSteeringItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] steering manifest server URI

data/lib/m3u8/date_range_item.rb

@@ -4,6 +4,7 @@ module M3u8
   # DateRangeItem represents a #EXT-X-DATERANGE tag
   class DateRangeItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] unique date range identifier

data/lib/m3u8/define_item.rb

@@ -6,6 +6,7 @@ module M3u8
   # exclusive modes: NAME/VALUE, IMPORT, or QUERYPARAM.
   class DefineItem
     extend M3u8
+    include Serializable
 
     # @return [String, nil] variable name
     # @return [String, nil] variable value

data/lib/m3u8/discontinuity_item.rb

@@ -4,6 +4,8 @@ module M3u8
   # DiscontinuityItem represents a EXT-X-DISCONTINUITY tag to indicate a
   # discontinuity between the SegmentItems that proceed and follow it.
   class DiscontinuityItem
+    include Serializable
+
     # Render as an m3u8 EXT-X-DISCONTINUITY tag.
     # @return [String]
     def to_s

data/lib/m3u8/encryptable.rb

@@ -25,6 +25,16 @@ module M3u8
       base.send :attr_accessor, :key_format_versions
     end
 
+    # Initialize from HLS attribute names or normalized symbol keys,
+    # storing only the normalized keys.
+    # @param params [Hash] attribute key-value pairs
+    def initialize(params = {})
+      convert_key_names(params).each do |key, value|
+        value = params[key] if value.nil?
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
     # Render encryption attributes as a comma-separated string.
     # @return [String]
     def attributes_to_s

data/lib/m3u8/gap_item.rb

@@ -5,6 +5,8 @@ module M3u8
   # to which it applies does not contain media data and should not be
   # loaded by clients.
   class GapItem
+    include Serializable
+
     # Render as an m3u8 EXT-X-GAP tag.
     # @return [String]
     def to_s

data/lib/m3u8/key_item.rb

@@ -5,14 +5,7 @@ module M3u8
   class KeyItem
     include Encryptable
     extend M3u8
-
-    # @param params [Hash] attribute key-value pairs
-    def initialize(params = {})
-      options = convert_key_names(params)
-      options.merge(params).each do |key, value|
-        instance_variable_set("@#{key}", value)
-      end
-    end
+    include Serializable
 
     # Parse an EXT-X-KEY tag.
     # @param text [String] raw tag line

data/lib/m3u8/map_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # Initialization Section
   class MapItem
     extend M3u8
+    include Serializable
     include M3u8
     include AttributeFormatter
 

data/lib/m3u8/media_item.rb

@@ -4,6 +4,7 @@ module M3u8
   # MediaItem represents a set of EXT-X-MEDIA attributes
   class MediaItem
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [String, nil] media type (AUDIO, VIDEO, etc.)

data/lib/m3u8/part_inf_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # information about partial segments in the playlist.
   class PartInfItem
     extend M3u8
+    include Serializable
 
     # @return [Float, nil] partial segment target duration
     attr_accessor :part_target

data/lib/m3u8/part_item.rb

@@ -5,6 +5,7 @@ module M3u8
   # segments.
   class PartItem
     extend M3u8
+    include Serializable
     include M3u8
     include AttributeFormatter
 

data/lib/m3u8/playback_start.rb

@@ -4,6 +4,7 @@ module M3u8
   # PlaybackStart represents a #EXT-X-START tag and attributes
   class PlaybackStart
     extend M3u8
+    include Serializable
     include AttributeFormatter
 
     # @return [Float, nil] time offset in seconds