Class: M3u8::Playlist

Inherits:
Object
  • Object
show all
Includes:
Serializable
Defined in:
lib/m3u8/playlist.rb

Overview

Playlist represents an m3u8 playlist, it can be a master playlist or a set of media segments

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Serializable

#as_json, serialize, #to_json

Constructor Details

#initialize(options = {}) ⇒ Playlist

Returns a new instance of Playlist.

Parameters:

  • options (Hash) (defaults to: {}) —

    playlist attributes



30
31
32
33
34
 
# File 'lib/m3u8/playlist.rb', line 30

def initialize(options = {})
  assign_options(options)
  @items = []
  @unknown_tags = []
end

Instance Attribute Details

#cache ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def cache
  @cache
end

#discontinuity_sequence ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def discontinuity_sequence
  @discontinuity_sequence
end

#iframes_only ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def iframes_only
  @iframes_only
end

#independent_segments ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def independent_segments
  @independent_segments
end

#items ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def items
  @items
end

#live ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def live
  @live
end

#part_inf ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def part_inf
  @part_inf
end

#sequence ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def sequence
  @sequence
end

#server_control ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def server_control
  @server_control
end

#target ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def target
  @target
end

#type ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def type
  @type
end

#unknown_tags ⇒ Array<String> (readonly)

Returns unrecognized #EXT tags found while parsing.

Returns:

  • (Array<String>) —

    unrecognized #EXT tags found while parsing



27
28
29
 
# File 'lib/m3u8/playlist.rb', line 27

def unknown_tags
  @unknown_tags
end

#version ⇒ Array, ...

Returns:

  • (Array) —

    list of items in the playlist

  • (Integer, nil) —

    EXT-X-VERSION value

  • (Boolean, nil) —

    EXT-X-ALLOW-CACHE value

  • (Integer) —

    EXT-X-TARGETDURATION value

  • (Integer) —

    EXT-X-MEDIA-SEQUENCE value

  • (Integer, nil) —

    EXT-X-DISCONTINUITY-SEQUENCE value

  • (String, nil) —

    EXT-X-PLAYLIST-TYPE (VOD or EVENT)

  • (Boolean) —

    whether playlist is I-frames only

  • (Boolean) —

    whether segments are independent

  • (Boolean) —

    whether playlist is live

  • (PartInfItem, nil) —

    EXT-X-PART-INF item

  • (ServerControlItem, nil) —

    EXT-X-SERVER-CONTROL item



21
22
23
 
# File 'lib/m3u8/playlist.rb', line 21

def version
  @version
end

Class Method Details

.build(options = {}) {|Builder| ... } ⇒ Playlist

Build a playlist using a DSL block.

Parameters:

  • options (Hash) (defaults to: {}) —

    playlist attributes

Yields:

  • (Builder) —

    block receives builder instance

Returns:



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/m3u8/playlist.rb', line 40

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

.codecs(options = {}) ⇒ String?

Generate a codecs string from codec options.

Parameters:

  • options (Hash) (defaults to: {}) —

    codec options (:profile, :level, etc.)

Returns:

  • (String, nil) —

    codecs string



54
55
56
57
 
# File 'lib/m3u8/playlist.rb', line 54

def self.codecs(options = {})
  item = PlaylistItem.new(options)
  item.codecs
end

.from_h(hash) ⇒ Playlist

Reconstruct a playlist from a Hash produced by #to_h.

Parameters:

  • hash (Hash) —

    playlist attributes and items

Returns:



71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/m3u8/playlist.rb', line 71

def self.from_h(hash)
  hash = hash.transform_keys(&:to_sym)
  items = hash.delete(:items) || []
  part_inf = hash.delete(:part_inf)
  server_control = hash.delete(:server_control)
  playlist = new(hash)
  playlist.part_inf = nested(PartInfItem, part_inf)
  playlist.server_control = nested(ServerControlItem, server_control)
  items.each { |attributes| playlist.items << item_from_h(attributes) }
  playlist
end

.read(input, strict: false) ⇒ Playlist

Parse an m3u8 playlist from a String or IO.

Parameters:

  • input (String, IO) —

    playlist content

  • strict (Boolean) (defaults to: false) —

    raise on unsupported tags when true

Returns:



63
64
65
66
 
# File 'lib/m3u8/playlist.rb', line 63

def self.read(input, strict: false)
  reader = Reader.new(strict: strict)
  reader.read(input)
end

Instance Method Details

#date_ranges ⇒ Array<DateRangeItem>

Returns:



249
250
251
 
# File 'lib/m3u8/playlist.rb', line 249

def date_ranges
  items.grep(DateRangeItem)
end

#duration ⇒ Float

Total duration of all segments.

Returns:

  • (Float) 


270
271
272
 
# File 'lib/m3u8/playlist.rb', line 270

def duration
  segments.sum(&:duration)
end

#errors ⇒ Array<String>

Collect validation errors for the playlist.

