class

M3U8::SegmentItem

Inherits M3U8::Concern / Reference / Object

SegmentItem represents a media segment in an HLS playlist.

It encapsulates the information provided by the EXTINF tag followed by the media segment URI.

According to RFC 8216, Section 4.3.2.1, The EXTINF tag specifies the duration of a Media Segment and may include an optional title or comment. It applies only to the next Media Segment.

Its format is:

#EXTINF:<duration>,[<title>]

For example:

#EXTINF:10.991,anything

This indicates that the following media segment has a duration of 10.991 seconds with an optional comment "anything".

In addition, a SegmentItem may optionally include:

  • An EXT-X-BYTERANGE tag (ByteRange) that specifies a sub-range of the media resource. (RFC 8216, Section 4.3.2.2)
  • An EXT-X-PROGRAM-DATE-TIME tag (Time or TimeItem) that associates an absolute date and time with the first sample of the following Media Segment. (RFC 8216, Section 4.3.2.6)

Properties:

  • duration: The duration of the segment as specified by the EXTINF tag.
  • segment: The URI of the media segment.
  • comment: An optional comment from the EXTINF tag.
  • byterange: A ByteRange object representing the sub-range of the segment, if specified.
  • program_date_time: A TimeItem object representing the absolute time associated with the segment.

Examples:

Creating a SegmentItem instance:

options = {
  duration:  10.991,
  segment:   "test.ts",
  comment:   "anything",
  byterange: {length: 4500, start: 600},
}
SegmentItem.new(options)
# => #<M3U8::SegmentItem:0x7e310e075cc0
#     @byterange=#<M3U8::ByteRange:0x7e310f201c00 @length=4500, @start=600>,
#     @comment="anything",
#     @duration=10.991,
#     @program_date_time=#<M3U8::TimeItem:0x7e310e0761b0 @time=1970-01-01 00:00:00.0 UTC>,
#     @segment="test.ts">

SegmentItem.new(10.991, "test.ts", "anything", "4500@600", "2010-02-19T14:54:23.031Z")
# => #<M3U8::SegmentItem:0x7e6830943b40
#     @byterange=#<M3U8::ByteRange:0x7e6831acf990 @length=4500, @start=600>,
#     @comment="anything",
#     @duration=10.991,
#     @program_date_time=#<M3U8::TimeItem:0x7e6830949cf0 @time=2010-02-19 14:54:23.031000000 UTC>,
#     @segment="test.ts">

Convert to a string representation of the SegmentItem:

SegmentItem.new(10.991, "test.ts", "anything", "4500@600", "2010-02-19T14:54:23.031Z").to_s
# => "#EXTINF:10.991,anything\n" +
#    "#EXT-X-BYTERANGE:4500@600\n" +
#    "#EXT-X-PROGRAM-DATE-TIME:2010-02-19T14:54:23.031Z\n" +
#    "test.ts"

Constructors

new(params : NamedTuple = NamedTuple.new)

Constructs a new SegmentItem from a NamedTuple.

The NamedTuple may include the following keys:

  • duration (Float64): The duration of the segment.
  • segment (String): The URI of the media segment.
  • comment (String): A comment associated with the segment.
  • byterange (ByteRange, NamedTuple, or String): The byterange, which can be provided as a NamedTuple, ByteRange, or string.
  • program_date_time (TimeItem, Time, or String): The program date/time, which can be a TimeItem, Time, or ISO8601 string.

Example:

options = {
  duration:          10.991,
  segment:           "test.ts",
  comment:           "anything",
  byterange:         {length: 4500, start: 600},
  program_date_time: "2010-02-19T14:54:23.031Z",
}
SegmentItem.new(options)
# => #<M3U8::SegmentItem:0x7e756d37b7c0
#     @byterange=#<M3U8::ByteRange:0x7e756e5074b0 @length=4500, @start=600>,
#     @comment="anything",
#     @duration=10.991,
#     @program_date_time=#<M3U8::TimeItem:0x7e756d386c60 @time=2010-02-19 14:54:23.031000000 UTC>,
#     @segment="test.ts">
Source
new(duration : Float64 | Nil = nil, segment : Nil | String = nil, comment : Nil | String = nil, byterange = nil, program_date_time = nil)

Initializes a new SegmentItem instance.

The parameters are assigned to the corresponding properties. The byterange (Byterange) and program_date_time (TimeItem) parameters are parsed using their respective parsing methods, allowing them to be provided in different forms (e.g. as a NamedTuple, string, or object).

Examples:

SegmentItem.new(10.991, "test.ts", "anything", "4500@600", "2010-02-19T14:54:23.031Z")
# => #<M3U8::SegmentItem:0x7e6830943b40
#     @byterange=#<M3U8::ByteRange:0x7e6831acf990 @length=4500, @start=600>,
#     @comment="anything",
#     @duration=10.991,
#     @program_date_time=#<M3U8::TimeItem:0x7e6830949cf0 @time=2010-02-19 14:54:23.031000000 UTC>,
#     @segment="test.ts">

SegmentItem.new(
  duration: 10.991,
  segment: "test.ts",
  comment: "anything",
  byterange: {length: 4500, start: 600},
  program_date_time: Time.parse_iso8601("2010-02-19T14:54:23.031Z"),
)
# => #<M3U8::SegmentItem:0x7ffa96913700
#     @byterange=#<M3U8::ByteRange:0x7ffa97a9f3f0 @length=4500, @start=600>,
#     @comment="anything",
#     @duration=10.991,
#     @program_date_time=#<M3U8::TimeItem:0x7ffa9691e7b0 @time=2010-02-19 14:54:23.031000000 UTC>,
#     @segment="test.ts">
Source

Instance methods

byterange

The ByteRange specifying a sub-section of the segment (if provided).

Source
byterange=(byterange)

Setter for the byterange property.

Allows setting the byterange attribute using a ByteRange object, a NamedTuple, or a string. The input is parsed using ByteRange.parse.

Example:

item = SegmentItem.new
item.byterange = ByteRange.new(length: 4500, start: 600)
item.byterange = {length: 4500, start: 600}
item.byterange = "4500@600"

item.byterange
# => #<M3U8::ByteRange:0x784ba59ea7e0 @length=4500, @start=600>
Source
comment

An optional comment from the EXTINF tag.

Source
comment=(comment : String | Nil)

An optional comment from the EXTINF tag.

Source
duration

The required duration from the EXTINF tag.

Source
duration=(duration : Float64 | Nil)

The required duration from the EXTINF tag.

Source
program_date_time

The program date/time (TimeItem) associated with the segment (if provided).

Source
program_date_time=(time)

Setter for the program_date_time property.

Allows setting the program_date_time attribute using a TimeItem, Time, or ISO-8601 string. The input is parsed using TimeItem.parse.

Example:

item = SegmentItem.new
item.program_date_time = TimeItem.new("2010-02-19T14:54:23Z")
item.program_date_time = TimeItem.new(Time.iso8601("2010-02-19T14:54:23.031Z"))
item.program_date_time = Time.parse_iso8601("2010-02-19T14:54:23.031Z")
item.program_date_time = "2010-02-19T14:54:23.031Z"

item.program_date_time
# => #<M3U8::TimeItem:0x7f5e17fedea0 @time=2010-02-19 14:54:23.031000000 UTC>
Source
segment

The URI of the media segment.

Source
segment=(segment : String | Nil)

The URI of the media segment.

Source
to_s

Returns the string representation of the segment, including the EXTINF tag, an optional EXT-X-BYTERANGE tag, an optional EXT-X-PROGRAM-DATE-TIME tag, and the segment URI.

The components are joined with newline characters.

Example:

options = {
  duration:  10.991,
  segment:   "test.ts",
  comment:   "anything",
  byterange: "4500@600",
}
SegmentItem.new(options).to_s
# => "#EXTINF:10.991,anything\n" +
#    "#EXT-X-BYTERANGE:4500@600\n" +
#    "test.ts"

SegmentItem.new(10.991, "test.ts", "anything", "4500@600", "2010-02-19T14:54:23.031Z").to_s
# => "#EXTINF:10.991,anything\n" +
#    "#EXT-X-BYTERANGE:4500@600\n" +
#    "#EXT-X-PROGRAM-DATE-TIME:2010-02-19T14:54:23.031Z\n" +
#    "test.ts"
Source