Subtitle Source

Supply your own VTT or SRT subtitle file as an external track instead of using Imgix’s AI transcription engine.

video-subtitle-src accepts a URL-encoded URL pointing to a publicly accessible .vtt or .srt file. Imgix fetches the file at request time and incorporates it into the output as a subtitle track.

https://assets.imgix.net/videos/girl-reading-book-in-library.mp4?fm=hls&video-subtitle-src=https%3A%2F%2Fexample.com%2Fsubtitles.vtt&video-subtitle-lang=en

Multiple Tracks

To add more than one subtitle track, use indexed variants: video-subtitle-src[1], video-subtitle-src[2], and so on. The bare video-subtitle-src parameter is equivalent to video-subtitle-src[0]. Pair each indexed source with a corresponding video-subtitle-lang[N] to tag the track’s language.

https://assets.imgix.net/videos/girl-reading-book-in-library.mp4?fm=hls
  &video-subtitle-src[0]=https%3A%2F%2Fexample.com%2Fen.vtt
  &video-subtitle-lang[0]=en
  &video-subtitle-src[1]=https%3A%2F%2Fexample.com%2Fes.vtt
  &video-subtitle-lang[1]=es

Each indexed track is delivered as a separate subtitle rendition in the HLS or DASH manifest, or as a selectable track for sidecar VTT delivery.

Base64 Variant

If the subtitle URL contains characters that are difficult to percent-encode, use video-subtitle-src64[N] to supply the URL as a Base64-encoded string instead. The value must be a standard Base64-encoded URL.

https://assets.imgix.net/videos/girl-reading-book-in-library.mp4?fm=hls&video-subtitle-src64=aHR0cHM6Ly9leGFtcGxlLmNvbS9zdWJ0aXRsZXMudnR0&video-subtitle-lang=en

Aliases

video-caption-src and video-caption-src64 are accepted as aliases for video-subtitle-src and video-subtitle-src64, respectively.

Delivery

Supplied subtitle tracks are delivered the same way as AI-generated ones:

• HLS / DASH (fm=hls, fm=dash): The track is embedded in the manifest as a subtitle rendition. Media players surface it automatically.
• Sidecar VTT (fm=vtt): Use video-subtitle-lang to select which track to return when multiple tracks are present.

When video-subtitle-src is set, Imgix uses the provided file as the caption source and does not run AI transcription, even if video-generate-subtitles=true is also present. The provided file always takes precedence.

Live Demo

The player below loads two subtitle tracks using indexed video-subtitle-src[N] — an English track and a French translation, both hosted as static VTT files. Use the CC/subtitles button in the player controls to switch between languages.

https://assets.imgix.net/Source%20Upload.mp4?fm=vtt
  &video-subtitle-src[0]=https%3A%2F%2Fassets.imgix.net%2Fdocs%2Fsubtitles-byos-demo.vtt
  &video-subtitle-lang[0]=en
  &video-subtitle-src[1]=https%3A%2F%2Fassets.imgix.net%2Fdocs%2Fsubtitles-byos-demo-fr.vtt
  &video-subtitle-lang[1]=fr