@dantea/opencut 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/dist/commands.d.ts +9 -1
  2. package/dist/commands.js +32 -5
  3. package/dist/index.js +1 -0
  4. package/dist/inspection.js +5 -0
  5. package/dist/mix-options.d.ts +59 -0
  6. package/dist/mix-options.js +23 -0
  7. package/dist/system-probe +0 -0
  8. package/dist/video.d.ts +1 -1
  9. package/dist/video.js +28 -3
  10. package/docs/AUDIO_MIX.md +132 -0
  11. package/docs/CLI.md +46 -6
  12. package/docs/INSTALL.md +13 -8
  13. package/docs/SDK.md +14 -3
  14. package/docs/VIDEO_DEFINITIONS.md +17 -8
  15. package/node_modules/@opencut/core/dist/index.d.ts +1 -0
  16. package/node_modules/@opencut/core/dist/index.js +1 -0
  17. package/node_modules/@opencut/core/dist/inspection.d.ts +115 -0
  18. package/node_modules/@opencut/core/dist/professional-mix.d.ts +129 -0
  19. package/node_modules/@opencut/core/dist/professional-mix.js +70 -0
  20. package/node_modules/@opencut/core/dist/project.d.ts +68 -0
  21. package/node_modules/@opencut/core/dist/project.js +15 -0
  22. package/node_modules/@opencut/core/dist/render-plan.d.ts +5 -1
  23. package/node_modules/@opencut/core/dist/render-plan.js +11 -4
  24. package/node_modules/@opencut/core/dist/render-sources.d.ts +4 -0
  25. package/node_modules/@opencut/core/dist/timeline-view.d.ts +1 -0
  26. package/node_modules/@opencut/core/dist/video-audio-mix.d.ts +25 -0
  27. package/node_modules/@opencut/core/dist/video-audio-mix.js +36 -0
  28. package/node_modules/@opencut/core/dist/video-build.js +2 -2
  29. package/node_modules/@opencut/core/dist/video-compiler.d.ts +3 -0
  30. package/node_modules/@opencut/core/dist/video-compiler.js +20 -1
  31. package/node_modules/@opencut/core/dist/video-definition.d.ts +121 -0
  32. package/node_modules/@opencut/core/dist/video-definition.js +6 -1
  33. package/node_modules/@opencut/core/dist/video-files.d.ts +55 -0
  34. package/node_modules/@opencut/core/dist/video-media-cache.d.ts +15 -0
  35. package/node_modules/@opencut/core/dist/{video-recipe-cache.js → video-media-cache.js} +7 -7
  36. package/node_modules/@opencut/core/dist/video-package-format.d.ts +53 -0
  37. package/node_modules/@opencut/core/dist/video-picture-cache.d.ts +3 -0
  38. package/node_modules/@opencut/core/dist/video-picture-cache.js +29 -0
  39. package/node_modules/@opencut/core/dist/video-preview.d.ts +56 -1
  40. package/node_modules/@opencut/core/dist/video-preview.js +7 -2
  41. package/node_modules/@opencut/core/dist/video-processing.js +2 -2
  42. package/node_modules/@opencut/core/dist/video-render.d.ts +14 -4
  43. package/node_modules/@opencut/core/dist/video-render.js +21 -3
  44. package/node_modules/@opencut/core/dist/video-watch.d.ts +5 -0
  45. package/node_modules/@opencut/core/dist/video-watch.js +18 -2
  46. package/node_modules/@opencut/core/dist/video.d.ts +5 -0
  47. package/node_modules/@opencut/core/dist/video.js +2 -0
  48. package/node_modules/@opencut/core/package.json +3 -3
  49. package/node_modules/@opencut/media/dist/audio-graph.d.ts +88 -0
  50. package/node_modules/@opencut/media/dist/audio-graph.js +292 -0
  51. package/node_modules/@opencut/media/dist/audio-mastering.d.ts +29 -0
  52. package/node_modules/@opencut/media/dist/audio-mastering.js +205 -0
  53. package/node_modules/@opencut/media/dist/deepfilter.d.ts +4 -0
  54. package/node_modules/@opencut/media/dist/deepfilter.js +76 -0
  55. package/node_modules/@opencut/media/dist/dialogue-analysis.d.ts +32 -0
  56. package/node_modules/@opencut/media/dist/dialogue-analysis.js +214 -0
  57. package/node_modules/@opencut/media/dist/enhance.js +11 -3
  58. package/node_modules/@opencut/media/dist/index.d.ts +4 -1
  59. package/node_modules/@opencut/media/dist/index.js +1 -1
  60. package/node_modules/@opencut/media/dist/picture-cache.d.ts +39 -0
  61. package/node_modules/@opencut/media/dist/picture-cache.js +169 -0
  62. package/node_modules/@opencut/media/dist/picture-seek.d.ts +4 -0
  63. package/node_modules/@opencut/media/dist/picture-seek.js +77 -0
  64. package/node_modules/@opencut/media/dist/process-memory +0 -0
  65. package/node_modules/@opencut/media/dist/process.d.ts +2 -1
  66. package/node_modules/@opencut/media/dist/process.js +13 -4
  67. package/node_modules/@opencut/media/dist/professional-mix.d.ts +34 -0
  68. package/node_modules/@opencut/media/dist/professional-mix.js +411 -0
  69. package/node_modules/@opencut/media/dist/render-budget.d.ts +1 -1
  70. package/node_modules/@opencut/media/dist/render-budget.js +7 -5
  71. package/node_modules/@opencut/media/dist/render.d.ts +33 -47
  72. package/node_modules/@opencut/media/dist/render.js +273 -333
  73. package/node_modules/@opencut/media/dist/transform-layer.d.ts +7 -1
  74. package/node_modules/@opencut/media/dist/transform-layer.js +32 -2
  75. package/node_modules/@opencut/media/dist/video-enhance +0 -0
  76. package/node_modules/@opencut/media/dist/video-filter.d.ts +2 -0
  77. package/node_modules/@opencut/media/dist/video-filter.js +4 -0
  78. package/node_modules/@opencut/media/dist/video-interpolate +0 -0
  79. package/node_modules/@opencut/media/package.json +2 -2
  80. package/node_modules/@opencut/sdk/dist/index.d.ts +2 -2
  81. package/node_modules/@opencut/sdk/dist/index.js +1 -1
  82. package/node_modules/@opencut/sdk/package.json +3 -3
  83. package/node_modules/@opencut/shared/dist/index.d.ts +1 -0
  84. package/node_modules/@opencut/shared/dist/index.js +1 -0
  85. package/node_modules/@opencut/shared/dist/professional-mix.d.ts +98 -0
  86. package/node_modules/@opencut/shared/dist/professional-mix.js +30 -0
  87. package/node_modules/@opencut/shared/package.json +1 -1
  88. package/package.json +5 -5
  89. package/skills/video-editor/SKILL.md +13 -1
  90. package/skills/video-editor/references/cli.md +14 -0
  91. package/skills/video-editor/references/sdk.md +9 -0
  92. package/skills/video-editor/references/video-definitions.md +7 -3
  93. package/node_modules/@opencut/core/dist/video-recipe-cache.d.ts +0 -16
