Restore subtitles for a WordPress video

Distinguish a missing track from one that does not play

Open the page as a visitor, start the video, and look for the subtitle control in the player. Depending on the browser, it may have another name or sit in a menu. Record whether the control is absent, offers a language that stays blank, or displays text at the wrong time. A menu offering “French” while no text appears points toward the loaded track or its timestamps. A player without a control first requires identifying the video, block type, and available controls.

Record the page URL, video filename, and expected language. Play a passage with speech and note the time displayed in the player. Compare that passage with the expected text. If the problem occurs only on a phone, record the browser and whether video enters full screen. A mobile player may present controls differently. If several languages are affected, try each track separately to avoid correcting a valid file when another is empty.

In the editor, select the block containing the player. The Video block for a site-hosted file and an embed block opening another provider's player require different actions. In the Video block, the caption beneath the video remains text associated with the block. The subtitle track displays inside the player at specified times. If you see fixed text below the media but no text during playback, look for the track in player options.

Prepare a minimal, readable WebVTT file

On an authorized copy, use a short staging video whose content you can recognize at two moments. You can record a few seconds of voice or reuse an authorized training clip. Keep the original subtitle file separate. In a plain-text editor, save a UTF-8 test file with the .vtt extension. Check the complete name on systems hiding extensions to avoid actually creating temoin.vtt.txt. A word processor may add invisible formatting to a file that looks readable on screen.

The file begins with WEBVTT, followed by a blank line. Each text segment contains a start, end, and text to display. Use a period before milliseconds and an arrow written with two hyphens and a greater-than sign. Leave a blank line between segments. If your source is SRT, renaming the file does not convert its structure. Recreate timestamps in genuine WebVTT or ask the video editor to export the track in that format.

Here are two dummy segments for a clip at least seven seconds long. At two seconds, “Bienvenue dans l’atelier” should be visible. At four and a half seconds, the player should display the second segment. Adapt text and timestamps to events actually present in your video. For a track intended for deaf or hard-of-hearing people, also identify sounds needed for understanding and the speaker where unclear. A track translating only dialogue may meet a different need.

WEBVTT

00:00:01.000 --> 00:00:03.500
Bienvenue dans l’atelier.

00:00:04.000 --> 00:00:06.000
[La porte se ferme]
Nous commençons.

Approach 1. Add or correct the track in the Video block

Open the page on the copy with an account able to edit it and upload files. Select the Video block, then open Text tracks in the block toolbar. Depending on interface language, the label may correspond to “Text tracks.” Add a track to upload the test file. Once added, open its settings. Give it a label the player can display, such as “Français de recette”. Enter fr as the source language, or the code actually matching the file's language. Choose the kind according to purpose, then confirm with “Apply” if displayed in track settings. Ensure playback controls are enabled in block settings, then save the staging page.

The “Captions” kind suits transcription of dialogue and useful sounds in the video's language. “Subtitles” may display translated dialogue according to audience needs. Types intended for chapters or metadata serve another role. A track uploaded with the wrong kind may be present in the page without appearing in the expected menu. If you keep two French tracks for different purposes, distinguish their labels and check that the player lets users select the correct one.

If adding is refused, check the message, account, and filename. WordPress knows the text/vtt MIME type, but effective upload rules may depend on the site and plugins. First try the small valid file on the copy and compare using an authorized account. Ask the maintainer to check the precise rule if rejection continues. Broader permission may affect other media. If the old track works on another page, retain it in the Media Library during testing.

Approach 2. Check the file, response, and timestamps

Save the staging page and open its visitor view. In the player, start the video and explicitly choose the test track. The browser may wait for selection before requesting the file. If the menu still shows no language, inspect the document around the correct video. For a native player, locate the track element inside video. Compare its src URL, kind, srclang language, and label with entered settings. A page containing two players may lead you to inspect the wrong track.

If the track is in the document but remains blank, observe its request in the browser's Network panel after selecting it. Check final URL, response status, and contents. A login page, HTML error document, or refusal message may be served where the file should be. Even a successful HTTP code may hide an incorrect response. Expected content begins with WEBVTT, and the intended response type is text/vtt. Compare logged-in and logged-out playback to identify media restricted to administration or a session.

If the track is on another origin, compare protocol, hostname, and port for page and track. First try serving the same file from the staging page's origin. If it works, open Network to compare the original request and remote response's CORS headers. For HTML you maintain, crossorigin belongs on the video element and also affects video loading. If files are public, the maintainer can try crossorigin="anonymous" with a response allowing the page's origin. Then check both video and track playback. For authenticated media, retain intended access and choose configuration with the hosting manager.

Correct a readable but mistimed or incomplete track

