How to Fix Subtitle Timing: Linear Drift, Constant Timecode Offsets & Framerate Calibration

/**
 * Converts standard SRT/VTT timecode into total signed integer milliseconds.
 * Formats: '01:23:45,678' (SRT) or '01:23:45.678' (WebVTT)
 */
function timecodeToMs(timecodeStr) {
  const [timePart, millisPart] = timecodeStr.trim().replace(',', '.').split('.');
  const [hours, minutes, seconds] = timePart.split(':').map(Number);

  const ms = Number(millisPart.padEnd(3, '0').slice(0, 3));
  return (hours * 3600000) + (minutes * 60000) + (seconds * 1000) + ms;
}

/**
 * Converts integer milliseconds into standard 'HH:MM:SS,mmm' SRT format.
 * Automatically clamps negative values to 0 to prevent player desync crashes.
 */
function msToTimecode(totalMs, isVtt = false) {
  const clamped = Math.max(0, Math.round(totalMs));

  const hours = Math.floor(clamped / 3600000);
  const minutes = Math.floor((clamped % 3600000) / 60000);
  const seconds = Math.floor((clamped % 60000) / 1000);
  const ms = clamped % 1000;

  const delimiter = isVtt ? '.' : ',';
  return [
    String(hours).padStart(2, '0'),
    String(minutes).padStart(2, '0'),
    String(seconds).padStart(2, '0')
  ].join(':') + delimiter + String(ms).padStart(3, '0');
}

/**
 * Shifts full cue line containing '<start> --> <end>'
 */
function retimeCueLine(line, offsetMs, stretchMultiplier = 1.0) {
  const regex = /(\d{2}:\d{2}:\d{2}[,.]\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2}[,.]\d{3})/;
  const match = line.match(regex);
  if (!match) return line;

  const isVtt = line.includes('.');
  const startMs = (timecodeToMs(match[1]) * stretchMultiplier) + offsetMs;
  const endMs = (timecodeToMs(match[2]) * stretchMultiplier) + offsetMs;

  return `${msToTimecode(startMs, isVtt)} --> ${msToTimecode(endMs, isVtt)}`;
}