m3u8 0.8.2 → 1.8.1

data/lib/m3u8/part_item.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module M3u8
+  # PartItem represents an EXT-X-PART tag for Low-Latency HLS partial
+  # segments.
+  class PartItem
+    extend M3u8
+    include M3u8
+    include AttributeFormatter
+
+    # @return [String, nil] partial segment URI
+    # @return [Float, nil] partial segment duration
+    # @return [Boolean, nil] whether segment is independent
+    # @return [ByteRange, nil] byte range
+    # @return [Boolean, nil] whether segment is a gap
+    attr_accessor :uri, :duration, :independent, :byterange, :gap
+
+    # @param params [Hash] attribute key-value pairs
+    def initialize(params = {})
+      initialize_with_byterange(params)
+    end
+
+    # Parse an EXT-X-PART tag.
+    # @param text [String] raw tag line
+    # @return [PartItem]
+    def self.parse(text)
+      attributes = parse_attributes(text)
+      range_value = attributes['BYTERANGE']
+      range = ByteRange.parse(range_value) unless range_value.nil?
+      PartItem.new(
+        uri: attributes['URI'],
+        duration: attributes['DURATION'].to_f,
+        independent: parse_yes_no(attributes['INDEPENDENT']),
+        byterange: range,
+        gap: parse_yes_no(attributes['GAP'])
+      )
+    end
+
+    # Render as an m3u8 EXT-X-PART tag.
+    # @return [String]
+    def to_s
+      "#EXT-X-PART:#{formatted_attributes}"
+    end
+
+    private
+
+    def formatted_attributes
+      [unquoted_format('DURATION', decimal_format(duration)),
+       quoted_format('URI', uri),
+       independent_format,
+       quoted_format('BYTERANGE', byterange),
+       gap_format].compact.join(',')
+    end
+
+    def independent_format
+      return unless independent
+
+      'INDEPENDENT=YES'
+    end
+
+    def gap_format
+      return unless gap
+
+      'GAP=YES'
+    end
+  end
+end

data/lib/m3u8/playback_start.rb

@@ -1,34 +1,41 @@
 # frozen_string_literal: true
+
 module M3u8
   # PlaybackStart represents a #EXT-X-START tag and attributes
   class PlaybackStart
-    include M3u8
+    extend M3u8
+    include AttributeFormatter
+
+    # @return [Float, nil] time offset in seconds
+    # @return [Boolean, nil] whether start is precise
     attr_accessor :time_offset, :precise
 
+    # @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-START tag.
+    # @param text [String] raw tag line
+    # @return [PlaybackStart]
+    def self.parse(text)
       attributes = parse_attributes(text)
-      @time_offset = attributes['TIME-OFFSET'].to_f
       precise = attributes['PRECISE']
-      @precise = parse_yes_no(precise) unless precise.nil?
+      options = {
+        time_offset: attributes['TIME-OFFSET'].to_f,
+        precise: precise.nil? ? nil : parse_yes_no(precise)
+      }
+      PlaybackStart.new(options)
     end
 
+    # Render as an m3u8 EXT-X-START tag.
+    # @return [String]
     def to_s
       attributes = ["TIME-OFFSET=#{time_offset}",
-                    precise_format].compact.join(',')
+                    boolean_format('PRECISE', precise)].compact.join(',')
       "#EXT-X-START:#{attributes}"
     end
-
-    private
-
-    def precise_format
-      return if precise.nil?
-      "PRECISE=#{to_yes_no(precise)}"
-    end
   end
 end

data/lib/m3u8/playlist.rb

@@ -1,64 +1,188 @@
 # frozen_string_literal: true
+
 module M3u8
-  # Playlist represents an m3u8 playlist, it can be a master playlist or a set
-  # of media segments
+  # Playlist represents an m3u8 playlist, it can be a master playlist
+  # or a set of media segments
   class Playlist
