m3u8 0.8.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 79a1150cd18985b297585a60de9670a486eb1206
-  data.tar.gz: 723fc2ccb9856cadb5758678861e3e57b853d2c6
+SHA256:
+  metadata.gz: 2be533f088c62f6247e71b571a4481c92e56f8d575511ecae16be472dd90006a
+  data.tar.gz: 3d6de6bef331beefea33a156f6129dbcb30c89b195d807440acd740b53027a1b
 SHA512:
-  metadata.gz: 1ebb81bf922cee507b51beb8f608d7779a4ff35d64b935760e285675ce8715ae4e036748f622bdb91b762daf291e267fa1374bf6252631743582374be55fc611
-  data.tar.gz: 4983b2b1cb6826eb5293bf5df6011e203ed9067cac4a4e218a3e2537c9948f0dda8318028156cf3e5a9b392f1aa2a2418d61651223c2a14a59d58b86902d6e19
+  metadata.gz: edd32a67f619c6fd6b234163cbd16837cd92100f9d84f3729dd1ab09d6fdb1467f8cdab9e89cf64db344d4bb4359620c7aaad3d8532cb33195734a8c22833874
+  data.tar.gz: c24310d02ff3f844640618cf73fba927fd06bdf2f24e0c20d65166b459092f605d59f1ad408853342c3196e3eceed9535ef08a71c7c75bed8024d5f6383d2f8e

data/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', '3.3']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec
+      - name: Run linter
+        run: bundle exec rubocop

data/.rubocop.yml

@@ -1,9 +1,40 @@
 AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
   Exclude:
     - 'spec/spec_helper.rb'
     - 'm3u8.gemspec'
+    - 'vendor/**/*'
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'spec/**/*'
+Metrics/AbcSize:
+  Max: 35
+  Exclude:
+    - 'spec/**/*'
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
 Style/StringLiterals:
   EnforcedStyle: single_quotes
+Style/StringConcatenation:
+  Exclude:
+    - 'spec/**/*'
+Lint/FloatComparison:
+  Enabled: false
+Lint/DuplicateMethods:
+  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false

data/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Development Workflow
+
+- Small commits that can each be deployed independently
+- Each commit must not break production (CI/CD safe)
+- 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, Start, Stop, Document, Reword
+
+## Development Standards
+
+- **Tests must cover all behavior** - check with `coverage/index.html` after running specs
+- RuboCop enforces 80-char line limit and other style
+
+## Deployment
+
+Never deploy anything.

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+**1.0.0**
+
+* Full HLS spec compliance with draft-pantos-hls-rfc8216bis-19 (Protocol Version 13).
+* Added Low-Latency HLS support: `EXT-X-PART`, `EXT-X-PART-INF`, `EXT-X-SERVER-CONTROL`, `EXT-X-SKIP`, `EXT-X-PRELOAD-HINT`, `EXT-X-RENDITION-REPORT`.
+* Added HEVC/H.265 and AV1 video codec string generation.
+* Added AC-3, E-AC-3, FLAC, and Opus audio codec string generation.
+* Added new attributes to `PlaylistItem`: `STABLE-VARIANT-ID`, `VIDEO-RANGE`, `ALLOWED-CPC`, `PATHWAY-ID`, `REQ-VIDEO-LAYOUT`, `SUPPLEMENTAL-CODECS`, `SCORE`.
+* Added new attributes to `MediaItem`: `STABLE-RENDITION-ID`, `BIT-DEPTH`, `SAMPLE-RATE`.
+* Added `EXT-X-CONTENT-STEERING` tag support.
+* Added `EXT-X-DEFINE` tag support.
+* Added `EXT-X-GAP` and `EXT-X-BITRATE` tag support.
+* Upgraded CI from Travis CI to GitHub Actions.
+* Requires Ruby 3.0+.
+
+***
+
 **0.8.1**
 Merged pull request #23 from [ryanische](https:/github.com/ryanische) which fixes issue of CODEC attribute validation not matching the HLS I-D.
 

data/CLAUDE.md

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

data/Gemfile

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in m3u8.gemspec

data/Guardfile

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 guard :rspec, cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }

data/README.md

