aivee 0.0.0-stage → 0.1.0-dev.7025438

package/src/timeline/validate.mjs

@@ -0,0 +1,322 @@
+import { validateSourceFit } from './source-fit.mjs';
+import { validateAudioMix } from './audio-mix.mjs';
+import { frameRateNumber } from '../media/frame-rate.mjs';
+import { validateVisualKeyframes } from './keyframes.mjs';
+import { validateAudioMastering } from './audio-mastering.mjs';
+import { validateVisualMask } from './mask.mjs';
+import { validateSpeedRamp } from './speed-ramp.mjs';
+import { validateClipTransition } from './transition.mjs';
+import { validateBlendMode } from './blend-mode.mjs';
+import { validateAudioClipEffects } from './audio-effects.mjs';
+import { validateAudioTrackVolumeKeyframes, validateAudioVolumeKeyframes } from './audio-volume.mjs';
+import { validateProjectBackgroundColor } from './background.mjs';
+import { validateSpeechBubble } from './speech-bubble.mjs';
+
+const TRACK_KINDS = new Set(['video', 'audio', 'overlay']);
+
+export function validateTimeline(timeline) {
+  if (!timeline || typeof timeline !== 'object' || Array.isArray(timeline) || timeline.schemaVersion !== 1) throw new TypeError('Timeline must be an object with schemaVersion 1.');
+  const project = timeline.project;
+  if (!project || typeof project !== 'object' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(project.id ?? '')) throw new TypeError('Timeline project needs a kebab-case id.');
+  for (const field of ['width', 'height']) if (!Number.isSafeInteger(project[field]) || project[field] <= 0) throw new TypeError(`Timeline project ${field} must be a positive integer.`);
+  frameRateNumber(project.fps);
+  if (!Number.isFinite(project.durationSeconds) || project.durationSeconds <= 0) throw new TypeError('Timeline project durationSeconds must be positive.');
+  validateSourceFit(project.sourceFit, 'Timeline project sourceFit');
+  if (project.backgroundColor !== undefined) validateProjectBackgroundColor(project.backgroundColor, 'Timeline project backgroundColor');
+  if (!Array.isArray(timeline.assets) || !Array.isArray(timeline.tracks)) throw new TypeError('Timeline assets and tracks must be arrays.');
+  if (timeline.markers !== undefined) {
+    if (!Array.isArray(timeline.markers)) throw new TypeError('Timeline markers must be an array.');
+    const markerIds = new Set();
+    for (const marker of timeline.markers) {
+      if (!marker || typeof marker !== 'object' || Array.isArray(marker)
+          || !/^[a-z][a-z0-9-]*$/.test(marker.id ?? '') || markerIds.has(marker.id)) {
+        throw new TypeError('Timeline marker ids must be unique kebab-case ids.');
+      }
+      if (!Number.isFinite(marker.timeSeconds) || marker.timeSeconds < 0 || marker.timeSeconds > project.durationSeconds) {
+        throw new TypeError(`Timeline marker ${marker.id} must be within the project duration.`);
+      }
+      if (typeof marker.label !== 'string' || !marker.label.trim() || marker.label.length > 200) {
+        throw new TypeError(`Timeline marker ${marker.id} label must contain 1 to 200 characters.`);
+      }
+      if (marker.color !== undefined && (typeof marker.color !== 'string' || !/^#[0-9a-f]{6}$/i.test(marker.color))) {
+        throw new TypeError(`Timeline marker ${marker.id} color must be a six-digit hex color.`);
+      }
+      for (const field of Object.keys(marker)) {
+        if (!['id', 'timeSeconds', 'label', 'color'].includes(field)) throw new TypeError(`Timeline marker ${marker.id} has unsupported field ${field}.`);
+        if (marker[field] === undefined) throw new TypeError(`Timeline marker ${marker.id} field ${field} must not be undefined.`);
+      }
+      markerIds.add(marker.id);
+    }
+  }
+
+  const assets = new Set();
+  for (const asset of timeline.assets) {
+    if (!asset || !/^[a-z][a-z0-9-]*$/.test(asset.id ?? '') || assets.has(asset.id)) throw new TypeError('Timeline asset ids must be unique kebab-case ids.');
+    if (typeof asset.path !== 'string' || !asset.path.trim() || asset.path.startsWith('/') || /^[a-z]:[\\/]/i.test(asset.path) || asset.path.split(/[\\/]/).includes('..')) throw new TypeError(`Asset ${asset.id} needs a project-relative path without traversal.`);
+    if (asset.type !== undefined && !['video', 'audio', 'image'].includes(asset.type)) throw new TypeError(`Asset ${asset.id} has an unsupported media type.`);
+    if (asset.hasAudio !== undefined && typeof asset.hasAudio !== 'boolean') throw new TypeError(`Asset ${asset.id} has invalid audio metadata.`);
+    if (asset.videoStreams !== undefined) validateVideoStreams(asset.videoStreams, asset.id);
+    if (asset.audioStreams !== undefined) validateAudioStreams(asset.audioStreams, asset.id);
+    if (asset.durationSeconds !== undefined && (!Number.isFinite(asset.durationSeconds) || asset.durationSeconds <= 0)) throw new TypeError(`Asset ${asset.id} durationSeconds must be positive.`);
+    if (asset.streamTiming !== undefined) validateStreamTiming(asset.streamTiming, asset.id);
+    assets.add(asset.id);
+  }
+
+  const trackIds = new Set();
+  const trackOrders = new Set();
+  for (const track of timeline.tracks) {
+    if (!track || !/^[a-z][a-z0-9-]*$/.test(track.id ?? '') || trackIds.has(track.id)) throw new TypeError('Timeline track ids must be unique kebab-case ids.');
+    if (!TRACK_KINDS.has(track.kind) || !Number.isSafeInteger(track.order) || track.order < 0 || !Array.isArray(track.clips)) throw new TypeError(`Track ${track.id} has invalid kind, order, or clips.`);
+    if (trackOrders.has(track.order)) throw new TypeError(`Timeline track order ${track.order} is used more than once.`);
+    if (track.muted !== undefined && (track.kind !== 'audio' || typeof track.muted !== 'boolean')) throw new TypeError(`Track ${track.id} muted must be a boolean on an audio track.`);
+    if (track.solo !== undefined && (track.kind !== 'audio' || typeof track.solo !== 'boolean')) throw new TypeError(`Track ${track.id} solo must be a boolean on an audio track.`);
+    if (track.locked !== undefined && typeof track.locked !== 'boolean') throw new TypeError(`Track ${track.id} locked must be a boolean.`);
+    if (track.visible !== undefined && ((track.kind !== 'video' && track.kind !== 'overlay') || typeof track.visible !== 'boolean')) throw new TypeError(`Track ${track.id} visible must be a boolean on a video or overlay track.`);
+    if (track.allowOverlap !== undefined && typeof track.allowOverlap !== 'boolean') throw new TypeError(`Track ${track.id} allowOverlap must be a boolean.`);
+    if (track.volume !== undefined && (track.kind !== 'audio' || !Number.isFinite(track.volume) || track.volume < 0 || track.volume > 1)) throw new TypeError(`Track ${track.id} volume must be between 0 and 1 on an audio track.`);
+    if (track.audioEffects !== undefined) {
+      if (track.kind !== 'audio') throw new TypeError(`Track ${track.id} audioEffects are supported only on audio tracks.`);
+      validateAudioClipEffects(track.audioEffects, `track ${track.id}`);
+    }
+    validateAudioTrackVolumeKeyframes(track.volumeKeyframes, track, project.durationSeconds);
+    trackIds.add(track.id);
+    trackOrders.add(track.order);
+    const clipIds = new Set();
+    const clips = [...track.clips].sort((a, b) => a.timelineStart - b.timelineStart);
+    let previousEnd = 0;
+    for (const clip of clips) {
+      if (!clip || !/^[a-z][a-z0-9-]*$/.test(clip.id ?? '') || clipIds.has(clip.id)) throw new TypeError(`Track ${track.id} clip ids must be unique kebab-case ids.`);
+      clipIds.add(clip.id);
+      if (clip.enabled !== undefined && typeof clip.enabled !== 'boolean') throw new TypeError(`Clip ${clip.id} enabled must be a boolean.`);
+      if (!Number.isFinite(clip.timelineStart) || clip.timelineStart < 0 || !Number.isFinite(clip.durationSeconds) || clip.durationSeconds <= 0 || clip.timelineStart + clip.durationSeconds > project.durationSeconds + 1e-6) throw new TypeError(`Clip ${clip.id} has invalid timeline bounds.`);
+      if (track.kind === 'overlay') {
+        const hasComposition = typeof clip.composition === 'string' && clip.composition.trim();
+        const hasText = typeof clip.text === 'string' && clip.text.trim();
+        if (Boolean(hasComposition) === Boolean(hasText)) throw new TypeError(`Overlay ${clip.id} must define either a composition or text.`);
+        if (hasText) validateTextClip(clip);
+      } else if (!assets.has(clip.assetId)) throw new TypeError(`Clip ${clip.id} is missing its asset for the ${track.kind} track.`);
+      const assetRecord = timeline.assets.find((item) => item.id === clip.assetId);
+      if (track.kind === 'video' && assetRecord?.type === 'audio') throw new TypeError(`Video clip ${clip.id} references an audio-only asset.`);
+      if (track.kind === 'audio' && assetRecord?.type === 'image') throw new TypeError(`Audio clip ${clip.id} references an image asset.`);
+      if (track.kind === 'audio' && assetRecord?.type === 'video' && assetRecord.hasAudio === false) throw new TypeError(`Audio clip ${clip.id} references a video asset without audio.`);
+      if (clip.audioEffects !== undefined) {
+        if (track.kind !== 'audio') throw new TypeError(`Clip ${clip.id} audioEffects are supported only on audio tracks.`);
+        validateAudioClipEffects(clip.audioEffects, clip.id);
+      }
+      if (clip.volumeKeyframes !== undefined) {
+        if (track.kind !== 'audio') throw new TypeError(`Clip ${clip.id} volumeKeyframes are supported only on audio tracks.`);
+        validateAudioVolumeKeyframes(clip.volumeKeyframes, clip);
+      }
+      if (clip.audioStreamIndex !== undefined) {
+        if (track.kind !== 'audio' || !Number.isSafeInteger(clip.audioStreamIndex) || clip.audioStreamIndex < 0) {
+          throw new TypeError(`Clip ${clip.id} audioStreamIndex must be a non-negative integer on an audio track.`);
+        }
+        if (assetRecord?.audioStreams && clip.audioStreamIndex >= assetRecord.audioStreams.length) {
+          throw new TypeError(`Clip ${clip.id} audioStreamIndex exceeds the audio streams in asset ${assetRecord.id}.`);
+        }
+        if (!assetRecord?.audioStreams && clip.audioStreamIndex > 0) {
+          throw new TypeError(`Asset ${assetRecord?.id ?? clip.assetId} has no probed audio stream metadata for index ${clip.audioStreamIndex}.`);
+        }
+      }
+      if (clip.videoStreamIndex !== undefined) {
+        if (track.kind !== 'video' || assetRecord?.type === 'image' || !Number.isSafeInteger(clip.videoStreamIndex) || clip.videoStreamIndex < 0) {
+          throw new TypeError(`Clip ${clip.id} videoStreamIndex must be a non-negative integer on a video track.`);
+        }
+        if (assetRecord?.videoStreams && clip.videoStreamIndex >= assetRecord.videoStreams.length) {
+          throw new TypeError(`Clip ${clip.id} videoStreamIndex exceeds the video streams in asset ${assetRecord.id}.`);
+        }
+        if (!assetRecord?.videoStreams && clip.videoStreamIndex > 0) {
+          throw new TypeError(`Asset ${assetRecord?.id ?? clip.assetId} has no probed video stream metadata for index ${clip.videoStreamIndex}.`);
+        }
+      }
+      if (clip.fit !== undefined && track.kind !== 'video') throw new TypeError(`Clip ${clip.id} can set fit only on a video track.`);
+      if (track.kind === 'video') {
+        validateSourceFit(clip.fit, `Clip ${clip.id} fit`);
+        validatePlacement(clip, `Video clip ${clip.id}`);
+      }
+      if (clip.mask !== undefined) {
+        if (track.kind !== 'video' && track.kind !== 'overlay') throw new TypeError(`Clip ${clip.id} masks are supported on video and overlay tracks.`);
+        validateVisualMask(clip.mask, `Clip ${clip.id} mask`);
+      }
+      validateTransitions(track, clip);
+      validateBlendMode(clip, track.kind);
+      validateVisualKeyframes(track, clip);
+      if (clip.speedRamp !== undefined) {
+        if ((track.kind !== 'video' && track.kind !== 'audio')
+            || (track.kind === 'video' && assetRecord?.type === 'image')) {
+          throw new TypeError(`Clip ${clip.id} speedRamp requires video or audio media.`);
+        }
+        validateSpeedRamp(clip);
+      }
+      if (clip.playbackRate !== undefined && (!Number.isFinite(clip.playbackRate) || clip.playbackRate < 0.1 || clip.playbackRate > 5 || track.kind === 'overlay' || (track.kind === 'video' && assetRecord?.type === 'image'))) {
+        throw new TypeError(`Clip ${clip.id} playbackRate must be from 0.1 to 5 on video or audio media.`);
+      }
+      if (clip.reverse !== undefined && (typeof clip.reverse !== 'boolean'
+          || !['video', 'audio'].includes(track.kind)
+          || (track.kind === 'video' && assetRecord?.type === 'image'))) {
+        throw new TypeError(`Clip ${clip.id} reverse must be a boolean on video or audio media.`);
+      }
+      if (clip.reverse === true && clip.speedRamp !== undefined) {
+        throw new TypeError(`Clip ${clip.id} cannot combine reverse playback with a speedRamp.`);
+      }
+      if (clip.volume !== undefined && (track.kind !== 'audio' || !Number.isFinite(clip.volume) || clip.volume < 0 || clip.volume > 1)) throw new TypeError(`Clip ${clip.id} volume must be between 0 and 1 on an audio track.`);
+      for (const fade of ['fadeInSeconds', 'fadeOutSeconds']) {
+        if (clip[fade] !== undefined && (!Number.isFinite(clip[fade]) || clip[fade] < 0 || clip[fade] > clip.durationSeconds)) throw new TypeError(`Clip ${clip.id} ${fade} must be between 0 and its duration.`);
+      }
+      if ((clip.fadeInSeconds ?? 0) + (clip.fadeOutSeconds ?? 0) > clip.durationSeconds + 1e-6) throw new TypeError(`Clip ${clip.id} fades cannot exceed the clip duration.`);
+      if (track.kind !== 'overlay' && (!Number.isFinite(clip.sourceIn) || !Number.isFinite(clip.sourceOut) || clip.sourceIn < 0 || clip.sourceOut <= clip.sourceIn || (clip.speedRamp === undefined && Math.abs(clip.sourceOut - clip.sourceIn - clip.durationSeconds * (clip.playbackRate ?? 1)) > 1e-6))) throw new TypeError(`Clip ${clip.id} source range must match its timeline duration multiplied by playbackRate.`);
+      if (track.kind !== 'overlay' && Number.isFinite(assetRecord?.durationSeconds) && clip.sourceOut > assetRecord.durationSeconds + 1e-6) throw new TypeError(`Clip ${clip.id} sourceOut exceeds asset ${assetRecord.id} duration.`);
+      if (!track.allowOverlap && clip.timelineStart < previousEnd - 1e-6) throw new TypeError(`Track ${track.id} contains overlapping clips; set allowOverlap to true to permit them.`);
+      previousEnd = clip.timelineStart + clip.durationSeconds;
+    }
+  }
+  validateAudioMix(timeline);
+  validateAudioMastering(timeline);
+  return timeline;
+}
+
+function validateTransitions(track, clip) {
+  const transitions = ['transitionIn', 'transitionOut'].filter((field) => clip[field] !== undefined);
+  if (transitions.length === 0) return;
+  if (track.kind !== 'video' && track.kind !== 'overlay') throw new TypeError(`Clip ${clip.id} transitions are supported on video and overlay tracks.`);
+  for (const field of transitions) validateClipTransition(clip[field], clip, `Clip ${clip.id} ${field}`);
+  const incoming = clip.transitionIn;
+  const outgoing = clip.transitionOut;
+  if ((incoming?.durationSeconds ?? 0) + (outgoing?.durationSeconds ?? 0) > clip.durationSeconds + 1e-6) {
+    throw new TypeError(`Clip ${clip.id} transition durations cannot overlap.`);
+  }
+  if (clip.mask && [incoming, outgoing].some((transition) => transition?.type === 'wipe')) {
+    throw new TypeError(`Clip ${clip.id} wipe transitions cannot be combined with a static mask.`);
+  }
+  if (incoming?.type === 'wipe' && outgoing?.type === 'wipe' && incoming.direction !== outgoing.direction) {
+    throw new TypeError(`Clip ${clip.id} wipe transitions must use the same direction.`);
+  }
+  const usesOpacity = clip.keyframes?.some((frame) => frame.properties.opacity !== undefined);
+  if (usesOpacity && [incoming, outgoing].some((transition) => transition?.type === 'fade')) {
+    throw new TypeError(`Clip ${clip.id} fade transitions cannot be combined with opacity keyframes.`);
+  }
+  if (incoming?.type === 'fade' && (clip.fadeInSeconds ?? 0) > 0) {
+    throw new TypeError(`Clip ${clip.id} fade-in transition cannot be combined with fadeInSeconds.`);
+  }
+  if (outgoing?.type === 'fade' && (clip.fadeOutSeconds ?? 0) > 0) {
+    throw new TypeError(`Clip ${clip.id} fade-out transition cannot be combined with fadeOutSeconds.`);
+  }
+}
+
+function validateStreamTiming(timing, assetId) {
+  if (!timing || typeof timing !== 'object' || Array.isArray(timing)) throw new TypeError(`Asset ${assetId} streamTiming must be an object.`);
+  for (const field of ['containerStartSeconds', 'videoStartSeconds', 'videoDurationSeconds', 'audioStartSeconds', 'audioDurationSeconds']) {
+    if (timing[field] !== undefined && timing[field] !== null && !Number.isFinite(timing[field])) throw new TypeError(`Asset ${assetId} streamTiming.${field} must be finite or null.`);
+  }
+  for (const field of ['videoTimeBase', 'audioTimeBase']) {
+    if (timing[field] !== undefined && timing[field] !== null && typeof timing[field] !== 'string') throw new TypeError(`Asset ${assetId} streamTiming.${field} must be a string or null.`);
+  }
+}
+
+function validateAudioStreams(streams, assetId) {
+  if (!Array.isArray(streams)) throw new TypeError(`Asset ${assetId} audioStreams must be an array.`);
+  for (const [index, stream] of streams.entries()) {
+    if (!stream || typeof stream !== 'object' || Array.isArray(stream)
+        || stream.index !== index
+        || !Number.isSafeInteger(stream.streamIndex) || stream.streamIndex < 0
+        || (stream.codec !== null && stream.codec !== undefined && typeof stream.codec !== 'string')
+        || (stream.channels !== null && stream.channels !== undefined && (!Number.isSafeInteger(stream.channels) || stream.channels < 1))
+        || (stream.channelLayout !== null && stream.channelLayout !== undefined && typeof stream.channelLayout !== 'string')
+        || (stream.sampleRate !== null && stream.sampleRate !== undefined && (!Number.isSafeInteger(stream.sampleRate) || stream.sampleRate < 1))
+        || (stream.startSeconds !== null && stream.startSeconds !== undefined && !Number.isFinite(stream.startSeconds))
+        || (stream.durationSeconds !== null && stream.durationSeconds !== undefined && (!Number.isFinite(stream.durationSeconds) || stream.durationSeconds <= 0))
+        || (stream.timeBase !== null && stream.timeBase !== undefined && typeof stream.timeBase !== 'string')
+        || (stream.language !== null && stream.language !== undefined && typeof stream.language !== 'string')
+        || (stream.title !== null && stream.title !== undefined && typeof stream.title !== 'string')) {
+      throw new TypeError(`Asset ${assetId} audio stream ${index} has invalid metadata.`);
+    }
+  }
+}
+
+function validateVideoStreams(streams, assetId) {
+  if (!Array.isArray(streams)) throw new TypeError(`Asset ${assetId} videoStreams must be an array.`);
+  for (const stream of streams) {
+    if (!stream || typeof stream !== 'object' || Array.isArray(stream)
+        || (stream.index !== null && stream.index !== undefined && (!Number.isSafeInteger(stream.index) || stream.index < 0))
+        || (stream.streamIndex !== null && stream.streamIndex !== undefined && (!Number.isSafeInteger(stream.streamIndex) || stream.streamIndex < 0))
+        || (stream.codec !== null && stream.codec !== undefined && typeof stream.codec !== 'string')
+        || (stream.width !== null && stream.width !== undefined && (!Number.isSafeInteger(stream.width) || stream.width < 1))
+        || (stream.height !== null && stream.height !== undefined && (!Number.isSafeInteger(stream.height) || stream.height < 1))
+        || (stream.frameRate !== null && stream.frameRate !== undefined && (!Number.isFinite(stream.frameRate) || stream.frameRate <= 0))
+        || (stream.startSeconds !== null && stream.startSeconds !== undefined && !Number.isFinite(stream.startSeconds))
+        || (stream.durationSeconds !== null && stream.durationSeconds !== undefined && (!Number.isFinite(stream.durationSeconds) || stream.durationSeconds <= 0))
+        || (stream.timeBase !== null && stream.timeBase !== undefined && typeof stream.timeBase !== 'string')) {
+      throw new TypeError(`Asset ${assetId} video stream has invalid metadata.`);
+    }
+  }
+}
+
+function validateTextClip(clip) {
+  const position = { x: clip.x ?? 0.08, y: clip.y ?? 0.76, width: clip.width ?? 0.84, height: clip.height ?? 0.16 };
+  if (!Object.values(position).every(Number.isFinite) || position.x < 0 || position.y < 0 || position.width <= 0 || position.height <= 0 || position.x + position.width > 1 || position.y + position.height > 1) throw new TypeError(`Text overlay ${clip.id} has invalid normalized placement.`);
+  if (clip.wordWrap !== undefined && typeof clip.wordWrap !== 'boolean') throw new TypeError(`Text overlay ${clip.id} wordWrap must be a boolean.`);
+  if (clip.wordsPerLine !== undefined && (!Number.isSafeInteger(clip.wordsPerLine) || clip.wordsPerLine < 1 || clip.wordsPerLine > 20)) throw new TypeError(`Text overlay ${clip.id} wordsPerLine must be an integer from 1 to 20.`);
+  if (clip.wordTimings !== undefined) {
+    if (!Array.isArray(clip.wordTimings) || clip.wordTimings.length === 0) throw new TypeError(`Text overlay ${clip.id} wordTimings must be a non-empty array.`);
+    let previousStart = -Infinity;
+    for (const [index, word] of clip.wordTimings.entries()) {
+      if (!word || typeof word !== 'object' || Array.isArray(word)
+          || Object.keys(word).some((field) => !['text', 'start', 'end'].includes(field))
+          || typeof word.text !== 'string' || !word.text.trim()
+          || !Number.isFinite(word.start) || !Number.isFinite(word.end)
+          || word.start < 0 || word.end <= word.start || word.end > clip.durationSeconds + 1e-6
+          || word.start < previousStart) {
+        throw new TypeError(`Text overlay ${clip.id} wordTimings entry ${index + 1} is invalid.`);
+      }
+      previousStart = word.start;
+    }
+    if (clip.wordTimings.map((word) => word.text).join(' ') !== clip.text) throw new TypeError(`Text overlay ${clip.id} wordTimings text must match its caption text.`);
+    if (typeof clip.wordHighlightColor !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(clip.wordHighlightColor)) {
+      throw new TypeError(`Text overlay ${clip.id} wordHighlightColor must be a hex color.`);
+    }
+    if (clip.wordHighlightAnimation !== undefined && !['scale', 'pop'].includes(clip.wordHighlightAnimation)) {
+      throw new TypeError(`Text overlay ${clip.id} wordHighlightAnimation must be scale or pop.`);
+    }
+  } else if (clip.wordHighlightColor !== undefined || clip.wordHighlightAnimation !== undefined) {
+    throw new TypeError(`Text overlay ${clip.id} word highlighting options require wordTimings.`);
+  }
+  if (clip.fontSize !== undefined && (!Number.isSafeInteger(clip.fontSize) || clip.fontSize < 8 || clip.fontSize > 256)) throw new TypeError(`Text overlay ${clip.id} fontSize must be an integer from 8 to 256.`);
+  if (clip.fontFamily !== undefined && (typeof clip.fontFamily !== 'string' || !/^[\w ,'-]{1,80}$/.test(clip.fontFamily))) throw new TypeError(`Text overlay ${clip.id} fontFamily contains unsupported characters.`);
+  if (clip.fontWeight !== undefined && !['normal', 'bold', 100, 200, 300, 400, 500, 600, 700, 800, 900].includes(clip.fontWeight)) throw new TypeError(`Text overlay ${clip.id} fontWeight must be normal, bold, or a hundred-step weight from 100 to 900.`);
+  if (clip.lineHeight !== undefined && (!Number.isFinite(clip.lineHeight) || clip.lineHeight < 0.8 || clip.lineHeight > 2.5)) throw new TypeError(`Text overlay ${clip.id} lineHeight must be from 0.8 to 2.5.`);
+  if (clip.verticalAlign !== undefined && !['top', 'center', 'bottom'].includes(clip.verticalAlign)) throw new TypeError(`Text overlay ${clip.id} verticalAlign must be top, center, or bottom.`);
+  if (clip.paddingPixels !== undefined && (!Number.isSafeInteger(clip.paddingPixels) || clip.paddingPixels < 0 || clip.paddingPixels > 128)) throw new TypeError(`Text overlay ${clip.id} paddingPixels must be an integer from 0 to 128.`);
+  for (const color of ['color', 'backgroundColor']) {
+    if (clip[color] !== undefined && clip[color] !== 'transparent' && !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(clip[color])) throw new TypeError(`Text overlay ${clip.id} ${color} must be a hex color or transparent.`);
+  }
+  if (clip.textAlign !== undefined && !['left', 'center', 'right'].includes(clip.textAlign)) throw new TypeError(`Text overlay ${clip.id} textAlign must be left, center, or right.`);
+  if (clip.bubble !== undefined) validateSpeechBubble(clip.bubble, `Text overlay ${clip.id} bubble`);
+  if (clip.textOutline !== undefined) {
+    const outline = clip.textOutline;
+    if (!outline || typeof outline !== 'object' || Array.isArray(outline)
+        || Object.keys(outline).some((field) => !['color', 'widthPixels'].includes(field))
+        || typeof outline.color !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(outline.color)
+        || !Number.isFinite(outline.widthPixels) || outline.widthPixels <= 0 || outline.widthPixels > 12) {
+      throw new TypeError(`Text overlay ${clip.id} textOutline must define a hex color and widthPixels from 0 to 12.`);
+    }
+  }
+  if (clip.textShadow !== undefined) {
+    const shadow = clip.textShadow;
+    if (!shadow || typeof shadow !== 'object' || Array.isArray(shadow)
+        || Object.keys(shadow).some((field) => !['color', 'blurPixels', 'offsetXPixels', 'offsetYPixels'].includes(field))
+        || typeof shadow.color !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(shadow.color)
+        || !Number.isFinite(shadow.blurPixels) || shadow.blurPixels < 0 || shadow.blurPixels > 32
+        || !Number.isFinite(shadow.offsetXPixels) || Math.abs(shadow.offsetXPixels) > 32
+        || !Number.isFinite(shadow.offsetYPixels) || Math.abs(shadow.offsetYPixels) > 32) {
+      throw new TypeError(`Text overlay ${clip.id} textShadow has invalid color or bounds.`);
+    }
+  }
+}
+
+function validatePlacement(clip, label) {
+  const x = clip.x ?? 0;
+  const y = clip.y ?? 0;
+  const width = clip.width ?? 1;
+  const height = clip.height ?? 1;
+  if (![x, y, width, height].every(Number.isFinite) || x < 0 || y < 0 || width <= 0 || height <= 0 || x + width > 1 || y + height > 1) throw new TypeError(`${label} placement must fit within normalized canvas bounds.`);
+}

package/src/transcript/corrections.mjs

@@ -0,0 +1,21 @@
+import { validateTranscript } from './validate.mjs';
+
+export function applyTranscriptCorrections(transcript, corrections) {
+  validateTranscript(transcript);
+  if (!Array.isArray(corrections)) throw new TypeError('Transcript corrections must be an array.');
+  const words = transcript.words.map((word) => ({ ...word }));
+  const updated = new Set();
+  for (const [index, correction] of corrections.entries()) {
+    if (!correction || !Number.isSafeInteger(correction.wordIndex) || correction.wordIndex < 0 || correction.wordIndex >= words.length) throw new TypeError(`Correction ${index + 1} has an invalid wordIndex.`);
+    if (updated.has(correction.wordIndex)) throw new TypeError(`Word ${correction.wordIndex} has duplicate corrections.`);
+    updated.add(correction.wordIndex);
+    const word = words[correction.wordIndex];
+    if (correction.text !== undefined) {
+      if (typeof correction.text !== 'string' || !correction.text.trim()) throw new TypeError(`Correction ${index + 1} text must be a non-empty string.`);
+      word.text = correction.text.trim();
+    }
+    if (correction.start !== undefined) word.start = correction.start;
+    if (correction.end !== undefined) word.end = correction.end;
+  }
+  return validateTranscript({ ...transcript, words });
+}

package/src/transcript/normalize.mjs

@@ -0,0 +1,17 @@
+import { validateTranscript } from './validate.mjs';
+
+export function normalizeTranscript(input, durationSeconds, granularity = 'word') {
+  const sourceWords = Array.isArray(input) ? input : input?.words;
+  if (!Array.isArray(sourceWords)) throw new TypeError('Transcript input must contain a words array.');
+  const words = sourceWords
+    .filter((word) => word?.type === undefined || word.type === 'word')
+    .map((word) => ({
+      text: String(word.text ?? word.word ?? '').trim(),
+      start: Number(word.start),
+      end: Number(word.end),
+    }))
+    .filter((word) => word.text);
+  const transcript = { schemaVersion: 1, durationSeconds, granularity, words };
+  validateTranscript(transcript);
+  return transcript;
+}

package/src/transcript/provider.mjs

@@ -0,0 +1,42 @@
+import { existsSync, openSync, closeSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { probeMedia } from '../media/probe.mjs';
+import { normalizeTranscript } from './normalize.mjs';
+
+/** Run an injected transcription provider and persist its normalized result. */
+export async function transcribeWithProvider(projectPath, mediaPath, provider, options = {}) {
+  const project = resolve(projectPath);
+  const media = resolve(mediaPath);
+  if (!existsSync(join(project, 'meta.json'))) throw new Error(`Not a video project: ${project}`);
+  if (!provider || typeof provider !== 'object'
+      || !/^[a-z][a-z0-9-]*$/.test(provider.id ?? '')
+      || typeof provider.transcribe !== 'function') {
+    throw new TypeError('Provider must define a kebab-case id and async transcribe function.');
+  }
+  const granularity = options.granularity ?? 'word';
+  if (!['word', 'cue'].includes(granularity)) throw new TypeError('Provider granularity must be word or cue.');
+
+  const mediaInfo = probeMedia(media, { requireVideo: false });
+  const raw = await provider.transcribe({
+    mediaPath: media,
+    durationSeconds: mediaInfo.durationSeconds,
+    options: structuredClone(options.providerOptions ?? {}),
+  });
+  const transcript = normalizeTranscript(raw, mediaInfo.durationSeconds, granularity);
+  const transcriptPath = join(project, 'transcripts', 'transcript.json');
+  const fd = openSync(transcriptPath, 'wx');
+  try {
+    writeFileSync(fd, `${JSON.stringify(transcript, null, 2)}\n`);
+  } catch (error) {
+    unlinkSync(transcriptPath);
+    throw error;
+  } finally {
+    closeSync(fd);
+  }
+  return {
+    providerId: provider.id,
+    transcriptPath,
+    wordCount: transcript.words.length,
+    durationSeconds: transcript.durationSeconds,
+  };
+}

package/src/transcript/subtitles.mjs

@@ -0,0 +1,57 @@
+import { validateTranscript } from './validate.mjs';
+
+export function parseSubtitleText(contents, format) {
+  if (typeof contents !== 'string') throw new TypeError('Subtitle contents must be text.');
+  if (!['srt', 'vtt'].includes(format)) throw new TypeError('Subtitle format must be srt or vtt.');
+  const text = contents.replace(/^\uFEFF/, '').replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+  const words = [];
+  for (const block of text.split(/\n\s*\n/)) {
+    const lines = block.split('\n');
+    const timeIndex = lines.findIndex((line) => line.includes('-->'));
+    if (timeIndex < 0) continue;
+    const match = lines[timeIndex].match(/^\s*((?:\d{2}:)?\d{2}:\d{2}[,.]\d{3})\s+-->\s+((?:\d{2}:)?\d{2}:\d{2}[,.]\d{3})(?:\s+.*)?$/);
+    if (!match) throw new TypeError(`Invalid ${format.toUpperCase()} timestamp: ${lines[timeIndex]}`);
+    const start = parseTimestamp(match[1]);
+    const end = parseTimestamp(match[2]);
+    const cueText = lines.slice(timeIndex + 1).join(' ')
+      .replace(/<[^>]*>/g, '')
+      .replace(/&amp;/gi, '&').replace(/&lt;/gi, '<').replace(/&gt;/gi, '>').replace(/&nbsp;/gi, ' ')
+      .replace(/\s+/g, ' ').trim();
+    if (cueText) words.push({ text: cueText, start, end });
+  }
+  if (!words.length) throw new TypeError(`No subtitle cues found in ${format.toUpperCase()} input.`);
+  return { words };
+}
+
+export function formatSubtitleText(transcript, format) {
+  validateTranscript(transcript);
+  if (!['srt', 'vtt'].includes(format)) throw new TypeError('Subtitle format must be srt or vtt.');
+  const cues = transcript.words.map((word, index) => [
+    ...(format === 'srt' ? [String(index + 1)] : []),
+    `${formatTimestamp(word.start, format)} --> ${formatTimestamp(word.end, format)}`,
+    word.text.replace(/\s*\n\s*/g, ' '),
+  ].join('\n'));
+  return `${format === 'vtt' ? 'WEBVTT\n\n' : ''}${cues.join('\n\n')}\n`;
+}
+
+function parseTimestamp(value) {
+  const normalized = value.replace(',', '.');
+  const parts = normalized.split(':');
+  const seconds = Number(parts.pop());
+  const minutes = Number(parts.pop());
+  const hours = parts.length ? Number(parts.pop()) : 0;
+  if (![hours, minutes, seconds].every(Number.isFinite) || minutes >= 60 || seconds >= 60) {
+    throw new TypeError(`Invalid subtitle time: ${value}`);
+  }
+  return hours * 3600 + minutes * 60 + seconds;
+}
+
+function formatTimestamp(seconds, format) {
+  const milliseconds = Math.round(seconds * 1000);
+  const hours = Math.floor(milliseconds / 3_600_000);
+  const minutes = Math.floor((milliseconds % 3_600_000) / 60_000);
+  const wholeSeconds = Math.floor((milliseconds % 60_000) / 1000);
+  const fraction = milliseconds % 1000;
+  const time = `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(wholeSeconds).padStart(2, '0')}`;
+  return `${time}${format === 'srt' ? ',' : '.'}${String(fraction).padStart(3, '0')}`;
+}

package/src/transcript/validate.mjs

@@ -0,0 +1,39 @@
+export function validateTranscript(transcript) {
+  if (!transcript || typeof transcript !== 'object' || Array.isArray(transcript)) {
+    throw new TypeError('Transcript must be a JSON object.');
+  }
+  if (transcript.schemaVersion !== 1) {
+    throw new TypeError('Transcript schemaVersion must be 1.');
+  }
+  if (!Number.isFinite(transcript.durationSeconds) || transcript.durationSeconds <= 0) {
+    throw new TypeError('Transcript durationSeconds must be a positive number.');
+  }
+  if (!Array.isArray(transcript.words)) {
+    throw new TypeError('Transcript words must be an array.');
+  }
+  if (transcript.granularity !== undefined && !['word', 'cue'].includes(transcript.granularity)) {
+    throw new TypeError('Transcript granularity must be word or cue.');
+  }
+
+  let previousStart = -Infinity;
+  for (const [index, word] of transcript.words.entries()) {
+    const label = `Transcript word ${index + 1}`;
+    if (!word || typeof word !== 'object' || Array.isArray(word)) {
+      throw new TypeError(`${label} must be an object.`);
+    }
+    if (typeof word.text !== 'string' || !word.text.trim()) {
+      throw new TypeError(`${label} text must be a non-empty string.`);
+    }
+    if (!Number.isFinite(word.start) || !Number.isFinite(word.end) || word.start < 0 || word.end <= word.start) {
+      throw new TypeError(`${label} must have finite times with 0 <= start < end.`);
+    }
+    if (word.end > transcript.durationSeconds) {
+      throw new TypeError(`${label} ends after the source duration.`);
+    }
+    if (word.start < previousStart) {
+      throw new TypeError(`${label} starts before the previous word.`);
+    }
+    previousStart = word.start;
+  }
+  return transcript;
+}