CDI (Cloud Digital Interface) Baseline Profile Ancillary Data Format Specification

Document version	01.00
Document owner	Amazon Web Services
Summary	This document specifies the format of ST 291-1 ancillary data payloads sent to and received from the CDI SDK.
Scope	The specifications in this document apply to ancillary data streams carried through the AWS CDI SDK's (Software Development Kit) AVM (Audio, Video, Metadata) API (Application Program Interface).
Status	current
Compatibility	CDI SDK version 1.0 and later support this version of the CDI baseline profile. Minor release number changes will only contain clarifications and corrections and therefore will maintain backwards compatibility with the SDK. The major number will be incremented when new features are added or any other incompatibility is introduced. A corresponding update to the CDI SDK will be required to support the changes documented in these future baseline profile documents.

Configuration Structure

The CdiAvmConfig structure is used to pass media format information through the CDI SDK for each stream. It contains three parts: a URI, a data array, and a data array size. The URI for this specification is defined to be https://cdi.elemental.com/specs/baseline-ancillary-data .

The bytes of the array are the ASCII characters forming <name>=<value> pairs, terminated by a semicolon. Each entry is separated from the next by a space character. data_size is the total number of characters comprising the string of names, values, and separators. No terminating carriage return or NUL character shall be included.

Supported parameter names and allowed values are:

cdi_profile_version - [required] version number string in the form of xx.yy where xx is the two digit major number and yy is the two digit minor number

Note: The CDI SDK provides CdiAvmMakeBaselineConfiguration() for generating an appropriate CdiAvmConfig structure to pass to CdiAvmTxPayload() and CdiAvmParseBaselineConfiguration() for parsing CdiAvmConfig structures from the receive payload callback function. These functions alleviate the need for application programs to deal directly with the CdiAvmConfig structure for CDI baseline media types, including ancillary data.

The configuration structure is fixed for all ancillary data streams:

uri = "https://dez7slaihsw2s.cloudfront.net/baseline-ancillary-data" [NUL terminated]
data_bytes = "cdi_profile_version=01.00;"
data_size = 26

Payload Format

The format of ancillary data payloads is based loosely on SMPTE 2110-40 which references IETF RFC 8331. Notable changes include:

The first 16 bytes, up to and including the Length field, are not included in the CDI header. CDI is not based on RTP so the RTP header is unnecessary.
The width of the ANC_Count field is increased by 8 bits which were taken from the "reserved" field.
The F bit's position has changed.

The meanings of all the remaining fields are the same as in RFC 8331. Each payload must contain exactly one interlaced field or one progressive frame of ancillary data packets.

Each ancillary data payload starts with a header as shown in the section below:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           ANC_Count           | F |         reserved          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The section below is repeated once for each ancillary data packet, as specified by ANC_Count.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |C|   Line_Number       |   Horizontal_Offset   |S|  StreamNum  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         DID       |        SDID       |   Data_Count      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                            User_Data_Words...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |   Checksum_Word   |word_align |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Note that on the receive side of a CDI connection, the scatter-gather entries that describe the ancillary data packets in memory may start and end at arbitrary four byte word boundaries. Unlike audio and video, the irregular structure of ancillary data makes predicting packet boundaries impractical on the transmit side.

References

IETF RFC 8331: https://tools.ietf.org/html/rfc8331
ST 2110-40:2018 - SMPTE Standard - Professional Media Over Managed IP Networks: SMPTE ST 291-1 Ancillary Data," in ST 2110-40:2018, 25 April 2018, doi: 10.5594/SMPTE.ST2110-40.2018: https://ieeexplore.ieee.org/document/8353279