m3u8 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c38180f01d16f00854720acaf6fc8359f2362417e19b8e45248a1573597716ca
-  data.tar.gz: b5192ed27a57a1f3a06d32f09d5d1fdbcd3c1e788d6bf515c68f739531ba8f23
+  metadata.gz: 395231edf55669bc7358629d116d5f7486a74bf1e7c5f6f9287497b758178511
+  data.tar.gz: f1592e2cd9cc9d175e3f06c7b330baffea7271ff1c153895865c35ed96e1c17e
 SHA512:
-  metadata.gz: be03dc5ca38934401073972dfab62b7ec35e4733eda199a91320b1b668e4046f04eae8518a720795d945bf7439da70ebe2d15d9bb53db3cd65cffedd3f70c0d9
-  data.tar.gz: a4faf2090ab7d3cd6c5788723a842d795903748e42a8ced6726af626ae81dc4373262074c2eeff70baae56c3b73c02d5a4a93d6caf84646d530092202c54dda1
+  metadata.gz: 7e0c36b5d0afbd29e1d822c020e0302c052c1051c2637e90795772165f9ca5f2a452ad9e4da593d895f88dbf3527d831829dc741dfbb9d2b88b9f8223f02b3c0
+  data.tar.gz: d7631c7d2cf13392f4a317c00f0cf7f90097695da58d20cdb5a76d66db01ce2e93643c48cfbf30d40f9b20260c793ffb9e430f0aea0f99c5c25d8c9c253fca93

data/.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2', '3.3']
+        ruby-version: ['3.1', '3.2', '3.3', '3.4']
     steps:
       - uses: actions/checkout@v4
       - name: Set up Ruby ${{ matrix.ruby-version }}

data/.gitignore

@@ -2,5 +2,5 @@
 /coverage
 /pkg
 /tmp
-.Gemfile.lock
+Gemfile.lock
 .ruby-version

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
   NewCops: enable
   SuggestExtensions: false
   Exclude:
@@ -24,7 +24,7 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Enabled: false
 Layout/LineLength:
-  Max: 120
+  Max: 80
   Exclude:
     - 'spec/**/*'
 Style/StringLiterals:

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+**1.8.0**
+
+* Standardized all item classes to use class-level `self.parse` methods,
+  converting `PlaybackStart`, `DateRangeItem`, `PlaylistItem`, and
+  `SegmentItem` from instance-level parse.
+* Applied `AttributeFormatter` to `MapItem` and `PartItem`, replacing
+  manual format helpers with `quoted_format` and `unquoted_format`.
+* Extracted `tag_value` helper in `Reader`, replacing repeated `gsub`
+  tag-prefix patterns.
+* Normalized `Reader` lambda syntax, converting `proc` blocks to
+  lambdas.
+* Removed `include M3u8` from `Reader` since all parsing now uses
+  class-level methods.
+* Added YARD `@param`/`@return` documentation to all public methods
+  and attributes across the entire codebase.
+
+***
+
 **1.7.0**
 
 * Added HLS Interstitials first-class `DateRangeItem` accessors:

data/Gemfile

@@ -4,3 +4,9 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in m3u8.gemspec
 gemspec
+
+gem 'rake'
+gem 'rspec', '>= 3.0'
+gem 'rubocop', require: false
+gem 'rubocop-rake', require: false
+gem 'simplecov', require: false

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2016 Seth Deckard
+Copyright (c) 2014-2026 Seth Deckard
 
 MIT License
 

data/README.md

