Create one WebVTT segment playlist per language containing EXT-X-TARGETDURATION and media segment entries that reference .vtt files with matching timestamps
In each .vtt file, ensure cue timestamps align with segment boundaries and include a WEBVTT header line at the top of every file
In the HLS multivariant playlist, add EXT-X-MEDIA TYPE=SUBTITLES tags with GROUP-ID, NAME, LANGUAGE, AUTOSELECT, DEFAULT, and URI for each language track
In each EXT-X-STREAM-INF line, add SUBTITLES="{GROUP-ID}" referencing the subtitle group
Test in hls.js and in Safari/AVPlayer; inspect whether cue rendering, language switching, and FORCED subtitle behavior work correctly across both players
Known gotchas
WebVTT cue timestamps in segment files must be relative to the media timeline, not wall-clock time; off-by-one segment boundaries cause cues to display in the wrong segment
Some HLS players ignore subtitles if the LANGUAGE attribute uses a non-BCP-47 tag (e.g., 'eng' instead of 'en'); use two-letter ISO 639-1 codes for broadest compatibility
Forced subtitles (for translating on-screen foreign-language text) require FORCED=YES on the EXT-X-MEDIA tag; without it, players will not auto-display them for viewers who have subtitles turned off
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp