aivee 0.0.0-stage → 0.1.0-dev.7025438

package/src/timeline/audio-mix.mjs

@@ -0,0 +1,105 @@
+import { sampleAudioVolumeKeyframes } from './audio-volume.mjs';
+
+export function validateAudioMix(timeline) {
+  const mix = timeline.audioMix;
+  if (mix === undefined) return timeline;
+  if (!mix || typeof mix !== 'object' || Array.isArray(mix) || (mix.ducking !== undefined && !Array.isArray(mix.ducking))
+      || (mix.sidechain !== undefined && !Array.isArray(mix.sidechain))) {
+    throw new TypeError('Timeline audioMix ducking and sidechain settings must be arrays when provided.');
+  }
+  const tracks = new Map(timeline.tracks.map((track) => [track.id, track]));
+  for (const [index, rule] of (mix.ducking ?? []).entries()) {
+    const source = tracks.get(rule?.sourceTrackId);
+    const target = tracks.get(rule?.targetTrackId);
+    if (!source || !target || source.kind !== 'audio' || target.kind !== 'audio' || source === target) throw new TypeError(`Audio ducking rule ${index + 1} must reference two different audio tracks.`);
+    if (!Number.isFinite(rule.attenuation) || rule.attenuation < 0 || rule.attenuation > 1) throw new TypeError(`Audio ducking rule ${index + 1} attenuation must be between 0 and 1.`);
+    for (const field of ['attackSeconds', 'releaseSeconds']) if (!Number.isFinite(rule[field] ?? 0) || (rule[field] ?? 0) < 0) throw new TypeError(`Audio ducking rule ${index + 1} ${field} must be non-negative.`);
+  }
+  for (const [index, rule] of (mix.sidechain ?? []).entries()) {
+    const source = tracks.get(rule?.sourceTrackId);
+    const target = tracks.get(rule?.targetTrackId);
+    if (!source || !target || source.kind !== 'audio' || target.kind !== 'audio' || source === target
+        || source.clips.length === 0 || target.clips.length === 0) {
+      throw new TypeError(`Audio sidechain rule ${index + 1} must reference two different non-empty audio tracks.`);
+    }
+    const settings = resolveAudioSidechainSettings(rule);
+    if (!Number.isFinite(settings.thresholdDb) || settings.thresholdDb < -60 || settings.thresholdDb > 0) throw new TypeError(`Audio sidechain rule ${index + 1} thresholdDb must be between -60 and 0.`);
+    if (!Number.isFinite(settings.ratio) || settings.ratio < 1 || settings.ratio > 20) throw new TypeError(`Audio sidechain rule ${index + 1} ratio must be between 1 and 20.`);
+    if (!Number.isFinite(settings.attackSeconds) || settings.attackSeconds < 0.00001 || settings.attackSeconds > 2) throw new TypeError(`Audio sidechain rule ${index + 1} attackSeconds must be between 0.00001 and 2.`);
+    if (!Number.isFinite(settings.releaseSeconds) || settings.releaseSeconds < 0.00001 || settings.releaseSeconds > 9) throw new TypeError(`Audio sidechain rule ${index + 1} releaseSeconds must be between 0.00001 and 9.`);
+    for (const field of Object.keys(rule)) {
+      if (!['sourceTrackId', 'targetTrackId', 'thresholdDb', 'ratio', 'attackSeconds', 'releaseSeconds'].includes(field)) {
+        throw new TypeError(`Audio sidechain rule ${index + 1} has an unsupported field: ${field}.`);
+      }
+    }
+  }
+  return timeline;
+}
+
+export function resolveAudioSidechainSettings(rule) {
+  return {
+    thresholdDb: rule.thresholdDb ?? -24,
+    ratio: rule.ratio ?? 4,
+    attackSeconds: rule.attackSeconds ?? 0.01,
+    releaseSeconds: rule.releaseSeconds ?? 0.25,
+  };
+}
+
+export function buildAudioVolumeAutomation(timeline, track, clip) {
+  const start = clip.timelineStart;
+  const end = start + clip.durationSeconds;
+  const baseVolume = (clip.volume ?? 1) * (track.volume ?? 1);
+  const duckRamps = [];
+  for (const rule of timeline.audioMix?.ducking ?? []) {
+    if (rule.targetTrackId !== track.id) continue;
+    const source = timeline.tracks.find((item) => item.id === rule.sourceTrackId);
+    for (const sourceClip of source._duckingIntervals ?? source.clips) {
+      const duckStart = Math.max(start, sourceClip.timelineStart);
+      const duckEnd = Math.min(end, sourceClip.timelineStart + sourceClip.durationSeconds);
+      if (duckEnd <= duckStart) continue;
+      duckRamps.push({
+        start: duckStart,
+        end: duckEnd,
+        attenuation: rule.attenuation,
+        attackSeconds: rule.attackSeconds ?? 0,
+        releaseSeconds: rule.releaseSeconds ?? 0,
+      });
+    }
+  }
+
+  const points = new Set([start, end]);
+  const fadeIn = clip.fadeInSeconds ?? 0;
+  const fadeOut = clip.fadeOutSeconds ?? 0;
+  if (fadeIn > 0) points.add(start + fadeIn);
+  if (fadeOut > 0) points.add(end - fadeOut);
+  for (const keyframe of clip.volumeKeyframes ?? []) points.add(start + keyframe.time);
+  for (const keyframe of track.volumeKeyframes ?? []) {
+    if (keyframe.time > start && keyframe.time < end) points.add(keyframe.time);
+  }
+  for (const ramp of duckRamps) {
+    points.add(Math.max(start, ramp.start - ramp.attackSeconds));
+    points.add(ramp.start);
+    points.add(ramp.end);
+    points.add(Math.min(end, ramp.end + ramp.releaseSeconds));
+  }
+
+  return [...points].sort((a, b) => a - b).map((time) => {
+    let volume = baseVolume;
+    volume *= sampleAudioVolumeKeyframes(track.volumeKeyframes, time);
+    volume *= sampleAudioVolumeKeyframes(clip.volumeKeyframes, time - start);
+    if (fadeIn > 0 && time < start + fadeIn) volume *= Math.max(0, (time - start) / fadeIn);
+    if (fadeOut > 0 && time > end - fadeOut) volume *= Math.max(0, (end - time) / fadeOut);
+    for (const ramp of duckRamps) volume *= duckFactorAt(time, ramp);
+    return { time, volume: Number(volume.toFixed(6)) };
+  });
+}
+
+function duckFactorAt(time, ramp) {
+  if (time < ramp.start) {
+    const attackStart = ramp.start - ramp.attackSeconds;
+    if (ramp.attackSeconds === 0 || time <= attackStart) return 1;
+    return 1 - ((time - attackStart) / ramp.attackSeconds) * (1 - ramp.attenuation);
+  }
+  if (time <= ramp.end || ramp.releaseSeconds === 0 || time >= ramp.end + ramp.releaseSeconds) return time <= ramp.end ? ramp.attenuation : 1;
+  return ramp.attenuation + ((time - ramp.end) / ramp.releaseSeconds) * (1 - ramp.attenuation);
+}

