Skip to content

Latest commit

 

History

History
459 lines (275 loc) · 12.2 KB

manifest.md

File metadata and controls

459 lines (275 loc) · 12.2 KB
Raw

Manifest Object

Table of Contents

Overview

A Manifest Object and its sub-parts are data structures returned by multiple APIs of the player.

Its data represents the corresponding streaming protocol's Manifest equivalent (MPD for DASH, Manifest for Microsoft Smooth Streaming etc.).

Basically, the structure of a Manifest file has the following hierarchy:

Manifest Object
  ...Manifest data and methods
  Period Object
    ...Period properties
    Adaptation Object
      ...Adaptation data and methods
      Representation Object
        ...Representation data and methods
        RepresentationIndex Object
          ...RepresentationIndex data and methods
            SegmentObject
            ...SegmentObject data

Due to this highly hierachical structure, each level will be described in its own chapter here.

⚠️ Like in the rest of this documentation, any variable or method not defined here can change without notice.

Only use the documented variables and open an issue if you think it's not enough.

Structure of a Manifest Object

The manifest Object represents the Manifest file of the content loaded.

properties

The manifest Object has the following properties.

periods

type: Array.<Period>

A single Manifest instance can contain multiple Periods, which are periods of time for which the list of available type of contents (audio tracks, subtitles, video tracks...) can be different.

Such example of Periods could be multiple Programs of a live contents, which can be each in different languages, for example.

The player will switch smoothly across subsequent Periods within playback.

Most Streaming technologies (e.g. HLS and Smooth) do not have a "Period" concept. For those, the Manifest will only have one Period for the whole content.

adaptations

⚠️ This property is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

type: Object

Adaptation objects for the first Period.

Both of those lines have the same effect:

console.log(manifest.adaptations);
console.log(manifest.periods[0].adaptations);

See the Period chapter for more information on Adaptations.

isLive

type: Boolean

true if the content is a "live" content (e.g. a live TV Channel). false otherwise.

uris

type: Array.<string>

The list of uris that can be used to refer to the Manifest file.

transport

type: string

The type of transport used. For now, this can only be equal to either dash or smooth.

Structure of a Period Object

A Period is an object describing what to play during a certain time periods.

A Manifest can have a single Period, which means that the played content do not change its characteristics (same languages, same bitrates etc.) or multiple ones.

A good example of a content with multiple Periods would be a live channel broadcasting multiple foreign films. Each film, being in a different language, will need to be part of a new Period.

properties

id

type: string

This id should be a string unique to that Period. It serves identifications purpose, when updating the Manifest for example.

start

type: Number

Start time at which the Period begins in the whole content, in seconds.

end

type: Number|undefined

End time at which the Period ends in the whole content, in seconds.

If not set or set to undefined, it means that the end is unknown, in which case it is the current last content of the current Manifest.

adaptations

type: Object

The Adaptations (tracks if you want) for the current content, per-type (audio/video/text/image).

See the Adaptation chapter for more info about an Adaptation's structure.

The Adaptation object can contain any of the following keys:

  • audio (Array.<Adaptation>): The audio Adaptation(s) available.
  • video (Array.<Adaptation>): The video Adaptation(s) available.
  • text (Array.<Adaptation>): The text Adaptation(s) available.
  • image (Array.<Adaptation>): The image Adaptation(s) available.

Structure of an Adaptation Object

An Adaptation is a set of streams representing the exact same contents in multiple forms (different sizes, different bitrates...). Concretely, a frequent usecase is to have a single video Adaptation and multiple audio ones, one for each language available.

As such, it is also often called in the API a track.

properties

id

type: string

This id should be a string unique to that Adaptation. It serves identifications purpose, when updating the Manifest for example.

type

type: string

The type of the Adaptation. The possible types are:

  • "video"
  • "audio"
  • "text"
  • "image"

language

type: string|undefined

