WARP Streaming Format

Catalog A Catalog is a MOQT Track that provides information about the other tracks being produced by a WARP publisher. A Catalog is used by WARP 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 therelationship between tracks, properties of the tracks that consumers may use for selection and any relevant initialization data. The catalog track MUST have a case-sensitive Track Name of "catalog". A catalog object MAY be independent of other catalog objects or it MAY represent a delta update of a prior catalog object. The first catalog object published within a new group MUST be independent. A catalog object SHOULD only be published only when the availability of tracks changes. Each catalog update MUST be mapped to a discreet MOQT Object.

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 a 'tracks' 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. 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
WARP version	version
Supports delta updates	supportsDeltaUpdates
Tracks	tracks
Track namespace	namespace
Track name	name
Packaging	packaging
Track label	label
Render group	renderGroup
Alternate group	altGroup
Initialization data	initData
Dependencies	depends
Temporal ID	temporalId
Spatial ID	spatialId
Codec	codec
Mime type	mimeType
Framerate	framerate
Bitrate	bitrate
Width	width
Height	height
Audio sample rate	samplerate
Channel configuration	channelConfig
Display width	displayWidth
Display height	displayHeight
Language	lang

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

WARP version Location: R Required: Yes JSON Type: Number Specifies the version of WARP 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.

Supports delta updates Location: R Required: Optional JSON Type: Boolean A Boolean that if true indicates that the publisher MAY issue incremental (delta) updates - see . If false or absent, then the publisher guarantees that they will NOT issue any incremental updates and that any future updates to the catalog will be independent. The default value is false. This field MUST be present if its value is true, but may be omitted if the value is false.

Tracks Location: R Required: Yes JSON Type: Array An array of track objects .

Tracks object A track object is a collection of fields whose location is specified 'T' in Table 2.

Track namespace Location: TFC Required: Optional JSON Type: String The name space under which the track name is defined. See section 2.3 of . 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.

Track name Location: T Required: Yes JSON Type: String A string defining the name of the track. See section 2.3 of . Within the catalog, track names MUST be unique per namespace.

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	Draft
LOC	"loc"	See RFC XXXX

Track label Location: TF 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 spec requires UTF-8 support by decoders.

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

Alternate group Location: TF 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 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 Location: TF Required: Optional JSON Type: String A string holding Base64 encoded initialization data for the track.

Dependencies Location: T Required: Optional JSON Type: Array 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 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 with higher temporal fidelity.

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 with higher fidelity.

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 .

Mimetype Location: T Required: Optional JSON Type: String A string defining the mime type of the track.

Framerate Location: T Required: Optional JSON Type: Number A number defining the video framerate of the track, expressed as frames per second.

Bitrate Location: T Required: Optional JSON Type: Number A number defining the bitrate of track, expressed in bits per second.

Width Location: T Required: Optional JSON Type: Number A number expressing the encoded width of the video frames in pixels.

Height Location: T Required: Optional JSON Type: Number A number expressing the encoded height of the video frames in pixels.

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.

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.

Display width Location: T Required: Optional JSON Type: Number A number expressing the intended display width of the track content in pixels.

Display height Location: T Required: Optional JSON Type: Number A number expressing the intended display height of the track content in pixels.

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 .

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 namespace is absent, which infers that each track must inherit the namespace of the catalog. Additionally this example shows the presence of the supportsDeltaUpdates flag.

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.

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.

Timeline track The timeline track provides data about the previously published groups and their relationship to wallclock time, media time and associated timed-metadata. Timeline tracks allow players to seek to precise points behind the live head in a live broadcast, or for random access in a VOD asset. A timeline track may also be used to insert events at media times which do not correlate with Object boundaries. Timeline tracks are optional. Multiple timeline tracks MAY exist inside a catalog.

Timeline track payload The payload of a timeline track is a UTF-8 encoded CSV text file. This payload is formatted according to RFC4180 "Common Format and MIME Type for Comma-Separated Values (CSV)" Files . The separator is a comma and each line is separated by a carriage return. The mime-type of a timeline track MUST be specified as "text/csv" in the catalog. Each timeline track begins with a header row of MEDIA_PTS,GROUP_ID,OBJECT_ID, WALLCLOCK,METADATA. This row defines the 5 columns of data within each record.

MEDIA_PTS: a media timestamp rounded to the nearest millisecond. This entry MUST not be empty. If the Object ID entry is present, then this value MUST match the media presentation timestamp of the first media sample in the referenced Object.
GROUP_ID: the MOQT Group ID. This entry MAY be empty.
OBJECT_ID: the MOQT Object ID. This entry MAY be empty.
WALLCLOCK: the wallclock time at which the media was encoded, expressed as the number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT). For VOD assets, or if the wallclock time is not known, the value SHOULD be 0.
METADATA: a flexible field holding arbitrary string metadata. This field may be empty. If not empty, it MUST be enclosed in double quotes. A double-quote appearing inside this field MUST be escaped by preceding it with another double quote.

Timeline Catalog requirements A timeline track MUST carry a 'type' identifier in the Catalog with a value of "timeline". A timeline track MUST carry a 'dependencies' attribute which contains an array of all track names to which the timeline track applies.

Timeline track updating. The publisher MUST publish a complete timeline in the first MOQT Object of each MOQT Group. The publisher MAY publish incremental updates in the second and subsequent Objects within each GROUP. Incremental updates only contain timeline events since the last timeline Object. Group duration SHOULD not exceed 30 seconds.