package/src/timeline/audio-track-effects.mjs

@@ -0,0 +1,139 @@
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from '../render/process.mjs';
+import { buildAudioClipEffectFilters } from './audio-effects.mjs';
+import { buildAudioVolumeAutomation } from './audio-mix.mjs';
+
+export function applyAudioTrackEffectProxies(root, timeline, temporaryAssets) {
+  const context = prepareAudioTrackEffectProxies(root, timeline, temporaryAssets);
+  try {
+    for (const job of context.jobs) {
+      const result = spawnSync('ffmpeg', job.args, {
+        encoding: 'utf8',
+        windowsHide: true,
+        cwd: root,
+        maxBuffer: 4 * 1024 * 1024,
+      });
+      if (result.error || result.status !== 0) {
+        throw new Error(`Could not apply audio effects to track ${job.trackId}: ${result.error?.message ?? result.stderr.trim()}`);
+      }
+    }
+    return context.timeline;
+  } catch (error) {
+    removePreparedAssets(temporaryAssets, context.startIndex);
+    throw error;
+  }
+}
+
+export async function applyAudioTrackEffectProxiesAsync(root, timeline, temporaryAssets, renderControl) {
+  const context = prepareAudioTrackEffectProxies(root, timeline, temporaryAssets);
+  try {
+    for (const job of context.jobs) {
+      renderControl.assertActive();
+      try {
+        await runProcess('ffmpeg', job.args, { cwd: root, signal: renderControl.signal, stdio: 'capture' });
+      } catch (error) {
+        if (renderControl.signal.aborted) throw renderControl.signal.reason ?? error;
+        throw new Error(`Could not apply audio effects to track ${job.trackId}: ${error.message}`, { cause: error });
+      }
+      renderControl.assertActive();
+    }
+    return context.timeline;
+  } catch (error) {
+    removePreparedAssets(temporaryAssets, context.startIndex);
+    throw error;
+  }
+}
+
+function prepareAudioTrackEffectProxies(root, timeline, temporaryAssets) {
+  const next = structuredClone(timeline);
+  const startIndex = temporaryAssets.length;
+  const jobs = [];
+  try {
+    for (const track of next.tracks) {
+      if (track.kind !== 'audio' || !track.audioEffects?.length || track.clips.length === 0) continue;
+      const sourceClips = track.clips.map((clip) => ({ timelineStart: clip.timelineStart, durationSeconds: clip.durationSeconds }));
+      const labels = [];
+      const filters = [];
+      const args = [];
+      for (const [index, clip] of track.clips.entries()) {
+        const asset = next.assets.find((entry) => entry.id === clip.assetId);
+        if (!asset) throw new TypeError(`Track ${track.id} clip ${clip.id} is missing its audio asset.`);
+        args.push('-i', join(root, ...asset.path.split('/')));
+        const automation = buildAudioVolumeAutomation(next, track, clip);
+        const label = `trackclip${index}`;
+        labels.push(`[${label}]`);
+        const steps = [
+          `atrim=start=${clip.sourceIn}:end=${clip.sourceOut}`,
+          'asetpts=PTS-STARTPTS',
+          'aresample=48000',
+          'aformat=sample_fmts=fltp:channel_layouts=stereo',
+          `volume='${toVolumeExpression(automation, clip.timelineStart)}':eval=frame`,
+          `adelay=delays=${Math.round(clip.timelineStart * 1000)}:all=1`,
+        ];
+        filters.push(`[${index}:a:${clip.audioStreamIndex ?? 0}]${steps.join(',')}[${label}]`);
+      }
+      const effectFilters = buildAudioClipEffectFilters(track.audioEffects);
+      const outputLabel = 'trackfxout';
+      filters.push(`${labels.join('')}amix=inputs=${labels.length}:duration=longest:normalize=0,apad=whole_dur=${next.project.durationSeconds},atrim=duration=${next.project.durationSeconds},asetpts=PTS-STARTPTS${effectFilters.length ? `,${effectFilters.join(',')}` : ''}[${outputLabel}]`);
+      const id = `track-effects-${track.id}-${randomUUID().slice(0, 8)}`;
+      const relativePath = `assets/.${id}-${randomUUID()}.wav`;
+      const absolutePath = join(root, ...relativePath.split('/'));
+      temporaryAssets.push(absolutePath);
+      jobs.push({
+        trackId: track.id,
+        args: [
+          '-nostdin', '-hide_banner', '-v', 'error', '-y', '-filter_threads', '1', '-filter_complex_threads', '1',
+          ...args, '-filter_complex', filters.join(';'), '-map', `[${outputLabel}]`, '-vn', '-ar', '48000', '-ac', '2', '-c:a', 'pcm_s16le', absolutePath,
+        ],
+      });
+      next.assets.push({ id, path: relativePath, type: 'audio', hasAudio: true, durationSeconds: next.project.durationSeconds });
+      track.clips = [{
+        id: `processed-${track.id}`,
+        assetId: id,
+        sourceIn: 0,
+        sourceOut: next.project.durationSeconds,
+        timelineStart: 0,
+        durationSeconds: next.project.durationSeconds,
+      }];
+      track.volume = 1;
+      delete track.volumeKeyframes;
+      delete track.audioEffects;
+      track._duckingIntervals = sourceClips;
+    }
+
+    const effectedTrackIds = new Set(next.tracks.filter((track) => track.kind === 'audio' && track._duckingIntervals).map((track) => track.id));
+    if (next.audioMix?.ducking) {
+      const ducking = next.audioMix.ducking.filter((rule) => !effectedTrackIds.has(rule.targetTrackId));
+      if (ducking.length === 0) delete next.audioMix.ducking;
+      else next.audioMix.ducking = ducking;
+      if (Object.keys(next.audioMix).length === 0) delete next.audioMix;
+    }
+    return { timeline: next, jobs, startIndex };
+  } catch (error) {
+    removePreparedAssets(temporaryAssets, startIndex);
+    throw error;
+  }
+}
+
+function removePreparedAssets(temporaryAssets, startIndex) {
+  for (const asset of temporaryAssets.splice(startIndex)) rmSync(asset, { force: true });
+}
+
+function toVolumeExpression(points, clipStart) {
+  if (points.length === 0) return '1';
+  let expression = String(points.at(-1).volume);
+  for (let index = points.length - 2; index >= 0; index--) {
+    const from = points[index];
+    const to = points[index + 1];
+    const fromTime = from.time - clipStart;
+    const toTime = to.time - clipStart;
+    const span = toTime - fromTime;
+    if (span <= 0) continue;
+    const linear = `(${from.volume}+(${to.volume - from.volume})*(t-${fromTime})/${span})`;
+    expression = `if(lt(t\\,${toTime})\\,${linear}\\,${expression})`;
+  }
+  return expression;
+}

