Validate Android WebVTT Cue Timing Against a Pinned Draft

Direct answer

Pin the WebVTT document revision before writing tests. The W3C page currently publishes a Candidate Recommendation Draft dated 2026-05-20; it is a work in progress, not a final Recommendation. Use that dated snapshot for the grammar and mark the status honestly in design notes. An Android player implementation is a separate artifact and may support only a subset. Android Media3 documentation lists WebVTT among supported subtitle formats, but that does not prove a product uses Media3, accepts every cue feature, or renders the same output on every device. A WebVTT cue has a start and end timestamp and a payload. Start times are nondecreasing in file order, and each end must be strictly later than its own start. Different caption or subtitle cues may overlap. Do not impose a blanket no-overlap rule on all subtitle files. The specification separately describes chapter files as nested cues; that chapter profile is stricter and is not a general restriction on caption timelines. Make the selected file kind explicit, then test against that kind rather than treating every timed-text file as a chapter list. Cue timestamps are offsets relative to the playback timeline of the associated audio or video resource. They are not wall-clock instants, AudioRecord capture timestamps, AudioTimestamp clock readings, or evidence that a translated phrase begins at the same instant as the recognized source phrase. Bind a sidecar to a media identity and timeline revision. If a transcription pipeline supplies segment times, record which source clock and media artifact produced them and how any conversion was established. Without a verified mapping, leave timing unresolved instead of manufacturing a precise subtitle alignment. Use the timestamp grammar rather than permissive date parsing: hours may be omitted when zero but are required when nonzero; an included hours component has two or more ASCII digits. Minutes and seconds are two ASCII digits from 00 through 59, and the fractional portion has three decimal digits. Validate ranges and checked conversion to the chosen internal unit. Preserve millisecond values exactly where possible; rounding to frames or sample indices is a separate player-specific conversion. A cue identifier is optional, but present identifiers must be unique under this pinned draft. Do not use one as a permanent media key or provenance proof. Authoring conformance is separate from player tolerance: a parser may accept or normalize nonconforming input, so a successful preview does not establish source-file conformance. Treat cue payload as WebVTT text with a defined subset of cue markup, not as arbitrary HTML. The W3C algorithm constructs WebVTT nodes from supported cue tags, timestamps, and character references; it is not a general browser document or permission to send payload into a WebView. Keep cue text as data, render only through the tested player/parser, and do not execute links or fetch referenced resources. Unknown tags, malformed entities, voice/language annotations, bidirectional text, and multiline payloads need explicit tested behavior. Keep the source payload available for review when a library normalizes it. Preserve distinctions between parsing and editorial transformations. A valid file may still contain an unsuitable translation, badly segmented captions, or a cue mapped to the wrong speaker. Do not silently merge overlaps, sort cues, drop identifiers, or shift offsets to make a player preview look tidy. If an output policy repairs a cue, retain the original cue, the transformation rule, and a reviewable diff. A media player may also replace or hide cues according to track mode and rendering policy; successful parse is not proof that a user saw the expected text. Test a real serializer/parser pair with fixtures for the signature, BOM and line endings, optional cue IDs, exact millisecond timestamps, hour values, equal-start cues, permitted overlap, invalid end-before-start, out-of-order starts, chapter-only nesting, CR/LF text, entities, supported cue tags, unknown markup, duplicate IDs, empty payload, and large input. Include a media fixture with a known playback timeline and inspect the selected player version. Compare cue objects, time offsets, and rendered results separately; a single screenshot or parser success cannot establish subtitle accuracy or capture-clock synchronization. Keep raw transcript, translation, cue proposal, reviewed sidecar, and exported file as distinct revisions. Record the source media ID/hash where permitted, language tags, subtitle kind, W3C revision, parser/player version, timing origin, and user decision without logging private dialogue by default. A local transcription workflow is still responsible for access, storage, retention, export, and consent. This method does not claim Cove integrates Media3, records subtitle files, supports WebVTT, or has measured subtitle quality.

A translated subtitle overlaps the next speaker turn

A local transcript has two short overlapping speakers. A translation step expands one sentence, and an exporter is tempted to push the second cue later so it no longer overlaps. The original timing came from a media-relative transcript fixture, not from a microphone clock map.

Decision

Keep the source cue times and language revisions separate, validate start ordering and each cue end, allow subtitle overlap where the selected profile permits it, and show the proposed text/timing diff for review.

Expected outcome

The exported sidecar preserves documented media offsets and honest overlap. It does not claim that translated text is synchronized to speech without a separately tested alignment method.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Pinned W3C document revision and track kind
• Cue order, overlap, unique-ID, timestamp, and payload fixtures
• Target parser/player behavior and reviewed timing diff

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

1. Pin the document and file kind. Record the W3C 2026-05-20 CRD snapshot, parser version, player version, and whether the track is captions, subtitles, chapters, or metadata. A chapter-only rule must not silently become a subtitle rule.
2. Establish the media timeline origin. Bind cues to one media artifact and its playback timeline. Store the upstream time unit and conversion evidence; do not substitute wall time, AudioRecord timestamps, or unverified translation alignment.
3. Parse and validate cue structure. Check the WebVTT signature, hours optional only when zero, timestamp grammar, nondecreasing starts, end later than start, unique present identifiers, payload boundaries, line endings, and size limits. Record authoring-conformance results separately from the actual player parser acceptance.
4. Keep payload inert and transformations visible. Render only through a pinned, tested WebVTT parser/player. Do not treat cue payload as arbitrary HTML or fetch embedded-looking links; preserve original payload and show any text, timing, or ordering repair.
5. Round-trip against the target player. Use synthetic overlapping and boundary cues plus a known media timeline. Compare parser objects, serialized file, selected track, displayed cue, and review outcome independently; scope conclusions to that player build.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• The article and fixtures identify the 2026-05-20 W3C Candidate Recommendation Draft as a draft snapshot, not a final Recommendation.
• Subtitle overlap is permitted where applicable, while start ordering and per-cue end-after-start remain checked; chapter nesting is not imposed on all caption files.
• Cue offsets remain tied to a named media timeline and are not equated with microphone clocks or translation alignment without separate evidence.
• Payload is parsed as WebVTT cue text, not arbitrary HTML; unsupported tags and transformations remain visible and reviewable.
• Player and parser results are scoped to the tested build; no Cove WebVTT/Media3 integration or quality result is implied.

Decision table

Failure patterns to prevent

• Treating every overlap as invalid
• Applying chapter nesting rules to subtitles
• Treating media offsets as capture-clock or translation alignment

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Android privacy and security
• W3C — WebVTT 1 Candidate Recommendation Draft, 2026-05-20 snapshot
• WHATWG — HTML track element and timed text tracks
• Android Developers — Media3 supported subtitle formats

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions