class

M3U8::Codecs

Inherits M3U8::Concern / Reference / Object

Codecs represents the CODECS attribute used in HTTP Live Streaming (HLS).

In HLS (RFC 8216), the CODECS attribute (further detailed in RFC 6381) is a comma-separated list of codec identifiers that describe the media contained in a Media Segment. This attribute is used in the EXT-X-STREAM-INF tag to indicate what codecs (and profiles) are required to play back a stream.

#EXT-X-STREAM-INF:BANDWIDTH=65000,CODECS="mp4a.40.5"
audio-only.m3u8

There are two primary ways to use Codecs:

If the codecs property is set, that pre-computed string is used directly.
Otherwise, the codecs string is constructed by deriving the video and audio codec codes from the remaining properties:
- For audio, the audio_codec property is mapped as follows:

        "aac-lc"  => "mp4a.40.2"  (AAC low complexity)
        "he-aac"  => "mp4a.40.5"  (HE-AAC)
        "mp3"     => "mp4a.40.34" (MPEG-1 Audio Layer 3)

For video, both the profile and level properties must be provided. For example, for H.264 (AVC) video the following mappings are used:

        Baseline Profile:
          Level 3.0 => "avc1.66.30"
          Level 3.1 => "avc1.42001f"

        Main Profile:
          Level 3.0 => "avc1.77.30"
          Level 3.1 => "avc1.4d001f"
          Level 4.0 => "avc1.4d0028"
          Level 4.1 => "avc1.4d0029"

        High Profile:
          Level 3.1 => "avc1.64001f"
          Level 4.0 => "avc1.640028"
          Level 4.1 => "avc1.640029"

When constructing the codec string:

If a video codec is expected (i.e. both profile and level are provided) but the mapping is not recognized, no codec string is output.
Likewise, if an audio_codec is specified but unrecognized, the codec string is empty.

For more details on these mappings and the overall semantics of HLS, refer to:

RFC 8216 (HTTP Live Streaming) Section 4.3.4.2
RFC 6381 (The 'Codecs' and 'Profiles' Parameters for "Bucket" Media Types)
The HTTP Live Streaming FAQ (which discusses recommended values for stream playback)

Constructors

new(params : NamedTuple = NamedTuple.new)

Creates a new Codecs instance from a NamedTuple.

Examples:

options = {audio_codec: "aac-lc"}
Codecs.new(options)
Codecs.new(audio_codec: "aac-lc")

Source

new(codecs : Nil | String = nil, audio_codec : Nil | String = nil, level = nil, profile : Nil | String = nil)

Initializes a new Codecs instance. Parameters with @ prefix are automatically assigned as instance variables.

Parameters:

codecs: A pre-computed codec string (if provided, it is used directly).
audio_codec: The name of the audio codec (e.g. aac-lc, he-aac, mp3).
level: The numeric level used to determine the video codec.
profile: The video profile (e.g. baseline, main, high).

Example:

Codecs.new

Source

Instance methods

==(other : Codecs)

Compares this Codecs instance with another Codecs instance.

Equality is determined by comparing their CODECS strings.

Example:

left = Codecs.new(audio_codec: "aac-lc")
right = Codecs.new(audio_codec: "aac-lc")
left == right # => true

Source

==(other : String)

Compares this Codecs instance with a String.

The instance is considered equal to the string if its CODECS string matches.

Example:

left = Codecs.new(audio_codec: "aac-lc")
right = "aac-lc"
left == right # => true

Source

audio_codec

Audio codec identifier (e.g., aac-lc)

Source

audio_codec=(audio_codec : String | Nil)

Audio codec identifier (e.g., aac-lc)

Source

codecs

Predefined codec string

Source

codecs=(codecs : String | Nil)

Predefined codec string

Source

empty?

Returns true if the codecs string is empty.

Examples:

codecs = Codecs.new
codecs.empty? # => true
codecs.audio_codec = "aac-lc"
codecs.empty? # => false

Source

level

Video level (e.g., 3.0, 3.1, etc.)

The video codecs string is determined from both the video profile and level.

baseline Profile:
- Level 3.0 => avc1.66.30
- Level 3.1 => avc1.42001f
main Profile:
- Level 3.0 => avc1.77.30
- Level 3.1 => avc1.4d001f
- Level 4.0 => avc1.4d0028
- Level 4.1 => avc1.4d0029
high Profile:
- Level 3.1 => avc1.64001f
- Level 4.0 => avc1.640028
- Level 4.1 => avc1.640029

Source

level=(level : Float64 | Nil)

Video level (e.g., 3.0, 3.1, etc.)

The video codecs string is determined from both the video profile and level.

baseline Profile:
- Level 3.0 => avc1.66.30
- Level 3.1 => avc1.42001f
main Profile:
- Level 3.0 => avc1.77.30
- Level 3.1 => avc1.4d001f
- Level 4.0 => avc1.4d0028
- Level 4.1 => avc1.4d0029
high Profile:
- Level 3.1 => avc1.64001f
- Level 4.0 => avc1.640028
- Level 4.1 => avc1.640029

Source

profile

Video profile (e.g., baseline, main, high)

The video codecs string is determined from both the video profile and level.

baseline Profile:
- Level 3.0 => avc1.66.30
- Level 3.1 => avc1.42001f
main Profile:
- Level 3.0 => avc1.77.30
- Level 3.1 => avc1.4d001f
- Level 4.0 => avc1.4d0028
- Level 4.1 => avc1.4d0029
high Profile:
- Level 3.1 => avc1.64001f
- Level 4.0 => avc1.640028
- Level 4.1 => avc1.640029

Source

profile=(profile : String | Nil)

Video profile (e.g., baseline, main, high)

The video codecs string is determined from both the video profile and level.

baseline Profile:
- Level 3.0 => avc1.66.30
- Level 3.1 => avc1.42001f
main Profile:
- Level 3.0 => avc1.77.30
- Level 3.1 => avc1.4d001f
- Level 4.0 => avc1.4d0028
- Level 4.1 => avc1.4d0029
high Profile:
- Level 3.1 => avc1.64001f
- Level 4.0 => avc1.640028
- Level 4.1 => avc1.640029

Source

to_s

Returns the CODECS string for this instance.

If a pre-computed codecs string is provided, it is returned directly. Otherwise, the method constructs the codecs string by computing the video codec (from profile and level) and the audio codec (from audio_codec).

Examples:

Codecs.new(codecs: "test").to_s                                      # => "test"
Codecs.new(audio_codec: "aac-lc").to_s                               # => "mp4a.40.2"
Codecs.new(profile: "baseline", level: 3.0, audio_codec: "mp3").to_s # => "avc1.66.30,mp4a.40.34"

Source