package/src/timeline/audio-volume.mjs

@@ -0,0 +1,63 @@
+export function validateAudioVolumeKeyframes(keyframes, clip) {
+  if (keyframes === undefined) return;
+  if (!Array.isArray(keyframes) || keyframes.length === 0 || keyframes.length > 512) {
+    throw new TypeError(`Clip ${clip.id} volumeKeyframes must be an array with 1 to 512 entries.`);
+  }
+  if (keyframes[0]?.time !== 0) throw new TypeError(`Clip ${clip.id} volumeKeyframes must start at time 0.`);
+  let previousTime = -1;
+  for (const [index, keyframe] of keyframes.entries()) {
+    if (!keyframe || typeof keyframe !== 'object' || Array.isArray(keyframe)
+        || Object.keys(keyframe).some((field) => !['time', 'volume'].includes(field))
+        || !Number.isFinite(keyframe.time) || keyframe.time < 0 || keyframe.time > clip.durationSeconds
+        || keyframe.time <= previousTime
+        || !Number.isFinite(keyframe.volume) || keyframe.volume < 0 || keyframe.volume > 1) {
+      throw new TypeError(`Clip ${clip.id} volumeKeyframes entry ${index + 1} must have an increasing time and volume from 0 to 1 within the clip.`);
+    }
+    previousTime = keyframe.time;
+  }
+}
+
+export function sampleAudioVolumeKeyframes(keyframes = [], time) {
+  if (keyframes.length === 0) return 1;
+  if (time <= keyframes[0].time) return keyframes[0].volume;
+  for (let index = 1; index < keyframes.length; index++) {
+    const next = keyframes[index];
+    if (time > next.time) continue;
+    const previous = keyframes[index - 1];
+    const amount = (time - previous.time) / (next.time - previous.time);
+    return previous.volume + (next.volume - previous.volume) * amount;
+  }
+  return keyframes.at(-1).volume;
+}
+
+export function validateAudioTrackVolumeKeyframes(keyframes, track, projectDurationSeconds) {
+  if (keyframes === undefined) return;
+  if (track.kind !== 'audio') throw new TypeError(`Track ${track.id} volumeKeyframes are supported only on audio tracks.`);
+  if (!Array.isArray(keyframes) || keyframes.length === 0 || keyframes.length > 512) {
+    throw new TypeError(`Track ${track.id} volumeKeyframes must be an array with 1 to 512 entries.`);
+  }
+  if (keyframes[0]?.time !== 0) throw new TypeError(`Track ${track.id} volumeKeyframes must start at time 0.`);
+  let previousTime = -1;
+  for (const [index, keyframe] of keyframes.entries()) {
+    if (!keyframe || typeof keyframe !== 'object' || Array.isArray(keyframe)
+        || Object.keys(keyframe).some((field) => !['time', 'volume'].includes(field))
+        || !Number.isFinite(keyframe.time) || keyframe.time < 0 || keyframe.time > projectDurationSeconds
+        || keyframe.time <= previousTime
+        || !Number.isFinite(keyframe.volume) || keyframe.volume < 0 || keyframe.volume > 1) {
+      throw new TypeError(`Track ${track.id} volumeKeyframes entry ${index + 1} must have an increasing project time and volume from 0 to 1.`);
+    }
+    previousTime = keyframe.time;
+  }
+}
+
+export function sliceAudioVolumeKeyframes(keyframes, start, end) {
+  if (!keyframes) return undefined;
+  const sliced = [{ time: 0, volume: sampleAudioVolumeKeyframes(keyframes, start) }];
+  for (const keyframe of keyframes) {
+    if (keyframe.time > start && keyframe.time < end) {
+      sliced.push({ time: keyframe.time - start, volume: keyframe.volume });
+    }
+  }
+  if (end > start) sliced.push({ time: end - start, volume: sampleAudioVolumeKeyframes(keyframes, end) });
+  return sliced;
+}