@@ -12,7 +12,7 @@ m3u8 provides easy generation and parsing of m3u8 playlists defined in [RFC 8216
 
 ## Requirements
 
-Ruby 3.0+
+Ruby 3.1+
 
 ## Installation
 

data/lib/m3u8/attribute_formatter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Shared helpers for formatting HLS tag attributes
+  module AttributeFormatter
+    # Format a quoted attribute (e.g. KEY="value").
+    # @param key [String] attribute name
+    # @param value [Object, nil] attribute value
+    # @return [String, nil] formatted string or nil when value is nil
+    def quoted_format(key, value)
+      %(#{key}="#{value}") unless value.nil?
+    end
+
+    # Format an unquoted attribute (e.g. KEY=value).
+    # @param key [String] attribute name
+    # @param value [Object, nil] attribute value
+    # @return [String, nil] formatted string or nil when value is nil
+    def unquoted_format(key, value)
+      "#{key}=#{value}" unless value.nil?
+    end
+
+    # Format a YES/NO boolean attribute (e.g. KEY=YES).
+    # @param key [String] attribute name
+    # @param value [Boolean, nil] attribute value
+    # @return [String, nil] formatted string or nil when value is nil
+    def boolean_format(key, value)
+      "#{key}=#{value == true ? 'YES' : 'NO'}" unless value.nil?
+    end
+  end
+end

data/lib/m3u8/bitrate_item.rb

@@ -4,19 +4,26 @@ module M3u8
   # BitrateItem represents an EXT-X-BITRATE tag that indicates the
   # approximate bitrate of the following media segments in kbps.
   class BitrateItem
+    # @return [Integer, nil] approximate bitrate in kbps
     attr_accessor :bitrate
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
       params.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
+    # Parse an EXT-X-BITRATE tag.
+    # @param text [String] raw tag line
+    # @return [BitrateItem]
     def self.parse(text)
       value = text.gsub('#EXT-X-BITRATE:', '').strip
       BitrateItem.new(bitrate: value.to_i)
     end
 
+    # Render as an m3u8 EXT-X-BITRATE tag.
+    # @return [String]
     def to_s
       "#EXT-X-BITRATE:#{bitrate}"
     end

data/lib/m3u8/builder.rb

@@ -28,6 +28,7 @@ module M3u8
       gap: 'GapItem'
     }.freeze
 
+    # @param playlist [Playlist] playlist to build into
     def initialize(playlist)
       @playlist = playlist
     end

data/lib/m3u8/byte_range.rb

@@ -3,14 +3,20 @@
 module M3u8
   # ByteRange represents sub range of a resource
   class ByteRange
+    # @return [Integer, nil] number of bytes
+    # @return [Integer, nil] start offset in bytes
     attr_accessor :length, :start
 
+    # @param params [Hash] :length and optional :start
     def initialize(params = {})
       params.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
+    # Parse a byte range string (e.g. "4500@600").
+    # @param text [String] byte range string
+    # @return [ByteRange]
     def self.parse(text)
       values = text.split('@')
       length_value = values[0].to_i
@@ -19,6 +25,8 @@ module M3u8
       ByteRange.new(options)
     end
 
+    # Render as a byte range string (e.g. "4500@600").
+    # @return [String]
     def to_s
       "#{length}#{start_format}"
     end

data/lib/m3u8/codecs.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module M3u8
+  # Codec lookup tables for HLS playlist items
+  module Codecs
+    AUDIO_CODECS = {
+      'aac-lc' => 'mp4a.40.2',
+      'he-aac' => 'mp4a.40.5',
+      'mp3' => 'mp4a.40.34',
+      'ac-3' => 'ac-3',
+      'ec-3' => 'ec-3',
+      'e-ac-3' => 'ec-3',
+      'flac' => 'fLaC',
+      'opus' => 'Opus'
+    }.freeze
+
+    BASELINE_CODECS = {
+      3.0 => 'avc1.66.30',
+      3.1 => 'avc1.42001f'
+    }.freeze
+
+    MAIN_CODECS = {
+      3.0 => 'avc1.77.30',
+      3.1 => 'avc1.4d001f',
+      4.0 => 'avc1.4d0028',
+      4.1 => 'avc1.4d0029'
+    }.freeze
+
+    HIGH_LEVELS = [3.0, 3.1, 3.2, 4.0, 4.1, 4.2,
+                   5.0, 5.1, 5.2].freeze
+
+    HEVC_CODECS = {
+      ['hevc-main', 3.1] => 'hvc1.1.6.L93.B0',
+      ['hevc-main', 4.0] => 'hvc1.1.6.L120.B0',
+      ['hevc-main', 5.0] => 'hvc1.1.6.L150.B0',
+      ['hevc-main', 5.1] => 'hvc1.1.6.L153.B0',
+      ['hevc-main-10', 3.1] => 'hvc1.2.4.L93.B0',
+      ['hevc-main-10', 4.0] => 'hvc1.2.4.L120.B0',
+      ['hevc-main-10', 5.0] => 'hvc1.2.4.L150.B0',
+      ['hevc-main-10', 5.1] => 'hvc1.2.4.L153.B0'
+    }.freeze
+
+    AV1_CODECS = {
+      ['av1-main', 3.1] => 'av01.0.04M.08',
+      ['av1-main', 4.0] => 'av01.0.08M.08',
+      ['av1-main', 5.0] => 'av01.0.12M.08',
+      ['av1-main', 5.1] => 'av01.0.13M.08',
+      ['av1-high', 3.1] => 'av01.1.04H.10',
+      ['av1-high', 4.0] => 'av01.1.08H.10',
+      ['av1-high', 5.0] => 'av01.1.12H.10',
+      ['av1-high', 5.1] => 'av01.1.13H.10'
+    }.freeze
+
+    # Look up the codec string for an audio codec name.
+    # @param codec [String, nil] audio codec name
+    # @return [String, nil] codec string
+    def self.audio_codec(codec)
+      return if codec.nil?
+
+      AUDIO_CODECS[codec.downcase]
+    end
+
+    # Look up the codec string for a video profile and level.
+    # @param profile [String, nil] video profile name
+    # @param level [Float, Integer, nil] video level
+    # @return [String, nil] codec string
+    def self.video_codec(profile, level)
+      return if profile.nil? || level.nil?
+
+      level = level.to_f
+      name = profile.downcase
+      return BASELINE_CODECS[level] if name == 'baseline'
+      return MAIN_CODECS[level] if name == 'main'
+      return high_codec_string(level) if name == 'high'
+      return HEVC_CODECS[[profile, level]] if name.start_with?('hevc-')
+
+      AV1_CODECS[[profile, level]] if name.start_with?('av1-')
+    end
+
+    def self.high_codec_string(level)
+      return nil unless HIGH_LEVELS.include?(level)
+
+      hex = level.to_s.sub('.', '').to_i.to_s(16)
+      "avc1.6400#{hex}"
+    end
+
+    private_class_method :high_codec_string
+  end
+end

data/lib/m3u8/content_steering_item.rb

@@ -5,15 +5,22 @@ module M3u8
   # indicates a Content Steering Manifest for dynamic pathway selection.
   class ContentSteeringItem
     extend M3u8
+    include AttributeFormatter
 
+    # @return [String, nil] steering manifest server URI
+    # @return [String, nil] default pathway ID
     attr_accessor :server_uri, :pathway_id
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
       params.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
+    # Parse an EXT-X-CONTENT-STEERING tag.
+    # @param text [String] raw tag line
+    # @return [ContentSteeringItem]
     def self.parse(text)
       attributes = parse_attributes(text)
       ContentSteeringItem.new(
@@ -22,6 +29,8 @@ module M3u8
       )
     end
 
+    # Render as an m3u8 EXT-X-CONTENT-STEERING tag.
+    # @return [String]
     def to_s
       "#EXT-X-CONTENT-STEERING:#{formatted_attributes}"
     end
@@ -29,18 +38,8 @@ module M3u8
     private
 
     def formatted_attributes
-      [server_uri_format,
-       pathway_id_format].compact.join(',')
-    end
-
-    def server_uri_format
-      %(SERVER-URI="#{server_uri}")
-    end
-
-    def pathway_id_format
-      return if pathway_id.nil?
-
-      %(PATHWAY-ID="#{pathway_id}")
+      [quoted_format('SERVER-URI', server_uri),
+       quoted_format('PATHWAY-ID', pathway_id)].compact.join(',')
     end
   end
 end

data/lib/m3u8/date_range_item.rb

@@ -3,8 +3,30 @@
 module M3u8
   # DateRangeItem represents a #EXT-X-DATERANGE tag
   class DateRangeItem
-    include M3u8
-
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] unique date range identifier
+    # @return [String, nil] CLASS attribute
+    # @return [String, nil] start date (ISO 8601)
+    # @return [String, nil] end date (ISO 8601)
+    # @return [Float, nil] duration in seconds
+    # @return [Float, nil] planned duration in seconds
+    # @return [String, nil] SCTE-35 command hex string
+    # @return [String, nil] SCTE-35 out hex string
+    # @return [String, nil] SCTE-35 in hex string
+    # @return [String, nil] CUE attribute
+    # @return [Boolean, nil] END-ON-NEXT flag
+    # @return [Hash, nil] client-defined X- attributes
+    # @return [String, nil] interstitial asset URI
+    # @return [String, nil] interstitial asset list URI
+    # @return [Float, nil] interstitial resume offset
+    # @return [Float, nil] interstitial playout limit
+    # @return [String, nil] interstitial restrict value
+    # @return [String, nil] interstitial snap value
+    # @return [String, nil] interstitial timeline occupies
+    # @return [String, nil] interstitial timeline style
+    # @return [String, nil] content may vary flag
     attr_accessor :id, :class_name, :start_date, :end_date, :duration,
                   :planned_duration, :scte35_cmd, :scte35_out, :scte35_in,
                   :cue, :end_on_next, :client_attributes,
