The basic idea
A web page that shows video has to solve three problems for subtitles: where the text comes from, how it is matched to the video’s playback time, and how it is drawn. In general terms, the page gives the browser or the player a text track, the player watches the playback clock, and it displays each cue while the clock is inside the cue’s time range. The viewer controls whether any of it is shown.
The details depend on which kind of player the page uses, so it helps to separate three common situations.
Three common situations
The browser’s own video element. Modern browsers can play video without extra software. A page can attach one or more text tracks to the video element, each pointing to a subtitle file and carrying a language and a label. The browser handles loading, timing, drawing and the viewer’s menu. This is the simplest setup and the one other methods build on. It generally expects a web-oriented text format, and the overview of file formats explains why that family is the usual choice.
A custom player built by the site. Many sites wrap the browser’s video element in their own controls. The site may still use the browser’s text tracks, or it may read the subtitle file itself and draw the text with its own code. The second approach gives the designers full control over style and position, but it also means accessibility features such as sizes and menus must be built and tested by the site, rather than inherited.
An embedded player from another service. A page may embed a player hosted elsewhere, usually inside a frame. Subtitles are then managed by that service: the page owner uploads text or enables a feature, and the player shows a menu. The page itself has limited influence over how it behaves, and the available options depend on the service.
What the page needs to provide
- The subtitle file, in a format the player accepts, stored somewhere the page can reach. Many players, especially browsers, restrict loading text from other web addresses unless the server permits it. If subtitles work locally and fail once published, this kind of permission is a common cause.
- Track information: the language code, a readable label, and whether the track is meant as subtitles or captions. The article on subtitle tracks and language selection explains why these matter.
- A default, if wanted. Many pages leave subtitles off until the viewer asks for them.
- A fallback. If JavaScript, the player or the format fails, a transcript on the page is a useful backup for many users, though a transcript is a separate thing; see transcript differences for how it compares.
Styling on the web
In the browser’s built-in approach, appearance comes from several layers. The subtitle file may carry some styling, the page may add style rules for subtitles, and the viewer’s own browser or operating system settings may override both. Because of that last layer, a page cannot count on exact fonts or colors. The discussion of styling information in subtitle files covers what a file can store.
Some points specific to web pages:
- Subtitles are drawn over the video, so they can be hidden behind page elements if the layout is not careful.
- When the video goes full screen, the player has to bring the subtitles with it. Custom players sometimes fail here.
- Controls, such as a bar at the bottom of the video, can overlap cues. Many players raise the text when the controls appear.
- On small screens, the size relative to the video matters; text that is comfortable on a desktop can be tiny on a phone.
Accessibility on the page
A subtitle menu must be reachable by keyboard, and its entries should be understandable to screen readers. The button that turns subtitles on should be clearly labeled and should show its state. Do not assume this is true of a custom player; test it. Viewers who change their device settings for subtitle appearance should see those settings respected where possible.
Requirements for accessible web video vary by place, sector and type of site, and they change. This article gives general information only. Consult the relevant authority or a qualified professional about obligations that apply to you, and see the discussion of accessibility regulations for orientation.
Things that go wrong
- No menu appears. The track is missing, the file failed to load, or the player hides the control. Check that the file can be reached directly and that its address is correct.
- Text appears as boxes or odd symbols. Usually a character encoding problem.
- Timing is off. The file may have been made for a different version of the video, or its timing may have drifted; see fixing sync drift.
- Works in one browser but not another. Players differ in the formats and features they support. Test across the browsers and devices your audience uses.
- Subtitles show twice. The page includes both a text track and burned-in text, or two tracks in the same language.
- The wrong language starts. Check default flags and the language codes.
- Mobile players take over. Some phones open video in their own full-screen player, which may use its own subtitle settings and ignore the page’s styling.
Streaming and adaptive video
Many sites deliver video in small pieces, adjusting quality as the viewer’s connection changes. Subtitles can be delivered the same way, in pieces, or as a single file. These arrangements are managed by the hosting or streaming setup, and their requirements differ. If you use one, follow its documentation for accepted formats, naming and how multiple languages are declared.
Habits worth building
- Keep the subtitle files as the source of truth, separate from the page code.
- Name tracks consistently and use correct language codes.
- Test with subtitles on, off, and in full screen, on a computer and a phone.
- Test with keyboard-only navigation.
- Re-test after any change to the player or the page template, since updates can break subtitle support quietly.
- Check the file’s quality before publishing, using a quality checklist, so the player is not blamed for problems in the text.