Returns:

  • (Array<String>) —

    list of error messages



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/m3u8/playlist.rb', line 193

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

#freeze ⇒ Playlist

Freeze the playlist and all its items.

Returns:



153
154
155
156
157
158
159
160
 
# File 'lib/m3u8/playlist.rb', line 153

def freeze
  items.each { |item| freeze_item(item) }
  items.freeze
  unknown_tags.freeze
  part_inf&.freeze
  server_control&.freeze
  super
end

#keys ⇒ Array<KeyItem>

Returns:



239
240
241
 
# File 'lib/m3u8/playlist.rb', line 239

def keys
  items.grep(KeyItem)
end

#live? ⇒ Boolean

Whether this is a live (non-VOD) media playlist.

Returns:

  • (Boolean) 


136
137
138
139
140
 
# File 'lib/m3u8/playlist.rb', line 136

def live?
  return false if master?

  @live
end

#maps ⇒ Array<MapItem>

Returns:



244
245
246
 
# File 'lib/m3u8/playlist.rb', line 244

def maps
  items.grep(MapItem)
end

#master? ⇒ Boolean

Whether this is a master (multivariant) playlist.

Returns:

  • (Boolean) 


144
145
146
147
148
149
 
# File 'lib/m3u8/playlist.rb', line 144

def master?
  return @master unless @master.nil?
  return false if playlist_size.zero? && segment_size.zero?

  playlist_size.positive?
end

#media_items ⇒ Array<MediaItem>

Returns:



234
235
236
 
# File 'lib/m3u8/playlist.rb', line 234

def media_items
  items.grep(MediaItem)
end

#parts ⇒ Array<PartItem>

Returns:



254
255
256
 
# File 'lib/m3u8/playlist.rb', line 254

def parts
  items.grep(PartItem)
end

#playlists ⇒ Array<PlaylistItem>

Returns:



229
230
231
 
# File 'lib/m3u8/playlist.rb', line 229

def playlists
  items.grep(PlaylistItem)
end

#resolve_variables(imported: {}, query: {}) ⇒ Playlist

Resolve EXT-X-DEFINE variable references into a new Playlist.

Parameters:

  • imported (Hash) (defaults to: {}) —

    values for IMPORT definitions

  • query (Hash) (defaults to: {}) —

    values for QUERYPARAM definitions

Returns:



130
131
132
 
# File 'lib/m3u8/playlist.rb', line 130

def resolve_variables(imported: {}, query: {})
  VariableResolver.new(self, imported: imported, query: query).resolve
end

#segments ⇒ Array<SegmentItem>

Returns:



224
225
226
 
# File 'lib/m3u8/playlist.rb', line 224

def segments
  items.grep(SegmentItem)
end

#session_data ⇒ Array<SessionDataItem>

Returns:



259
260
261
 
# File 'lib/m3u8/playlist.rb', line 259

def session_data
  items.grep(SessionDataItem)
end

#session_keys ⇒ Array<SessionKeyItem>

Returns:



264
265
266
 
# File 'lib/m3u8/playlist.rb', line 264

def session_keys
  items.grep(SessionKeyItem)
end

#to_h ⇒ Hash<Symbol, Object>

Convert the playlist into a Hash of its attributes and items. Each item Hash carries an :item_type key identifying its class.

Returns:

  • (Hash<Symbol, Object>) 


173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/m3u8/playlist.rb', line 173

def to_h
  {
    master: master?,
    live: live?,
    version: version,
    independent_segments: independent_segments,
    iframes_only: iframes_only,
    type: type,
    target: target,
    sequence: sequence,
    discontinuity_sequence: discontinuity_sequence,
    cache: cache,
    part_inf: part_inf&.to_h,
    server_control: server_control&.to_h,
    items: items.map { |item| item_to_h(item) }
  }
end

#to_s ⇒ String

Render the playlist as an m3u8 string.

Returns:

  • (String) 


164
165
166
167
168
 
# File 'lib/m3u8/playlist.rb', line 164

def to_s
  output = StringIO.open
  write(output)
  output.string
end

#valid? ⇒ Boolean

Whether the playlist passes all validations.

Returns:

  • (Boolean) 


209
210
211
 
# File 'lib/m3u8/playlist.rb', line 209

def valid?
  errors.empty?
end

#warnings ⇒ Array<String>

Collect non-fatal conformance warnings (version compatibility and Low-Latency HLS recommendations).

Returns:

  • (Array<String>) —

    list of warning messages



216
217
218
219
220
221
 
# File 'lib/m3u8/playlist.rb', line 216

def warnings
  [].tap do |list|
    version_warnings(list)
    low_latency_warnings(list)
  end
end

#write(output) ⇒ void

This method returns an undefined value.

Write the playlist to an IO object.

Parameters:

  • output (IO) —

    writable IO object



121
122
123
124
 
# File 'lib/m3u8/playlist.rb', line 121

def write(output)
  writer = Writer.new(output)
  writer.write(self)
end