@@ -19,86 +41,114 @@ module M3u8
       X-CONTENT-MAY-VARY
     ].freeze
 
+    # @param options [Hash] attribute key-value pairs
     def initialize(options = {})
       options.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
     end
 
-    def parse(text)
+    # Parse an EXT-X-DATERANGE tag.
+    # @param text [String] raw tag line
+    # @return [DateRangeItem]
+    def self.parse(text)
       attributes = parse_attributes(text)
-      @id = attributes['ID']
-      @class_name = attributes['CLASS']
-      @start_date = attributes['START-DATE']
-      @end_date = attributes['END-DATE']
-      @duration = parse_float(attributes['DURATION'])
-      @planned_duration = parse_float(attributes['PLANNED-DURATION'])
-      @scte35_cmd = attributes['SCTE35-CMD']
-      @scte35_out = attributes['SCTE35-OUT']
-      @scte35_in = attributes['SCTE35-IN']
-      @cue = attributes['CUE']
-      @end_on_next = attributes.key?('END-ON-NEXT')
-      parse_interstitials(attributes)
-      @client_attributes = parse_client_attributes(attributes)
-    end
-
+      options = parse_base_attributes(attributes)
+                .merge(parse_interstitials(attributes))
+                .merge(client_attributes:
+                         parse_client_attributes(attributes))
+      DateRangeItem.new(options)
+    end
+
+    def self.parse_base_attributes(attributes)
+      { id: attributes['ID'],
+        class_name: attributes['CLASS'],
+        start_date: attributes['START-DATE'],
+        end_date: attributes['END-DATE'],
+        duration: parse_float(attributes['DURATION']),
+        planned_duration:
+          parse_float(attributes['PLANNED-DURATION']),
+        scte35_cmd: attributes['SCTE35-CMD'],
+        scte35_out: attributes['SCTE35-OUT'],
+        scte35_in: attributes['SCTE35-IN'],
+        cue: attributes['CUE'],
+        end_on_next: attributes.key?('END-ON-NEXT') }
+    end
+    private_class_method :parse_base_attributes
+
+    def self.parse_interstitials(attributes)
+      { asset_uri: attributes['X-ASSET-URI'],
+        asset_list: attributes['X-ASSET-LIST'],
+        resume_offset:
+          parse_float(attributes['X-RESUME-OFFSET']),
+        playout_limit:
+          parse_float(attributes['X-PLAYOUT-LIMIT']),
+        restrict: attributes['X-RESTRICT'],
+        snap: attributes['X-SNAP'],
+        timeline_occupies:
+          attributes['X-TIMELINE-OCCUPIES'],
+        timeline_style: attributes['X-TIMELINE-STYLE'],
+        content_may_vary:
+          attributes['X-CONTENT-MAY-VARY'] }
+    end
+    private_class_method :parse_interstitials
+
+    # Render as an m3u8 EXT-X-DATERANGE tag.
+    # @return [String]
     def to_s
       "#EXT-X-DATERANGE:#{formatted_attributes}"
     end
 
