Video Options

The videoOptions object controls render-level behavior when response.format is set to "mp4", "webm", "mov", "mkv", or "gif".

All Options#

{
  "videoOptions": {
    "fps": 30,
    "quality": 80,
    "trimStart": 0,
    "trimEnd": 20,
    "duration": 8,
    "muted": true,

    "subtitleSource": "https://example.com/subtitles.srt",
    "subtitleFontSize": "30px",
    "subtitleFontWeight": "700",
    "subtitleColor": "#ffffff",
    "subtitleBackground": "rgba(0,0,0,0.5)",
    "subtitleFontFamily": "Inter, sans-serif",
    "subtitlePosition": "bottom",
    "subtitleOffset": "50px",
    "subtitlePaddingX": "16px",
    "subtitlePaddingY": "8px",
    "subtitleBorderRadius": "6px",

    "combinePages": true,
    "pageTransition": "fade",
    "pageTransitionDuration": 0.5
  }
}

Performance and Quality#

FPS#

• videoOptions.fps
• Type: number
• Range: 1 to 30
• Controls output frame rate. When not specified, FPS is set automatically based on video length (shorter videos get higher FPS, up to 30). GIF defaults to 15 FPS.

Quality#

• videoOptions.quality
• Type: number
• Range: 1 to 100
• Higher values produce better visual quality with larger file size.

Trimming and Duration#

Trim Range#

• videoOptions.trimStart
• videoOptions.trimEnd
• Type: number (seconds)

When both are provided, output duration is calculated as trimEnd - trimStart.

Duration Fallback#

• videoOptions.duration
• Type: number (seconds)
• Used as a fallback duration when a trim range is not provided.

Audio#

Muted#

• videoOptions.muted
• Type: boolean
• true: force mute all output audio (video elements and page audio)
• false: include audio from video elements and page-level audio

Page-Level Audio#

Each page can have multiple audio tracks (e.g., background music + voiceover) configured in the Studio editor. Audio tracks are automatically mixed into the video output alongside any video element audio.

Each audio track supports:

• Volume control — adjust the mix level relative to other tracks
• Fade in / fade out — smooth audio transitions
• Trim — use a specific portion of the audio file
• Offset — delay when the audio starts playing within the page
• Loop — repeat the audio to fill the full page duration

Audio Source#

• videoOptions.audioSource
• Supported forms:
  • string: a single audio URL applied to the first audio track on each rendered page
  • array: per-page (and optionally per-track) source mapping for targeted overrides

Per-page format:

{
  "videoOptions": {
    "audioSource": [
      { "page": 1, "url": "https://example.com/music.mp3" },
      { "page": 1, "track": 1, "url": "https://example.com/voiceover.mp3" },
      { "pageId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "url": "https://example.com/chapter-2-music.mp3" }
    ]
  }
}

When audioSource is provided as a string, it overrides the first audio track URL on each rendered page. When provided as an array, each entry targets a specific page (by page number or pageId) and track. If the target track index doesn't exist, a new track is created. Passing a single string on a multi-page render applies the same audio to every page.

Subtitles#

Subtitle Source#

• videoOptions.subtitleSource
• Supported forms:
  • string: single source URL for single-page renders
  • array: per-page source mapping for multi-page renders

Per-page format:

{
  "videoOptions": {
    "subtitleSource": [
      { "page": 1, "url": "https://example.com/intro.mp3" },
      { "page": 2, "url": "https://example.com/chapter-2.srt" }
    ]
  }
}

Subtitle Styling#

Word-by-Word Subtitles#

Set subtitleMode: "word-by-word" to reveal each word in sync with the audio, the style used in lyric and karaoke videos on TikTok and Reels. Words of the current line appear one at a time as they are spoken or sung, and the line stays on screen until the next one starts.

{
  "videoOptions": {
    "subtitleSource": "https://example.com/song.mp3",
    "subtitleMode": "word-by-word",
    "subtitlePosition": "center",
    "subtitleBackground": "transparent",
    "subtitleFontFamily": "Special Elite",
    "subtitleShadowBlur": 8
  }
}

A few tips for this mode:

• For the borderless lyric-video look, set subtitleBackground: "transparent" and add a text shadow for readability. The default background renders a stable pill sized for the whole line.
• Word timing comes from transcription. Music with heavy instrumentation can throw the transcription off. If the generated words are wrong, pass an .srt file with the correct lyrics as subtitleSource instead: word timings are then spread across each cue's duration, so your text is always right.
• subtitlePosition: "center" places the line in the middle of the frame and ignores subtitleOffset.

Multi-Page Combine Options#

Combine Pages#

• videoOptions.combinePages
• Type: boolean
• Combines multi-page video renders into one final video.

Page Transition#

• videoOptions.pageTransition
• Type: string
• Supported values:
  • fade
  • fadeblack
  • fadewhite
  • dissolve
  • wipeleft
  • wiperight
  • wipeup
  • wipedown
  • slideleft
  • slideright
  • slideup
  • slidedown
  • circleopen
  • circleclose
  • pixelize
• Omit or use "none" for hard cuts.

Page Transition Duration#

• videoOptions.pageTransitionDuration
• Type: number
• Range: 0.1 to 2 (seconds)

Complete Request Example#

await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <YOUR_API_KEY>",
  },
  body: JSON.stringify({
    templateId: "<YOUR_TEMPLATE_ID>",
    modifications: {
      "page1@title": "Intro",
      "page2@title": "Features",
      "page3@title": "CTA",
    },
    response: {
      format: "webm",
      type: "url",
      includePages: [1, 2, 3],
    },
    videoOptions: {
      fps: 30,
      quality: 80,
      muted: true,
      combinePages: true,
      pageTransition: "fade",
      pageTransitionDuration: 0.5,
      subtitleSource: [
        { page: 1, url: "https://example.com/intro.mp3" },
        { page: 2, url: "https://example.com/chapter2.mp3" },
      ],
      subtitleFontSize: "30px",
      subtitleColor: "#ffffff",
      subtitleBackground: "rgba(0,0,0,0.5)",
    },
  }),
});