Subtitle

The Subtitle annotation is a bit special, as it spans the entire range of the MediaObject. One Subtitle Annotation contains all the subtitle captions in a particular language and for a given subtitle preset of the clip.

Learn more about subtitling in Limecraft Flow here.

objectType, funnel, type

The Subtitle Annotation is actually a StructuredAnnotation.

The objectType will be "StructuredAnnotation", the type of the StructuredAnnotation will be "SUBTITLE", and the funnel is set to "Subtitle".

All the subtitle-specific properties are inside the structuredDescription.

Example

The example below shows a single Subtitle Annotation, with two lines of text, which is the result of the automatic subtitler. The example contains some comments explaining the properties.

{
  "funnel": "Subtitle",
  "objectType": "StructuredAnnotation",
  "type": "SUBTITLE",
  "tags": [
    "automatic_subtitler_version:3.13.0"
  ],
  "source": "automatic_subtitling",
  "label": "Automatic Subtitling Mon Oct 28 2019 14:28:17 GMT+0100 (Central European Standard Time)",
  "structuredDescription": {
    // each entry in this array is one subtitle item which is shown during a specific time period on the screen
    "subtitles": [
      {
        "start": 1910,
        "end": 1966,
        // ...
        // discussed further below
      },
      {
          // ...
      }
    ],

    // the subtitle should use the settings defined in this preset. The preset should be defined in the production settings
    "subtitlePresetId": "preset_001"
  },

  // which language is the subtitle in?
  "language": "en"
}

subtitles

The structuredDescription.subtitles array contains the individual timecoded captions. One such a caption might look like this:

{
    // start and end in frames
    "start": 1910,
    "end": 1966,

    // the region referenced here should be defined. At the moment we support topRegion and bottomRegion.
    "region": "bottomRegion",

    // contains warnings generated by the automatic subtitler. Warnings indicate a situation where
    // not all spotting rules could be respected
    "warnings": [
      {
        "type": "WPM",
        "value": 267,
        "target": 180
      }
    ],

    // How confident is the automatic subtitler about the timing of this subtitle?
    "confidence": 0.9189915107473923,

    // Does the end of the subtitle split a sentence in two? (does the sentence continue in the next subtitle)
    "sentenceSplit": false,

    // textParts contains the actual subtitle item's content. A single textPart will have type
    // "span" or type "lineBreak".
    "textParts": [
        {
            "content": "This blade has a dark past.",
            "type": "span",
            "style": "yellowStyle"
        },
        {
            "type": "lineBreak"
        },
        {
            "content": "This is in white ",
            "type": "span",
            "style": "whiteStyle"
        },
        {
            "content": "and cyan.",
            "type": "span",
            "style": "cyanStyle"
        },
        {
            "type": "lineBreak"
        }
    ]
}
Field Description

start

The first frame where the caption should appear on screen.

end

The caption will remain visible up to (but not including) this frame.

region

The region where this caption should appear. In practice, two regions are supported: "bottomRegion" and "topRegion". The exact position and size of these regions is defined in the subtitle template settings.

warnings

An array of warnings applicable to the current subtitle. These usually contain violations regarding the spotting rules. They are not updated automatically, and are usually set by the subtitle engine once, after automatically generating the Subtitle annotation.

confidence

How confident are we about the subtitles?

sentenceSplit

textParts

This contains the actual textual content of the subtitle. It is split up in parts however. See the textParts section below.

Field Name Required Type Description Format

confidence

Double

double

dirty

Boolean

end

Long

int64

region

String

sentenceSplit

Boolean

start

Long

int64

style

String

textParts

List of SubtitlePart

warnings

List of SpottingRuleWarning

textParts

The textParts is an array of objects which together represent the content of the caption.

Subtitle text parts example

The caption shown in the above image will be represented by textParts equal to this:

[
    {
        "content": "This blade has a dark past.",
        "type": "span",
        "style": "yellowStyle"
    },
    {
        "type": "lineBreak"
    },
    {
        "content": "This is in white ",
        "type": "span",
        "style": "whiteStyle"
    },
    {
        "content": "and cyan.",
        "type": "span",
        "style": "cyanStyle"
    },
    {
        "type": "lineBreak"
    }
]

A single element in the textParts array can have these properties:

Field Description

type

A string representing the type of textPart.

  • "lineBreak" Break to the next line. Other properties on the textPart are ignored

  • "span" Textual content.

content

Textual content (a String)

style

A string referencing the defined style to apply. This style is defined on the subtitle template.

Language

The language field is used to store the language the Subtitle is in. See Annotation for information on the possible values for the language.

subtitlePresetId

The structuredDescription.subtitlePresetId field refers to the subtitle template used to create the Subtitle. Styling will be loaded from this template. Learn more about templates in Limecraft Flow here.

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.

genericType

String

id

Long

The id of this resource

int64

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

mediaObject

MediaObject

mediaObjectId

Long

int64

modifiedBy

String

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

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

structuredAnnotation

SubtitleObject

structuredDescription

Object

systemFields

CustomFields

tags

Set of string

translatedFromId

Long

int64

translatedToIds

Set of long

int64

type

String

Enum: MINIME, EBU_CORE, TRANSCRIBER, TECHNICAL_DETAILS, GENERIC, SUBTITLE, SHOT,

version

Long

The version of this resource, used for Optimistic Locking

int64