+    # Parse SCTE-35 command data.
+    # @return [Scte35, nil]
     def scte35_cmd_info
       Scte35.parse(scte35_cmd) unless scte35_cmd.nil?
     end
 
+    # Parse SCTE-35 out data.
+    # @return [Scte35, nil]
     def scte35_out_info
       Scte35.parse(scte35_out) unless scte35_out.nil?
     end
 
+    # Parse SCTE-35 in data.
+    # @return [Scte35, nil]
     def scte35_in_info
       Scte35.parse(scte35_in) unless scte35_in.nil?
     end
 
+    def self.parse_client_attributes(attributes)
+      attributes.select do |key|
+        key.start_with?('X-') && !INTERSTITIAL_KEYS.include?(key)
+      end
+    end
+    private_class_method :parse_client_attributes
+
     private
 
     def formatted_attributes
       [%(ID="#{id}"),
-       class_name_format,
+       quoted_format('CLASS', class_name),
        %(START-DATE="#{start_date}"),
-       end_date_format,
-       duration_format,
-       planned_duration_format,
+       quoted_format('END-DATE', end_date),
+       unquoted_format('DURATION', duration),
+       unquoted_format('PLANNED-DURATION', planned_duration),
        client_attributes_format,
        interstitial_formats,
-       scte35_cmd_format,
-       scte35_out_format,
-       scte35_in_format,
-       cue_format,
+       unquoted_format('SCTE35-CMD', scte35_cmd),
+       unquoted_format('SCTE35-OUT', scte35_out),
+       unquoted_format('SCTE35-IN', scte35_in),
+       quoted_format('CUE', cue),
        end_on_next_format].flatten.compact.join(',')
     end
 