package/src/timeline/background.mjs

@@ -0,0 +1,8 @@
+export const DEFAULT_PROJECT_BACKGROUND_COLOR = '#10141c';
+
+export function validateProjectBackgroundColor(value, label = 'Project backgroundColor') {
+  if (value !== null && (typeof value !== 'string' || !/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(value))) {
+    throw new TypeError(`${label} must be a 3, 4, 6, or 8 digit hex color, or null for transparent.`);
+  }
+  return value;
+}

package/src/timeline/blend-mode.mjs

@@ -0,0 +1,34 @@
+const BLEND_MODES = new Set([
+  'normal',
+  'multiply',
+  'screen',
+  'overlay',
+  'darken',
+  'lighten',
+  'color-dodge',
+  'color-burn',
+  'hard-light',
+  'soft-light',
+  'difference',
+  'exclusion',
+  'hue',
+  'saturation',
+  'color',
+  'luminosity',
+]);
+
+export function validateBlendMode(clip, trackKind) {
+  if (clip.blendMode === undefined) return;
+  if (trackKind !== 'video' && trackKind !== 'overlay') {
+    throw new TypeError(`Clip ${clip.id} blendMode is supported only on video and overlay tracks.`);
+  }
+  if (typeof clip.blendMode !== 'string' || !BLEND_MODES.has(clip.blendMode)) {
+    throw new TypeError(`Clip ${clip.id} blendMode must be one of: ${[...BLEND_MODES].join(', ')}.`);
+  }
+}
+
+export function blendModeStyle(clip) {
+  return clip.blendMode && clip.blendMode !== 'normal'
+    ? `mix-blend-mode:${clip.blendMode};`
+    : '';
+}

