How do I add subtitles to a video?

Orshot allows you to automatically generate and overlay subtitles on your videos. You can configure subtitles directly in the Studio editor per page, or pass a subtitleSource via the API at render time.

Page-Level Subtitles#

You can attach subtitles to each page directly in the Studio editor:

• Upload an SRT file — subtitles are used as-is, no transcription needed
• Auto-generate from page audio — generated voiceovers reuse their word timings; uploaded and other audio is transcribed

Page subtitles include full styling controls (font, color, background, position) that are configured visually in the editor. These styles are automatically applied during rendering.

API Usage#

You can also provide subtitles via the videoOptions.subtitleSource field in the render API request. This is useful for dynamic subtitle sources or when you want to override page-level settings.

Single Page Templates#

For single-page templates, pass a direct URL string to your source file.

{
  "templateId": "your-template-id",
  "modifications": {
    "text": "Hello World"
  },
  "response": {
    "format": "mp4"
  },
  "videoOptions": {
    "subtitleSource": "https://example.com/audio.mp3",
    "subtitleColor": "#ffffff",
    "subtitleBackground": "rgba(0,0,0,0.5)",
    "subtitleFontSize": "32px",
    "subtitleOffset": "50px"
  }
}

Multi-Page Templates#

For multi-page templates (like carousels turned into video slideshows), you can specify different subtitle sources for each page. Each page's video segment will use its corresponding source.

Pass an array of objects, where each object specifies the page number and the url.

{
  "templateId": "your-multipage-template-id",
  "modifications": { ... },
  "response": {
    "format": "mp4",
    "includePages": [1, 2]
  },
  "videoOptions": {
    "subtitleSource": [
      {
        "page": 1,
        "url": "https://example.com/intro-audio.mp3"
      },
      {
        "page": 2,
        "url": "https://example.com/part-2-audio.mp3"
      }
    ],
    // Styling applies globally to all pages
    "subtitleColor": "#ffffff",
    "subtitleBackground": "#000000"
  }
}

Word-by-Word Subtitles (Lyric Videos)#

Set subtitleMode: "word-by-word" to reveal each word in sync with the audio instead of showing the whole phrase at once. Combined with subtitlePosition: "center", this produces the lyric-video style popular on TikTok and Reels.

{
  "templateId": "your-template-id",
  "response": {
    "format": "mp4"
  },
  "videoOptions": {
    "subtitleSource": "https://example.com/song.mp3",
    "subtitleMode": "word-by-word",
    "subtitlePosition": "center",
    "subtitleBackground": "transparent",
    "subtitleShadowBlur": 8,
    "subtitleMaxWordsPerLine": 4,
    "subtitleWordSpacing": "0.6em"
  }
}

How it works:

• Audio sources are transcribed with word-level timestamps. Each line shows up to subtitleMaxWordsPerLine words, and every word appears at the moment it is spoken or sung. A line stays visible until the next one starts.
• .srt and .vtt sources skip transcription; word timings are spread across each cue's duration. This is the reliable path for song lyrics: if automatic transcription mishears the vocals, upload an SRT with the correct lyrics and timing.
• The same mode is available in the Studio editor under the page's subtitle settings (Display: Word by word), where the style is saved on the template so every render and workflow uses it.

Supported Formats#

The subtitleSource URL can point to:

• Audio Files: .mp3, .wav, .m4a (Automated transcription via OpenAI Whisper)
• Video Files: .mp4, .mov, .webm (Audio extracted & transcribed)
• Subtitle Files: .srt, .vtt (Used directly without transcription)

Caption Presets#

Pass videoOptions.captionPreset to apply a complete named caption style in one option — or pick the same presets visually in the Studio subtitle popover:

{
  "templateId": "your-template-id",
  "response": { "format": "mp4" },
  "videoOptions": {
    "subtitleSource": "https://example.com/audio.mp3",
    "captionPreset": "karaoke"
  }
}

A preset layers between the page's saved subtitle styles and your explicit subtitle* options, so any individual property you pass still wins — "captionPreset": "karaoke", "subtitlePosition": "center" uses the karaoke look centered on screen.

Two things worth knowing before you reach for one:

• A preset sets subtitleMode and subtitleFontFamily along with the look. Every preset except minimal switches the page to word-by-word, and each brings its own font (karaoke and outline use Inter, bold uses Archivo Black, neon uses Poppins, pill uses Helvetica). Pass subtitleMode or subtitleFontFamily explicitly to keep your own.
• An unrecognised preset name is ignored rather than rejected, so a typo silently leaves your existing subtitle styling in place.

subtitleWordReveal, subtitleActiveColor and subtitleActiveBackground only take effect in word-by-word mode — there is no "current word" to style in phrase mode.

Styling Options#

When using page-level subtitles, styles are configured visually in the Studio editor. When using API-level subtitles, you can customize appearance with the following videoOptions properties:

Use subtitleWordReveal: "highlight" for karaoke-style captions or "align" to reveal spoken words while keeping the growing line centered. Set subtitleSplit: "letter" for a type-on effect. Use subtitleMaxCharsPerLine when a character limit fits the design better than a word limit.

Font Support#

You can use any Google Font by specifying its name in subtitleFontFamily. The system will automatically fetch and load it.

"videoOptions": {
  "subtitleFontFamily": "Inter, sans-serif"
}