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, AI_DETECTOR_RESULT,

version

✔

Long

The version of this resource, used for Optimistic Locking

int64