Common Catalog Format for moq-transport

Catalog A Catalog is a MOQT Object that provides information about tracks from a given publisher. A Catalog is used by publishers for advertising their output and for subscribers in consuming that output. The payload of the Catalog object is opaque to Relays and can be end-to-end encrypted. The Catalog provides the names and namespaces of the tracks being produced, along with the relationship between tracks, properties of the tracks that consumers may use for selection and any relevant initialization data. A special case of the catalog exists which describes other catalogs instead of tracks. A catalog might describe tracks, or catalogs, but never both at the same time.

Catalog version Versions of this catalog specification are defined using monotonically increasing integers. 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. This document defines version 1.

Catalog Fields A catalog is a JSON document, comprised of a series of mandatory and optional fields. At a minimum, a catalog MUST provide all mandatory fields and one of either a 'tracks' field or a 'catalogs' field. 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. To prevent custom field name collisions with future versions, custom field names SHOULD be prefixed using reverse domain name notation e.g "com.example-size". The order of field names within the JSON document is not important. Any track or catalog field declared at the root level is inherited by all tracks or catalogs. Any track or catalog field declared within a track or catalog object overwrites any inherited value. A parser MUST ignore fields it does not understand. Table 1 provides an overview of all fields defined by this document.

Field	Name	Required	Location	JSON type
Catalog version	version	yes	R	String
Streaming format	streamingFormat	yes	RC	String
Streaming format version	streamingFormatVersion	yes	RC	String
Tracks	tracks	opt	R	Array
Catalogs	catalogs	opt	R	Array
Track namespace	namespace	opt	RTC	String
Track name	name	yes	TC	String
Packaging	packaging	yes	RT	String
Track operation	operation	yes	RT	String
Track label	label	opt	RT	String
Render group	renderGroup	opt	RT	Number
Alternate group	altGroup	opt	RT	Number
Initialization data	initData	opt	RT	String
Initialization track	initTrack	opt	RT	String
Selection parameters	selectionParams	opt	RT	Object
Dependencies	depends	opt	T	Array
Temporal ID	temporalId	opt	T	Number
Spatial ID	spatialId	opt	T	Number
Codec	codec	opt	S	String
Mime type	mimeType	opt	S	String
Framerate	framerate	opt	S	Number
Bitrate	bitrate	opt	S	Number
Width	width	opt	S	Number
Height	height	opt	S	Number
Audio sample rate	samplerate	opt	S	Number
Channel configuration	channelConfig	opt	S	String
Display width	displayWidth	opt	S	Number
Display height	displayHeight	opt	S	Number
Language	lang	opt	S	String

Required: 'yes' indicates a mandatory field in non-patch catalogs, 'opt' indicates an optional field Location:

'R' - the field is located in the Root of the JSON object.
'RC' - the field may be located in either the Root or a Catalog object.
'RTC' - the field may be located in either the Root, or a Track object or a Catalog object.
'TC' - the field may be located in either a Track object or a Catalog object.
'RT' - the field may be located in either the Root or a Track object.
'T' - the field is located in a Track object.
'S' - the field is located in the Selection Parameters object.

Streaming format A number indicating the streaming format type. Every MoQ Streaming Format normatively referencing this catalog format MUST register itself in the "MoQ Streaming Format Type" table. See for additional details.

Streaming format version A string indicating the version of the streaming format to which this catalog applies. The structure of the version string is defined by the streaming format.

Tracks An array of track objects . If the 'tracks' field is present then the 'catalog' field MUST NOT be present.

Catalogs An array of catalog objects . If the 'catalogs' field is present then the 'tracks' field MUST NOT be present. A catalog MUST NOT list itself in the catalog array.

Catalog object A catalog object is a collection of fields whose location is specified as 'RC', 'TC' or 'RTC' in Table 1.

Tracks object A track object is a collection of fields whose location is specified as 'RT', 'TC' or 'RTC' in Table 1.

Track namespace The name space under which the track name is defined. See section 2.3 of . If the track namespace is declared in the root of the JSON document, then its value is inherited by all tracks and catalogs and it does not need to be re-declared within each track or catalog object. A namespace declared in a track object or catalog object overwrites any inherited name space. The track namespace is optional. If it is not declared at the root or track level, then each track MUST inherit the namespace of the catalog track.

Track name A string defining the name of the track. See section 2.3 of . Within the catalog, track names MUST be unique per namespace.

Packaging A string defining the type of payload encapsulation. Allowed values are strings as defined in Table 2. Table 2: Allowed packaging values

Name	Value	Draft
CMAF	"cmaf"	See RFC XXXX
LOC	"loc"	See RFC XXXX

Track operations Each track description can specify an optional operation value that identifies the catalog producer's intent. Track operation is an enumeration of values as defined below.

Add: Indicates the track is added to the catalog and the consumers of the catalog may subscribe to the track.
Delete: Indicates that media producer is no longer producing media on the associated track. Subscribers SHOULD terminate their subscriptions.

A catalog update in which all previously added tracks are deleted SHOULD be interpreted by a subscriber to indicate that the publisher has terminated the broadcast. Table 3 defines the numerical values for the track operations. Table 3: Allowed track operations

Name	Value	Default value
Add	add	yes
Delete	delete

The default track operation is 'add'. This value does not need to be declared in the track object.

