If the video plays but the subtitles do not, test the track separately before editing the transcript. Use the small same-origin example below to separate a loading problem from a timing problem.
Attach a track the player can select
Put the final video and UTF-8 VTT on the same site. Place the track element inside video, using a relative URL that resolves from the page. Set srclang to the language of the text, not automatically the language of the audio. Give each language its own label. Use captions for a track that also conveys relevant sounds.
<video controls src="lesson.mp4">
<track kind="subtitles" src="example-en.vtt"
srclang="en" label="English" default>
</video>
Make a two-file test before changing the player
Download the example VTT and use the same English demonstration video shown below. Put both files beside a small HTML page on a test web server. If you keep the names in the example markup, name the media file lesson.mp4 and the track example-en.vtt. Open the page through its web address. Opening a file directly from a desktop folder can introduce browser restrictions that make a working track look broken. Start with one track so you can tell exactly which file produced the text on screen.
The sample contains only the workshop announcement. Silence on the subtitle layer during the opening words is expected. Pause at eight seconds and compare the displayed sentence with the sample cue. Then seek to thirteen seconds and check that it has cleared. These two observations test different things. Seeing the right sentence proves that the player found and parsed at least one cue. Seeing it disappear at the expected point helps rule out a second subtitle track or text already embedded in the picture.
Follow the request when the subtitles menu is empty
Open the browser’s network panel, reload the page and select the English track. Look for the request that ends in .vtt. If no request appears, inspect the video element on the published page. A content editor may show the correct markup in its draft while removing a track element when the page is saved. If the request does appear, compare its full address with the location of the uploaded file. A relative path in an article nested under a course directory can point somewhere different from the same path on your test page.
Read the response body as well as the status. You should see the WEBVTT header, a blank line and the timed cue. If the response starts with an HTML document, follow the redirect or login rule that served it. If the response contains the expected subtitle but the browser reports a cross-origin error, try serving the same file beside the page as a diagnostic. When that works, have the media host check its allowed origin and the video element’s cross-origin setting before editing any cue times.
Use the pattern of the delay to find the edit
Choose three spoken phrases you can identify without reading their subtitles. Note the playback time of each phrase and compare it with the cue start. If all three have shifted by the same amount, look for a new introduction or a trimmed opening. If the first two match and the third is late, inspect the cut between the second and third phrases. Moving every cue would break the first two matches. When the delay grows gradually, confirm which video file the player is serving before changing individual cues.
Finally, repeat the test on the published article with the language menu open. Select each language by name and check a phrase you can identify, then turn subtitles off. If words remain visible, pause the video and compare the picture with the original recording. Captions already burned into a video remain visible even when a separate track is disabled. Record the video filename, selected track and failing playback time when passing the issue to a colleague. Those three details let another person reproduce the problem without guessing which version you saw.
Workflow sample
English synthetic speech, written for the public EasySub demo. This illustrative VTT preserves cue 3 of the original SRT; it is not a new production export or a professionally proofread transcript.
WEBVTT 3 00:00:07.950 --> 00:00:12.149 Our next workshop starts on June 15 at 9:30.
WebVTT · EN · Download the demonstration video · Original SRT (English)
Test the cue, not just the menu
Select English in the player and seek to eight seconds. The example should be visible there, but not at thirteen seconds. If the track never loads, open its URL directly: an HTML login page returned with status 200 is still not a VTT file. Serve it as text/vtt. With a separate media domain, check the video’s crossorigin setting and the server’s CORS response.
Frequently asked questions
What if the text is right but appears late?
Compare the published media with the edit used for transcription. A newly inserted intro shifts later cues; an internal cut shifts only the following passage. Check either side of every edit before changing all timestamps.