The language of the Adaptation. This is particularly useful for audio and text Adaptations.

Note that this property is not always present in an Adaptation.

normalizedLanguage

type: string|undefined

An attempt to translate the language of the Adaptation into an ISO 639-3 code. If the translation attempt fails (no corresponding ISO 639-3 language code is found), it will equal the value of language

Note that this property is not always present in an Adaptation.

isAudioDescription

type: Boolean|undefined

This property only makes sense for audio Adaptations. In this case, if true it means that the audio track has added commentaries for the visually impaired.

isClosedCaption

type: Boolean|undefined

This property only makes sense for text Adaptations. In this case, if true it means that the text track has added hints for the hard of hearing.

isTrickModeTrack

type : Boolean|undefined

This property only makes sense for video Adaptations. In this case, if true it means that the video track is a trick mode track that will be played only if the user start the trick mode on the respective main adaptation.

representations

type: Array.<Representation>

The Represesentations for this Adaptation.

See the Representation chapter for more info about a Representation's structure.

methods

getAvailableBitrates

return value: Array.<Number>

Returns every bitrates available for this Adaptation.

Structure of a Representation Object

A Representation is an Adaptation encoded in a certain way. It is defined by multiple values (a codec, a bitrate). Only some of them are documented here (as stated before, open an issue if you would like to access other properties).

properties

id

type: string

This id should be a string unique to that Representation.

bitrate

type: Number

The bitrate of the Representation.

codec

type: string|undefined

The codec of the Representation.

decipherable

type: boolean|undefined

Whether we are able to decrypt this Representation / unable to decrypt it or if we don't know yet:

  • if true, it means that we know we were able to decrypt this Representation in the current content.
  • if false, it means that we know we were unable to decrypt this Representation
  • if undefined there is no certainty on this matter

height

type: Number|undefined

This property makes the most sense for video Representations. It defines the height of the video, in pixels.

width

type: Number|undefined

This property makes the most sense for video Representations. It defines the width of the video, in pixels.

index

type: RepresentationIndex

The represesentation index for this Representation.

See the RepresentationIndex chapter for more info about a RepresentationIndex's structure.

frameRate

type: string|undefined

The represesentation frame rate for this Representation. It defines either the number of frames per second as an integer (24), or as a ratio (24000 / 1000).

hdrInfo

type: Object|undefined

Information about the hdr characteristics of the track. (see HDR support documentation)

Structure of a RepresentationIndex Object

A RepresentationIndex is an uniform way of declaring the segment index in any Manifest.

That's the part that calculates which segments will be needed. Because the index can be different depending on the type of contents/transport most interactions here are done through few methods which hide the complexity underneath.

methods

getSegments

arguments:

  • up (Number): The position, in seconds from which you want to get the segment.

  • duration (Number): The duration in seconds from the asked position

return value: Array.<Segment>

Returns the needed segments as defined by the current Manifest during an asked timeframe.

See the Segment chapter for more info about a Segment's structure.

Structure of a Segment Object

A Segment object defines a segment, as generated by the RepresentationIndex.

Those segments can have multiple useful properties which for the most part are described here.

properties

id

type: string

This id should be a string unique to that segment.

timescale

type: Number

The timescale in which the duration and time are expressed.

Basically, divide any of those by the timescale to obtain seconds.

duration

type: Number|undefined

The duration, timescaled, of the Segments in s.

time

type: Number

The start time, timescaled, of the Segments in s.

isInit

type: Boolean|undefined

If true, the segment concerned is an init segment.

range

type: Array.<Number>|null|undefined

If defined, it means that the segment is defined in a certain byte range remotely. In this case, the array contains two elements, the start byte and the end byte.

indexRange

type: Array.<Number>|null|undefined

If defined, it means that a segment index is defined in a certain byte range remotely. In this case, the array contains two elements, the start byte and the end byte.

number

type: Number|undefined

The number of the segment (if numbered), useful with certain types of index.