class M3U8::Codecs

• M3U8::Codecs
• Reference
• Object

Overview

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:

1. If the #codecs property is set, that pre-computed string is used directly.

2. 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)

Included Modules

• M3U8::Concern

Extended Modules

• M3U8::Concern

Defined in:

Constructors

• .new(params : NamedTuple = NamedTuple.new)

  Creates a new Codecs instance from a NamedTuple.

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

  Initializes a new Codecs instance.

Instance Method Summary

• #==(other : Codecs)

  Compares this Codecs instance with another Codecs instance.

• #==(other : String)

  Compares this Codecs instance with a String.

• #audio_codec : String | Nil

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

• #audio_codec=(audio_codec : String | Nil)

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

• #codecs : String | Nil

  Predefined codec string

• #codecs=(codecs : String | Nil)

  Predefined codec string

• #empty?

  Returns true if the #codecs string is empty.

• #level : Float64 | Nil

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

• #level=(level : Float64 | Nil)

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

• #profile : String | Nil

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

• #profile=(profile : String | Nil)

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

• #to_s

  Returns the CODECS string for this instance.

Constructor Detail

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

Codecs.new

Instance Method Detail

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

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

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

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"