Convert Subtitles for Video.js

Video.js captions should usually be delivered as WebVTT (VTT) because the player runs in a browser environment. Video.js is built on HTML5 video technology, so it expects web-native subtitle formats. For a format comparison, see best subtitle format for Video.js. Converting SRT or ASS to VTT ensures captions work reliably across all browsers and Video.js configurations.

Quick answer

Use the Video.js Subtitle Converter to turn SRT or ASS source subtitles into WebVTT output before attaching captions to the player. The converter prepares the caption file. You still need to test the Video.js track configuration separately.

When to use this workflow

Use this workflow when:

Subtitles came from a transcription tool as SRT: Rev, Otter, Descript, and most transcription services export SRT by default
Subtitles came from an editor as ASS: Aegisub exports with advanced styling that browsers don’t support
A Video.js integration needs a web-ready caption file: Converting to VTT ensures browser compatibility
Captions fail because a file was renamed instead of converted: Renaming .srt to .vtt doesn’t convert the format

If the file is already VTT, validate it before debugging player settings using the WebVTT Validator.

Why Video.js needs VTT

Video.js is built on HTML5 video technology, so it expects WebVTT format:

Browser-native support: VTT is the W3C standard for HTML5 video captions
Reliable parsing: Video.js’s caption engine is optimized for VTT
Better debugging: If the VTT file is valid, caption issues are more likely to come from the player setup or server configuration, not the subtitle format
Cross-browser compatibility: VTT works consistently across Chrome, Firefox, Safari, and Edge

Step-by-step workflow

1. Keep the source subtitle file for editing or archive

Before converting, save a copy of the original file. You’ll need it if you want to make edits later or restore styling (for ASS files).

2. Convert to VTT

Open the Video.js Subtitle Converter
Upload or paste the SRT, VTT, or ASS subtitle content
Click Convert to VTT
The tool automatically:
- Adds the WEBVTT header (if missing)
- Converts timestamp format to VTT style (dots instead of commas)
- Removes SRT cue numbers (optional in VTT)
- Strips ASS styling and override tags
- Preserves subtitle text and timing

3. Confirm the output is VTT

Check the converted VTT file:

✅ Header: First line is WEBVTT (uppercase)
✅ Timestamps: Use dots (00:00:01.000), not commas (00:00:01,000)
✅ Text: Subtitle text is intact and readable
✅ Encoding: Non-English characters display correctly

4. Download the VTT file

Click Download VTT to save the converted file. The file is ready to use in Video.js.

5. Attach the VTT file to Video.js

Add the VTT file to your Video.js configuration:

<video id="my-video" class="video-js" controls preload="auto">
  <source src="video.mp4" type="video/mp4" />
  <track kind="subtitles" src="captions.en.vtt" srclang="en" label="English" default />
</video>

<script>
  var player = videojs('my-video');
</script>

6. Test captions in the actual page

Open the page in a browser and verify:

Captions appear in the Video.js subtitle menu
Text displays at the correct times
No timing drift or sync issues
Captions work across different browsers (Chrome, Firefox, Safari, Edge)

What changes during conversion

From SRT to VTT:

✅ Header added: WEBVTT line added at the top
✅ Timestamps converted: Commas → dots (00:00:01,000 → 00:00:01.000)
✅ Cue numbers removed: Sequential numbers (1, 2, 3) are optional in VTT
✅ Text preserved: Subtitle text and timing stay the same

From ASS to VTT:

✅ Header added: WEBVTT line added at the top
✅ Timestamps converted: ASS format → VTT dot-based format
✅ Text preserved: Subtitle text stays the same
✅ Line breaks preserved: ASS \N → actual line breaks
❌ Styling removed: Colors, fonts, borders, shadows are stripped
❌ Positioning lost: All subtitles appear in the default position
❌ Override tags removed: {\an8}, {\c&HFF0000&}, {\pos(x,y)}, etc. are deleted

Unsupported styling metadata is removed. The output is ready to validate as a VTT file.

Common mistakes

Assuming conversion fixes player configuration

Conversion only prepares the subtitle file. If captions still don’t appear, check the track URL, kind, label, language, and browser console.

Fix: After conversion, validate the VTT file. See how to validate WebVTT files for a detailed walkthrough. Then check the Video.js configuration and browser console for errors.

Testing only the text file

A valid-looking VTT file still needs to be tested in the real Video.js environment. Issues like wrong MIME type, CORS errors, or malformed cues may only appear during playback.

Fix: Always test the VTT file in the actual Video.js player, not just in a text editor.

Shipping ASS as the browser caption file

ASS is useful in editors, but it’s not the normal final caption format for browser-based Video.js playback. Browsers don’t support ASS natively.

