Archived docs Get your API Key
Documentation
🤖 AI Assistant

Subtitles element

Type: object

Defines a subtitles element, allowing you to add subtitles to the video. Subtitles can be automatically generated by transcribing the audio or provided via a URL to a subtitle file (SRT, VTT or ASS). You can customize the appearance of the subtitles using the settings property, including style, font, colors, position and more.

Working with the Subtitles element

Special considerations

The subtitles element works a bit differently than other elements:

  • It can only be used in the Movie elements array, meaning that you cannot enable or disable it on a per-scene basis.
  • You can't have multiple subtitles elements in a single movie
  • It's always processed at the end of the rendering process once the movie is complete
  • The automatic transcription "listens" to the audio track of the movie and transcribes it into text. If the voice is not clear, the transcription may not be accurate.

Providing your own captions

If you provide the captions in the captions property, the voiceover will not be transcribed and the captions will be displayed instead. The supported formats for the captions property are: SRT, VTT and ASS.

The word highlighting option is not available when providing your own captions unless your provide the captions in ASS format and the captions include the timing for each word.

Manual review of the transcription

In some cases, you may want to manually review the transcription before finally publishing the movie.

To manually review the transcription:

  1. Render the movie with the automatic transcription enabled.
  2. Download the transcription file in ASS format. You will find a URL to file in the GET /v2/movies response object (ass property) along with the URL to the rendered movie.
  3. Open the ASS file with a text editor and review the transcription.
  4. Upload the edited ASS file to public server and get a URL to the file.
  5. Render the movie again, this time providing the URL to the edited ASS file in the captions property.

Properties

The following properties are required:

  • type

captions

Specifies the captions to be used as subtitles. This can be either a URL pointing to a subtitle file, or the actual subtitle content directly embedded as a string. Supported subtitle formats for URLs or inline subtitles are: SRT, VTT, and ASS. If this property is omitted, the subtitles will be automatically generated from the audio track of the video.
Type string
Required No

comment

A field for adding descriptive notes or internal memos related to the subtitles element. This comment is for your reference and does not affect the rendering process.
Type string
Required No

language

The language of the audio to be transcribed. Specify a supported language code (e.g., en for English, es for Spanish) to improve transcription accuracy. Use auto to enable automatic language detection by the API.
Type string
Required No
Default Value "auto"
Enum Values auto, en, bg, ca, cs, da, nl, en-AU, en-GB, en-NZ, en-IN, en-US, et, fr, fi, nl-BE, de, de-CH, el, hi, hi-Latn, hu, id, it, ja, ko, lv, lt, ms, no, pl, pt, pt-BR, ro, ru, sk, es, es-419, sv, th, tr, uk, vi, zh, zh-TW

model

Specifies the transcription model to use when automatically generating subtitles from the audio. If a model is not specified, a default model will be used. Different models may offer varying levels of accuracy or support different languages.
Type string
Required No
Default Value "default"
Enum Values default, whisper

settings

Settings to customize the appearance of the subtitles, including style, font, colors, positioning, and other visual attributes. These settings allow you to tailor the subtitles to match your video's aesthetics and improve readability. Available settings depend on the chosen style.
Type object
Required No
Default Value {}

This object contains the following properties:

  • all-caps: (boolean, optional) - Makes the subtitles uppercase.

    • Default: false

  • box-color: (string, optional) - Color of the box behind the subtitles. Depending on the style, it can be the background color of the spoken word or the full line.

    • Default: "#000000"

  • font-family: (string, optional) - Font family of the subtitles. One of the font families below or a custom font family name if <code>font-url</code> is provided.

    • Default: "Arial"
    • Allowed values: Arial, Arial Bold, Katibeh, Lalezar, Libre Baskerville, Lobster, Luckiest Guy, Nanum Pen Script, Nunito, Pacifico, Roboto, Comic Neue, Orelega One, Oswald, Oswald Bold, Shrikhand, Fredericka the Great, Permanent Marker, NotoSans Bold, Simplified Chinese, Traditional Chinese, Japanese, Korean, Korean Bold

  • font-size: (integer, optional) - Font size of the subtitles. Usual sizes are between 90 and 150. Defaults to 5% of the movie width.

  • font-url: (string, optional) - URL to the font file to use for the subtitles. The font file must be in TTF format. The <code>font-family</code> property must match the font family name in the font file.

  • keywords: (array, optional) - Keywords provides additional vocabulary to the transcription process. Use it to improve the accuracy of the transcription of non-standard words or phrases. This options is only available for the default model.

  • line-color: (string, optional) - Color of the rest of words in the sentence.

    • Default: "#FFFFFF"

  • max-words-per-line: (integer, optional) - Maximum number of words per line. Setting this to 1 will show one word at a time.

    • Default: 4

  • outline-color: (string, optional) - Outline color of the subtitles.

    • Default: "#000000"

  • outline-width: (integer, optional) - Width of the outline.

    • Default: 0

  • position: (string, optional) - Position of the subtitles relative to the movie canvas.

    • Default: "bottom-center"
    • Allowed values: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right, mid-bottom-center, mid-top-center, custom

  • replace: (object, optional) - Replaces words with the specified replacement. Useful to correct the transcription of non-standard words or phrases. The object is a key-value pair where the key is the word to replace and the value is the replacement.

  • shadow-color: (string, optional) - Shadow color of the subtitles.

    • Default: "#000000"

  • shadow-offset: (integer, optional) - Offset of the shadow.

    • Default: 0

  • style: (string, optional) - Style of the subtitles. Classic styles show simple text overlays, while boxed styles show a box behind the subtitles. Check the examples for more details.

    • Default: "classic"
    • Allowed values: classic, classic-progressive, classic-one-word, boxed-line, boxed-word

  • word-color: (string, optional) - Color of word that is being spoken at the moment.

    • Default: "#FFFF00"

  • x: (integer, optional) - X coordinate of the subtitles relative to the movie canvas. This property is only used when the position property is set to custom.

    • Default: 0

  • y: (integer, optional) - Y coordinate of the subtitles relative to the movie canvas. This property is only used when the position property is set to custom.

    • Default: 0

type

This field specifies the element's type and must be set to subtitles for subtitles elements.
Type string
Required Yes
Enum Values subtitles

Examples

Example 1: Simple Image Element

This example demonstrates a movie with three images displayed in a slideshow. Each image is displayed for 3 seconds with a zoom effect and a pan effect.

{
  "resolution": "full-hd",
  "scenes": [
    {
      "comment": "First scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-01.jpg",
          "zoom": 3,
          "pan": "right"
        }
      ]
    },
    {
      "comment": "Second scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-02.jpg",
          "zoom": -3,
          "pan": "left"
        }
      ]
    },
    {
      "comment": "Third scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-03.jpg",
          "zoom": 3,
          "pan": "top"
        }
      ]
    }
  ]
}

Example 2: Image with Scaling and Rotation

This example shows how to scale an image and rotate it.

{
  "scenes": [
    {
      "elements": [
        {
          "type": "image",
          "src": "https://assets.json2video.com/assets/images/sunglasses-emoji-small.png",
          "x": 835,
          "y": 575,
          "width": 250,
          "height": 250,
          "rotate": {
            "angle": 360,
            "speed": 1
          }
        }
      ]
    }
  ]
}
← Previous: VoiceNext: Mastering →