+    # @return [Array] list of items in the playlist
+    # @return [Integer, nil] EXT-X-VERSION value
+    # @return [Boolean, nil] EXT-X-ALLOW-CACHE value
+    # @return [Integer] EXT-X-TARGETDURATION value
+    # @return [Integer] EXT-X-MEDIA-SEQUENCE value
+    # @return [Integer, nil] EXT-X-DISCONTINUITY-SEQUENCE value
+    # @return [String, nil] EXT-X-PLAYLIST-TYPE (VOD or EVENT)
+    # @return [Boolean] whether playlist is I-frames only
+    # @return [Boolean] whether segments are independent
+    # @return [Boolean] whether playlist is live
+    # @return [PartInfItem, nil] EXT-X-PART-INF item
+    # @return [ServerControlItem, nil] EXT-X-SERVER-CONTROL item
     attr_accessor :items, :version, :cache, :target, :sequence,
                   :discontinuity_sequence, :type, :iframes_only,
-                  :independent_segments, :live
+                  :independent_segments, :live, :part_inf,
+                  :server_control
 
+    # @param options [Hash] playlist attributes
     def initialize(options = {})
       assign_options(options)
       @items = []
     end
 
+    # Build a playlist using a DSL block.
+    # @param options [Hash] playlist attributes
+    # @yield [Builder] block receives builder instance
+    # @return [Playlist] frozen playlist
+    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.freeze
+    end
+
+    # Generate a codecs string from codec options.
+    # @param options [Hash] codec options (:profile, :level, etc.)
+    # @return [String, nil] codecs string
     def self.codecs(options = {})
       item = PlaylistItem.new(options)
       item.codecs
     end
 
+    # Parse an m3u8 playlist from a String or IO.
+    # @param input [String, IO] playlist content
+    # @return [Playlist] frozen playlist
     def self.read(input)
       reader = Reader.new
       reader.read(input)
     end
 
+    # Write the playlist to an IO object.
+    # @param output [IO] writable IO object
+    # @return [void]
     def write(output)
       writer = Writer.new(output)
       writer.write(self)
     end
 
+    # Whether this is a live (non-VOD) media playlist.
+    # @return [Boolean]
     def live?
       return false if master?
+
       @live
     end
 
+    # Whether this is a master (multivariant) playlist.
+    # @return [Boolean]
     def master?
       return @master unless @master.nil?
       return false if playlist_size.zero? && segment_size.zero?
-      playlist_size > 0
+
+      playlist_size.positive?
+    end
+
+    # Freeze the playlist and all its items.
+    # @return [Playlist]
+    def freeze
+      items.each { |item| freeze_item(item) }
+      items.freeze
+      part_inf&.freeze
+      server_control&.freeze
+      super
     end
 
+    # Render the playlist as an m3u8 string.
+    # @return [String]
     def to_s
       output = StringIO.open
       write(output)
       output.string
     end
 
+    # Collect validation errors for the playlist.
+    # @return [Array<String>] list of error messages
+    def errors
+      [].tap do |errors|
+        validate_mixed_items(errors)
+        validate_target_duration(errors)
+        validate_segment_items(errors)
+        validate_playlist_items(errors)
+        validate_media_items(errors)
+        validate_key_items(errors)
+        validate_session_key_items(errors)
+        validate_session_data_items(errors)
+        validate_part_items(errors)
+      end
+    end
+
+    # Whether the playlist passes all validations.
+    # @return [Boolean]
     def valid?
-      return false if playlist_size > 0 && segment_size > 0
-      true
+      errors.empty?
+    end
+
+    # @return [Array<SegmentItem>]
+    def segments
+      items.grep(SegmentItem)
+    end
+
+    # @return [Array<PlaylistItem>]
+    def playlists
+      items.grep(PlaylistItem)
+    end
+
+    # @return [Array<MediaItem>]
+    def media_items
+      items.grep(MediaItem)
+    end
+
+    # @return [Array<KeyItem>]
+    def keys
+      items.grep(KeyItem)
+    end
+
+    # @return [Array<MapItem>]
+    def maps
+      items.grep(MapItem)
+    end
+
+    # @return [Array<DateRangeItem>]
+    def date_ranges
+      items.grep(DateRangeItem)
+    end
+
+    # @return [Array<PartItem>]
+    def parts
+      items.grep(PartItem)
+    end
+
+    # @return [Array<SessionDataItem>]
+    def session_data
+      items.grep(SessionDataItem)
+    end
+
+    # @return [Array<SessionKeyItem>]
+    def session_keys
+      items.grep(SessionKeyItem)
     end
 