package/src/timeline/caption-layouts.mjs

@@ -0,0 +1,61 @@
+const SOCIAL_LAYOUT = {
+  x: 0.08, y: 0.68, width: 0.84, height: 0.24, fontSize: 64,
+  fontWeight: 800, lineHeight: 1.05, verticalAlign: 'bottom', paddingPixels: 14,
+  wordWrap: true,
+  textShadow: { color: '#000000cc', blurPixels: 6, offsetXPixels: 0, offsetYPixels: 3 },
+  color: '#ffffff', backgroundColor: '#00000000', textAlign: 'center',
+};
+
+const LAYOUTS = {
+  subtitle: {
+    x: 0.08, y: 0.76, width: 0.84, height: 0.16, fontSize: 54,
+    fontWeight: 600, verticalAlign: 'bottom', paddingPixels: 12, wordWrap: true,
+    textShadow: { color: '#000000b8', blurPixels: 4, offsetXPixels: 0, offsetYPixels: 2 },
+    color: '#ffffff', backgroundColor: '#000000b8', textAlign: 'center',
+  },
+  social: SOCIAL_LAYOUT,
+  socialPop: {
+    ...SOCIAL_LAYOUT,
+    wordHighlight: true, wordHighlightColor: '#ffe45c', wordHighlightAnimation: 'pop',
+  },
+  socialStack: {
+    ...SOCIAL_LAYOUT,
+    y: 0.64, height: 0.3, fontSize: 58, lineHeight: 1.02,
+    wordsPerCaption: 6, wordsPerLine: 3,
+    wordHighlight: true, wordHighlightColor: '#ffe45c', wordHighlightAnimation: 'pop',
+  },
+  speechBubble: {
+    x: 0.32, y: 0.66, width: 0.62, height: 0.1, fontSize: 44,
+    fontWeight: 600, lineHeight: 1.12, verticalAlign: 'center', paddingPixels: 22,
+    wordWrap: true, wordsPerCaption: 6, wordsPerLine: 3,
+    wordHighlight: true, wordHighlightColor: '#426BEB', wordHighlightAnimation: 'scale',
+    color: '#172236', backgroundColor: '#ffffff', textAlign: 'left',
+    textShadow: { color: '#17223622', blurPixels: 10, offsetXPixels: 0, offsetYPixels: 4 },
+    bubble: { tailSide: 'bottom', tailPosition: 0.16, tailSizePixels: 26, cornerRadiusPixels: 28 },
+  },
+  lowerThird: {
+    x: 0.08, y: 0.72, width: 0.76, height: 0.18, fontSize: 48,
+    fontWeight: 600, verticalAlign: 'bottom', paddingPixels: 12, wordWrap: true,
+    textShadow: { color: '#000000b8', blurPixels: 3, offsetXPixels: 0, offsetYPixels: 2 },
+    color: '#ffffff', backgroundColor: '#000000b8', textAlign: 'left',
+  },
+};
+
+export const CAPTION_LAYOUT_PRESETS = Object.freeze(Object.fromEntries(
+  Object.entries(LAYOUTS).map(([name, layout]) => [name, Object.freeze({
+    ...layout,
+    ...(layout.textOutline ? { textOutline: Object.freeze({ ...layout.textOutline }) } : {}),
+    ...(layout.textShadow ? { textShadow: Object.freeze({ ...layout.textShadow }) } : {}),
+  })]),
+));
+
+export function listCaptionLayoutPresets() {
+  return Object.keys(CAPTION_LAYOUT_PRESETS);
+}
+
+export function resolveCaptionLayoutPreset(name = 'subtitle') {
+  if (typeof name !== 'string' || !Object.hasOwn(CAPTION_LAYOUT_PRESETS, name)) {
+    throw new TypeError(`Unknown caption layout preset: ${name}`);
+  }
+  return structuredClone(CAPTION_LAYOUT_PRESETS[name]);
+}

