@zync/zync-screnplay-player 0.1.251 → 0.1.252

package/dist/timing.cjs

@@ -0,0 +1,1050 @@
+const EPSILON = 1e-6;
+const DEFAULT_FPS = 30;
+const MIN_CHUNK_DURATION_SECONDS = 0.26;
+
+const cloneValue = (value) => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return JSON.parse(JSON.stringify(value));
+};
+
+const toFiniteNumber = (value, fallback = null) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+
+  return parsed;
+};
+
+const isDisabled = (value) =>
+  value === true || value === "true" || value === 1 || value === "1";
+
+const buildInterval = (start, end) => {
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    return null;
+  }
+
+  if (end <= start + EPSILON) {
+    return null;
+  }
+
+  return { start, end };
+};
+
+const isMeaningfulDuration = (duration) =>
+  Number.isFinite(duration) &&
+  duration > Math.max(EPSILON, MIN_CHUNK_DURATION_SECONDS - EPSILON);
+
+const mergeIntervals = (intervals = []) => {
+  if (!Array.isArray(intervals) || intervals.length === 0) {
+    return [];
+  }
+
+  const normalized = intervals
+    .map((interval) => buildInterval(interval?.start, interval?.end))
+    .filter(Boolean)
+    .sort((a, b) => a.start - b.start);
+
+  if (normalized.length === 0) {
+    return [];
+  }
+
+  return normalized.reduce((merged, current) => {
+    const previous = merged[merged.length - 1];
+
+    if (!previous) {
+      merged.push({ ...current });
+      return merged;
+    }
+
+    if (current.start <= previous.end + EPSILON) {
+      previous.end = Math.max(previous.end, current.end);
+      return merged;
+    }
+
+    merged.push({ ...current });
+    return merged;
+  }, []);
+};
+
+const subtractIntervals = (range, cuts = []) => {
+  const start = toFiniteNumber(range?.start, null);
+  const end = toFiniteNumber(range?.end, null);
+
+  if (
+    !Number.isFinite(start) ||
+    !Number.isFinite(end) ||
+    end <= start + EPSILON
+  ) {
+    return [];
+  }
+
+  if (!Array.isArray(cuts) || cuts.length === 0) {
+    return [{ start, end }];
+  }
+
+  const mergedCuts = mergeIntervals(cuts);
+  const kept = [];
+  let cursor = start;
+
+  for (const cut of mergedCuts) {
+    if (cut.end <= cursor + EPSILON) {
+      continue;
+    }
+
+    if (cut.start >= end - EPSILON) {
+      break;
+    }
+
+    if (cut.start > cursor + EPSILON) {
+      kept.push({
+        start: cursor,
+        end: Math.min(cut.start, end),
+      });
+    }
+
+    cursor = Math.max(cursor, cut.end);
+
+    if (cursor >= end - EPSILON) {
+      break;
+    }
+  }
+
+  if (cursor < end - EPSILON) {
+    kept.push({ start: cursor, end });
+  }
+
+  return kept.filter((interval) => interval.end > interval.start + EPSILON);
+};
+
+const clipIntervalToRange = (interval, rangeStart, rangeEnd) => {
+  const start = Math.max(interval.start, rangeStart);
+  const end = Math.min(interval.end, rangeEnd);
+  return buildInterval(start, end);
+};
+
+const mapTimeAfterCuts = (time, cuts = []) => {
+  const normalizedTime = toFiniteNumber(time, null);
+  if (!Number.isFinite(normalizedTime)) {
+    return 0;
+  }
+
+  if (!Array.isArray(cuts) || cuts.length === 0) {
+    return normalizedTime;
+  }
+
+  let removedDuration = 0;
+
+  for (const cut of cuts) {
+    if (cut.start >= normalizedTime) {
+      break;
+    }
+
+    removedDuration += Math.max(
+      0,
+      Math.min(normalizedTime, cut.end) - cut.start
+    );
+  }
+
+  return Math.max(0, normalizedTime - removedDuration);
+};
+
+const isCaptionEffect = (effect) =>
+  typeof effect?.type === "string" && effect.type.includes("caption");
+
+const getSegmentTiming = (segment) => {
+  const duration = Math.max(
+    0,
+    toFiniteNumber(segment?.layout?.data?.duration, 0)
+  );
+  const trimLeft = Math.max(
+    0,
+    toFiniteNumber(segment?.layout?.data?.trimLeft, 0)
+  );
+  const trimRight = Math.max(
+    0,
+    toFiniteNumber(segment?.layout?.data?.trimRight, 0)
+  );
+  const playableStart = trimLeft;
+  const playableEnd = Math.max(playableStart, duration - trimRight);
+  const playableDuration = Math.max(0, playableEnd - playableStart);
+
+  return {
+    duration,
+    trimLeft,
+    trimRight,
+    playableStart,
+    playableEnd,
+    playableDuration,
+  };
+};
+
+const getCaptionPunctuationRange = (entry = {}) => {
+  const punctuations = Array.isArray(entry?.punctuations)
+    ? entry.punctuations
+    : [];
+
+  if (!punctuations.length) {
+    return null;
+  }
+
+  let minStart = Infinity;
+  let maxEnd = 0;
+
+  punctuations.forEach((punctuation) => {
+    const start = toFiniteNumber(punctuation?.start, Infinity);
+    const end = toFiniteNumber(punctuation?.end, -Infinity);
+
+    if (start < minStart) {
+      minStart = start;
+    }
+
+    if (end > maxEnd) {
+      maxEnd = end;
+    }
+  });
+
+  if (!Number.isFinite(minStart) || maxEnd <= minStart + EPSILON) {
+    return null;
+  }
+
+  return {
+    start: minStart,
+    end: maxEnd,
+  };
+};
+
+const getCaptionEntryOffset = (entry = {}) => {
+  const directOffset = toFiniteNumber(entry?.offset, null);
+
+  if (Number.isFinite(directOffset)) {
+    return directOffset;
+  }
+
+  const originalOffset = toFiniteNumber(entry?.originalOffset, null);
+
+  if (Number.isFinite(originalOffset)) {
+    return originalOffset;
+  }
+
+  const punctuationRange = getCaptionPunctuationRange(entry);
+
+  return punctuationRange?.start ?? null;
+};
+
+const getCaptionEntryTiming = (entry = {}) => {
+  const offset = getCaptionEntryOffset(entry);
+  const directDuration = toFiniteNumber(entry?.duration, null);
+
+  if (Number.isFinite(offset) && Number.isFinite(directDuration)) {
+    if (directDuration > EPSILON) {
+      return { offset, duration: directDuration };
+    }
+
+    return null;
+  }
+
+  const punctuationRange = getCaptionPunctuationRange(entry);
+
+  if (!punctuationRange) {
+    return null;
+  }
+
+  const resolvedOffset = Number.isFinite(offset)
+    ? offset
+    : punctuationRange.start;
+  const resolvedDuration = punctuationRange.end - resolvedOffset;
+
+  if (resolvedDuration <= EPSILON) {
+    return null;
+  }
+
+  return {
+    offset: resolvedOffset,
+    duration: resolvedDuration,
+  };
+};
+
+const normalizeCaptionEntriesWithTiming = (entries = []) => {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+
+  return entries.map((entry) => {
+    const normalizedEntry = { ...entry };
+    const timing = getCaptionEntryTiming(entry);
+
+    if (timing) {
+      normalizedEntry.offset = timing.offset;
+      normalizedEntry.duration = timing.duration;
+
+      if (normalizedEntry.originalOffset == null) {
+        normalizedEntry.originalOffset = timing.offset;
+      }
+    }
+
+    if (Array.isArray(entry?.punctuations)) {
+      normalizedEntry.punctuations = entry.punctuations.map((punctuation) => ({
+        ...punctuation,
+        ...(punctuation?.start != null && punctuation?.originalStart == null
+          ? { originalStart: punctuation.start }
+          : {}),
+        ...(punctuation?.end != null && punctuation?.originalEnd == null
+          ? { originalEnd: punctuation.end }
+          : {}),
+      }));
+    }
+
+    return normalizedEntry;
+  });
+};
+
+const collectDisabledTranscriptIntervals = (transcripts = []) => {
+  if (!Array.isArray(transcripts)) {
+    return [];
+  }
+
+  const intervals = [];
+
+  transcripts.forEach((transcript) => {
+    if (!isDisabled(transcript?.disabled)) {
+      return;
+    }
+
+    const offset = toFiniteNumber(transcript?.offset, null);
+    const duration = toFiniteNumber(transcript?.duration, null);
+    if (
+      !Number.isFinite(offset) ||
+      !Number.isFinite(duration) ||
+      duration <= EPSILON
+    ) {
+      return;
+    }
+
+    intervals.push({
+      start: offset,
+      end: offset + duration,
+    });
+  });
+
+  return mergeIntervals(intervals);
+};
+
+const collectSegmentDisabledIntervals = (segment, timing) => {
+  const effects = Array.isArray(segment?.effects) ? segment.effects : [];
+  const cuts = [];
+
+  effects.forEach((effect) => {
+    if (!isCaptionEffect(effect)) {
+      return;
+    }
+
+    const intervals = collectDisabledTranscriptIntervals(
+      effect?.data?.transcript_text || []
+    );
+
+    intervals.forEach((interval) => {
+      const clipped = clipIntervalToRange(
+        interval,
+        timing.playableStart,
+        timing.playableEnd
+      );
+
+      if (clipped) {
+        cuts.push(clipped);
+      }
+    });
+  });
+
+  return mergeIntervals(cuts);
+};
+
+const collectGlobalDisabledIntervals = (screenplay) => {
+  const allIntervals = [];
+  const segmentTrack = screenplay?.tracks?.find(
+    (track) => track.type === "segment"
+  );
+  const captionTrack = screenplay?.tracks?.find(
+    (track) => track.type === "caption"
+  );
+
+  let segmentTimelineCursor = 0;
+
+  if (Array.isArray(segmentTrack?.segments)) {
+    segmentTrack.segments.forEach((segment) => {
+      const timing = getSegmentTiming(segment);
+      if (isDisabled(segment?.layout?.removed)) {
+        const removed = buildInterval(
+          segmentTimelineCursor,
+          segmentTimelineCursor + timing.playableDuration
+        );
+        if (removed) allIntervals.push(removed);
+      }
+      const localCuts = collectSegmentDisabledIntervals(segment, timing);
+
+      localCuts.forEach((cut) => {
+        const start = segmentTimelineCursor + (cut.start - timing.trimLeft);
+        const end = segmentTimelineCursor + (cut.end - timing.trimLeft);
+        const absolute = buildInterval(start, end);
+
+        if (absolute) {
+          allIntervals.push(absolute);
+        }
+      });
+
+      segmentTimelineCursor += timing.playableDuration;
+    });
+  }
+
+  if (Array.isArray(captionTrack?.segments)) {
+    captionTrack.segments.forEach((segment) => {
+      const segmentOffset = toFiniteNumber(segment?.data?.offset, 0);
+      const intervals = collectDisabledTranscriptIntervals(
+        segment?.data?.transcript_text || []
+      );
+
+      intervals.forEach((interval) => {
+        const absolute = buildInterval(
+          segmentOffset + interval.start,
+          segmentOffset + interval.end
+        );
+
+        if (absolute) {
+          allIntervals.push(absolute);
+        }
+      });
+    });
+  }
+
+  const initialCuts = mergeIntervals(allIntervals);
+  // Video drops tiny retained chunks around cuts. Include those discarded
+  // source ranges before normalizing every track so they share one timeline.
+  segmentTimelineCursor = 0;
+  for (const segment of segmentTrack?.segments || []) {
+    const timing = getSegmentTiming(segment);
+    const start = segmentTimelineCursor;
+    const end = start + timing.playableDuration;
+    segmentTimelineCursor = end;
+    if (
+      isDisabled(segment?.layout?.removed) ||
+      !initialCuts.some(
+        (cut) => cut.start < end - EPSILON && cut.end > start + EPSILON
+      )
+    )
+      continue;
+    for (const range of subtractIntervals({ start, end }, initialCuts)) {
+      if (!isMeaningfulDuration(range.end - range.start))
+        allIntervals.push(range);
+    }
+  }
+  return mergeIntervals(allIntervals);
+};
+
+const normalizeTextAndPunctuations = (text, punctuations = []) => {
+  if (!Array.isArray(punctuations) || punctuations.length === 0) {
+    return {
+      text,
+      punctuations: [],
+    };
+  }
+
+  if (typeof text !== "string") {
+    return {
+      text,
+      punctuations,
+    };
+  }
+
+  const words = text.split(" ");
+  if (words.length === 0) {
+    return {
+      text,
+      punctuations,
+    };
+  }
+
+  const wordIndexOrder = [];
+  const seen = new Set();
+
+  punctuations.forEach((punctuation) => {
+    const index = toFiniteNumber(punctuation?.index, null);
+    if (!Number.isInteger(index)) {
+      return;
+    }
+
+    if (index < 0 || index >= words.length) {
+      return;
+    }
+
+    if (!seen.has(index)) {
+      seen.add(index);
+      wordIndexOrder.push(index);
+    }
+  });
+
+  if (wordIndexOrder.length === 0) {
+    return {
+      text,
+      punctuations: [],
+    };
+  }
+
+  const filteredWords = wordIndexOrder
+    .map((wordIndex) => words[wordIndex])
+    .filter((word) => word !== undefined);
+
+  if (filteredWords.length === 0) {
+    return {
+      text,
+      punctuations: [],
+    };
+  }
+
+  const indexMap = new Map(
+    wordIndexOrder.map((wordIndex, mappedIndex) => [wordIndex, mappedIndex])
+  );
+
+  const normalizedPunctuations = punctuations
+    .filter((punctuation) =>
+      indexMap.has(toFiniteNumber(punctuation?.index, null))
+    )
+    .map((punctuation) => ({
+      ...punctuation,
+      index: indexMap.get(toFiniteNumber(punctuation?.index, null)),
+    }));
+
+  return {
+    text: filteredWords.join(" "),
+    punctuations: normalizedPunctuations,
+  };
+};
+
+const clipTranscriptToRange = ({
+  transcript,
+  rangeStart,
+  rangeEnd,
+  offsetMode,
+  offsetBase = 0,
+  stripDisabled = false,
+}) => {
+  if (!transcript) {
+    return null;
+  }
+
+  if (stripDisabled && isDisabled(transcript?.disabled)) {
+    return null;
+  }
+
+  const transcriptStart = toFiniteNumber(transcript?.offset, null);
+  const transcriptDuration = toFiniteNumber(transcript?.duration, null);
+  if (
+    !Number.isFinite(transcriptStart) ||
+    !Number.isFinite(transcriptDuration) ||
+    transcriptDuration <= EPSILON
+  ) {
+    return null;
+  }
+
+  const transcriptEnd = transcriptStart + transcriptDuration;
+  const overlapStart = Math.max(transcriptStart, rangeStart);
+  const overlapEnd = Math.min(transcriptEnd, rangeEnd);
+  if (overlapEnd <= overlapStart + EPSILON) {
+    return null;
+  }
+
+  const clonedTranscript = cloneValue(transcript);
+  const mapOffset = (value) =>
+    offsetMode === "relative" ? value - offsetBase : value;
+
+  clonedTranscript.offset = mapOffset(overlapStart);
+  clonedTranscript.duration = overlapEnd - overlapStart;
+
+  const punctuations = Array.isArray(transcript?.punctuations)
+    ? transcript.punctuations
+    : [];
+
+  const clippedPunctuations = punctuations
+    .map((punctuation) => {
+      const punctuationStart = toFiniteNumber(punctuation?.start, null);
+      const punctuationEnd = toFiniteNumber(punctuation?.end, null);
+
+      if (
+        !Number.isFinite(punctuationStart) ||
+        !Number.isFinite(punctuationEnd) ||
+        punctuationEnd <= punctuationStart + EPSILON
+      ) {
+        return null;
+      }
+
+      const clippedStart = Math.max(punctuationStart, overlapStart);
+      const clippedEnd = Math.min(punctuationEnd, overlapEnd);
+      if (clippedEnd <= clippedStart + EPSILON) {
+        return null;
+      }
+
+      return {
+        ...punctuation,
+        ...(punctuation.wordObject && punctuationStart < rangeStart - EPSILON
+          ? { __wordObjectOnsetClipped: true }
+          : {}),
+        start: mapOffset(clippedStart),
+        end: mapOffset(clippedEnd),
+      };
+    })
+    .filter(Boolean);
+
+  const wasClipped =
+    overlapStart > transcriptStart + EPSILON ||
+    overlapEnd < transcriptEnd - EPSILON;
+
+  if (wasClipped && clippedPunctuations.length > 0) {
+    const { text, punctuations: normalizedPunctuations } =
+      normalizeTextAndPunctuations(transcript?.text, clippedPunctuations);
+
+    clonedTranscript.text = text;
+    clonedTranscript.punctuations = normalizedPunctuations;
+  } else {
+    clonedTranscript.text = transcript?.text;
+    clonedTranscript.punctuations = clippedPunctuations;
+  }
+
+  return clonedTranscript;
+};
+
+const normalizeTranscriptsForRange = ({
+  transcripts,
+  rangeStart,
+  rangeEnd,
+  offsetMode,
+  offsetBase,
+  stripDisabled,
+}) => {
+  if (!Array.isArray(transcripts)) {
+    return [];
+  }
+
+  return transcripts
+    .map((transcript) =>
+      clipTranscriptToRange({
+        transcript,
+        rangeStart,
+        rangeEnd,
+        offsetMode,
+        offsetBase,
+        stripDisabled,
+      })
+    )
+    .filter(Boolean);
+};
+
+const normalizeSegmentTrack = (segmentTrack, globalCuts) => {
+  if (!segmentTrack || !Array.isArray(segmentTrack?.segments)) {
+    return segmentTrack;
+  }
+
+  const normalizedSegments = [];
+  let timelineCursor = 0;
+
+  segmentTrack.segments.forEach((segment, segmentIndex) => {
+    const timing = getSegmentTiming(segment);
+    const { duration, playableStart, playableEnd, playableDuration, trimLeft } =
+      timing;
+
+    const isRemoved = isDisabled(segment?.layout?.removed);
+    if (isRemoved) {
+      // Timed tracks consume the same global cut below. Omit this layout now
+      // so preparing the returned screenplay again cannot apply it twice.
+      timelineCursor += playableDuration;
+      return;
+    }
+    if (playableDuration <= EPSILON) {
+      const untouched = cloneValue(segment);
+      untouched.__transitionAfter = true;
+      untouched.__originSegmentIndex = segmentIndex;
+      normalizedSegments.push(untouched);
+      timelineCursor += playableDuration;
+      return;
+    }
+
+    const localCuts = [];
+    const segmentAbsoluteStart = timelineCursor;
+    const segmentAbsoluteEnd = segmentAbsoluteStart + playableDuration;
+
+    globalCuts.forEach((globalCut) => {
+      if (globalCut.end <= segmentAbsoluteStart + EPSILON) {
+        return;
+      }
+
+      if (globalCut.start >= segmentAbsoluteEnd - EPSILON) {
+        return;
+      }
+
+      const overlapStart = Math.max(globalCut.start, segmentAbsoluteStart);
+      const overlapEnd = Math.min(globalCut.end, segmentAbsoluteEnd);
+      if (overlapEnd <= overlapStart + EPSILON) {
+        return;
+      }
+
+      const localStart = trimLeft + (overlapStart - segmentAbsoluteStart);
+      const localEnd = trimLeft + (overlapEnd - segmentAbsoluteStart);
+      const localInterval = buildInterval(localStart, localEnd);
+
+      if (localInterval) {
+        localCuts.push(localInterval);
+      }
+    });
+
+    const mergedLocalCuts = mergeIntervals(localCuts);
+    const keptRanges = subtractIntervals(
+      { start: playableStart, end: playableEnd },
+      mergedLocalCuts
+    );
+
+    if (keptRanges.length === 0) {
+      timelineCursor += playableDuration;
+      return;
+    }
+
+    keptRanges.forEach((keptRange, chunkIndex) => {
+      const chunkDuration = keptRange.end - keptRange.start;
+      if (
+        chunkDuration <= EPSILON ||
+        (mergedLocalCuts.length > 0 && !isMeaningfulDuration(chunkDuration))
+      ) {
+        return;
+      }
+
+      const clonedChunk = cloneValue(segment);
+
+      clonedChunk.layout.data.trimLeft = keptRange.start;
+      clonedChunk.layout.data.trimRight = Math.max(0, duration - keptRange.end);
+      clonedChunk.__transitionAfter = chunkIndex === keptRanges.length - 1;
+      clonedChunk.__originSegmentIndex = segmentIndex;
+
+      if (Array.isArray(clonedChunk.effects)) {
+        clonedChunk.effects = clonedChunk.effects.map((effect) => {
+          if (!isCaptionEffect(effect)) {
+            return effect;
+          }
+
+          const normalizedEffect = cloneValue(effect);
+          normalizedEffect.data = normalizedEffect.data || {};
+          normalizedEffect.data.transcript_text = normalizeTranscriptsForRange({
+            transcripts: effect?.data?.transcript_text || [],
+            rangeStart: keptRange.start,
+            rangeEnd: keptRange.end,
+            offsetMode: "absolute",
+            offsetBase: keptRange.start,
+            stripDisabled: true,
+          });
+          return normalizedEffect;
+        });
+      }
+
+      normalizedSegments.push(clonedChunk);
+    });
+
+    timelineCursor += playableDuration;
+  });
+
+  return {
+    ...segmentTrack,
+    segments: normalizedSegments,
+  };
+};
+
+const resolveSegmentDuration = (segment, trackType) => {
+  const explicitDuration = toFiniteNumber(segment?.data?.duration, null);
+  if (Number.isFinite(explicitDuration) && explicitDuration > EPSILON) {
+    return explicitDuration;
+  }
+
+  if (trackType !== "caption") {
+    return null;
+  }
+
+  const transcripts = Array.isArray(segment?.data?.transcript_text)
+    ? segment.data.transcript_text
+    : [];
+
+  const maxEnd = transcripts.reduce((currentMax, transcript) => {
+    const offset = toFiniteNumber(transcript?.offset, null);
+    const duration = toFiniteNumber(transcript?.duration, null);
+
+    if (
+      !Number.isFinite(offset) ||
+      !Number.isFinite(duration) ||
+      duration <= EPSILON
+    ) {
+      return currentMax;
+    }
+
+    return Math.max(currentMax, offset + duration);
+  }, 0);
+
+  return maxEnd > EPSILON ? maxEnd : null;
+};
+
+const shiftSourceMediaStart = (segment, deltaInSeconds) => {
+  if (
+    !segment?.data ||
+    !Number.isFinite(deltaInSeconds) ||
+    deltaInSeconds === 0
+  ) {
+    return;
+  }
+
+  const sourceVideoStart = toFiniteNumber(
+    segment?.data?.sourceVideo?.start,
+    segment?.data?.sourceVideo ? 0 : null
+  );
+  if (Number.isFinite(sourceVideoStart)) {
+    segment.data.sourceVideo.start = Math.max(
+      0,
+      sourceVideoStart + deltaInSeconds
+    );
+  }
+
+  const sourceAudioStart = toFiniteNumber(
+    segment?.data?.sourceAudio?.start,
+    segment?.data?.sourceAudio ? 0 : null
+  );
+  if (Number.isFinite(sourceAudioStart)) {
+    segment.data.sourceAudio.start = Math.max(
+      0,
+      sourceAudioStart + deltaInSeconds
+    );
+  }
+};
+
+const normalizeTimedTrack = (
+  track,
+  globalCuts,
+  trackType,
+  timelineEnd = null
+) => {
+  if (!track || !Array.isArray(track?.segments)) {
+    return track;
+  }
+
+  const normalizedSegments = [];
+
+  track.segments.forEach((segment) => {
+    const segmentStart = toFiniteNumber(segment?.data?.offset, 0);
+    let segmentDuration = resolveSegmentDuration(segment, trackType);
+    // An open-ended soundtrack plays to the pre-cut segment timeline end.
+    // Bound it in the same coordinates as globalCuts so source audio can be
+    // advanced or split exactly like an explicitly timed audio segment.
+    if (
+      trackType === "audio" &&
+      !Number.isFinite(segmentDuration) &&
+      timelineEnd > EPSILON
+    ) {
+      segmentDuration = timelineEnd - segmentStart;
+      if (segmentDuration <= EPSILON) return;
+    }
+
+    if (!Number.isFinite(segmentDuration) || segmentDuration <= EPSILON) {
+      const shiftedSegment = cloneValue(segment);
+      shiftedSegment.data = shiftedSegment.data || {};
+      shiftedSegment.data.offset = mapTimeAfterCuts(segmentStart, globalCuts);
+
+      if (trackType === "caption") {
+        shiftedSegment.data.transcript_text = normalizeTranscriptsForRange({
+          transcripts: segment?.data?.transcript_text || [],
+          rangeStart: 0,
+          rangeEnd: Number.POSITIVE_INFINITY,
+          offsetMode: "relative",
+          offsetBase: 0,
+          stripDisabled: true,
+        });
+
+        if (shiftedSegment.data.transcript_text.length === 0) {
+          return;
+        }
+      }
+
+      normalizedSegments.push(shiftedSegment);
+      return;
+    }
+
+    const segmentEnd = segmentStart + segmentDuration;
+    const wasCut = globalCuts.some(
+      (cut) =>
+        cut.start < segmentEnd - EPSILON && cut.end > segmentStart + EPSILON
+    );
+    const keptRanges = subtractIntervals(
+      { start: segmentStart, end: segmentEnd },
+      globalCuts
+    );
+
+    keptRanges.forEach((keptRange) => {
+      const chunkDuration = keptRange.end - keptRange.start;
+      if (
+        chunkDuration <= EPSILON ||
+        (wasCut && !isMeaningfulDuration(chunkDuration))
+      ) {
+        return;
+      }
+
+      const clonedChunk = cloneValue(segment);
+      clonedChunk.data = clonedChunk.data || {};
+      clonedChunk.data.offset = mapTimeAfterCuts(keptRange.start, globalCuts);
+      clonedChunk.data.duration = chunkDuration;
+
+      const sourceTimeDelta = keptRange.start - segmentStart;
+      shiftSourceMediaStart(clonedChunk, sourceTimeDelta);
+
+      if (trackType === "caption") {
+        const localStart = keptRange.start - segmentStart;
+        const localEnd = keptRange.end - segmentStart;
+
+        clonedChunk.data.transcript_text = normalizeTranscriptsForRange({
+          transcripts: segment?.data?.transcript_text || [],
+          rangeStart: localStart,
+          rangeEnd: localEnd,
+          offsetMode: "relative",
+          offsetBase: localStart,
+          stripDisabled: true,
+        });
+
+        if (clonedChunk.data.transcript_text.length === 0) {
+          return;
+        }
+      }
+
+      normalizedSegments.push(clonedChunk);
+    });
+  });
+
+  return {
+    ...track,
+    segments: normalizedSegments,
+  };
+};
+
+const normalizeDisabledTranscripts = (screenplayInput) => {
+  const screenplay = cloneValue(screenplayInput) || {};
+  if (!Array.isArray(screenplay?.tracks)) {
+    return screenplay;
+  }
+
+  // Repair legacy caption timing before deriving cuts, using the same helper
+  // that prepares editor previews and saved screenplays.
+  for (const track of screenplay.tracks) {
+    for (const segment of track?.segments || []) {
+      const carriers = [
+        segment,
+        ...(Array.isArray(segment?.effects) ? segment.effects : []),
+      ];
+      for (const carrier of carriers) {
+        if (Array.isArray(carrier?.data?.transcript_text))
+          carrier.data.transcript_text = normalizeCaptionEntriesWithTiming(
+            carrier.data.transcript_text
+          );
+      }
+    }
+  }
+
+  const globalDisabledIntervals = collectGlobalDisabledIntervals(screenplay);
+  if (globalDisabledIntervals.length === 0) {
+    return screenplay;
+  }
+
+  const segmentTimelineEnd = (
+    screenplay.tracks.find((track) => track.type === "segment")?.segments || []
+  ).reduce(
+    (end, segment) => end + getSegmentTiming(segment).playableDuration,
+    0
+  );
+
+  screenplay.tracks = screenplay.tracks.map((track) => {
+    if (!track || !Array.isArray(track?.segments)) {
+      return track;
+    }
+
+    switch (track.type) {
+      case "segment":
+        return normalizeSegmentTrack(track, globalDisabledIntervals);
+      case "effect":
+        return normalizeTimedTrack(track, globalDisabledIntervals, "effect");
+      case "audio":
+        return normalizeTimedTrack(
+          track,
+          globalDisabledIntervals,
+          "audio",
+          segmentTimelineEnd
+        );
+      case "caption":
+        return normalizeTimedTrack(track, globalDisabledIntervals, "caption");
+      default:
+        return track;
+    }
+  });
+
+  return screenplay;
+};
+
+// Canonical, dependency-free timing artifact. Zync vendors this file verbatim in
+// common/helper/screenplayTiming.cjs; verify parity before releasing either repo.
+const prepareScreenplay = (input) => {
+  const screenplay = normalizeDisabledTranscripts(input);
+  for (const track of screenplay.tracks || []) {
+    if (track.type === "segment")
+      track.segments = (track.segments || [])
+        .map((segment, index) => {
+          segment.__originSegmentIndex ??= index;
+          return segment;
+        })
+        .filter((s) => !isDisabled(s.layout?.removed));
+  }
+  return screenplay;
+};
+const getScreenplayTiming = (input, { prepared = false } = {}) => {
+  const screenplay = prepared ? input : prepareScreenplay(input);
+  const segments = (
+    screenplay.tracks?.find((t) => t.type === "segment")?.segments || []
+  ).filter((s) => !isDisabled(s.layout?.removed));
+  const segmentFrames = segments.map((segment) =>
+    Math.max(
+      1,
+      Math.round(getSegmentTiming(segment).playableDuration * DEFAULT_FPS)
+    )
+  );
+  let cursor = 0;
+  const sequences = segments.map((segment, index) => {
+    const frames = segmentFrames[index];
+    const overlapFrames =
+      screenplay.input?.theme === "none" &&
+      index < segments.length - 1 &&
+      frames >= 15 &&
+      segmentFrames[index + 1] >= 15 &&
+      (segment.transitionAfter ?? segment.__transitionAfter) !== false
+        ? 15
+        : 0;
+    const startFrame = cursor;
+    cursor += frames - overlapFrames;
+    return {
+      originSegmentIndex: segment.__originSegmentIndex ?? index,
+      startFrame,
+      endFrame: startFrame + frames,
+      durationInFrames: frames,
+      overlapFrames,
+    };
+  });
+  return {
+    fps: DEFAULT_FPS,
+    durationInFrames: cursor,
+    durationSeconds: cursor / DEFAULT_FPS,
+    sequences,
+  };
+};
+module.exports = {
+  normalizeCaptionEntriesWithTiming,
+  normalizeDisabledTranscripts,
+  prepareScreenplay,
+  getScreenplayTiming,
+};