+    # Total duration of all segments.
+    # @return [Float]
     def duration
-      duration = 0.0
-      items.each do |item|
-        duration += item.duration if item.is_a?(M3u8::SegmentItem)
-      end
-      duration
+      segments.sum(&:duration)
     end
 
     private
 
+    def freeze_item(item)
+      item.byterange&.freeze if item.respond_to?(:byterange)
+      item.program_date_time&.freeze if item.respond_to?(:program_date_time)
+      item.client_attributes&.freeze if item.respond_to?(:client_attributes)
+      item.freeze
+    end
+
     def assign_options(options)
       options = defaults.merge(options)
 
@@ -72,6 +196,8 @@ module M3u8
       @independent_segments = options[:independent_segments]
       @master = options[:master]
       @live = options[:live]
+      @part_inf = options[:part_inf]
+      @server_control = options[:server_control]
     end
 
     def defaults
@@ -84,12 +210,94 @@ module M3u8
       }
     end
 
+    def validate_part_items(errors)
+      parts.each do |item|
+        errors << 'Part item requires a URI' if item.uri.nil?
+        errors << 'Part item requires a duration' if item.duration.nil?
+      end
+    end
+
+    def validate_session_data_items(errors)
+      session_data.each do |item|
+        errors << 'Session data item requires a data ID' if item.data_id.nil?
+        if !item.value.nil? && !item.uri.nil?
+          errors << 'Session data item cannot have both value and URI'
+        elsif item.value.nil? && item.uri.nil?
+          errors << 'Session data item requires a value or URI'
+        end
+      end
+    end
+
+    def validate_key_items(errors)
+      keys.each do |item|
+        next if item.method == 'NONE'
+
+        next unless item.uri.nil?
+
+        errors << 'Key item requires a URI ' \
+                  'when method is not NONE'
+      end
+    end
+
+    def validate_session_key_items(errors)
+      session_keys.each do |item|
+        next if item.method == 'NONE'
+
+        next unless item.uri.nil?
+
+        errors << 'Session key item requires a URI ' \
+                  'when method is not NONE'
+      end
+    end
+
+    def validate_playlist_items(errors)
+      playlists.each do |item|
+        unless item.bandwidth&.positive?
+          errors << 'Playlist item requires a bandwidth'
+        end
+        errors << 'Playlist item requires a URI' if item.uri.nil?
+      end
+    end
+
+    def validate_media_items(errors)
+      media_items.each do |item|
+        errors << 'Media item requires a type' if item.type.nil?
+        errors << 'Media item requires a group ID' if item.group_id.nil?
+        errors << 'Media item requires a name' if item.name.nil?
+      end
+    end
+
+    def validate_segment_items(errors)
+      segments.each do |segment|
+        errors << 'Segment item requires a segment URI' if segment.segment.nil?
+        if segment.duration&.negative?
+          errors << 'Segment item has negative duration'
+        end
+      end
+    end
+
+    def validate_target_duration(errors)
+      return if master?
+
+      max = segments.filter_map { |s| s.duration&.round }.max
+      return if max.nil? || target >= max
+
+      errors << "Target duration #{target} is less than " \
+                "segment duration of #{max}"
+    end
+
+    def validate_mixed_items(errors)
+      return unless playlist_size.positive? && segment_size.positive?
+
+      errors << 'Playlist contains both master and media items'
+    end
+
     def playlist_size
-      items.count { |item| item.is_a?(PlaylistItem) }
+      playlists.size
     end
 
     def segment_size
-      items.count { |item| item.is_a?(SegmentItem) }
+      segments.size
     end
   end
 end