Fix: Convert ASS to VTT before using it in Video.js.

Renaming instead of converting

Changing .srt to .vtt leaves SRT timing and missing WebVTT structure behind. Browsers reject renamed files.

Fix: Use the Video.js Subtitle Converter to properly convert the file.

Using the wrong MIME type

If the server sends Content-Type: text/plain or application/octet-stream, the browser refuses to parse the file as WebVTT.

Fix: Configure the server to send Content-Type: text/vtt for .vtt files. See How to fix VTT MIME type for HTML5 video for server-specific instructions.

Forgetting CORS headers for cross-origin VTT files

If your video page is at example.com and the VTT file is at cdn.example.com, the browser blocks the request unless the server sends Access-Control-Allow-Origin headers.

Fix: Configure CORS on the CDN or origin server, and add crossorigin="anonymous" to the <video> element.

Troubleshooting scenarios

Scenario 1: Captions don’t appear in Video.js

Possible causes:

VTT file is malformed (missing WEBVTT header, wrong timestamp format)
Server sends wrong MIME type (text/plain instead of text/vtt)
CORS headers missing (cross-origin request blocked)
Track element has wrong src URL (404 error)
Video.js version doesn’t support VTT (very old versions)

Fix:

Validate the VTT file with the WebVTT Validator
Check the browser console for errors (F12 → Console tab)
Check the Network tab for the VTT request - verify it returns 200 OK and Content-Type: text/vtt
If cross-origin, verify CORS headers and crossorigin="anonymous" attribute
Update Video.js to the latest version if using an old version

For MIME type issues, see how to fix VTT MIME type for HTML5 video. For a broader troubleshooting walkthrough, see Why Video.js captions are not showing.

Scenario 2: Captions appear but text is garbled

Cause: Wrong text encoding (e.g., Windows-1252 instead of UTF-8).

Fix: Re-save the source file as UTF-8 before converting, or use the Subtitle Encoding Fixer after conversion.

Scenario 3: Captions work in Chrome but not Firefox or Safari

Cause: Firefox and Safari are stricter about MIME types and CORS than Chrome.

Fix:

Confirm Content-Type: text/vtt (not text/plain)
If cross-origin, ensure Access-Control-Allow-Origin is set
Check the browser console for specific error messages

Scenario 4: Timestamps are off by a few seconds

Cause: Rounding errors during conversion, or the original file had precision issues.

Fix: Use the Subtitle Time Shifter to adjust timing after conversion.

Scenario 5: Some cues are missing from the VTT output

Cause: The source file has malformed cues (missing timestamps, wrong format) that the converter skipped.

Fix: Validate the source file before converting. Fix any errors, then re-convert.

Frequently asked questions

Does Video.js support SRT natively?

No. Video.js relies on the browser’s native <track> element, which only supports WebVTT. To use SRT, you need a plugin or conversion.

Can I use SRT with a Video.js plugin?

Yes, but it’s not recommended. Plugins add complexity, increase bundle size, and may have compatibility issues. Converting SRT to VTT is simpler and more reliable.

What’s the difference between VTT and SRT?

Difference	SRT	VTT
Header	None	`WEBVTT` required
Timestamps	`00:00:01,000` (comma)	`00:00:01.000` (dot)
Browser support	❌ Not native	✅ Native
Video.js support	⚠️ Plugin required	✅ Native

Can I style VTT captions in Video.js?

Yes. Video.js supports custom caption styling via CSS and configuration options. You can customize font, color, background, size, and position.

How do I add multiple subtitle languages?

Add multiple <track> elements with different srclang and label attributes:

<video id="my-video" class="video-js" controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="subtitles" src="captions.en.vtt" srclang="en" label="English" default />
  <track kind="subtitles" src="captions.es.vtt" srclang="es" label="Español" />
  <track kind="subtitles" src="captions.fr.vtt" srclang="fr" label="Français" />
</video>

What if my VTT file has a BOM (Byte Order Mark)?

Some text editors (Notepad on Windows) save UTF-8 files with a BOM - 3 invisible bytes at the start. The WebVTT parser sees this as garbage before WEBVTT and rejects the file.

Fix: Re-save the file as “UTF-8 without BOM” in your editor.

Can I use VTT for live streaming with Video.js?

Yes. Video.js supports live VTT captions via HLS (HTTP Live Streaming) or DASH (Dynamic Adaptive Streaming over HTTP).

What’s the best way to serve VTT files?

MIME type: Configure your server to send Content-Type: text/vtt
CORS: If cross-origin, send Access-Control-Allow-Origin headers
Encoding: Always use UTF-8 encoding