Skip to content
Book Your Discovery Call

How to add captions to a Shopify video

Captions on a Shopify video. Step 1, a WebVTT file in Content > Files with one caption, timed 0.5 to 4 seconds: Sam: This lid twists off in one turn for cleaning. Step 2, one track line in your theme's video, using file_url.

Shopify has no setting for captions on the videos you upload, and its Horizon and Dawn themes don't add them. There are two ways to add captions: host the video on YouTube or Vimeo and use their captions, or upload a WebVTT captions file to Content > Files and add one <track> line to your theme's video code. Either way, the captions need to be accurate and name each speaker.

We built the second option on a client's store in October. Here's how both work, and why we add a transcript as well.

What Shopify does and doesn't do out of the box

You can upload a video as product media or to Content > Files and give it alt text, or add a YouTube or Vimeo link as product media. None of those places has a field for a captions file.

The Liquid video object that themes read has no captions property, and the video_tag filter that themes use to print a video has no option for them. We checked Horizon 4.3.0 and Dawn 16.0.0: neither has a <track> element in any section, block or snippet.

Shopify's accessibility guidance for themes recommends closed captions.

Option 1: Host on YouTube or Vimeo and use their captions

Horizon's and Dawn's video sections both accept a YouTube or Vimeo link. The embedded player brings that platform's captions and CC button with it.

The trade-offs:

  • It's their player. The controls, the look and the terms are YouTube's or Vimeo's, not your theme's.
  • Privacy. In our November 1 test, a standard YouTube embed set five youtube.com cookies as the page loaded and contacted Google's ad servers. YouTube's privacy-enhanced version, on youtube-nocookie.com, set none, but Horizon and Dawn embed from youtube.com. The Vimeo player set four cookies.
  • Speed. In the same test, the YouTube player downloaded about 1.2 MB before anyone pressed play, and the Vimeo player about 570 KB. Horizon and Dawn hold the player back until the shopper presses play, as long as the video has a cover image and doesn't autoplay, so give it one.

Option 2: Captions on a video hosted by Shopify

Step 1: Write the WebVTT file

WebVTT is a plain text format, saved as a .vtt file in UTF-8. It starts with the word WEBVTT and a blank line. Then each caption gets a line with its start and end times, the text, and a blank line.

WEBVTT

00:00:00.500 --> 00:00:04.000
Sam: This lid twists off
in one turn for cleaning.

00:00:04.000 --> 00:00:06.000
[water running]

00:00:06.000 --> 00:00:11.500
Jordan: And it goes straight
in the dishwasher.

Three rules that trip people up:

  • Times use a period before the milliseconds, as in 00:00:04.000. A comma there is the SRT format. In our tests, a file with commas loaded but showed no captions.
  • Name the speaker whenever the speaker changes, and add sounds that matter in square brackets. WCAG's definition of captions includes both.
  • Type the name as plain text. WebVTT also has a voice tag, <v Sam>, but in our tests Chrome, Firefox and Safari's engine didn't show the name it holds.

Here's the first caption in Firefox, on a test page we built:

A video player in Firefox, paused 2 seconds into a sample clip titled Product video, showing a mug graphic, with captions on. The caption reads: Sam: This lid twists off in one turn for cleaning. The controls include a CC button.

Step 2: Upload it to Content > Files

In your Shopify admin, go to Content > Files and upload the .vtt file. Paid plans accept any file type except HTML. Note the file name, because the theme finds the file by it.

Shopify serves it as a generic download, not as WebVTT. Chrome, Firefox and Safari's engine loaded it anyway in our tests, on a live store and locally.

Step 3: Add the track to your theme's video

Because video_tag can't add a track, the theme writes its own <video> element. This sample assumes a section with a video setting and a text setting that holds the captions file's name:

{%- liquid
  assign video = section.settings.video
  assign captions = section.settings.captions_file
  assign mp4s = video.sources | where: 'mime_type', 'video/mp4'
  assign poster = video.preview_image
-%}
{%- if video != blank and captions != blank -%}
<video controls playsinline preload="metadata"
  poster="{{ poster | image_url: width: 1280 }}"
  width="{{ poster.width }}" height="{{ poster.height }}"
  {% if video.alt != blank %}
    aria-label="{{ video.alt | escape }}"
  {% endif %}
>
  {% for source in mp4s %}
    <source src="{{ source.url }}" type="{{ source.mime_type }}">
  {% endfor %}
  <track kind="captions" srclang="en" label="English"
    src="{{ captions | file_url }}">
</video>
{%- endif -%}

Why each choice matters:

  • The video's alt text as its name. Screen readers announce it when a shopper reaches the video, and WCAG asks for at least a short description of every video. Set it on the video in Content > Files.
  • A poster, width and height. Shopify makes a preview image for every uploaded video. As the poster it gives shoppers a cover image, and its width and height let the browser hold the video's space, so the page doesn't shift as it loads. Keep height: auto on the video in your theme's CSS.
  • MP4 sources only. Shopify also makes a streaming (HLS) version of each upload, and video_tag offers it to browsers that can play it. In our experience, iPhones show a separate captions file reliably with MP4, less so with the stream.
  • file_url. It turns the file name into the file's address on your store's own domain, the same one the page is on. In our tests, Chrome and Firefox refused a captions file from another domain unless the video had a crossorigin attribute.
  • No crossorigin. With the file on your own domain, you don't need it. Adding it changes how the browser requests every file the video uses, for no gain.
  • No default attribute. Captions start off, and shoppers turn them on with the CC control, as on YouTube. WCAG accepts closed captions, the kind a viewer switches on. If a video with speech autoplays muted, add default so its captions start on.

Like the sample, our client's section shows no video until a captions file is set.

To check your work, play the video and turn captions on. Browsers fetch the captions file only then, so a page that loads fine can still have a broken file.

Updating captions later

Use Replace, not a new upload. In Content > Files, choose Replace next to the file and pick the corrected .vtt. Shopify keeps the file name, and since the theme looks the file up by name, the page shows the new captions with no theme change.

A fresh upload with the same name gets a different name, so the theme keeps showing the old captions.

Add a transcript too

Captions help shoppers who can't hear the video. A descriptive transcript helps those who can't see it, or who would rather read. It includes all the dialogue with each speaker named, the sounds that matter, and anything shown but not said, such as a step the narration skips or a phone number in on-screen text. Put it on the same page as text, for example under the video. We add both to every video with speech.

Questions we hear

Do background videos need captions?

Not if they have no sound, since captions are for audio. Two other rules still apply: describe in text anything the video shows that shoppers need to know (1.2.1), and if it starts by itself and moves for more than five seconds, give shoppers a way to pause or stop it (2.2.2). A short clip on a loop counts. A video with speech that starts muted still needs captions.

Can I use auto-generated captions?

As a starting point. W3C's guidance on captions warns that automatic captions are often wrong. Correct the text, add speaker names and the sounds that matter, then upload the finished file.

Should I use SRT or VTT?

VTT for a Shopify-hosted video. In our tests, Chrome, Firefox and Safari's engine all refused an SRT file in a <track>. To convert one, add WEBVTT and a blank line at the top, and change the commas in the times to periods. YouTube and Vimeo accept either.

Can I add captions to a product's media videos?

Not from the product's media section, which has no captions field. Add the video as a YouTube or Vimeo link instead, or have a developer extend the product gallery to read a captions file name from a product metafield.

Braun Design Co is a boutique Shopify Plus partner in Austin. Custom themes, migrations, and ADA and WCAG 2.2 AA accessibility work for brands that already sell.

If your store has videos without captions or transcripts, we can add them to the theme you already have. Book a 30-minute call.

Back to BDC Blog

Let's build something amazing together

Share your project details and let's start the conversation

Or book your discovery call

Required fields are marked with an asterisk.

Search