@@ -1,16 +1,20 @@
1
+ import { prepareProfessionalMix } from './professional-mix.js';
2
+ import { audioSampleAtFrame, buildAudioGraph } from './audio-graph.js';
1
3
  import { decodeStillFrame } from './frame.js';
2
- import { canvasColorPattern, opaqueCanvasColor, visualGeometry, sourceColorMatrix, usesLayerTransform, maximumVisualScale, roomEchoes, } from '@opencut/shared';
4
+ import { canvasColorPattern, opaqueCanvasColor, visualGeometry, sourceColorMatrix, usesLayerTransform, maximumVisualScale, } from '@opencut/shared';
3
5
  import { access, link, lstat, mkdtemp, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
4
6
  import { constants } from 'node:fs';
5
7
  import { dirname, extname, join, resolve } from 'node:path';
6
- import { probeMedia, isStillImage, videoSourceDuration, audioSourceDuration, } from './probe.js';
8
+ import { probeMedia, isStillImage, videoSourceDuration } from './probe.js';
7
9
  import { checkRenderSignal, MediaError, runMediaTool } from './process.js';
8
10
  import { accountRenderBytes, accountRenderFile } from './render-budget.js';
9
11
  import { renderQualities, renderQualityProfiles } from '@opencut/shared';
10
12
  import { renderProgress } from './render-progress.js';
11
- import { fitVisual } from './video-filter.js';
13
+ import { fitVisual, indexedSeekArgs } from './video-filter.js';
14
+ import { pictureSeekCheck } from './picture-seek.js';
12
15
  import { stageTransformLayer } from './transform-layer.js';
13
16
  import { rasterizeTextLayer } from './text.js';
17
+ import { cachePicture } from './picture-cache.js';
14
18
  export const renderResolutions = ['project', '720p', '1080p'];
15
19
  export const renderCodecs = ['h264', 'hevc'];
16
20
  function validateOptions(options) {
@@ -53,7 +57,7 @@ function validateOptions(options) {
53
57
  clip.frameCount <= 0 ||
54
58
  (clip.retiming !== undefined &&
55
59
  (!validRetiming(clip.retiming) ||
56
- !Number.isInteger(clip.retiming.sourceOriginNs))) ||
60
+ !validSourceOrigin(clip.retiming))) ||
57
61
  !Number.isSafeInteger(clip.sourceStartFrame + clip.frameCount) ||
58
62
  !Number.isSafeInteger(clip.timelineStartFrame + clip.frameCount) ||
59
63
  clip.timelineStartFrame + clip.frameCount > frameCount ||
@@ -92,27 +96,6 @@ function validateOptions(options) {
92
96
  !validAudioFades(clip, numerator, denominator)))
93
97
  throw new MediaError('Invalid video render plan: use positive integer frame counts, even sides up to 3840 (at most 3840x2160 pixels), 1–120 fps, at most 64 non-subtitle visual/audio clips (or 128 legacy segments), valid transforms and #RRGGBB[AA]/transparent background, and 600 seconds.');
94
98
  }