-    def class_name_format
-      quoted_format('CLASS', class_name)
-    end
-
-    def end_date_format
-      quoted_format('END-DATE', end_date)
-    end
-
-    def duration_format
-      unquoted_format('DURATION', duration)
-    end
-
-    def planned_duration_format
-      unquoted_format('PLANNED-DURATION', planned_duration)
-    end
-
     def client_attributes_format
       return if client_attributes.nil? || client_attributes.empty?
 
       client_attributes.map do |attribute|
         value = attribute.last
-        value_format = decimal?(value) ? value : %("#{value}")
-        "#{attribute.first}=#{value_format}"
+        fmt = decimal?(value) ? value : %("#{value}")
+        "#{attribute.first}=#{fmt}"
       end
     end
 
@@ -113,76 +163,16 @@ module M3u8
       end
     end
 
-    def parse_interstitials(attributes)
-      @asset_uri = attributes['X-ASSET-URI']
-      @asset_list = attributes['X-ASSET-LIST']
-      @resume_offset = parse_float(attributes['X-RESUME-OFFSET'])
-      @playout_limit = parse_float(attributes['X-PLAYOUT-LIMIT'])
-      @restrict = attributes['X-RESTRICT']
-      @snap = attributes['X-SNAP']
-      @timeline_occupies = attributes['X-TIMELINE-OCCUPIES']
-      @timeline_style = attributes['X-TIMELINE-STYLE']
-      @content_may_vary = attributes['X-CONTENT-MAY-VARY']
-    end
-
     def interstitial_formats