@@ -1,18 +1,18 @@
 [![Gem Version](https://badge.fury.io/rb/m3u8.svg)](http://badge.fury.io/rb/m3u8)
-[![Build Status](https://travis-ci.org/sethdeckard/m3u8.svg?branch=master)](https://travis-ci.org/sethdeckard/m3u8)
-[![Coverage Status](https://coveralls.io/repos/github/sethdeckard/m3u8/badge.svg?branch=master)](https://coveralls.io/github/sethdeckard/m3u8?branch=master)
-[![Code Climate](https://codeclimate.com/github/sethdeckard/m3u8/badges/gpa.svg)](https://codeclimate.com/github/sethdeckard/m3u8)
-[![Dependency Status](https://gemnasium.com/sethdeckard/m3u8.svg)](https://gemnasium.com/sethdeckard/m3u8)
-[![security](https://hakiri.io/github/sethdeckard/m3u8/master.svg)](https://hakiri.io/github/sethdeckard/m3u8/master)
+[![CI](https://github.com/sethdeckard/m3u8/actions/workflows/ci.yml/badge.svg)](https://github.com/sethdeckard/m3u8/actions/workflows/ci.yml)
 # m3u8
 
-m3u8 provides easy generation and parsing of m3u8 playlists defined in the [HTTP Live Streaming (HLS)](https://tools.ietf.org/html/draft-pantos-http-live-streaming-20) Internet Draft published by Apple.
+m3u8 provides easy generation and parsing of m3u8 playlists defined in the [HTTP Live Streaming (HLS)](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis) Internet Draft published by Apple.
 
-* The library completely implements version 20 of the HLS Internet Draft.
+* Full coverage of [draft-pantos-hls-rfc8216bis-19](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-19) (Protocol Version 13), including Low-Latency HLS and Content Steering.
 * Provides parsing of an m3u8 playlist into an object model from any File, StringIO, or string.
 * Provides ability to write playlist to a File or StringIO or expose as string via to_s.
 * Distinction between a master and media playlist is handled automatically (single Playlist class).
-* Optionally, the library can automatically generate the audio/video codecs string used in the CODEC attribute based on specified H.264, AAC, or MP3 options (such as Profile/Level).
+* Automatic generation of codec strings for H.264, HEVC, AV1, AAC, AC-3, E-AC-3, FLAC, Opus, and MP3.
+
+## Requirements
+
+Ruby 3.0+
 
 ## Installation
 
@@ -31,7 +31,7 @@ Or install it yourself as:
     $ gem install m3u8
 
 ## Usage (creating playlists)
-    
+
 Create a master playlist and add child playlists for adaptive bitrate streaming:
 
 ```ruby
@@ -46,8 +46,8 @@ options = { width: 1920, height: 1080, profile: 'high', level: 4.1,
             audio_codec: 'aac-lc', bandwidth: 540, uri: 'test.url' }
 item = M3u8::PlaylistItem.new(options)
 playlist.items << item
-```    
- 
+```
+
 Add alternate audio, camera angles, closed captions and subtitles by creating MediaItem instances and adding them to the Playlist:
 
 ```ruby
@@ -57,8 +57,25 @@ hash = { type: 'AUDIO', group_id: 'audio-lo', language: 'fre',
 item = M3u8::MediaItem.new(hash)
 playlist.items << item
 ```
-  
-Create a standard playlist and add MPEG-TS segments via SegmentItem. You can also specify options for this type of playlist, however these options are ignored if playlist becomes a master playlist (anything but segments added):
+
+Add Content Steering for dynamic CDN pathway selection:
+
+```ruby
+item = M3u8::ContentSteeringItem.new(
+  server_uri: 'https://example.com/steering',
+  pathway_id: 'CDN-A'
+)
+playlist.items << item
+```
+
+Add variable definitions:
+
+```ruby
+item = M3u8::DefineItem.new(name: 'base', value: 'https://example.com')
+playlist.items << item
+```
+
+Create a standard playlist and add MPEG-TS segments via SegmentItem:
 
 ```ruby
 options = { version: 1, cache: false, target: 12, sequence: 1 }
@@ -67,7 +84,42 @@ playlist = M3u8::Playlist.new(options)
 item = M3u8::SegmentItem.new(duration: 11, segment: 'test.ts')
 playlist.items << item
 ```
-    
+
+### Low-Latency HLS
+
+Create an LL-HLS playlist with server control, partial segments, and preload hints:
+
+```ruby
+server_control = M3u8::ServerControlItem.new(
+  can_skip_until: 24.0, part_hold_back: 1.0,
+  can_block_reload: true
+)
+part_inf = M3u8::PartInfItem.new(part_target: 0.5)
+playlist = M3u8::Playlist.new(
+  version: 9, target: 4, sequence: 100,
+  server_control: server_control, part_inf: part_inf,
+  live: true
+)
+
+item = M3u8::SegmentItem.new(duration: 4.0, segment: 'seg100.mp4')
+playlist.items << item
+
+part = M3u8::PartItem.new(
+  duration: 0.5, uri: 'seg101.0.mp4', independent: true
+)
+playlist.items << part
+
+hint = M3u8::PreloadHintItem.new(type: 'PART', uri: 'seg101.1.mp4')
+playlist.items << hint
+
+report = M3u8::RenditionReportItem.new(
+  uri: '../alt/index.m3u8', last_msn: 101, last_part: 0
+)
+playlist.items << report
+```
+
+### Writing playlists
+
 You can pass an IO object to the write method:
 
 ```ruby
@@ -80,7 +132,7 @@ You can also access the playlist as a string:
 
 ```ruby
 playlist.to_s
-``` 
+```
 
 M3u8::Writer is the class that handles generating the playlist output.
 
@@ -92,7 +144,6 @@ options = { width: 1920, height: 1080, codecs: 'avc1.66.30,mp4a.40.2',
 item = M3u8::PlaylistItem.new(options)
 ```
 
-
 ## Usage (parsing playlists)
 
 ```ruby
@@ -106,42 +157,93 @@ Access items in playlist:
 
 ```ruby
 playlist.items.first
-#  => #<M3u8::PlaylistItem:0x007fa569bc7698 @program_id="1", @resolution="1920x1080", 
-#  @codecs="avc1.640028,mp4a.40.2", @bandwidth="5042000", 
-#  @playlist="hls/1080-7mbps/1080-7mbps.m3u8">
+#  => #<M3u8::PlaylistItem ...>
 ```
 
-Create a new playlist item with options:
+Parse an LL-HLS playlist:
 
 ```ruby
-options = { width: 1920, height: 1080, profile: 'high', level: 4.1,
-            audio_codec: 'aac-lc', bandwidth: 540, uri: 'test.url' }
-item = M3u8::PlaylistItem.new(options)
-#add it to the top of the playlist
-playlist.items.unshift(item)
+file = File.open 'spec/fixtures/ll_hls_playlist.m3u8'
+playlist = M3u8::Playlist.read(file)
+playlist.server_control.can_block_reload
+# => true
+playlist.part_inf.part_target
+# => 0.5
 ```
 
-M3u8::Reader is the class handles parsing if you want more control over the process.
+M3u8::Reader is the class that handles parsing if you want more control over the process.
 
-## Usage (misc)
-Generate the codec string based on audio and video codec options without dealing a playlist instance:
+## Codec string generation
+
+Generate the codec string based on audio and video codec options without dealing with a playlist instance:
 
 ```ruby
 options = { profile: 'baseline', level: 3.0, audio_codec: 'aac-lc' }
 codecs = M3u8::Playlist.codecs(options)
 # => "avc1.66.30,mp4a.40.2"
-```  
-      
-* Values for audio_codec (codec name): aac-lc, he-aac, mp3   
-* Values for profile (H.264 Profile): baseline, main, high.
-* Values for level (H.264 Level): 3.0, 3.1, 4.0, 4.1. 
-
-Not all Levels and Profiles can be combined and validation is not currently implemented, consult H.264 documentation for further details.
-
+```
 
-## Roadmap 
-* Implement validation of all tags, attributes, and values per HLS I-D.
-* Perhaps support for different versions of HLS I-D, defaulting to latest.
+### Video codecs
+
+| Profile | Description |
+|---------|-------------|
+| `baseline`, `main`, `high` | H.264/AVC |
+| `hevc-main`, `hevc-main-10` | HEVC/H.265 |
+| `av1-main`, `av1-high` | AV1 |
+
+### Audio codecs
+
+| Value | Codec |
+|-------|-------|
+| `aac-lc` | AAC-LC |
+| `he-aac` | HE-AAC |
+| `mp3` | MP3 |
+| `ac-3` | AC-3 (Dolby Digital) |
+| `ec-3`, `e-ac-3` | E-AC-3 (Dolby Digital Plus) |
+| `flac` | FLAC |
+| `opus` | Opus |
+
+## Supported tags
+
+### Master playlist tags
+* `EXT-X-STREAM-INF` / `EXT-X-I-FRAME-STREAM-INF` — including `STABLE-VARIANT-ID`, `VIDEO-RANGE`, `ALLOWED-CPC`, `PATHWAY-ID`, `REQ-VIDEO-LAYOUT`, `SUPPLEMENTAL-CODECS`, `SCORE`
+* `EXT-X-MEDIA` — including `STABLE-RENDITION-ID`, `BIT-DEPTH`, `SAMPLE-RATE`
+* `EXT-X-SESSION-DATA`
+* `EXT-X-SESSION-KEY`
+* `EXT-X-CONTENT-STEERING`
+
+### Media playlist tags
+* `EXT-X-TARGETDURATION`
+* `EXT-X-MEDIA-SEQUENCE`
+* `EXT-X-DISCONTINUITY-SEQUENCE`
+* `EXT-X-PLAYLIST-TYPE`
+* `EXT-X-I-FRAMES-ONLY`
+* `EXT-X-ALLOW-CACHE`
+
+### Media segment tags
+* `EXTINF`
+* `EXT-X-BYTERANGE`
+* `EXT-X-DISCONTINUITY`
+* `EXT-X-KEY`
+* `EXT-X-MAP`
+* `EXT-X-PROGRAM-DATE-TIME`
+* `EXT-X-DATERANGE`
+* `EXT-X-GAP`
+* `EXT-X-BITRATE`
+
+### Universal tags
+* `EXT-X-INDEPENDENT-SEGMENTS`
+* `EXT-X-START`
+* `EXT-X-DEFINE`
+* `EXT-X-VERSION`
+
+### Low-Latency HLS tags
+* `EXT-X-SERVER-CONTROL`
+* `EXT-X-PART-INF`
+* `EXT-X-PART`
+* `EXT-X-SKIP`
+* `EXT-X-PRELOAD-HINT`
+* `EXT-X-RENDITION-REPORT`
 
 ## Contributing
 
@@ -152,6 +254,5 @@ Not all Levels and Profiles can be combined and validation is not currently impl
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
 
-
 ## License
 MIT License - See [LICENSE.txt](https://github.com/sethdeckard/m3u8/blob/master/LICENSE.txt) for details.

data/Rakefile

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 

data/lib/m3u8/bitrate_item.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module M3u8
+  # BitrateItem represents an EXT-X-BITRATE tag that indicates the
+  # approximate bitrate of the following media segments in kbps.
+  class BitrateItem
+    attr_accessor :bitrate
+
+    def initialize(params = {})
+      params.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse(text)
+      value = text.gsub('#EXT-X-BITRATE:', '').strip
+      BitrateItem.new(bitrate: value.to_i)
+    end
+
+    def to_s
+      "#EXT-X-BITRATE:#{bitrate}"
+    end
+  end
+end

data/lib/m3u8/byte_range.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   # ByteRange represents sub range of a resource
   class ByteRange
@@ -26,6 +27,7 @@ module M3u8
 
     def start_format
       return if start.nil?
+
       "@#{start}"
     end
   end

data/lib/m3u8/content_steering_item.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module M3u8
+  # ContentSteeringItem represents an EXT-X-CONTENT-STEERING tag which
+  # indicates a Content Steering Manifest for dynamic pathway selection.
+  class ContentSteeringItem
+    extend M3u8
+
+    attr_accessor :server_uri, :pathway_id
+
+    def initialize(params = {})
+      params.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      ContentSteeringItem.new(
+        server_uri: attributes['SERVER-URI'],
+        pathway_id: attributes['PATHWAY-ID']
+      )
+    end
+
+    def to_s
+      "#EXT-X-CONTENT-STEERING:#{formatted_attributes}"
+    end
+
+    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}")
+    end
+  end
+end

data/lib/m3u8/date_range_item.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
+
 module M3u8
   # DateRangeItem represents a #EXT-X-DATERANGE tag
   class DateRangeItem
     include M3u8
+
     attr_accessor :id, :class_name, :start_date, :end_date, :duration,
                   :planned_duration, :scte35_cmd, :scte35_out, :scte35_in,
                   :end_on_next, :client_attributes
@@ -24,7 +26,7 @@ module M3u8
       @scte35_cmd = attributes['SCTE35-CMD']
       @scte35_out = attributes['SCTE35-OUT']
       @scte35_in = attributes['SCTE35-IN']
-      @end_on_next = attributes.key?('END-ON-NEXT') ? true : false
+      @end_on_next = attributes.key?('END-ON-NEXT')
       @client_attributes = parse_client_attributes(attributes)
     end
 
@@ -50,26 +52,31 @@ module M3u8
 
     def class_name_format
       return if class_name.nil?
+
       %(CLASS="#{class_name}")
     end
 
     def end_date_format
       return if end_date.nil?
+
       %(END-DATE="#{end_date}")
     end
 
     def duration_format
       return if duration.nil?
+
       "DURATION=#{duration}"
     end
 
     def planned_duration_format
       return if planned_duration.nil?
+
       "PLANNED-DURATION=#{planned_duration}"
     end
 
     def client_attributes_format
-      return if client_attributes.nil?
+      return if client_attributes.nil? || client_attributes.empty?
+
       client_attributes.map do |attribute|
         value = attribute.last
         value_format = decimal?(value) ? value : %("#{value}")
@@ -78,31 +85,37 @@ module M3u8
     end
 
     def decimal?(value)
-      return true if value =~ /\A\d+\Z/
+      val = value.to_s
+      return true if val =~ /\A\d+\Z/
+
       begin
-        return true if Float(value)
-      rescue
+        true if Float(val)
+      rescue StandardError
         false
       end
     end
 
     def scte35_cmd_format
       return if scte35_cmd.nil?
+
       "SCTE35-CMD=#{scte35_cmd}"
     end
 
     def scte35_out_format
       return if scte35_out.nil?
+
       "SCTE35-OUT=#{scte35_out}"
     end
 
     def scte35_in_format
       return if scte35_in.nil?
+
       "SCTE35-IN=#{scte35_in}"
     end
 
     def end_on_next_format
       return unless end_on_next
+
       'END-ON-NEXT=YES'
     end
 

data/lib/m3u8/define_item.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module M3u8
+  # DefineItem represents an EXT-X-DEFINE tag which provides variable
+  # definitions for variable substitution. Supports three mutually
+  # exclusive modes: NAME/VALUE, IMPORT, or QUERYPARAM.
+  class DefineItem
+    extend M3u8
+
+    attr_accessor :name, :value, :import, :queryparam
+
+    def initialize(params = {})
+      params.each do |key, val|
+        instance_variable_set("@#{key}", val)
+      end
+    end
+
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      DefineItem.new(
+        name: attributes['NAME'],
+        value: attributes['VALUE'],
+        import: attributes['IMPORT'],
+        queryparam: attributes['QUERYPARAM']
+      )
+    end
+
+    def to_s
+      "#EXT-X-DEFINE:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      if import
+        %(IMPORT="#{import}")
+      elsif queryparam
+        %(QUERYPARAM="#{queryparam}")
+      else
+        %(NAME="#{name}",VALUE="#{value}")
+      end
+    end
+  end
+end

data/lib/m3u8/discontinuity_item.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   # DiscontinuityItem represents a EXT-X-DISCONTINUITY tag to indicate a
   # discontinuity between the SegmentItems that proceed and follow it.

data/lib/m3u8/encryptable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   # Encapsulates logic common to encryption key tags
   module Encryptable

data/lib/m3u8/error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   class InvalidPlaylistError < StandardError
   end

data/lib/m3u8/gap_item.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module M3u8
+  # GapItem represents an EXT-X-GAP tag to indicate that the segment URI
+  # to which it applies does not contain media data and should not be
+  # loaded by clients.
+  class GapItem
+    def to_s
+      '#EXT-X-GAP'
+    end
+  end
+end

data/lib/m3u8/key_item.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module M3u8
   # KeyItem represents a set of EXT-X-KEY attributes
   class KeyItem