95
- function gainExpression(keys) {
96
- const first = keys[0];
97
- const intervals = [{ end: first.sample, value: String(first.value) }];
98
- for (let i = 1; i < keys.length; i++) {
99
- const left = keys[i - 1];
100
- const right = keys[i];
101
- if (right.sample > left.sample)
102
- intervals.push({
103
- end: right.sample,
104
- value: `${left.value}+(${right.value}-${left.value})*(n-${left.sample})/${right.sample - left.sample}`,
105
- });
106
- }
107
- intervals.push({ end: Infinity, value: String(keys.at(-1).value) });
108
- function build(start, end) {
109
- if (end - start === 1)
110
- return intervals[start].value;
111
- const middle = Math.floor((start + end) / 2);
112
- return `if(lt(n,${intervals[middle - 1].end}),${build(start, middle)},${build(middle, end)})`;
113
- }
114
- return build(0, intervals.length);
115
- }
116
99
  function validRational(time) {
117
100
  return (!!time &&
118
101
  Number.isSafeInteger(time.numerator) &&
@@ -127,6 +110,11 @@ function timeDifference(a, b) {
127
110
  return (BigInt(a.numerator) * BigInt(b.denominator) -
128
111
  BigInt(b.numerator) * BigInt(a.denominator));
129
112
  }
113
+ function validSourceOrigin(retiming) {
114
+ return (Number.isInteger(retiming.sourceOriginNs) &&
115
+ (retiming.localSourceOriginNs === undefined ||
116
+ Number.isInteger(retiming.localSourceOriginNs)));
117
+ }
130
118
  function validRetiming(timing) {
131
119
  return (!!timing &&
132
120
  [
@@ -189,8 +177,39 @@ export function validateSubtitleBurnIn(clips) {
189
177
  throw new MediaError(`Burn-in supports up to ${maxBurnedSubtitleCues} visible subtitle cues per render. Shorten the render range or export a sidecar.`);
190
178
  }
191
179
  }
180
+ async function existingOutput(path) {
181
+ return lstat(path).catch((error) => {
182
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
183
+ return null;
184
+ throw error;
185
+ });
186
+ }
187
+ async function protectSourceFiles(options, destination) {
188
+ if (!options.overwrite || !destination)
189
+ return;
190
+ const paths = new Set();
191
+ for (const clip of options.visualClips ?? options.segments ?? [])
192
+ if ('path' in clip && clip.path)
193
+ paths.add(clip.path);
194
+ for (const transition of options.visualTransitions ?? [])
195
+ for (const layer of transition.layers)
196
+ paths.add(layer.path);
197
+ for (const clip of options.audioClips ?? [])
198
+ paths.add(clip.path);
199
+ for (const path of paths) {
200
+ checkRenderSignal(options.signal);
201
+ const source = await stat(path).catch((error) => {
202
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
203
+ return null;
204
+ throw error;
205
+ });
206
+ if (source?.dev === destination.dev && source.ino === destination.ino)
207
+ throw new MediaError(`Render output must not replace source media '${path}'.`);
208
+ }
209
+ }
192
210
  /** Prepare filters and stage unique held frames when executing a render. */
193
- async function prepareTimeline(options, png = false, scratch) {
211
+ async function prepareTimeline(options, mode = 'mp4', scratch, checkPictureSeek) {
212
+ const png = mode === 'png';
194
213
  checkRenderSignal(options.signal);
195
214
  validateOptions(options);
196
215
  const codec = options.codec ?? 'h264';
@@ -255,7 +274,8 @@ async function prepareTimeline(options, png = false, scratch) {
255
274
  endFrame > frameCount ||
256
275
  (options.range && options.outputFrameRate))
257
276
  throw new MediaError('Preview range must satisfy 0 <= start < end <= timeline frame count; range and outputFrameRate cannot be combined.');
258
- if (png && endFrame - startFrame !== 1)
277
+ const rangeFrameCount = endFrame - startFrame;
278
+ if (png && rangeFrameCount !== 1)
259
279
  throw new MediaError('PNG rendering requires exactly one project frame.');
260
280
  if (codec === 'hevc' && (outputWidth < 16 || outputHeight < 16))
261
281
  throw new MediaError('HEVC requires output dimensions of at least 16 × 16 pixels.');
@@ -273,7 +293,7 @@ async function prepareTimeline(options, png = false, scratch) {
273
293
  outputRate.numerator < outputRate.denominator ||
274
294
  outputRate.numerator > 120 * outputRate.denominator)
275
295
  throw new MediaError('Output frame rate must be between 1 and 120 fps.');
276
- const ticks = BigInt(endFrame - startFrame) *
296
+ const ticks = BigInt(rangeFrameCount) *
277
297
  BigInt(denominator) *
278
298
  BigInt(outputRate.numerator);
279
299
  const divisor = BigInt(numerator) * BigInt(outputRate.denominator);
@@ -282,15 +302,10 @@ async function prepareTimeline(options, png = false, scratch) {
282
302
  const path = resolve(options.output);
283
303
  if (extname(path).toLowerCase() !== (png ? '.png' : '.mp4'))
284
304
  throw new MediaError(`Render output must have a ${png ? '.png' : '.mp4'} extension.`);
285
- try {
286
- const existing = await lstat(path);
287
- if (!options.overwrite || !existing.isFile())
288
- throw new MediaError(`Refusing to overwrite existing output '${path}'. Use --overwrite for a regular file.`);
289
- }
290
- catch (error) {
291
- if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
292
- throw error;
293
- }
305
+ const existing = await existingOutput(path);
306
+ if (existing && (!options.overwrite || !existing.isFile()))
307
+ throw new MediaError(`Refusing to overwrite existing output '${path}'. Use --overwrite for a regular file.`);
308
+ await protectSourceFiles(options, existing);
294
309
  try {
295
310
  if (!(await stat(dirname(path))).isDirectory())
296
311
  throw new Error('Not a directory');
@@ -331,6 +346,8 @@ async function prepareTimeline(options, png = false, scratch) {
331
346
  warnings,
332
347
  stagedInputs,
333
348
  encoders,
349
+ pictureRanges: undefined,
350
+ audioMix: undefined,
334
351
  };
335
352
  const filters = [];
336
353
  const sources = new Map(options.sourceMetadata);
@@ -338,22 +355,6 @@ async function prepareTimeline(options, png = false, scratch) {
338
355
  const inputs = new Map();
339
356
  const readSource = async (clip) => {
340
357
  checkRenderSignal(options.signal);
341
- if (options.overwrite) {
342
- // Never let explicit replacement target any source, including aliases.
343
- const existing = await stat(path).catch((error) => {
344
- if (error instanceof Error &&
345
- 'code' in error &&
346
- error.code === 'ENOENT')
347
- return null;
348
- throw error;
349
- });
350
- const original = await stat(clip.path).catch(() => null);
351
- if (existing &&
352
- original &&
353
- existing.dev === original.dev &&
354
- existing.ino === original.ino)
355
- throw new MediaError(`Render output must not replace source media '${clip.path}'.`);
356
- }
357
358
  let source = sources.get(clip.path);
358
359
  if (!source) {
359
360
  try {
@@ -367,14 +368,6 @@ async function prepareTimeline(options, png = false, scratch) {
367
368
  }
368
369
  return source;
369
370
  };
370
- let input = 0;
371
- const registerInput = (filename, write) => {
372
- const argumentIndex = args.push('-threads', '1', '-i', filename) - 1;
373
- stagedInputs.push({ filename, argumentIndex, write });
374
- return input++;
375
- };
376
- filters.push(`color=c=${opaqueCanvasColor(options.backgroundColor ?? '#000000')}:s=${width}x${height}:r=${rate},` +
377
- `format=rgba,trim=end_frame=${frameCount},settb=1/${numerator},setpts=N*${denominator}[canvas0]`);
378
371
  const transitions = options.visualTransitions ?? [];
379
372
  const byOwner = new Map();
380
373
  const windows = new Map();
@@ -396,7 +389,7 @@ async function prepareTimeline(options, png = false, scratch) {
396
389
  transition.layers.some((layer) => !visualClips.some(({ clipId }) => clipId === layer.clipId) ||
397
390
  !layer.retiming ||
398
391
  !validRetiming(layer.retiming) ||
399
- !Number.isInteger(layer.retiming.sourceOriginNs) ||
392
+ !validSourceOrigin(layer.retiming) ||
400
393
  layer.timelineStartFrame !== ramp.startFrame ||
401
394
  layer.frameCount !== ramp.endFrame - ramp.startFrame ||
402
395
  layer.ramp.startFrame !== ramp.startFrame ||
@@ -412,19 +405,39 @@ async function prepareTimeline(options, png = false, scratch) {
412
405
  windows.set(layer.clipId, ranges);
413
406
  }
414
407
  }
408
+ let input = 0;
409
+ const registerInput = (filename, write) => {
410
+ const argumentIndex = args.push('-threads', '1', '-i', filename) - 1;
411
+ stagedInputs.push({ filename, argumentIndex, write });
412
+ return input++;
413
+ };
415
414
  const overlapsRange = (clip) => clip.timelineStartFrame < endFrame &&
416
415
  clip.timelineStartFrame + clip.frameCount > startFrame;
417
416
  const visibleClips = visualClips.filter((clip) => !clip.subtitle || overlapsRange(clip));
418
417
  validateSubtitleBurnIn(visibleClips);
418
+ const pictureCache = mode === 'mp4' && scratch ? options.pictureCache : undefined;
419
+ if (options.pictureCache)
420
+ encoders.add('ffv1');
421
+ if (!pictureCache)
422
+ filters.push(`color=c=${opaqueCanvasColor(options.backgroundColor ?? '#000000')}:s=${width}x${height}:r=${rate},` +
423
+ `format=rgba,trim=end_frame=${rangeFrameCount},settb=1/${numerator},setpts=(N+${startFrame})*${denominator}[canvas0]`);
419
424
  const heldFrames = new Map();
420
425
  const framesync = 'eof_action=pass:repeatlast=0';
426
+ const holdLastFrame = 'repeatlast=1';
427
+ const transformsLayer = (clip) => !!(clip.grade || clip.crop) ||
428
+ usesLayerTransform(clip.rotation, !!clip.animation);
429
+ const rasterize = (clip, transformed = transformsLayer(clip)) => (options.rasterizeText ?? rasterizeTextLayer)(width, height, clip.text, clip, options.signal, transformed);
421
430
  const prepareLayer = async (clip, label, scratchName, ramp) => {
422
- const transformed = Boolean(ramp || clip.grade || clip.crop) ||
423
- usesLayerTransform(clip.rotation, !!clip.animation);
431
+ const transformed = !!ramp || transformsLayer(clip);
424
432
  const first = Math.max(startFrame, clip.timelineStartFrame);
425
433
  const last = Math.min(endFrame, clip.timelineStartFrame + clip.frameCount);
434
+ // Direct callers also validate off-range clips. Keep their full source
435
+ // window for preflight, even though the overlay gate excludes them.
436
+ const inRange = first < last;
437
+ const layerStart = inRange ? first : clip.timelineStartFrame;
438
+ const layerFrames = inRange ? last - first : clip.frameCount;
426
439
  const transform = (source) => {
427
- if (first >= last)
440
+ if (!inRange)
428
441
  return;
429
442
  encoders.add('ffv1');
430
443
  const hold = !clip.animation && (source.kind === 'text' || !source.sampling);
@@ -433,8 +446,8 @@ async function prepareTimeline(options, png = false, scratch) {
433
446
  width,
434
447
  height,
435
448
  rate: frameRate,
436
- startFrame: first,
437
- frameCount: hold ? 1 : last - first,
449
+ startFrame: layerStart,
450
+ frameCount: hold ? 1 : layerFrames,
438
451
  visual: clip,
439
452
  ...(clip.grade && { grade: clip.grade }),
440
453
  source,
@@ -444,14 +457,12 @@ async function prepareTimeline(options, png = false, scratch) {
444
457
  }, destination);
445
458
  await accountRenderFile(destination);
446
459
  });
447
- filters.push(`[${layerInput}:v]format=rgba,settb=1/${numerator},setpts=(N+${first})*${denominator}[${label}]`);
448
- return { x: 0, y: 0, sync: hold ? 'repeatlast=1' : framesync };
460
+ filters.push(`[${layerInput}:v]format=rgba,settb=1/${numerator},setpts=(N+${layerStart})*${denominator}[${label}]`);
461
+ return { x: 0, y: 0, sync: hold ? holdLastFrame : framesync };
449
462
  };
450
463
  if (clip.text) {
451
- const text = clip.text;
452
- const rasterize = () => (options.rasterizeText ?? rasterizeTextLayer)(width, height, text, clip, options.signal, transformed);
453
464
  checkRenderSignal(options.signal);
454
- const { x, y, png, warning } = await rasterize();
465
+ const { x, y, png, warning } = await rasterize(clip, transformed);
455
466
  checkRenderSignal(options.signal);
456
467
  if (warning)
457
468
  warnings.push(`Clip '${clip.clipId}': ${warning}`);
@@ -459,7 +470,7 @@ async function prepareTimeline(options, png = false, scratch) {
459
470
  return;
460
471
  // Let the text raster cache own the bytes between preparation and staging.
461
472
  const readRaster = async () => {
462
- const { png } = await rasterize();
473
+ const { png } = await rasterize(clip, transformed);
463
474
  if (!png)
464
475
  throw new MediaError(`Clip '${clip.clipId}' lost its text raster during export.`);
465
476
  return png;
@@ -476,7 +487,7 @@ async function prepareTimeline(options, png = false, scratch) {
476
487
  });
477
488
  // Hold the static image from time zero and gate it to the clip interval.
478
489
  filters.push(`[${textInput}:v]format=rgba,settb=1/${numerator},setpts=0[${label}]`);
479
- return { x, y, sync: 'repeatlast=1' };
490
+ return { x, y, sync: holdLastFrame };
480
491
  }
481
492
  const source = await readSource(clip);
482
493
  const { video } = source;
@@ -543,45 +554,50 @@ async function prepareTimeline(options, png = false, scratch) {
543
554
  duration <= 0 ||
544
555
  sourceOutSeconds > duration + 0.000001))
545
556
  throw new MediaError(`Clip '${clip.clipId}' source out exceeds the current video duration or its duration is unknown. Re-import the media and trim to a known video range.`);
546
- // Sample before trimming so source selection is invariant under splitting.
547
- // A source frame first covers the project tick at or after its PTS.
548
- // Rounding down or to nearest can show a frame before its presentation time.
557
+ const clipOffset = layerStart - clip.timelineStartFrame;
558
+ const sourceFirst = clip.sourceStartFrame + clipOffset;
549
559
  const { retiming } = clip;
550
- const seekTarget = clip.sourceStartFrame + first - clip.timelineStartFrame;
551
- // Indexed, zero-origin MOV/MP4 still previews can decode from the preceding
552
- // keyframe. Keep its native PTS, including pre-roll frames before the seek,
553
- // so the same frame covers the requested project tick even on VFR input.
554
- const seekFrame = png &&
560
+ // Keep preroll timestamps so indexed and sequential decoding sample the
561
+ // same source frame even across variable-frame-rate gaps.
562
+ const candidateSeekFrame = (png || transformed || checkPictureSeek) &&
555
563
  !still &&
556
- !transformed &&
557
564
  !retiming &&
558
- first < last &&
565
+ inRange &&
559
566
  source.startTimeSeconds === 0 &&
560
567
  video.startTimeSeconds === 0 &&
561
568
  /\.(mp4|mov)$/i.test(source.path)
562
- ? Math.max(0, seekTarget - Math.ceil((2 * numerator) / denominator))
569
+ ? Math.max(0, sourceFirst - Math.ceil((2 * numerator) / denominator))
563
570
  : 0;
564
- const seekSeconds = (seekFrame * denominator) / numerator;
565
- // An fps start_time shifts the source and output grids independently.
566
- // A seek preserves absolute PTS, so let fps start at the decoded keyframe.
567
- const frameSampling = `fps=${rate}${seekFrame ? '' : ':start_time=0'}:round=${retiming ? 'near' : 'up'}:eof_action=pass,tpad=stop_mode=clone:stop=1,`;
568
- // Pick an absolute project frame before shifting to this piece's local clock.
569
- // Two source ns cover PTS rounding and truncation of the shared source origin.
570
- const frameNs = `(1000000000*${denominator}/${numerator})`;
571
- const sampling = still
572
- ? `loop=loop=-1:size=1:start=0,trim=end_frame=${clip.frameCount}`
573
- : retiming
574
- ? 'setpts=PTS-STARTPTS,settb=1/1000000000,' +
575
- `setpts=(ceil((PTS-(${retiming.sourceOriginNs})-2)*${retiming.speed.denominator}/${retiming.speed.numerator}/${frameNs})-${clip.timelineStartFrame})*${frameNs},` +
576
- frameSampling +
577
- `trim=end_frame=${clip.frameCount}`
578
- : seekFrame
579
- ? frameSampling +
580
- `trim=start_pts=${seekTarget}:end_pts=${seekTarget + last - first}`
581
- : 'setpts=PTS-STARTPTS,' +
582
- frameSampling +
583
- `trim=start_frame=${clip.sourceStartFrame}:end_frame=${sourceEnd}`;
584
571
  const inputPath = held?.path ?? (await inputPathFor(source.path));
572
+ const seekSeconds = (candidateSeekFrame * denominator) / numerator;
573
+ const useIndexedSeek = candidateSeekFrame > 0 &&
574
+ (!checkPictureSeek ||
575
+ (await checkPictureSeek(inputPath, stream, seekSeconds, sourceFirst, frameRate)));
576
+ const frameSampling = (indexed = false) => `fps=${rate}${indexed ? '' : ':start_time=0'}:round=${retiming ? 'near' : 'up'}:eof_action=pass,tpad=stop_mode=clone:stop=1`;
577
+ const sequentialSampling = `setpts=PTS-STARTPTS,${frameSampling()},trim=start_frame=${sourceFirst}:end_frame=${sourceFirst + layerFrames}`;
578
+ let sampling;
579
+ if (still) {
580
+ sampling = 'trim=end_frame=1';
581
+ }
582
+ else if (retiming) {
583
+ // Sample on the project grid before trimming. Two nanoseconds cover
584
+ // PTS rounding and truncation of the shared source origin.
585
+ const frameNs = `(1000000000*${denominator}/${numerator})`;
586
+ const origin = retiming.localSourceOriginNs ?? retiming.sourceOriginNs;
587
+ const start = retiming.localSourceOriginNs === undefined
588
+ ? clip.timelineStartFrame
589
+ : 0;
590
+ sampling =
591
+ 'setpts=PTS-STARTPTS,settb=1/1000000000,' +
592
+ `setpts=(ceil((PTS-(${origin})-2)*${retiming.speed.denominator}/${retiming.speed.numerator}/${frameNs})-${start})*${frameNs},` +
593
+ `${frameSampling()},trim=start_frame=${clipOffset}:end_frame=${clipOffset + layerFrames}`;
594
+ }
595
+ else if (useIndexedSeek) {
596
+ sampling = `${frameSampling(true)},trim=start_pts=${sourceFirst}:end_pts=${sourceFirst + layerFrames}`;
597
+ }
598
+ else {
599
+ sampling = sequentialSampling;
600
+ }
585
601
  if (transformed) {
586
602
  return transform({
587
603
  kind: 'media',
@@ -594,35 +610,43 @@ async function prepareTimeline(options, png = false, scratch) {
594
610
  : displayWidth / displayHeight,
595
611
  matrix,
596
612
  ...(!still && {
597
- sampling: `${sampling},trim=start_frame=${first - clip.timelineStartFrame}:end_frame=${last - clip.timelineStartFrame}`,
613
+ sampling: {
614
+ filter: sampling,
615
+ ...(useIndexedSeek && {
616
+ seek: {
617
+ seconds: seekSeconds,
618
+ fallbackFilter: sequentialSampling,
619
+ },
620
+ }),
621
+ },
598
622
  }),
599
623
  });
600
624
  }
601
625
  const geometry = visualGeometry(width, height, rotated ? displayHeight : displayWidth, rotated ? displayWidth : displayHeight, clip);
602
- if (seekFrame && !args.includes('-copyts'))
626
+ if (useIndexedSeek && !args.includes('-copyts'))
603
627
  args.push('-copyts');
604
- args.push('-threads', '1', ...(seekFrame ? ['-ss', seekSeconds.toFixed(6), '-noaccurate_seek'] : []), '-i', inputPath);
628
+ args.push('-threads', '1', ...(useIndexedSeek ? indexedSeekArgs(seekSeconds) : []), '-i', inputPath);
605
629
  if (!held)
606
630
  inputs.set(clip.clipId, input);
607
- // Preserve sampling on the project grid, then crop the time range before
608
- // scaling or converting frames that the preview will never show.
609
- const ranged = !!options.range && first < last;
610
- const rangeTrim = ranged && !seekFrame
611
- ? `trim=start_frame=${first - clip.timelineStartFrame}:end_frame=${last - clip.timelineStartFrame},`
612
- : '';
613
- filters.push(`[${input++}:${stream}]${sampling},${rangeTrim}` +
631
+ filters.push(`[${input++}:${stream}]${sampling},` +
614
632
  `${fitVisual(geometry, matrix)},format=rgba,` +
615
633
  ((clip.opacity ?? 1) === 1 ? '' : `lut=a=val*${clip.opacity},`) +
616
- `settb=1/${numerator},setpts=(N+${ranged ? first : clip.timelineStartFrame})*${denominator}[${label}]`);
617
- return { x: geometry.x, y: geometry.y, sync: framesync };
634
+ `settb=1/${numerator},setpts=(N+${layerStart})*${denominator}[${label}]`);
635
+ // A fitted still has identical pixels throughout its gated interval.
636
+ return {
637
+ x: geometry.x,
638
+ y: geometry.y,
639
+ sync: still ? holdLastFrame : framesync,
640
+ };
618
641
  };
619
- const enabled = (start, end) => `gte(n,${start})*lt(n,${end})`;
642
+ // Overlay counts from zero while its input timestamps use project time.
643
+ const enabled = (start, end) => `gte(n,${start - startFrame})*lt(n,${end - startFrame})`;
620
644
  let canvas = 0;
621
645
  const overlay = (label, { x, y, sync }, gate) => {
622
646
  filters.push(`[canvas${canvas}][${label}]overlay=x=${x}:y=${y}:${sync}:format=rgb:alpha=straight:enable='${gate}'[canvas${canvas + 1}]`);
623
647
  canvas++;
624
648
  };
625
- for (const [index, clip] of visibleClips.entries()) {
649
+ for (const [index, clip] of (pictureCache ? [] : visibleClips).entries()) {
626
650
  const label = `layer${index}`;
627
651
  // A transition can contribute even when its owner's base clip is off-range.
628
652
  const placement = !options.snapshotSource || overlapsRange(clip)
@@ -656,218 +680,102 @@ async function prepareTimeline(options, png = false, scratch) {
656
680
  overlay(group, { x: 0, y: 0, sync: framesync }, gate);
657
681
  }
658
682
  }
659
- filters.push(`[canvas${canvas}]trim=start_frame=${startFrame}:end_frame=${endFrame},settb=1/${numerator},setpts=N*${denominator},scale=${outputWidth}:${outputHeight}:out_color_matrix=bt709,setsar=1,` +
683
+ let picture = `[canvas${canvas}]settb=1/${numerator},setpts=N*${denominator},scale=${outputWidth}:${outputHeight}:out_color_matrix=bt709,setsar=1`;
684
+ if (pictureCache) {
685
+ const checkSeek = pictureSeekCheck(options.signal);
686
+ const { concat, ranges } = await cachePicture({
687
+ options,
688
+ cache: pictureCache,
689
+ visualClips,
690
+ byOwner,
691
+ startFrame,
692
+ endFrame,
693
+ outputWidth,
694
+ outputHeight,
695
+ warnings,
696
+ rasterize,
697
+ encode: async (startFrame, endFrame, destination) => {
698
+ const staging = renderScratch(options.output, '.opencut-picture-', options.scratchDirectory);
699
+ try {
700
+ const segment = await prepareTimeline({
701
+ ...options,
702
+ range: { startFrame, endFrame },
703
+ outputFrameRate: undefined,
704
+ }, 'picture', staging, checkSeek);
705
+ await staging.stage(segment, options.signal);
706
+ await runMediaTool('ffmpeg', [...segment.args, destination], 4 * 1024 * 1024, 600_000, {
707
+ signal: options.signal,
708
+ writesFile: true,
709
+ });
710
+ }
711
+ finally {
712
+ await staging.close();
713
+ }
714
+ },
715
+ });
716
+ prepared.pictureRanges = ranges;
717
+ args.push('-f', 'concat', '-safe', '0', '-protocol_whitelist', 'file');
718
+ const pictureInput = registerInput('picture.ffconcat', (destination) => writeFile(destination, concat, {
719
+ flag: 'wx',
720
+ signal: options.signal,
721
+ }));
722
+ // Concat transports pictures in order. Regenerate their timestamps on the
723
+ // project grid so container time bases and range boundaries cannot accrue drift.
724
+ picture = `[${pictureInput}:v]settb=1/${numerator},setpts=N*${denominator},setsar=1`;
725
+ }
726
+ filters.push(picture +
727
+ ',' +
660
728
  (options.outputFrameRate
661
729
  ? `fps=${outputRate.numerator}/${outputRate.denominator}:round=up:eof_action=pass,tpad=stop_mode=clone:stop=1,trim=end_frame=${outputFrameCount},settb=1/${outputRate.numerator},setpts=N*${outputRate.denominator},`
662
730
  : '') +
663
731
  (png
664
732
  ? 'format=rgb24[video]'
665
733
  : 'format=yuv420p,setparams=range=tv:colorspace=bt709:color_primaries=bt709:color_trc=bt709[video]'));
666
- if (png) {
667
- args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]', '-an', '-frames:v', '1', '-c:v', 'png', '-threads', '1', '-f', 'image2');
734
+ if (mode !== 'mp4') {
735
+ args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]');
736
+ if (png)
737
+ args.push('-an', '-frames:v', '1', '-c:v', 'png', '-threads', '1', '-f', 'image2');
738
+ else
739
+ args.push('-map_metadata', '-1', '-an', '-c:v', 'ffv1', '-level', '3', '-threads', '2', '-fps_mode', 'passthrough', '-enc_time_base:v', `1/${numerator}`, '-f', 'nut');
668
740
  return prepared;
669
741
  }
670
- // Round absolute project boundaries to the nearest 48 kHz sample. Never sum
671
- // independently rounded durations: fractional frame rates must not accumulate drift.
672
- const sample = (frame, rate = frameRate, offset, sign = 1n) => {
673
- const scale = BigInt(offset?.denominator ?? 1);
674
- const divisor = BigInt(rate.numerator) * scale;
675
- const n = (BigInt(frame) * BigInt(rate.denominator) * scale +
676
- sign * BigInt(offset?.numerator ?? 0) * BigInt(rate.numerator)) *
677
- 48000n;
678
- return Number((2n * n + divisor) / (2n * divisor));
679
- };
680
- const sampleTime = (time, offset, sign = 1n) => sample(time.numerator, { numerator: time.denominator, denominator: 1 }, offset, sign);
681
- const totalSamples = options.range
682
- ? sample(frameCount)
683
- : sample(outputFrameCount, outputRate);
684
- const audioLabels = ['[silence]'];
685
- filters.push(`anullsrc=r=48000:cl=stereo,atrim=end_sample=${totalSamples},asettb=1/48000,asetpts=N[silence]`);
686
- const timelineSample = (clip, edge, fade) => {
687
- const sign = edge === 'start' ? 1n : -1n;
688
- if (clip.retiming) {
689
- const time = edge === 'start'
690
- ? clip.retiming.timelineStart
691
- : clip.retiming.timelineEnd;
692
- return sampleTime(time, fade, sign);
693
- }
694
- const frame = clip.timelineStartFrame + (edge === 'start' ? 0 : clip.frameCount);
695
- return sample(frame, frameRate, fade, sign);
696
- };
697
- const effectChain = (clip, count) => {
698
- const filters = [];
699
- const linear = (db) => 10 ** (db / 20);
700
- for (const effect of clip.effects ?? []) {
701
- switch (effect.type) {
702
- case 'eq':
703
- filters.push(`equalizer=f=${effect.frequency}:width_type=q:w=1:g=${effect.db}`);
704
- break;
705
- case 'compressor':
706
- filters.push(`acompressor=threshold=${linear(effect.threshold)}:ratio=${effect.ratio}:attack=5:release=100`);
707
- break;
708
- case 'limiter':
709
- filters.push(`alimiter=limit=${linear(effect.ceiling)}:level=0:latency=1`);
710
- break;
711
- case 'de-esser':
712
- if (effect.amount)
713
- filters.push(`deesser=i=${effect.amount}:m=0.5:f=0.5`);
714
- break;
715
- case 'reverb':
716
- if (effect.mix)
717
- filters.push(`aecho=1:1:${roomEchoes.map((echo) => echo.seconds * 1000).join('|')}:${roomEchoes.map((echo) => echo.gain * effect.mix).join('|')}`, `atrim=end_sample=${count}`);
718
- break;
719
- }
720
- }
721
- return filters.length ? filters.join(',') + ',' : '';
722
- };
723
- const envelope = (clip, start, end) => {
724
- const filters = [];
725
- if (clip.fadeIn) {
726
- const length = timelineSample(clip, 'start', clip.fadeIn.duration) - start;
727
- if (length > 0)
728
- filters.push(`afade=t=in:ss=0:ns=${length}:c=tri:silence=${clip.fadeIn.from}:unity=${clip.fadeIn.to}`);
729
- }
730
- if (clip.fadeOut) {
731
- const release = timelineSample(clip, 'end', clip.fadeOut.duration);
732
- if (end > release)
733
- filters.push(`afade=t=out:ss=${release - start}:ns=${end - release}:c=tri:silence=${clip.fadeOut.to}:unity=${clip.fadeOut.from}`);
734
- }
735
- filters.push(`volume=${clip.muted ? 0 : clip.volume}`);
736
- if (clip.gainKeys?.length) {
737
- const keys = clip.gainKeys.map(({ time, value }) => ({
738
- sample: timelineSample(clip, 'start', time) - start,
739
- value,
740
- }));
741
- const expression = gainExpression(keys);
742
- filters.push(`aeval='val(0)*${expression}|val(1)*${expression}':c=stereo`);
743
- }
744
- return filters.join(',');
745
- };
746
- const runs = [];
747
- for (const clip of options.audioClips ?? []) {
748
- const run = runs.at(-1);
749
- const previous = run?.at(-1);
750
- if (run &&
751
- previous?.retiming &&
752
- clip.retiming &&
753
- clip.tempoRunId !== undefined &&
754
- clip.tempoRunId === previous.tempoRunId &&
755
- clip.path === previous.path &&
756
- clip.required === previous.required &&
757
- clip.padAudio === previous.padAudio &&
758
- JSON.stringify(clip.effects ?? []) ===
759
- JSON.stringify(previous.effects ?? []) &&
760
- timeDifference(previous.retiming.timelineEnd, clip.retiming.timelineStart) === 0n &&
761
- timeDifference(previous.retiming.sourceOut, clip.retiming.sourceIn) ===
762
- 0n &&
763
- timeDifference(previous.retiming.speed, clip.retiming.speed) === 0n)
764
- run.push(clip);
765
- else
766
- runs.push([clip]);
742
+ const from = audioSampleAtFrame(startFrame, frameRate);
743
+ const to = options.range
744
+ ? from + audioSampleAtFrame(outputFrameCount, outputRate)
745
+ : audioSampleAtFrame(outputFrameCount, outputRate);
746
+ const mix = options.professionalMix;
747
+ let audioMap = '[audio]';
748
+ if (mix && mix.enabled !== false && scratch) {
749
+ const result = await prepareProfessionalMix(options, mix, await scratch.open(), readSource, {
750
+ base: audioSampleAtFrame(frameCount, frameRate),
751
+ from,
752
+ to,
753
+ });
754
+ prepared.audioMix = result.report;
755
+ warnings.push(...result.report.warnings);
756
+ args.push('-i', result.path);
757
+ audioMap = `${input++}:a:0`;
767
758
  }
768
- for (const [index, run] of runs.entries()) {
769
- const first = run[0];
770
- const last = run.at(-1);
771
- const source = await readSource(first);
772
- const { audio, video } = source;
773
- if (!audio) {
774
- if (first.required)
775
- throw new MediaError(`Clip '${first.clipId}' requires an audio stream. Re-import or relink the audio asset.`);
776
- continue;
777
- }
778
- const origin = video?.startTimeSeconds ??
779
- audio.startTimeSeconds ??
780
- source.startTimeSeconds ??
781
- 0;
782
- const offset = (audio.startTimeSeconds ?? origin) - origin;
783
- const duration = audioSourceDuration(source);
784
- if (last.required &&
785
- !last.padAudio &&
786
- (duration === null ||
787
- (last.retiming
788
- ? seconds(last.retiming.sourceOut)
789
- : ((last.sourceStartFrame + last.frameCount) * denominator) /
790
- numerator) >
791
- duration + 0.000001))
792
- throw new MediaError(`Clip '${last.clipId}' source out exceeds the current audio duration or its duration is unknown. Re-import the media and trim to a known audio range.`);
793
- const pieces = run
794
- .map((clip) => ({
795
- clip,
796
- start: timelineSample(clip, 'start'),
797
- end: timelineSample(clip, 'end'),
798
- }))
799
- .filter(({ start, end }) => end > start);
800
- if (!pieces.some(({ clip }) => !clip.muted && clip.volume > 0))
801
- continue;
802
- const start = pieces[0].start;
803
- const count = pieces.at(-1).end - start;
804
- const sourceStart = first.retiming
805
- ? sampleTime(first.retiming.sourceIn)
806
- : sample(first.sourceStartFrame);
807
- const sourceEnd = last.retiming
808
- ? sampleTime(last.retiming.sourceOut)
809
- : sourceStart + count;
810
- if (sourceEnd <= sourceStart)
811
- continue;
812
- let audioInput = inputs.get(first.clipId);
813
- if (audioInput === undefined) {
814
- audioInput = input++;
815
- args.push('-threads', '1', '-i', await inputPathFor(source.path));
816
- }
817
- const speed = first.retiming ? seconds(first.retiming.speed) : 1;
818
- // Keep one tempo filter across contiguous pieces. Only the run tail needs
819
- // padding to drain the tempo window, and each atempo pass stays within 0.5–2.
820
- const tempo = speed === 1
821
- ? ''
822
- : 'apad=pad_len=4800,' +
823
- (speed < 0.5
824
- ? `atempo=0.5,atempo=${speed * 2},`
825
- : speed > 2
826
- ? `atempo=2,atempo=${speed / 2},`
827
- : `atempo=${speed},`);
828
- const fitDuration = first.retiming
829
- ? `apad,atrim=end_sample=${count},asettb=1/48000,asetpts=N,`
830
- : '';
831
- const inputFilter = `[${audioInput}:${audio.index}]asetpts=PTS-STARTPTS+(${offset.toFixed(9)})/TB,` +
832
- 'aresample=48000:async=1:min_hard_comp=0:first_pts=0,aformat=sample_fmts=fltp:channel_layouts=stereo,' +
833
- `apad,atrim=start_sample=${sourceStart}:end_sample=${sourceEnd},asettb=1/48000,asetpts=N,` +
834
- tempo +
835
- fitDuration +
836
- effectChain(first, count);
837
- const delay = `adelay=${start}S:all=1[a${index}]`;
838
- if (pieces.length === 1) {
839
- const piece = pieces[0];
840
- filters.push(inputFilter +
841
- envelope(piece.clip, piece.start, piece.end) +
842
- ',' +
843
- delay);
844
- }
845
- else {
846
- // Route each sample to its piece once, apply that piece's envelope, then
847
- // join on the sample clock before mixing with other tracks.
848
- const labels = pieces.map((_, i) => `[run${index}p${i}]`);
849
- const boundaries = pieces.slice(1).map((piece) => piece.start - start);
850
- filters.push(inputFilter +
851
- `asegment=samples=${boundaries.join('|')}` +
852
- labels.join(''));
853
- const adjusted = pieces.map((piece, i) => {
854
- const label = `[run${index}g${i}]`;
855
- filters.push(labels[i] +
856
- 'asettb=1/48000,asetpts=N,' +
857
- envelope(piece.clip, piece.start, piece.end) +
858
- label);
859
- return label;
860
- });
861
- filters.push(adjusted.join('') +
862
- `concat=n=${pieces.length}:v=0:a=1,asettb=1/48000,asetpts=N,` +
863
- delay);
864
- }
865
- audioLabels.push(`[a${index}]`);
759
+ else {
760
+ await buildAudioGraph(options, {
761
+ filters,
762
+ readSource,
763
+ inputPathFor,
764
+ openInput: (clip, path) => {
765
+ const existing = inputs.get(clip.clipId);
766
+ if (existing !== undefined)
767
+ return existing;
768
+ args.push('-threads', '1', '-i', path);
769
+ return input++;
770
+ },
771
+ }, {
772
+ total: options.range
773
+ ? audioSampleAtFrame(frameCount, frameRate)
774
+ : audioSampleAtFrame(outputFrameCount, outputRate),
775
+ from,
776
+ to: options.range ? audioSampleAtFrame(endFrame, frameRate) : to,
777
+ });
866
778
  }
867
- // Stable linear gains, independent of the number of active sources. Match the
868
- // existing composer limiter, including latency compensation for sync markers.
869
- filters.push(`${audioLabels.join('')}amix=inputs=${audioLabels.length}:duration=first:normalize=0,` +
870
- `alimiter=limit=0.95:level=0:latency=1,atrim=start_sample=${sample(startFrame)}:end_sample=${options.range ? sample(endFrame) : totalSamples},asettb=1/48000,asetpts=N[audio]`);
871
779
  checkRenderSignal(options.signal);
872
780
  const metadataInput = options.buildMetadata === undefined ? -1 : input;
873
781
  if (options.buildMetadata !== undefined) {
@@ -887,14 +795,25 @@ async function prepareTimeline(options, png = false, scratch) {
887
795
  },
888
796
  });
889
797
  }
890
- args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]', '-map', '[audio]', '-map_metadata', String(metadataInput), '-c:v', codec === 'h264' ? 'libx264' : 'libx265', '-preset', encoding.preset, ...(videoBitrateKbps === undefined
798
+ args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]', '-map', audioMap, '-map_metadata', String(metadataInput), '-c:v', codec === 'h264' ? 'libx264' : 'libx265', '-preset', encoding.preset, ...(videoBitrateKbps === undefined
891
799
  ? ['-crf', encoding.crf]
892
800
  : ['-b:v', `${videoBitrateKbps}k`]), ...(codec === 'hevc'
893
801
  ? ['-x265-params', 'pools=2:log-level=error', '-tag:v', 'hvc1']
894
- : []), '-pix_fmt', 'yuv420p', '-threads', '2', '-fps_mode', 'passthrough', '-enc_time_base:v', `1/${outputRate.numerator}`, '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-video_track_timescale', String(outputRate.numerator), '-c:a', 'aac', '-b:a', `${audioBitrateKbps}k`, '-ar', String(audioSampleRate), '-ac', String(audioChannels), '-movflags', metadataInput < 0 ? '+faststart' : '+faststart+use_metadata_tags', '-f', 'mp4');
802
+ : []), '-pix_fmt', 'yuv420p', '-threads', '2', '-fps_mode', 'passthrough', '-enc_time_base:v', `1/${outputRate.numerator}`, '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-video_track_timescale', String(outputRate.numerator), ...(prepared.audioMix
803
+ ? ['-c:a', 'copy']
804
+ : [
805
+ '-c:a',
806
+ 'aac',
807
+ '-b:a',
808
+ `${audioBitrateKbps}k`,
809
+ '-ar',
810
+ String(audioSampleRate),
811
+ '-ac',
812
+ String(audioChannels),
813
+ ]), '-movflags', metadataInput < 0 ? '+faststart' : '+faststart+use_metadata_tags', '-f', 'mp4');
895
814
  return prepared;
896
815
  }
897
- /** Full preflight uses the exact same plan, media probes and filters as execution. */
816
+ /** Validate the composition and required encoders without populating the picture cache. */
898
817
  export async function validateVideoTimeline(options) {
899
818
  const prepared = await prepareTimeline(options);
900
819
  const encoders = (await runMediaTool('ffmpeg', ['-hide_banner', '-v', 'error', '-encoders'], 4 * 1024 * 1024, 60_000, { signal: options.signal })).toString('utf8');
@@ -949,7 +868,7 @@ function renderScratch(output, prefix, directory = dirname(resolve(output))) {
949
868
  export async function renderVideoTimeline(options) {
950
869
  const scratch = renderScratch(options.output, '.opencut-render-', options.scratchDirectory);
951
870
  try {
952
- const prepared = await prepareTimeline(options, false, scratch);
871
+ const prepared = await prepareTimeline(options, 'mp4', scratch);
953
872
  await scratch.stage(prepared, options.signal);
954
873
  const { args, path, quality, resolution, codec, outputWidth, outputHeight, frameRate, frameCount, durationSeconds, warnings, } = prepared;
955
874
  const { numerator, denominator } = frameRate;
@@ -1005,15 +924,10 @@ export async function renderVideoTimeline(options) {
1005
924
  checkRenderSignal(options.signal);
1006
925
  try {
1007
926
  if (options.overwrite) {
1008
- const destination = await lstat(path).catch((error) => {
1009
- if (error instanceof Error &&
1010
- 'code' in error &&
1011
- error.code === 'ENOENT')
1012
- return null;
1013
- throw error;
1014
- });
927
+ const destination = await existingOutput(path);
1015
928
  if (destination && !destination.isFile())
1016
929
  throw new MediaError(`Refusing to overwrite non-regular output '${path}'.`);
930
+ await protectSourceFiles(options, destination);
1017
931
  checkRenderSignal(options.signal);
1018
932
  // Same-filesystem rename replaces a complete file atomically.
1019
933
  await rename(rendered, path);
@@ -1040,17 +954,43 @@ export async function renderVideoTimeline(options) {
1040
954
  durationSeconds,
1041
955
  metadata: { ...metadata, path },
1042
956
  ...(warnings.length ? { warnings } : {}),
957
+ ...(prepared.pictureRanges && { pictureRanges: prepared.pictureRanges }),
958
+ ...(prepared.audioMix && { audioMix: prepared.audioMix }),
1043
959
  };
1044
960
  }
1045
961
  finally {
1046
962
  await scratch.close();
1047
963
  }
1048
964
  }
965
+ /** Analyze and verify a mix without composing or encoding picture. */
966
+ export async function analyzeTimelineAudioMix(options) {
967
+ validateOptions(options);
968
+ const mix = options.professionalMix;
969
+ if (!mix || mix.enabled === false)
970
+ throw new MediaError('Enable Professional Dialogue Mix before analyzing.');
971
+ const scratch = renderScratch(options.output, '.opencut-mix-', options.scratchDirectory);
972
+ try {
973
+ const base = audioSampleAtFrame(options.frameCount, options.frameRate);
974
+ const sources = new Map(options.sourceMetadata);
975
+ const result = await prepareProfessionalMix(options, mix, await scratch.open(), async ({ path }) => {
976
+ let metadata = sources.get(path);
977
+ if (!metadata) {
978
+ metadata = await probeMedia(path, options.signal);
979
+ sources.set(path, metadata);
980
+ }
981
+ return metadata;
982
+ }, { base, from: 0, to: base });
983
+ return result.report;
984
+ }
985
+ finally {
986
+ await scratch.close();
987
+ }
988
+ }
1049
989
  /** Lossless frame output from the same RGB compositor used by video exports. */
1050
990
  export async function renderTimelineFrame(options) {
1051
991
  const scratch = renderScratch(options.output, '.opencut-frame-');
1052
992
  try {
1053
- const prepared = await prepareTimeline(options, true, scratch);
993
+ const prepared = await prepareTimeline(options, 'png', scratch);
1054
994
  await scratch.stage(prepared, options.signal);
1055
995
  const rendered = join(await scratch.open(), 'frame.png');
1056
996
  await runMediaTool('ffmpeg', [...prepared.args, '-update', '1', rendered], 4 * 1024 * 1024, 600_000, { signal: options.signal });