ClipAnnotation

This represents a comment or a log about part of the media. In addition to a temporal range, it can also contain spatial indications to indicate it concerns a position of the video frame.

Details of a ClipAnnotation

The image below contains an example of a ClipAnnotation, in this case with funnel ReviewComment. We will discuss the fields important for it below.

Example of a ClipAnnotation

Description, tags and mentions

Like any annotation, the ClipAnnotation has a plain-text description, and also a tags field. In the Limecraft Flow UI, one can fill in the description and use the # or @ sign to include tags and mentions.

When saving the ClipAnnotation, this will be parsed into three different fields: description, tags and mentionIds.

field description

description

Plain text description, containing markers for mentions and tags.

Example:

"test hello @{3,karel2000} this is a #{tag with spaces} and some more plain text"
Example visualization ClipAnnotation description

tags

An array with strings representing the tags.

[
    "tag with spaces"
]

mentionIds

An array with user ids representing the users who are mentioned.

[
    27
]

It might be a bit confusing that the some of the information seems to be duplicated between the description, tags and mentionIds fields. Adding the tags and mentions inside the description should be seen as a UI mechanism to make it easy to add mentions and tags, but once they are saved, they are explicitly added to their own fields. The platform’s API backend does parse the description, but does not automatically fill in the mentionIds and tags fields based on it. This is a client responsibility.

Reference a part of the video frame via spatial, uiLocation

Some ClipAnnotations can have spatial information, linking them to a particular point in the video frame. This is done using the spatial and uiLocation fields.

field description

spatial

A string representing the position of the region the comment is about.

xywh=percent:25.8,31.7,1,1

Based on http://www.w3.org/TR/media-frags/#naming-space. At the moment, the UI will only recognize the particular format percent:x,y,1,1, where x is the horizontal position with 0 being the left of the video frame and 100.0 being the right of the video frame, and y is the vertical position (also between 0, for top, and 100, for bottom of the video frame).

uiLocation

A string representing the position of the user interface element with the comment. I.e. the "box" with the comment, as opposed to the "dot" it is talking about.

xywh=percent:68.5,68.6,1,1

See spatial for more info on the format.

Comment Threads using relatedToId

It is possible to give a 'reply' on another comment:

Illustration of threads

Internally, this is done using the relatedToId field. It should be set to the id of the original comment that this is a reply to. At the moment, the Limecraft Flow UI supports only one deeper level of comment replies.

In the image above, if the "test @karel500" comment has id 1200, the two comments below it should have its relatedToId set to 1200.

id relatedToId description

1200

the comment with "test @karel500"

1400

1200

the comment with "my reply"

1401

1200

the comment with "yet another reply"

Include transcript quote of matching time range

It is possible to refer to part of the transcript by setting the includesFrom field to ["transcript:en"] (to include from the English transcript). In the Limecraft Flow UI this is possible on logger subclips, and it looks like this:

ClipAnnotation with transcript quote

Including from the transcript will also add the matching transcription text to the annotation in the SOLR search index.

Restricted Visibility

The visibility of a ClipAnnotation can be adjusted so that it is only visible for workspace members with the VIEW_COMMENT_INTERNAL permission. The UI only exposes this functionality when the funnel is ReviewComment.

The activeSecurityClasses of the Production should contain "VIEW_COMMENT_INTERNAL" for this to work. The feature is not enabled otherwise.
Restricted annotation

The securityClasses field defines what extra permissions are required to view this comment. It is either empty (unset or empty array) or it is the ['VIEW_COMMENT_INTERNAL'] array.

In addition, the markForUnrestricted boolean field can be set to true to mark a comment with restricted visibility as a candidate for becoming available to the entire team. There is no backend functionality coupled to this, making the comment visible is a manual action.

securityClasses markForUnrestricted UI shows as

[] or unset

anything

A plain comment, visible to entire team

["VIEW_COMMENT_INTERNAL"]

false

A restricted comment

["VIEW_COMMENT_INTERNAL"]

true

A restricted comment, which is scheduled to become visible to the entire team.

Funnels

Today, there are two funnels in use for the ClipAnnotation objectType:

  • The ClipAnnotation funnel is used for subclips in the Logger application of the Limecraft Flow UI.

  • The ReviewComment funnel is used for comments in the Review application of the Limecraft Flow UI.

  • The Chapter funnel is used for chapters in the Summary application of the Limecraft Flow UI.

In the UI, not all features discussed on this page are available on both.

Feature ClipAnnotation funnel ReviewComment funnel

tags

✓

✓

transcription quote

✓

mentions

✓

threads

✓

refer to part of video frame (spatial and uiLocation)

✓

Property Reference

Field Name Required Type Description Format

annotationProductionId

✘

Long

int64

clipMetadata

✘

ClipMetadata

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

createdByShareId

✘

Long

int64

createdBySharedUserId

✘

Long

int64

creatorId

✘

Long

The id of the user who created this resource

int64

crossProduction

✘

Boolean

customFields

✘

CustomFields

deleted

✘

Date

date-time

description

✘

String

Textual contents of the Annotation

end

✘

Long

The frame range described by the annotation runs up to end, but not including it. Should be less than or equal to the amount of frames the MediaObject has.

int64

funnel

✘

String

Describes how the Annotation should be interpreted by the client application. Can be thought of as a subtype.

id

✔

Long

The id of this resource

int64

ignoreTimecode

✘

Boolean

includeTranslatedTo

✘

Boolean

includesFrom

✘

Set of string

keyframeFrames

✘

Long

int64

label

✘

String

language

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

markForUnrestricted

✘

Boolean

mediaObject

✘

MediaObject

mediaObjectId

✘

Long

int64

modifiedBy

✔

String

The request or process responsible for the last update of this resource

name

✘

String

objectType

✘

String

The data model type or class name of this resource

origin

✘

String

productionId

✘

Long

int64

rating

✘

Double

double

relatedToId

✘

Long

int64

securityClasses

✘

Set of string

Enum:

source

✘

String

spatial

✘

String

Link the Annotation to a specific part of the video or image frame. A Media Fragments Spatial Dimension description string is expected.

start

✘

Long

First frame of the Annotation. 0 is the first frame of the clip. The start frame is included in the frame range the annotation describes.

int64

systemFields

✘

CustomFields

tags

✘

Set of string

topics

✘

Set of string

translatedFromId

✘

Long

int64

translatedToIds

✘

Set of long

int64

uiLocation

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64