Offsets and durations use milliseconds
offset is the segment start from the beginning of the video. duration is the expected display or speech interval.
JSON segment
{
"text": "Example segment",
"offset": 8150,
"duration": 1200,
"lang": "en"
}Align a segment with playback
Convert the player position to milliseconds before comparing it with the transcript.
JavaScript
function segmentAt(segments, currentTimeSeconds) {
const position = currentTimeSeconds * 1000
return segments.find((segment) =>
position >= segment.offset &&
position < segment.offset + segment.duration
)
}Player events are not frame-perfect. Keep the source segment timing and treat the active segment as a presentation state.
Chunking preserves the covered range
When chunkSize groups several native segments, the merged offset starts at the first segment and its duration covers the end of the final segment. Request the native segment size when editing precision matters.
Store integers and the source language
Store milliseconds as integers to avoid floating-point drift. Keep the video ID, selected language and transcript source next to the segments so later cache or model changes do not make results ambiguous.