Annotations

Below is the structure of a generic Annotation. These properties are available on all annotations, as all annotation types extend from this base type. See the section on Common types of Annotation: about objectType and funnel below for more information on the particular types of annotations.

Perhaps the most important fields of an annotation are its start and end fields. The Annotation is usually about a temporal part of the MediaObject. The time where it starts is contained in start. So this is the first frame of the Annotation. The end field contains the frame where the Annotation ends. The end frame itself is not included in the range, so it is actually the first frame number which is no longer part of the Annotation. Essentially, the Annotation describes the open-ended frame range [start, end[.

By using frames to describe an Annotation range, we can unambiguously refer to a certain frame range of a video, or audio by using a default frame rate of 25 FPS for audio-only content.

Note: The value of -1 for the end field can be used to represent up until the end of the clip. This is equivalent to setting end to the actual duration of the MediaObject.

All annotations have a language field. This is not always used, but it can be important, e.g. for Subtitle and TranscriptAnnotation.

The language is a string with a language code from the IETF BCP 47 specification. A readable resource for this specification can be found here.

Usually we don’t directly interact with a base Annotation object, but rather with a subclass of it. The objectType tells you what type of Annotation you are dealing with. The funnel describes how the Annotation should be interpreted by a client application. This allows using the same objectType for different applications (by using a different funnel) as long as the structure of the annotations is the same.