If text displays with a constant offset, compare three reference points across the video. Record each sentence's actual time in the player and its corresponding segment start in the file. If the offset is similar everywhere, look for an introduction removed or added since export. If the discrepancy increases over time, check that the track was produced for this exact video version. A different edit may have different cuts or duration. Request a subtitle export matching the media actually published.

If only a few segments are missing, examine lines immediately before and after the passage. A missing blank line, malformed timestamp, or end preceding start may make a segment unusable. Also check that segment starts retain the expected order. For clear playback, avoid unnecessary overlaps in the working file. If accents are unreadable, reopen as UTF-8, correct damaged characters, and recheck the version received by the player. A text-editor correction may not have replaced the media used by the page.

Make a minimal correction to two or three segments and test it with the complete staging video. Seek to the middle using the playback bar, then return to the beginning. Check that segments appear and disappear at intended times. If revising the whole file, retain beginning, middle, and end reference points for the next review. Testing only the first sentence cannot assess the rest of the track.

Approach 3. Correct the track in an embedded player

If WordPress embeds an external player, first open the video at the provider in an authorized session. Select the language in that player. If the track is missing there too, the account managing the video must add or correct subtitles in that tool. If it works there, compare with the embedded page using the same media and language. A framed player generally receives configuration from the provider. Adding WebVTT to the site's Media Library does not automatically associate it with that player.

When video is available in several languages, name each track according to language and purpose. Activate tracks one by one and check the beginning and a characteristic passage. Browser or player preferences may select a language on load. Also check that visitors can choose another track or disable display. If two languages accidentally share the same file, correct the source association and leave other tracks intact. For regularly replaced videos, record which text file accompanies each edit.

To provide content access when the player is unavailable, you can add a transcript near the video. It helps users consult or search text without playing media. Also retain synchronized captions when the audience needs to follow picture and sound together. If the embed depends on a service unable to manage a suitable track, decide with the video owner whether the file should be published in a player offering these controls.

Test as a visitor and after reopening

On your authorized copy, create a reference page with a clip at least seven seconds long. Place two markers in the clip, such as a sentence around the second second and a door sound around four seconds. First open the page without a track and check that the player starts. Then add the minimal WebVTT and select “Français de recette”. At two seconds, the first sentence should display. At 3.75 seconds, no segment should be active. At 4.5 seconds, the second should appear. Pause playback, return to two seconds, and check that the first sentence is available again.

Next compare the actual video's corrected track on the copy in a logged-in session and visitor window. Test on a phone or browser representative of the original problem. Check keyboard access to the control when using a computer. On mobile, try in-page and full-screen playback where offered. If the video offers multiple tracks, test at least one other language as a counterexample and check that it has not changed.

If the page still serves the previous file, first compare the requested URL and response contents. A page may retain an old URL after replacement, or a cache may serve the previous file at the same URL. On the copy, use a versioned filename if it helps comparison, then update only the affected track. Have the identified cache layer checked before targeted purging. Confirm the change from a new session afterward.

Restore the old track if correction fails

Keep the original file and record each track's label, language, and kind before intervention. If the new version worsens playback, return to the affected block and reassociate the old track with its settings. For an external player, use the same rollback mechanism at the provider. If the page contains several videos, check that you restore the file in the correct player. Then reopen the page and check a known reference point and another track that should remain intact.

When correction works, remove the staging track from pages that should not display it. Before deleting media from the library, check that no other page uses it. Record the exact video, selected WebVTT file, track location, and times used for checking. If the player depends on another service, add the provider's video ID. The next person can verify the installed track as soon as a new edit arrives.

For an important video whose subtitles remain unavailable, give the person responsible the precise record. State whether the control is missing, the URL returns wrong content, or only certain segments are mistimed. Keep the transcript or other intended access during correction if information must remain available. This record enables resuming at the correct level: text file, player, or response supplying the track.

Compare with a minimal HTML player on the same origin

If the native block remains difficult to diagnose, a maintainer can compare its rendering with this player on a staging page. Replace both paths with your clip and public WebVTT on the same origin. The text file can be created free in a plain-text editor from the two segments above; no additional WordPress plugin is necessary.

Place the fragment in a Custom HTML block on the copy if your account is authorized to retain these elements. After saving, inspect the HTML actually served: a sanitization policy may remove a tag. Select the track and compare 2 s, 3.75 s, and 4.5 s. If this player works with the same files, focus investigation on the initial block's configuration. If it also fails, first check the VTT response and timestamps. Then remove the reference player; it must not duplicate the video on the final page.

<video controls preload="metadata" src="/medias/clip-temoin.mp4">
  <track kind="captions" src="/medias/clip-temoin-fr.vtt"
         srclang="fr" label="Français — essai" default>
</video>