class

M3U8::MediaItem

Inherits M3U8::Concern / Reference / Object

MediaItem represents a set of attributes for the EXT-X-MEDIA tag in an HLS playlist.

The EXT-X-MEDIA tag (defined in RFC 8216, Section 4.3.4.1) is used in HLS Master Playlists to associate media renditions with alternative tracks (e.g., audio or subtitles). It carries information such as the media type, group identifier, language, human-readable name, and additional parameters like auto-selection, default status, and more.

The following attributes are typically included:

  • TYPE: Indicates the type of media (e.g., AUDIO, VIDEO, SUBTITLES, CLOSED-CAPTIONS).
  • GROUP-ID: A string that groups related renditions together.
  • LANGUAGE: A language tag (as defined in RFC 5646) representing the primary language.
  • ASSOC-LANGUAGE: An associated language tag for alternate language roles.
  • NAME: A human-readable name for the rendition.
  • URI: An optional URI that points to a separate Media Playlist for this rendition.
  • AUTOSELECT: A flag indicating whether the rendition should be automatically selected.
  • DEFAULT: A flag indicating whether the rendition is the default selection.
  • FORCED: A flag for subtitles that indicates whether the rendition is forced.
  • INSTREAM-ID: For closed-caption renditions, an identifier for the specific caption channel.
  • CHARACTERISTICS: Additional characteristics for the rendition, as a comma-separated list.
  • CHANNELS: For audio, a string indicating the number of channels and their order.

Example EXT-X-MEDIA tag:

#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="eng_audio.m3u8"

This class provides methods to parse such a tag from a text string, create a new instance using a NamedTuple of parameters, and output the tag as a properly formatted string.

Constructors

new(params : NamedTuple = NamedTuple.new)

Constructs a new MediaItem instance from a NamedTuple of parameters.

The NamedTuple can include keys corresponding to the EXT-X-MEDIA attributes: type, group_id, language, assoc_language, name, uri, autoselect, default, forced, instream_id, characteristics, channels.

Example:

options = {
  type:       "AUDIO",
  group_id:   "aac",
  language:   "en",
  name:       "English",
  autoselect: true,
  default:    true,
  uri:        "eng_audio.m3u8",
}
MediaItem.new(options)
# => #<M3U8::MediaItem:0x7b19ac8eb2d0
#     @assoc_language=nil,
#     @autoselect=true,
#     @channels=nil,
#     @characteristics=nil,
#     @default=true,
#     @forced=nil,
#     @group_id="aac",
#     @instream_id=nil,
#     @language="en",
#     @name="English",
#     @type="AUDIO",
#     @uri="eng_audio.m3u8">
Source
new(type : Nil | String = nil, group_id : Nil | String = nil, language : Nil | String = nil, assoc_language : Nil | String = nil, name : Nil | String = nil, uri : Nil | String = nil, autoselect : Bool | Nil = nil, default : Bool | Nil = nil, forced : Bool | Nil = nil, instream_id : Nil | String = nil, characteristics : Nil | String = nil, channels : Nil | String = nil)

Initializes a new MediaItem instance.

All attributes default to nil if not provided.

Examples:

MediaItem.new(
  type: "AUDIO",
  group_id: "aac",
  language: "en",
  name: "English",
  autoselect: true,
  default: true,
  uri: "eng_audio.m3u8",
)
# => #<M3U8::MediaItem:0x7ea38df181b0
#     @assoc_language=nil,
#     @autoselect=true,
#     @channels=nil,
#     @characteristics=nil,
#     @default=true,
#     @forced=nil,
#     @group_id="aac",
#     @instream_id=nil,
#     @language="en",
#     @name="English",
#     @type="AUDIO",
#     @uri="eng_audio.m3u8">
Source

Class methods

parse(text)

Parses a text string representing an EXT-X-MEDIA tag and returns a new MediaItem instance.

The method extracts key/value pairs using parse_attributes (from M3U8::Concern) and converts them to appropriate types (e.g., booleans using parse_boolean).

Example:

text = %(#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="eng_audio.m3u8")
MediaItem.parse(text)
# => #<M3U8::MediaItem:0x7cd7249453f0
#     @assoc_language=nil,
#     @autoselect=true,
#     @channels=nil,
#     @characteristics=nil,
#     @default=true,
#     @forced=nil,
#     @group_id="aac",
#     @instream_id=nil,
#     @language="en",
#     @name="English",
#     @type="AUDIO",
#     @uri="eng_audio.m3u8">
Source

Instance methods

assoc_language
Source
assoc_language=(assoc_language : String | Nil)
Source
autoselect
Source
autoselect=(autoselect : Bool | Nil)
Source
channels
Source
channels=(channels : String | Nil)
Source
characteristics
Source
characteristics=(characteristics : String | Nil)
Source
default
Source
default=(default : Bool | Nil)
Source
forced
Source
forced=(forced : Bool | Nil)
Source
group_id
Source
group_id=(group_id : String | Nil)
Source
instream_id
Source
instream_id=(instream_id : String | Nil)
Source
language
Source
language=(language : String | Nil)
Source
name
Source
name=(name : String | Nil)
Source
to_s

Returns the string representation of the EXT-X-MEDIA tag.

The output is constructed by joining the formatted attributes with commas, and then prefixing the result with #EXT-X-MEDIA:.

Examples:

MediaItem.new(
  type: "AUDIO",
  group_id: "aac",
  language: "en",
  name: "English",
  autoselect: true,
  default: true,
  uri: "eng_audio.m3u8",
).to_s
# => "#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aac\",LANGUAGE=\"en\",NAME=\"English\",AUTOSELECT=YES,DEFAULT=YES,URI=\"eng_audio.m3u8\""
Source
type
Source
type=(type : String | Nil)
Source
uri=(uri : String | Nil)
Source