A catalog is a JSON [JSON] document, comprised of a series of mandatory and optional fields. At a minimum, a catalog MUST provide all mandatory fields. A producer MAY add additional fields to the ones described in this draft. Custom field names MUST NOT collide with field names described in this draft. The order of field names within the JSON document is not important.
A parser MUST ignore fields it does not understand.
Table 1 provides an overview of all fields defined by this document.
| Field | Name | Definition |
|---|---|---|
| MSF version | version | Section 5.1.1 |
| Delta update | deltaUpdate | Section 5.1.2 |
| Add tracks | addTracks | Section 5.1.3 |
| Remove tracks | removeTracks | Section 5.1.4 |
| Clone tracks | cloneTracks | Section 5.1.5 |
| Generated at | generatedAt | Section 5.1.6 |
| Is Complete | isComplete | Section 5.1.7 |
| Tracks | tracks | Section 5.1.8 |
| Track namespace | namespace | Section 5.1.10 |
| Track name | name | Section 5.1.11 |
| Packaging | packaging | Section 5.1.12 |
| Event timeline type | eventType | Section 5.1.13 |
| Is Live | isLive | Section 5.1.15 |
| Target latency | targetLatency | Section 5.1.16 |
| Track role | role | Section 5.1.14 |
| Track label | label | Section 5.1.17 |
| Render group | renderGroup | Section 5.1.18 |
| Alternate group | altGroup | Section 5.1.19 |
| Initialization data | initData | Section 5.1.20 |
| Dependencies | depends | Section 5.1.21 |
| Temporal ID | temporalId | Section 5.1.22 |
| Spatial ID | spatialId | Section 5.1.23 |
| Codec | codec | Section 5.1.24 |
| Mime type | mimeType | Section 5.1.25 |
| Framerate | framerate | Section 5.1.26 |
| Timescale | timescale | Section 5.1.27 |
| Bitrate | bitrate | Section 5.1.28 |
| Width | width | Section 5.1.29 |
| Height | height | Section 5.1.30 |
| Audio sample rate | samplerate | Section 5.1.31 |
| Channel configuration | channelConfig | Section 5.1.32 |
| Display width | displayWidth | Section 5.1.33 |
| Display height | displayHeight | Section 5.1.34 |
| Language | lang | Section 5.1.35 |
| Parent name | parentName | Section 5.1.36 |
| Track duration | trackDuration | Section 5.1.37 |
Table 2 defines the allowed locations for these fields within the document
| Location | Allowed locations for the field |
|---|---|
| R | The Root of the JSON object |
| T | Track object |
5.1.1. MSF version
Location: R Required: Yes JSON Type: Number
Specifies the version of MSF referenced by this catalog. There is no guarantee that future catalog versions are backwards compatible and field definitions and interpretation may change between versions. A subscriber MUST NOT attempt to parse a catalog version which it does not understand.
5.1.2. Delta update
Location: R Required: Optional JSON Type: Boolean
A Boolean that if true indicates that this catalog object represents a delta (or partial) update. A delta update has a restricted set of fields and special processing rules - see Section 5.2. This value SHOULD NOT be added to a catalog if it is false.
5.1.3. Add tracks
Location: R Required: Optional JSON Type: Array
Indicates a delta processing instruction to add new tracks. The value of this field is an Array of track objects Section 5.1.9.
5.1.4. Remove tracks
Location: R Required: Optional JSON Type: Array
Indicates a delta processing instruction to remove new tracks. The value of this field is an Array of track objects Section 5.1.9. Each track object MUST include a Track Name Section 5.1.11 field, MAY include a Track Namespace Section 5.1.10 field and MUST NOT hold any other fields.
5.1.5. Clone tracks
Location: R Required: Optional JSON Type: Array
Indicates a delta processing instruction to clone new tracks from previously declared tracks. The value of this field is an Array of track objects Section 5.1.9. Each track object MUST include a Parent Name Section 5.1.36 field.
5.1.6. Generated at
Location: R Required: Optional JSON Type: Number
The wallclock time at which this catalog instance was generated, expressed as the number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT). This field SHOULD NOT be included if the isLive field is false.
5.1.7. Is Complete
Location: R Required: Optional JSON Type: Boolean
Issued once a previously live broadcast is complete. This is a commitment that all tracks are complete, no new tracks will be added and no new content will be published. This field MUST NOT be included if it is FALSE. This field MUST NOT be removed from a catalog once it has been added.
5.1.8. Tracks
Location: R Required: Yes JSON Type: Array
An array of track objects Section 5.1.9.
5.1.9. Tracks object
A track object is JSON Object containing a collection of fields whose location is specified 'T' in Table 2.
5.1.10. Track namespace
Location: T Required: Optional JSON Type: String
The name space under which the track name is defined. See section 2.3 of [MoQTransport]. The track namespace is optional. If it is not declared within a track, then each track MUST inherit the namespace of the catalog track. A namespace declared in a track object overwrites any inherited name space.
5.1.11. Track name
Location: T Required: Yes JSON Type: String
A string defining the name of the track. See section 2.3 of [MoQTransport]. Within the catalog, track names MUST be unique per namespace.
5.1.12. Packaging
Location: T Required: Yes JSON Type: String
A string defining the type of payload encapsulation. Allowed values are strings as defined in Table 3.
Table 3: Allowed packaging values
| Name | Value | Reference |
|---|---|---|
| LOC | loc | See RFC XXXX |
| Media Timeline | mediatimeline | See Section 7 |
| Event Timeline | eventtimeline | See Section 8 |
5.1.13. Event timeline type
Location: T Required: Optional JSON Type: String
A String defining the type & structure of the data contained within the data field of the Event timeline track. Types are defined by the application provider and are not centrally registered. Implementers are encouraged to use a unique naming scheme, such as Reverse Domain Name Notation, to avoid naming collisions. This field is required if the Section 5.1.12 value is "eventtimeline". This field MUST NOT be used if the packaging value is not "eventtimeline".
5.1.14. Track role
Location: T Required: Optional JSON Type: String
A string defining the role of content carried by the track. Specified roles are described in Table 4. These role values are case-sensitive.
This role field MAY be used in conjunction with the Mimetype Section 5.1.25 to fully describe the content of the track.
Table 4: Reserved track roles
| Role | Description |
|---|---|
| audiodescription | An audio description for visually impaired users |
| video | Visual content |
| audio | Audio content |
| mediatimeline | An MSF media timeline Section 7 |
| eventtimeline | An MSF event timeline Section 8 |
| caption | A textual representation of the audio track |
| subtitle | A transcription of the spoken dialogue |
| signlanguage | A visual track for hearing impaired users. |
Custom roles MAY be used as long as they do not collide with the specified roles.
5.1.15. Is Live
Location: T Required: Yes JSON Type: Boolean
True if new Objects will be added to the track. False if no new Objects will be added to the track. This is sent under two possible conditions: * the publisher of a previously live track has ended the track. * the track is Video-On-Demand (VOD) and was never live.
5.1.16. Target latency
Location: T Required: Optional JSON Type: Number
The target latency in milliseconds. Target latency is defined as the offset in wallclock time between when content was encoded and when it is displayed to the end user. For example, if a frame of video is encoded at 10:08:32.638 UTC and the target latency is 5000, then that frame should be rendered to the end-user at 10:08:37.638 UTC. This field MUST NOT be included if isLive is FALSE. All tracks belonging to the same render group MUST have identical target latencies. All tracks belonging to the same alternate group MUST have identical target latencies. If this field is absent from the track definition, then the player MAY choose the latency with which it renders the content.
5.1.17. Track label
Location: T Required: Optional JSON Type: String
A string defining a human-readable label for the track. Examples might be "Overhead camera view" or "Deutscher Kommentar". Note that the [JSON] spec requires UTF-8 support by decoders.
5.1.18. Render group
Location: T Required: Optional JSON Type: Number
An integer specifying a group of tracks which are designed to be rendered together. Tracks with the same group number SHOULD be rendered simultaneously, are time-aligned and are designed to accompany one another. A common example would be tying together audio and video tracks.
5.1.19. Alternate group
Location: T Required: Optional JSON Type: Number
An integer specifying a group of tracks which are alternate versions of one-another. Alternate tracks represent the same media content, but differ in their selection properties. Alternate tracks MUST have matching media time sequences. A subscriber typically subscribes to one track from a set of tracks specifying the same alternate group number. A common example would be a set video tracks of the same content offered in alternate bitrates.
5.1.20. Initialization data
Location: T Required: Optional JSON Type: String
A string holding Base64 [BASE64] encoded initialization data for the track.
5.1.21. Dependencies
Location: T Required: Optional JSON Type: Array
Certain tracks may depend on other tracks for decoding. Dependencies holds an array of track names Section 5.1.11 on which the current track is dependent. Since only the track name is signaled, the namespace of the dependencies is assumed to match that of the track declaring the dependencies.
5.1.22. Temporal ID
Location: T Required: Optional JSON Type: Number
A number identifying the temporal layer/sub-layer encoding of the track, starting with 0 for the base layer, and increasing by 1 for the next higher temporal fidelity.
5.1.23. Spatial ID
Location: T Required: Optional JSON Type: Number
A number identifying the spatial layer encoding of the track, starting with 0 for the base layer, and increasing by 1 for the next higher fidelity.
5.1.24. Codec
Location: T Required: Optional JSON Type: String
A string defining the codec used to encode the track. For LOC packaged content, the string codec registrations are defined in Sect 3 and Section 4 of [WEBCODECS-CODEC-REGISTRY].
5.1.25. Mimetype
Location: T Required: Optional JSON Type: String
A string defining the mime type [MIME] of the track.
5.1.26. Framerate
Location: T Required: Optional JSON Type: Number
A number defining the video framerate of the track, expressed as frames per second.
5.1.27. Timescale
Location: T Required: Optional JSON Type: Number
The number of time units that pass per second.
5.1.28. Bitrate
Location: T Required: Optional JSON Type: Number
A number defining the bitrate of track, expressed in bits per second.
5.1.29. Width
Location: T Required: Optional JSON Type: Number
A number expressing the encoded width of the video frames in pixels.
5.1.30. Height
Location: T Required: Optional JSON Type: Number
A number expressing the encoded height of the video frames in pixels.
5.1.31. Audio sample rate
Location: T Required: Optional JSON Type: Number
The number of audio frame samples per second. This property SHOULD only accompany audio codecs.
5.1.32. Channel configuration
Location: T Required: Optional JSON Type: String
A string specifying the audio channel configuration. This property SHOULD only accompany audio codecs. A string is used in order to provide the flexibility to describe complex channel configurations for multi-channel and Next Generation Audio schemas.
5.1.33. Display width
Location: T Required: Optional JSON Type: Number
A number expressing the intended display width of the track content in pixels.
5.1.34. Display height
Location: T Required: Optional JSON Type: Number
A number expressing the intended display height of the track content in pixels.
5.1.35. Language
Location: T Required: Optional JSON Type: String
A string defining the dominant language of the track. The string MUST be one of the standard Tags for Identifying Languages as defined by [LANG].
5.1.36. Parent name
Location: T Required: Optional JSON Type: String
A string defining the parent track name Section 5.1.11 to be cloned. This field MUST only be included inside a Clone tracks Section 5.1.5 object.
5.1.37. Track duration
Location: T Required: Optional JSON Type: Number
The duration of the track expressed in integer milliseconds. This field MUST NOT be included if the isLive Section 5.1.15 field value is true.