package/src/timeline/captions.mjs

@@ -0,0 +1,80 @@
+import { validateTranscript } from '../transcript/validate.mjs';
+import { resolveCaptionLayoutPreset } from './caption-layouts.mjs';
+import { resolveSpeechBubble } from './speech-bubble.mjs';
+
+export function createCaptionTrack(transcript, options = {}) {
+  validateTranscript(transcript);
+  const layout = resolveCaptionLayoutPreset(options.layoutPreset);
+  const wordHighlight = options.wordHighlight ?? layout.wordHighlight ?? false;
+  if (typeof wordHighlight !== 'boolean') throw new TypeError('wordHighlight must be a boolean.');
+  if (wordHighlight && transcript.granularity === 'cue') throw new TypeError('Word highlighting requires word-level transcript timing.');
+  const wordHighlightColor = options.wordHighlightColor ?? layout.wordHighlightColor ?? '#ffe45c';
+  if (typeof wordHighlightColor !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(wordHighlightColor)) {
+    throw new TypeError('wordHighlightColor must be a hex color.');
+  }
+  if (!wordHighlight && options.wordHighlightColor !== undefined) throw new TypeError('wordHighlightColor requires wordHighlight: true.');
+  const wordHighlightAnimation = options.wordHighlightAnimation ?? layout.wordHighlightAnimation ?? 'scale';
+  if (!['scale', 'pop'].includes(wordHighlightAnimation)) throw new TypeError('wordHighlightAnimation must be scale or pop.');
+  if (!wordHighlight && options.wordHighlightAnimation !== undefined) throw new TypeError('wordHighlightAnimation requires wordHighlight: true.');
+  const wordsPerCaption = options.wordsPerCaption ?? layout.wordsPerCaption ?? 6;
+  if (!Number.isSafeInteger(wordsPerCaption) || wordsPerCaption < 1 || wordsPerCaption > 20) throw new TypeError('wordsPerCaption must be an integer from 1 to 20.');
+  const wordsPerLine = options.wordsPerLine ?? layout.wordsPerLine;
+  if (wordsPerLine !== undefined && (!Number.isSafeInteger(wordsPerLine) || wordsPerLine < 1 || wordsPerLine > 20)) {
+    throw new TypeError('wordsPerLine must be an integer from 1 to 20.');
+  }
+  const wordWrap = options.wordWrap ?? layout.wordWrap ?? false;
+  if (typeof wordWrap !== 'boolean') throw new TypeError('wordWrap must be a boolean.');
+  const maxGapSeconds = options.maxGapSeconds ?? 0.8;
+  if (!Number.isFinite(maxGapSeconds) || maxGapSeconds < 0) throw new TypeError('maxGapSeconds must be a non-negative number.');
+  const bubbleSource = options.bubble ?? layout.bubble;
+  const bubble = bubbleSource === undefined ? undefined : resolveSpeechBubble(bubbleSource, layout.bubble);
+
+  const groups = [];
+  let group = [];
+  for (const word of transcript.words) {
+    if (group.length && (group.length >= wordsPerCaption || word.start - group.at(-1).end > maxGapSeconds || /[.!?]$/.test(group.at(-1).text))) {
+      groups.push(group);
+      group = [];
+    }
+    group.push(word);
+  }
+  if (group.length) groups.push(group);
+
+  const clips = groups.map((words, index) => ({
+    id: `caption-${String(index + 1).padStart(3, '0')}`,
+    timelineStart: words[0].start,
+    durationSeconds: words.at(-1).end - words[0].start,
+    text: words.map(({ text }) => text).join(' '),
+    ...(wordsPerLine !== undefined ? { wordsPerLine } : {}),
+    ...(wordHighlight ? {
+      wordTimings: words.map((word) => ({
+        text: word.text,
+        start: word.start - words[0].start,
+        end: word.end - words[0].start,
+      })),
+      wordHighlightColor,
+      wordHighlightAnimation,
+    } : {}),
+    x: options.x ?? layout.x,
+    y: options.y ?? layout.y,
+    width: options.width ?? layout.width,
+    height: options.height ?? layout.height,
+    fontSize: options.fontSize ?? layout.fontSize,
+    ...(options.fontFamily !== undefined ? { fontFamily: options.fontFamily } : {}),
+    fontWeight: options.fontWeight ?? layout.fontWeight,
+    ...(options.lineHeight !== undefined || layout.lineHeight !== undefined ? { lineHeight: options.lineHeight ?? layout.lineHeight } : {}),
+    verticalAlign: options.verticalAlign ?? layout.verticalAlign,
+    wordWrap,
+    paddingPixels: options.paddingPixels ?? layout.paddingPixels,
+    textOutline: options.textOutline ?? layout.textOutline,
+    textShadow: options.textShadow ?? layout.textShadow,
+    color: options.color ?? layout.color,
+    backgroundColor: options.backgroundColor ?? layout.backgroundColor,
+    textAlign: options.textAlign ?? layout.textAlign,
+    ...(bubble === undefined ? {} : { bubble: structuredClone(bubble) }),
+    ...(options.fadeInSeconds ? { fadeInSeconds: options.fadeInSeconds } : {}),
+    ...(options.fadeOutSeconds ? { fadeOutSeconds: options.fadeOutSeconds } : {}),
+  }));
+
+  return { id: options.trackId ?? 'captions', kind: 'overlay', order: options.order ?? 100, clips };
+}