-      [asset_uri_format, asset_list_format,
-       resume_offset_format, playout_limit_format,
-       restrict_format, snap_format,
-       timeline_occupies_format, timeline_style_format,
-       content_may_vary_format]
-    end
-
-    def asset_uri_format
-      quoted_format('X-ASSET-URI', asset_uri)
-    end
-
-    def asset_list_format
-      quoted_format('X-ASSET-LIST', asset_list)
-    end
-
-    def resume_offset_format
-      unquoted_format('X-RESUME-OFFSET', resume_offset)
-    end
-
-    def playout_limit_format
-      unquoted_format('X-PLAYOUT-LIMIT', playout_limit)
-    end
-
-    def restrict_format
-      quoted_format('X-RESTRICT', restrict)
-    end
-
-    def snap_format
-      quoted_format('X-SNAP', snap)
-    end
-
-    def timeline_occupies_format
-      quoted_format('X-TIMELINE-OCCUPIES', timeline_occupies)
-    end
-
-    def timeline_style_format
-      quoted_format('X-TIMELINE-STYLE', timeline_style)
-    end
-
-    def content_may_vary_format
-      quoted_format('X-CONTENT-MAY-VARY', content_may_vary)
-    end
-
-    def scte35_cmd_format
-      unquoted_format('SCTE35-CMD', scte35_cmd)
-    end
-
-    def scte35_out_format
-      unquoted_format('SCTE35-OUT', scte35_out)
-    end
-
-    def scte35_in_format
-      unquoted_format('SCTE35-IN', scte35_in)
-    end
-
-    def cue_format
-      quoted_format('CUE', cue)
+      [quoted_format('X-ASSET-URI', asset_uri),
+       quoted_format('X-ASSET-LIST', asset_list),
+       unquoted_format('X-RESUME-OFFSET', resume_offset),
+       unquoted_format('X-PLAYOUT-LIMIT', playout_limit),
+       quoted_format('X-RESTRICT', restrict),
+       quoted_format('X-SNAP', snap),
+       quoted_format('X-TIMELINE-OCCUPIES', timeline_occupies),
+       quoted_format('X-TIMELINE-STYLE', timeline_style),
+       quoted_format('X-CONTENT-MAY-VARY', content_may_vary)]
     end
 
     def end_on_next_format
@@ -190,19 +180,5 @@ module M3u8
 
       'END-ON-NEXT=YES'
     end
-
-    def quoted_format(key, value)
-      %(#{key}="#{value}") unless value.nil?
-    end
-
-    def unquoted_format(key, value)
-      "#{key}=#{value}" unless value.nil?
-    end
-
-    def parse_client_attributes(attributes)
-      attributes.select do |key|
-        key.start_with?('X-') && !INTERSTITIAL_KEYS.include?(key)
-      end
-    end
   end
 end

data/lib/m3u8/define_item.rb

@@ -7,14 +7,22 @@ module M3u8
   class DefineItem
     extend M3u8
 
+    # @return [String, nil] variable name
+    # @return [String, nil] variable value
+    # @return [String, nil] imported variable name
+    # @return [String, nil] query parameter name
     attr_accessor :name, :value, :import, :queryparam
 
+    # @param params [Hash] attribute key-value pairs
     def initialize(params = {})
       params.each do |key, val|
         instance_variable_set("@#{key}", val)
       end
     end
 
+    # Parse an EXT-X-DEFINE tag.
+    # @param text [String] raw tag line
+    # @return [DefineItem]
     def self.parse(text)
       attributes = parse_attributes(text)
       DefineItem.new(
@@ -25,6 +33,8 @@ module M3u8
       )
     end
 
+    # Render as an m3u8 EXT-X-DEFINE tag.
+    # @return [String]
     def to_s
       "#EXT-X-DEFINE:#{formatted_attributes}"
     end

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
+    # Render as an m3u8 EXT-X-DISCONTINUITY tag.
+    # @return [String]
     def to_s
       "#EXT-X-DISCONTINUITY\n"
     end