Adding subtitles and captions to your videos

SmartVideo supports captions and subtitles in two ways: auto-imported from Vimeo, or manually added via WebVTT files.

Vimeo captions (auto-import)

If your video source is Vimeo, SmartVideo imports the captions that exist on the source when it first processes the video. Have all caption languages ready on Vimeo before then, so you don’t need a later caption fetch or a fresh source copy. Turn on caption import so the player shows the imported English track.

To enable caption import:

• WordPress plugin: Open SmartVideo in your WordPress admin sidebar. On the Settings tab, under Auto-conversions, turn on Import captions (it saves automatically).
• JavaScript snippet: Add youtubecaptions: true inside the existing swarmoptions.autoreplace object. Keep the other options already in that object.

The setting is named after YouTube for historical reasons. For Vimeo videos the option works as described; whether captions come across for a YouTube video that did convert is not something we can promise today.

Already converted the video, or added captions afterward? If no English captions are available and you have not supplied manual <track> elements, enable caption import and load a page with the video to request a captions-only fetch. The fetch is requested even if other caption languages were imported earlier. It runs asynchronously. After the captions have been fetched, reload the page so SmartVideo can attach the imported English track and show the CC control. If the video has captions only in other languages, add them with the captionsUrl helper and <track> elements below. This automatic fetch does not run for some videos whose captions were imported by an older version of SmartVideo. If the CC control still does not appear after a reload, add your captions with <track> elements (below), or put a fresh copy of the video on Vimeo and swap your embed to it.

Adding more languages when English captions were already imported: SmartVideo’s automatic caption check finds the existing English track and does not request another import. To import newly added languages, put a fresh copy of the video on Vimeo with all caption languages ready, then swap your site’s embed to that new video’s URL. Alternatively, add caption files manually with <track> elements.

SmartVideo imports every caption language available on the source Vimeo video. With caption import enabled and no manual <track> elements, the player adds the English track automatically. Use <track> elements to display other imported languages.

To display one of the additional imported languages, get its caption URL with the captionsUrl helper (run this in your browser console on any page with SmartVideo loaded):

swarmify.captionsUrl("https://player.vimeo.com/video/123456789", "es")

The first argument is the original video URL, the second is the language code. Paste the returned URL into a <track> element’s src (see below), and the language shows up in the player’s captions menu.

Adding any <track> element stops SmartVideo from adding the English track automatically. To keep English available alongside other languages, include an English <track> too. Get its URL with swarmify.captionsUrl("https://player.vimeo.com/video/123456789", "en"), using your original video URL.

Manual captions with WebVTT files

For full control over your captions, use the standard <track> element inside your SmartVideo tag with a WebVTT (.vtt) caption file.

<smartvideo src="https://your-video.example.com/file.mp4" width="1280" height="720" controls>
  <track default kind="captions" srclang="en" label="English" src="captions.vtt">
</smartvideo>

Multiple languages

You can add captions in multiple languages by including additional <track> elements. The one marked with default will be shown first, and viewers can switch between languages from the captions menu in the player controls.

<smartvideo src="https://your-video.example.com/file.mp4" width="1280" height="720" controls>
  <track default kind="captions" srclang="en" label="English" src="captions-en.vtt">
  <track kind="captions" srclang="es" label="Español" src="captions-es.vtt">
  <track kind="captions" srclang="fr" label="Français" src="captions-fr.vtt">
</smartvideo>

How captions show up in the player

• One caption track: the player shows a single CC toggle on the control bar (or inside the three-dot overflow menu on narrow players). Tap it once to turn captions on, tap again to turn them off.
• Multiple caption tracks: the CC button opens a submenu so viewers can pick a language or turn captions off.
• No caption files: the CC option is hidden entirely — you won’t see a stray “Captions” entry on videos that don’t have any.

Quick reference

For more details on the <track> element, see Mozilla’s reference documentation.

Keywords: captions, subtitles, WebVTT, VTT, track, YouTube captions, youtubecaptions, multiple languages, accessibility