Track label A string defining a human-readable label for the track. Examples might be "Overhead camera view" or "Deutscher Kommentar". Note that the spec requires UTF-8 support by decoders.

Render group 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 usually time-aligned and are designed to accompany one another. A common example would be tying together audio and video tracks.

Alternate group 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 SHOULD have matching framerate and 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.

Initialization data A string holding Base64 encoded initialization data for the track.

Initialization track A string specifying the track name of another track which holds initialization data for the current track. Initialization tracks MUST NOT be added to the tracks array . They are referenced only via the initialization track field of the track which they initialize.

Selection parameters An object holding a series of name/value pairs which a subscriber can use to select tracks for subscription. If present, the selection parameters object MUST NOT be empty. Any selection parameters declared at the root level are inherited by all tracks. A selection parameters object may exist at both the root and track level. Any declaration of a selection parameter at the track level overrides the inherited root value.

Dependencies Certain tracks may depend on other tracks for decoding. Dependencies holds an array of track names 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.

Temporal ID A number identifying the temporal layer/sub-layer encoding of the track, starting with 0 for the base layer, and increasing with higher temporal fidelity.

Spatial ID A number identifying the spatial layer encoding of the track, starting with 0 for the base layer, and increasing with higher fidelity.

Codec 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 . For CMAF packaged content, the string codec registrations are defined in XXX.

Mimetype A string defining the mime type of the track. This parameter is typically supplied with CMAF packaged content.

Framerate A number defining the framerate of the track, expressed as frames per second.

Bitrate A number defining the bitrate of track, expressed in bits second.

Width A number expressing the encoded width of the track content in pixels.

Height A number expressing the encoded height of the video frames in pixels.

Audio sample rate The number of audio frame samples per second. This property SHOULD only accompany audio codecs.

Channel configuration 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.

Display width A number expressing the intended display width of the track content in pixels.

Display height A number expressing the intended display height of the track content in pixels.

Language A string defining the dominant language of the track. The string MUST be one of the standard Tags for Identifying Languages as defined by .

Catalog Patch A catalog update might contain incremental changes. This is a useful property if many tracks may be initially declared but then there are small changes to a subset of tracks. The producer can issue a patch to describe these small changes. Changes are described incrementally, meaning that a patch can itself modify a prior patch. Patching leverages JSON PATCH to modify the catalog. JSON Patch is a format for expressing a sequence of operations to apply to a target JSON document. The following rules MUST be followed in processing patches:

The target JSON to be modified is the JSON document described by the preceding Object in the Catalog track, post any patching that may have been applied to that Object.
A Catalog Patch is identified by having a single array at the root level, holding a series of JSON objects, each object representing a single operation to be applied to the target JSON document.
Operations are applied sequentially in the order they appear in the array. Each operation in the sequence is applied to the target document; the resulting document becomes the target of the next operation. Evaluation continues until all operations are successfully applied or until an error condition is encountered.
Track namespaces and track names may not be changed across patch updates. To change either namespace or name, remove the track and then add a new track with matching properties and the new namespace and name.
Contents of the track selection properties object may not be varied across updates. To adjust a track selection property, the track must first be removed and then added with the new selection properties and a different name.

Catalog Examples The following section provides non-normative JSON examples of various catalogs compliant with this draft.

Time-aligned Audio/Video Tracks with single quality This example shows catalog for a media producer capable of sending LOC packaged, time-aligned audio and video tracks.

Simulcast video tracks - 3 alternate qualities along with audio This example shows catalog for a media producer capable of sending 3 time-aligned video tracks for high definition, low definition and medium definition video qualities, along with an audio track. In this example the namesapce is absent, which infers that each track must inherit the namespace of the catalog.

SVC video tracks with 2 spatial and 2 temporal qualities This example shows catalog for a media producer capable of sending scalable video codec with 2 spatial and 2 temporal layers with a dependency relation as shown below: | S1T1 | | | 1080p30 | | +----------+ | ^ | | +----------+ | | S1TO | | | 1080p15 | | +----------+ +-----+----+ ^ | SOT1 | | | 480p30 | | +----------+ | ^ +----------+ | | SOTO | | | 480p15 |---------+ +----------+ ]]> The corresponding catalog uses "depends" attribute to express the track relationships.

Patch update adding a track This example shows catalog for the media producer adding a slide track to an established video conference.

Patch update removing a track This example shows patch catalog update for a media producer removing the track from an established video conference.

Patch update removing all tracks and terminating the broadcast This example shows a patch catalog update for a media producer removing all tracks and terminating the broadcast.

CMAF Tracks with multiple qualities of audio and video This example shows catalog for a sports broadcast sending time-aligned audio and video tracks using CMAF packaging. Init segments are delivered as separate tracks.

Mixed format example - CMAF and LOC packaging in the same catalog This example shows catalog describing a broadcast with CMAF packaged video and LOC packaged audio.

CMAF Tracks with inband init segments This example shows catalog for a sports broadcast sending time-aligned audio and video tracks using CMAF packaging. Init segments are delivered as inband data.

Time-aligned Audio/Video Tracks with custom field values This example shows catalog for a media producer capable of sending LOC packaged, time-aligned audio and video tracks along with custom fields in each track description.

A catalog referencing catalogs for two different formats This example shows the catalog for a media producer that is outputting two streaming formats simultaneously under different namespaces. Note that each track name referenced points at another catalog object.