libcmml: Concepts of time in CMML

# Concepts of time in CMML

Using time specifications in CMML is powerful but somewhat confusing. So, we describe it here in more detail. CMML has specifications of time in the stream and the clip tag. There are two different concepts of time specifications possible in CMML: utc time and playback time.

## The stream tag

The stream tag contains specifications of the INPUT media document(s) in the media tags. Conversely, the attributes of the stream tag refer to the OUTPUT annodex media document for which this CMML file provides the markup.

### Basetime attribute

The basetime attribute maps the first frame of the OUTPUT annodex document to a playback time to be displayed with the first frame. This playback time can be given as npt or some smpte specification given as a name-value pair, and it defaults to 0.

### Utc attribute

The optional utc attribute maps the basetime to a real-world clock time. It is given as a utc value.

### Start attribute of source tags

The start attribute specifies the insertion time of the specified INPUT document into the Annodex media file, i.e. the absolute time at which this media document (offset by seekoffset time) will start within the OUTPUT Annodexed file. It will usually be given as a npt or smpte time, which has to be greater than the basetime given in the stream tag (or just greater than 0 if there is not basetime given). The value is given as a name-value pair separated by a colon ":" though the name can be omitted if using npt. The start attribute can also be given as a plain utc time, which has to be some time after the utc time given in the stream tag. utc specification is not possible when the utc attribute in the stream tag is not given. The default value for the start attribute is "npt:0".

### End attribute of source tags

The end attribute specifies when the inserted INPUT media document will end. The time specification is analogous to the start attribute. This attribute is optional as the default end of the INPUT media document is when it finishes.

### Location attribute of source tags

As the location is specified as a URI, it may contain temporal fragment offsets. These specify a temporal subpart of the INPUT media document which will be inserted into the Annodexed media stream.

## The clip tag

The clip tag contains specifications of insertion time of the clip into the Annodexed media file.

### Start and end attributes

Insertion start and end times are given in the start and end attributes and they are specified in the same way as the start and end attributes of the source tag.