@dantea/opencut 0.1.0 → 0.1.3

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 (44) hide show
  1. package/dist/commands.d.ts +1 -0
  2. package/dist/commands.js +3 -1
  3. package/dist/system-probe +0 -0
  4. package/dist/video.js +7 -0
  5. package/docs/CLI.md +40 -6
  6. package/docs/INSTALL.md +13 -8
  7. package/docs/SDK.md +10 -3
  8. package/docs/VIDEO_DEFINITIONS.md +13 -8
  9. package/node_modules/@opencut/core/dist/render-plan.d.ts +1 -0
  10. package/node_modules/@opencut/core/dist/render-plan.js +5 -4
  11. package/node_modules/@opencut/core/dist/render-sources.d.ts +1 -0
  12. package/node_modules/@opencut/core/dist/video-build.js +2 -2
  13. package/node_modules/@opencut/core/dist/video-media-cache.d.ts +15 -0
  14. package/node_modules/@opencut/core/dist/{video-recipe-cache.js → video-media-cache.js} +7 -7
  15. package/node_modules/@opencut/core/dist/video-picture-cache.d.ts +3 -0
  16. package/node_modules/@opencut/core/dist/video-picture-cache.js +29 -0
  17. package/node_modules/@opencut/core/dist/video-processing.js +2 -2
  18. package/node_modules/@opencut/core/dist/video-render.d.ts +4 -1
  19. package/node_modules/@opencut/core/dist/video-render.js +6 -1
  20. package/node_modules/@opencut/core/package.json +3 -3
  21. package/node_modules/@opencut/media/dist/enhance.js +11 -3
  22. package/node_modules/@opencut/media/dist/index.d.ts +1 -0
  23. package/node_modules/@opencut/media/dist/picture-cache.d.ts +39 -0
  24. package/node_modules/@opencut/media/dist/picture-cache.js +169 -0
  25. package/node_modules/@opencut/media/dist/picture-seek.d.ts +4 -0
  26. package/node_modules/@opencut/media/dist/picture-seek.js +77 -0
  27. package/node_modules/@opencut/media/dist/process-memory +0 -0
  28. package/node_modules/@opencut/media/dist/render.d.ts +5 -1
  29. package/node_modules/@opencut/media/dist/render.js +195 -109
  30. package/node_modules/@opencut/media/dist/transform-layer.d.ts +7 -1
  31. package/node_modules/@opencut/media/dist/transform-layer.js +32 -2
  32. package/node_modules/@opencut/media/dist/video-enhance +0 -0
  33. package/node_modules/@opencut/media/dist/video-filter.d.ts +2 -0
  34. package/node_modules/@opencut/media/dist/video-filter.js +4 -0
  35. package/node_modules/@opencut/media/dist/video-interpolate +0 -0
  36. package/node_modules/@opencut/media/package.json +2 -2
  37. package/node_modules/@opencut/sdk/package.json +3 -3
  38. package/node_modules/@opencut/shared/package.json +1 -1
  39. package/package.json +5 -5
  40. package/skills/video-editor/SKILL.md +7 -1
  41. package/skills/video-editor/references/cli.md +7 -0
  42. package/skills/video-editor/references/sdk.md +5 -0
  43. package/skills/video-editor/references/video-definitions.md +7 -3
  44. package/node_modules/@opencut/core/dist/video-recipe-cache.d.ts +0 -16
@@ -8,9 +8,11 @@ import { checkRenderSignal, MediaError, runMediaTool } from './process.js';
8
8
  import { accountRenderBytes, accountRenderFile } from './render-budget.js';
9
9
  import { renderQualities, renderQualityProfiles } from '@opencut/shared';
10
10
  import { renderProgress } from './render-progress.js';
11
- import { fitVisual } from './video-filter.js';
11
+ import { fitVisual, indexedSeekArgs } from './video-filter.js';
12
+ import { pictureSeekCheck } from './picture-seek.js';
12
13
  import { stageTransformLayer } from './transform-layer.js';
13
14
  import { rasterizeTextLayer } from './text.js';
15
+ import { cachePicture } from './picture-cache.js';
14
16
  export const renderResolutions = ['project', '720p', '1080p'];
15
17
  export const renderCodecs = ['h264', 'hevc'];
16
18
  function validateOptions(options) {
@@ -53,7 +55,7 @@ function validateOptions(options) {
53
55
  clip.frameCount <= 0 ||
54
56
  (clip.retiming !== undefined &&
55
57
  (!validRetiming(clip.retiming) ||
56
- !Number.isInteger(clip.retiming.sourceOriginNs))) ||
58
+ !validSourceOrigin(clip.retiming))) ||
57
59
  !Number.isSafeInteger(clip.sourceStartFrame + clip.frameCount) ||
58
60
  !Number.isSafeInteger(clip.timelineStartFrame + clip.frameCount) ||
59
61
  clip.timelineStartFrame + clip.frameCount > frameCount ||
@@ -127,6 +129,11 @@ function timeDifference(a, b) {
127
129
  return (BigInt(a.numerator) * BigInt(b.denominator) -
128
130
  BigInt(b.numerator) * BigInt(a.denominator));
129
131
  }
132
+ function validSourceOrigin(retiming) {
133
+ return (Number.isInteger(retiming.sourceOriginNs) &&
134
+ (retiming.localSourceOriginNs === undefined ||
135
+ Number.isInteger(retiming.localSourceOriginNs)));
136
+ }
130
137
  function validRetiming(timing) {
131
138
  return (!!timing &&
132
139
  [
@@ -189,8 +196,39 @@ export function validateSubtitleBurnIn(clips) {
189
196
  throw new MediaError(`Burn-in supports up to ${maxBurnedSubtitleCues} visible subtitle cues per render. Shorten the render range or export a sidecar.`);
190
197
  }
191
198
  }
199
+ async function existingOutput(path) {
200
+ return lstat(path).catch((error) => {
201
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
202
+ return null;
203
+ throw error;
204
+ });
205
+ }
206
+ async function protectSourceFiles(options, destination) {
207
+ if (!options.overwrite || !destination)
208
+ return;
209
+ const paths = new Set();
210
+ for (const clip of options.visualClips ?? options.segments ?? [])
211
+ if ('path' in clip && clip.path)
212
+ paths.add(clip.path);
213
+ for (const transition of options.visualTransitions ?? [])
214
+ for (const layer of transition.layers)
215
+ paths.add(layer.path);
216
+ for (const clip of options.audioClips ?? [])
217
+ paths.add(clip.path);
218
+ for (const path of paths) {
219
+ checkRenderSignal(options.signal);
220
+ const source = await stat(path).catch((error) => {
221
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
222
+ return null;
223
+ throw error;
224
+ });
225
+ if (source?.dev === destination.dev && source.ino === destination.ino)
226
+ throw new MediaError(`Render output must not replace source media '${path}'.`);
227
+ }
228
+ }
192
229
  /** Prepare filters and stage unique held frames when executing a render. */
193
- async function prepareTimeline(options, png = false, scratch) {
230
+ async function prepareTimeline(options, mode = 'mp4', scratch, checkPictureSeek) {
231
+ const png = mode === 'png';
194
232
  checkRenderSignal(options.signal);
195
233
  validateOptions(options);
196
234
  const codec = options.codec ?? 'h264';
@@ -255,7 +293,8 @@ async function prepareTimeline(options, png = false, scratch) {
255
293
  endFrame > frameCount ||
256
294
  (options.range && options.outputFrameRate))
257
295
  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)
296
+ const rangeFrameCount = endFrame - startFrame;
297
+ if (png && rangeFrameCount !== 1)
259
298
  throw new MediaError('PNG rendering requires exactly one project frame.');
260
299
  if (codec === 'hevc' && (outputWidth < 16 || outputHeight < 16))
261
300
  throw new MediaError('HEVC requires output dimensions of at least 16 × 16 pixels.');
@@ -273,7 +312,7 @@ async function prepareTimeline(options, png = false, scratch) {
273
312
  outputRate.numerator < outputRate.denominator ||
274
313
  outputRate.numerator > 120 * outputRate.denominator)
275
314
  throw new MediaError('Output frame rate must be between 1 and 120 fps.');
276
- const ticks = BigInt(endFrame - startFrame) *
315
+ const ticks = BigInt(rangeFrameCount) *
277
316
  BigInt(denominator) *
278
317
  BigInt(outputRate.numerator);
279
318
  const divisor = BigInt(numerator) * BigInt(outputRate.denominator);
@@ -282,15 +321,10 @@ async function prepareTimeline(options, png = false, scratch) {
282
321
  const path = resolve(options.output);
283
322
  if (extname(path).toLowerCase() !== (png ? '.png' : '.mp4'))
284
323
  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
- }
324
+ const existing = await existingOutput(path);
325
+ if (existing && (!options.overwrite || !existing.isFile()))
326
+ throw new MediaError(`Refusing to overwrite existing output '${path}'. Use --overwrite for a regular file.`);
327
+ await protectSourceFiles(options, existing);
294
328
  try {
295
329
  if (!(await stat(dirname(path))).isDirectory())
296
330
  throw new Error('Not a directory');
@@ -331,6 +365,7 @@ async function prepareTimeline(options, png = false, scratch) {
331
365
  warnings,
332
366
  stagedInputs,
333
367
  encoders,
368
+ pictureRanges: undefined,
334
369
  };
335
370
  const filters = [];
336
371
  const sources = new Map(options.sourceMetadata);
@@ -338,22 +373,6 @@ async function prepareTimeline(options, png = false, scratch) {
338
373
  const inputs = new Map();
339
374
  const readSource = async (clip) => {
340
375
  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
376
  let source = sources.get(clip.path);
358
377
  if (!source) {
359
378
  try {
@@ -367,14 +386,6 @@ async function prepareTimeline(options, png = false, scratch) {
367
386
  }
368
387
  return source;
369
388
  };
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
389
  const transitions = options.visualTransitions ?? [];
379
390
  const byOwner = new Map();
380
391
  const windows = new Map();
@@ -396,7 +407,7 @@ async function prepareTimeline(options, png = false, scratch) {
396
407
  transition.layers.some((layer) => !visualClips.some(({ clipId }) => clipId === layer.clipId) ||
397
408
  !layer.retiming ||
398
409
  !validRetiming(layer.retiming) ||
399
- !Number.isInteger(layer.retiming.sourceOriginNs) ||
410
+ !validSourceOrigin(layer.retiming) ||
400
411
  layer.timelineStartFrame !== ramp.startFrame ||
401
412
  layer.frameCount !== ramp.endFrame - ramp.startFrame ||
402
413
  layer.ramp.startFrame !== ramp.startFrame ||
@@ -412,19 +423,39 @@ async function prepareTimeline(options, png = false, scratch) {
412
423
  windows.set(layer.clipId, ranges);
413
424
  }
414
425
  }
426
+ let input = 0;
427
+ const registerInput = (filename, write) => {
428
+ const argumentIndex = args.push('-threads', '1', '-i', filename) - 1;
429
+ stagedInputs.push({ filename, argumentIndex, write });
430
+ return input++;
431
+ };
415
432
  const overlapsRange = (clip) => clip.timelineStartFrame < endFrame &&
416
433
  clip.timelineStartFrame + clip.frameCount > startFrame;
417
434
  const visibleClips = visualClips.filter((clip) => !clip.subtitle || overlapsRange(clip));
418
435
  validateSubtitleBurnIn(visibleClips);
436
+ const pictureCache = mode === 'mp4' && scratch ? options.pictureCache : undefined;
437
+ if (options.pictureCache)
438
+ encoders.add('ffv1');
439
+ if (!pictureCache)
440
+ filters.push(`color=c=${opaqueCanvasColor(options.backgroundColor ?? '#000000')}:s=${width}x${height}:r=${rate},` +
441
+ `format=rgba,trim=end_frame=${rangeFrameCount},settb=1/${numerator},setpts=(N+${startFrame})*${denominator}[canvas0]`);
419
442
  const heldFrames = new Map();
420
443
  const framesync = 'eof_action=pass:repeatlast=0';
444
+ const holdLastFrame = 'repeatlast=1';
445
+ const transformsLayer = (clip) => !!(clip.grade || clip.crop) ||
446
+ usesLayerTransform(clip.rotation, !!clip.animation);
447
+ const rasterize = (clip, transformed = transformsLayer(clip)) => (options.rasterizeText ?? rasterizeTextLayer)(width, height, clip.text, clip, options.signal, transformed);
421
448
  const prepareLayer = async (clip, label, scratchName, ramp) => {
422
- const transformed = Boolean(ramp || clip.grade || clip.crop) ||
423
- usesLayerTransform(clip.rotation, !!clip.animation);
449
+ const transformed = !!ramp || transformsLayer(clip);
424
450
  const first = Math.max(startFrame, clip.timelineStartFrame);
425
451
  const last = Math.min(endFrame, clip.timelineStartFrame + clip.frameCount);
452
+ // Direct callers also validate off-range clips. Keep their full source
453
+ // window for preflight, even though the overlay gate excludes them.
454
+ const inRange = first < last;
455
+ const layerStart = inRange ? first : clip.timelineStartFrame;
456
+ const layerFrames = inRange ? last - first : clip.frameCount;
426
457
  const transform = (source) => {
427
- if (first >= last)
458
+ if (!inRange)
428
459
  return;
429
460
  encoders.add('ffv1');
430
461
  const hold = !clip.animation && (source.kind === 'text' || !source.sampling);
@@ -433,8 +464,8 @@ async function prepareTimeline(options, png = false, scratch) {
433
464
  width,
434
465
  height,
435
466
  rate: frameRate,
436
- startFrame: first,
437
- frameCount: hold ? 1 : last - first,
467
+ startFrame: layerStart,
468
+ frameCount: hold ? 1 : layerFrames,
438
469
  visual: clip,
439
470
  ...(clip.grade && { grade: clip.grade }),
440
471
  source,
@@ -444,14 +475,12 @@ async function prepareTimeline(options, png = false, scratch) {
444
475
  }, destination);
445
476
  await accountRenderFile(destination);
446
477
  });
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 };
478
+ filters.push(`[${layerInput}:v]format=rgba,settb=1/${numerator},setpts=(N+${layerStart})*${denominator}[${label}]`);
479
+ return { x: 0, y: 0, sync: hold ? holdLastFrame : framesync };
449
480
  };
450
481
  if (clip.text) {
451
- const text = clip.text;
452
- const rasterize = () => (options.rasterizeText ?? rasterizeTextLayer)(width, height, text, clip, options.signal, transformed);
453
482
  checkRenderSignal(options.signal);
454
- const { x, y, png, warning } = await rasterize();
483
+ const { x, y, png, warning } = await rasterize(clip, transformed);
455
484
  checkRenderSignal(options.signal);
456
485
  if (warning)
457
486
  warnings.push(`Clip '${clip.clipId}': ${warning}`);
@@ -459,7 +488,7 @@ async function prepareTimeline(options, png = false, scratch) {
459
488
  return;
460
489
  // Let the text raster cache own the bytes between preparation and staging.
461
490
  const readRaster = async () => {
462
- const { png } = await rasterize();
491
+ const { png } = await rasterize(clip, transformed);
463
492
  if (!png)
464
493
  throw new MediaError(`Clip '${clip.clipId}' lost its text raster during export.`);
465
494
  return png;
@@ -476,7 +505,7 @@ async function prepareTimeline(options, png = false, scratch) {
476
505
  });
477
506
  // Hold the static image from time zero and gate it to the clip interval.
478
507
  filters.push(`[${textInput}:v]format=rgba,settb=1/${numerator},setpts=0[${label}]`);
479
- return { x, y, sync: 'repeatlast=1' };
508
+ return { x, y, sync: holdLastFrame };
480
509
  }
481
510
  const source = await readSource(clip);
482
511
  const { video } = source;
@@ -543,45 +572,50 @@ async function prepareTimeline(options, png = false, scratch) {
543
572
  duration <= 0 ||
544
573
  sourceOutSeconds > duration + 0.000001))
545
574
  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.
575
+ const clipOffset = layerStart - clip.timelineStartFrame;
576
+ const sourceFirst = clip.sourceStartFrame + clipOffset;
549
577
  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 &&
578
+ // Keep preroll timestamps so indexed and sequential decoding sample the
579
+ // same source frame even across variable-frame-rate gaps.
580
+ const candidateSeekFrame = (png || transformed || checkPictureSeek) &&
555
581
  !still &&
556
- !transformed &&
557
582
  !retiming &&
558
- first < last &&
583
+ inRange &&
559
584
  source.startTimeSeconds === 0 &&
560
585
  video.startTimeSeconds === 0 &&
561
586
  /\.(mp4|mov)$/i.test(source.path)
562
- ? Math.max(0, seekTarget - Math.ceil((2 * numerator) / denominator))
587
+ ? Math.max(0, sourceFirst - Math.ceil((2 * numerator) / denominator))
563
588
  : 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
589
  const inputPath = held?.path ?? (await inputPathFor(source.path));
590
+ const seekSeconds = (candidateSeekFrame * denominator) / numerator;
591
+ const useIndexedSeek = candidateSeekFrame > 0 &&
592
+ (!checkPictureSeek ||
593
+ (await checkPictureSeek(inputPath, stream, seekSeconds, sourceFirst, frameRate)));
594
+ const frameSampling = (indexed = false) => `fps=${rate}${indexed ? '' : ':start_time=0'}:round=${retiming ? 'near' : 'up'}:eof_action=pass,tpad=stop_mode=clone:stop=1`;
595
+ const sequentialSampling = `setpts=PTS-STARTPTS,${frameSampling()},trim=start_frame=${sourceFirst}:end_frame=${sourceFirst + layerFrames}`;
596
+ let sampling;
597
+ if (still) {
598
+ sampling = 'trim=end_frame=1';
599
+ }
600
+ else if (retiming) {
601
+ // Sample on the project grid before trimming. Two nanoseconds cover
602
+ // PTS rounding and truncation of the shared source origin.
603
+ const frameNs = `(1000000000*${denominator}/${numerator})`;
604
+ const origin = retiming.localSourceOriginNs ?? retiming.sourceOriginNs;
605
+ const start = retiming.localSourceOriginNs === undefined
606
+ ? clip.timelineStartFrame
607
+ : 0;
608
+ sampling =
609
+ 'setpts=PTS-STARTPTS,settb=1/1000000000,' +
610
+ `setpts=(ceil((PTS-(${origin})-2)*${retiming.speed.denominator}/${retiming.speed.numerator}/${frameNs})-${start})*${frameNs},` +
611
+ `${frameSampling()},trim=start_frame=${clipOffset}:end_frame=${clipOffset + layerFrames}`;
612
+ }
613
+ else if (useIndexedSeek) {
614
+ sampling = `${frameSampling(true)},trim=start_pts=${sourceFirst}:end_pts=${sourceFirst + layerFrames}`;
615
+ }
616
+ else {
617
+ sampling = sequentialSampling;
618
+ }
585
619
  if (transformed) {
586
620
  return transform({
587
621
  kind: 'media',
@@ -594,35 +628,43 @@ async function prepareTimeline(options, png = false, scratch) {
594
628
  : displayWidth / displayHeight,
595
629
  matrix,
596
630
  ...(!still && {
597
- sampling: `${sampling},trim=start_frame=${first - clip.timelineStartFrame}:end_frame=${last - clip.timelineStartFrame}`,
631
+ sampling: {
632
+ filter: sampling,
633
+ ...(useIndexedSeek && {
634
+ seek: {
635
+ seconds: seekSeconds,
636
+ fallbackFilter: sequentialSampling,
637
+ },
638
+ }),
639
+ },
598
640
  }),
599
641
  });
600
642
  }
601
643
  const geometry = visualGeometry(width, height, rotated ? displayHeight : displayWidth, rotated ? displayWidth : displayHeight, clip);
602
- if (seekFrame && !args.includes('-copyts'))
644
+ if (useIndexedSeek && !args.includes('-copyts'))
603
645
  args.push('-copyts');
604
- args.push('-threads', '1', ...(seekFrame ? ['-ss', seekSeconds.toFixed(6), '-noaccurate_seek'] : []), '-i', inputPath);
646
+ args.push('-threads', '1', ...(useIndexedSeek ? indexedSeekArgs(seekSeconds) : []), '-i', inputPath);
605
647
  if (!held)
606
648
  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}` +
649
+ filters.push(`[${input++}:${stream}]${sampling},` +
614
650
  `${fitVisual(geometry, matrix)},format=rgba,` +
615
651
  ((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 };
652
+ `settb=1/${numerator},setpts=(N+${layerStart})*${denominator}[${label}]`);
653
+ // A fitted still has identical pixels throughout its gated interval.
654
+ return {
655
+ x: geometry.x,
656
+ y: geometry.y,
657
+ sync: still ? holdLastFrame : framesync,
658
+ };
618
659
  };
619
- const enabled = (start, end) => `gte(n,${start})*lt(n,${end})`;
660
+ // Overlay counts from zero while its input timestamps use project time.
661
+ const enabled = (start, end) => `gte(n,${start - startFrame})*lt(n,${end - startFrame})`;
620
662
  let canvas = 0;
621
663
  const overlay = (label, { x, y, sync }, gate) => {
622
664
  filters.push(`[canvas${canvas}][${label}]overlay=x=${x}:y=${y}:${sync}:format=rgb:alpha=straight:enable='${gate}'[canvas${canvas + 1}]`);
623
665
  canvas++;
624
666
  };
625
- for (const [index, clip] of visibleClips.entries()) {
667
+ for (const [index, clip] of (pictureCache ? [] : visibleClips).entries()) {
626
668
  const label = `layer${index}`;
627
669
  // A transition can contribute even when its owner's base clip is off-range.
628
670
  const placement = !options.snapshotSource || overlapsRange(clip)
@@ -656,15 +698,63 @@ async function prepareTimeline(options, png = false, scratch) {
656
698
  overlay(group, { x: 0, y: 0, sync: framesync }, gate);
657
699
  }
658
700
  }
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,` +
701
+ let picture = `[canvas${canvas}]settb=1/${numerator},setpts=N*${denominator},scale=${outputWidth}:${outputHeight}:out_color_matrix=bt709,setsar=1`;
702
+ if (pictureCache) {
703
+ const checkSeek = pictureSeekCheck(options.signal);
704
+ const { concat, ranges } = await cachePicture({
705
+ options,
706
+ cache: pictureCache,
707
+ visualClips,
708
+ byOwner,
709
+ startFrame,
710
+ endFrame,
711
+ outputWidth,
712
+ outputHeight,
713
+ warnings,
714
+ rasterize,
715
+ encode: async (startFrame, endFrame, destination) => {
716
+ const staging = renderScratch(options.output, '.opencut-picture-', options.scratchDirectory);
717
+ try {
718
+ const segment = await prepareTimeline({
719
+ ...options,
720
+ range: { startFrame, endFrame },
721
+ outputFrameRate: undefined,
722
+ }, 'picture', staging, checkSeek);
723
+ await staging.stage(segment, options.signal);
724
+ await runMediaTool('ffmpeg', [...segment.args, destination], 4 * 1024 * 1024, 600_000, {
725
+ signal: options.signal,
726
+ writesFile: true,
727
+ });
728
+ }
729
+ finally {
730
+ await staging.close();
731
+ }
732
+ },
733
+ });
734
+ prepared.pictureRanges = ranges;
735
+ args.push('-f', 'concat', '-safe', '0', '-protocol_whitelist', 'file');
736
+ const pictureInput = registerInput('picture.ffconcat', (destination) => writeFile(destination, concat, {
737
+ flag: 'wx',
738
+ signal: options.signal,
739
+ }));
740
+ // Concat transports pictures in order. Regenerate their timestamps on the
741
+ // project grid so container time bases and range boundaries cannot accrue drift.
742
+ picture = `[${pictureInput}:v]settb=1/${numerator},setpts=N*${denominator},setsar=1`;
743
+ }
744
+ filters.push(picture +
745
+ ',' +
660
746
  (options.outputFrameRate
661
747
  ? `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
748
  : '') +
663
749
  (png
664
750
  ? 'format=rgb24[video]'
665
751
  : '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');
752
+ if (mode !== 'mp4') {
753
+ args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]');
754
+ if (png)
755
+ args.push('-an', '-frames:v', '1', '-c:v', 'png', '-threads', '1', '-f', 'image2');
756
+ else
757
+ 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
758
  return prepared;
669
759
  }
670
760
  // Round absolute project boundaries to the nearest 48 kHz sample. Never sum
@@ -894,7 +984,7 @@ async function prepareTimeline(options, png = false, scratch) {
894
984
  : []), '-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');
895
985
  return prepared;
896
986
  }
897
- /** Full preflight uses the exact same plan, media probes and filters as execution. */
987
+ /** Validate the composition and required encoders without populating the picture cache. */
898
988
  export async function validateVideoTimeline(options) {
899
989
  const prepared = await prepareTimeline(options);
900
990
  const encoders = (await runMediaTool('ffmpeg', ['-hide_banner', '-v', 'error', '-encoders'], 4 * 1024 * 1024, 60_000, { signal: options.signal })).toString('utf8');
@@ -949,7 +1039,7 @@ function renderScratch(output, prefix, directory = dirname(resolve(output))) {
949
1039
  export async function renderVideoTimeline(options) {
950
1040
  const scratch = renderScratch(options.output, '.opencut-render-', options.scratchDirectory);
951
1041
  try {
952
- const prepared = await prepareTimeline(options, false, scratch);
1042
+ const prepared = await prepareTimeline(options, 'mp4', scratch);
953
1043
  await scratch.stage(prepared, options.signal);
954
1044
  const { args, path, quality, resolution, codec, outputWidth, outputHeight, frameRate, frameCount, durationSeconds, warnings, } = prepared;
955
1045
  const { numerator, denominator } = frameRate;
@@ -1005,15 +1095,10 @@ export async function renderVideoTimeline(options) {
1005
1095
  checkRenderSignal(options.signal);
1006
1096
  try {
1007
1097
  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
- });
1098
+ const destination = await existingOutput(path);
1015
1099
  if (destination && !destination.isFile())
1016
1100
  throw new MediaError(`Refusing to overwrite non-regular output '${path}'.`);
1101
+ await protectSourceFiles(options, destination);
1017
1102
  checkRenderSignal(options.signal);
1018
1103
  // Same-filesystem rename replaces a complete file atomically.
1019
1104
  await rename(rendered, path);
@@ -1040,6 +1125,7 @@ export async function renderVideoTimeline(options) {
1040
1125
  durationSeconds,
1041
1126
  metadata: { ...metadata, path },
1042
1127
  ...(warnings.length ? { warnings } : {}),
1128
+ ...(prepared.pictureRanges && { pictureRanges: prepared.pictureRanges }),
1043
1129
  };
1044
1130
  }
1045
1131
  finally {
@@ -1050,7 +1136,7 @@ export async function renderVideoTimeline(options) {
1050
1136
  export async function renderTimelineFrame(options) {
1051
1137
  const scratch = renderScratch(options.output, '.opencut-frame-');
1052
1138
  try {
1053
- const prepared = await prepareTimeline(options, true, scratch);
1139
+ const prepared = await prepareTimeline(options, 'png', scratch);
1054
1140
  await scratch.stage(prepared, options.signal);
1055
1141
  const rendered = join(await scratch.open(), 'frame.png');
1056
1142
  await runMediaTool('ffmpeg', [...prepared.args, '-update', '1', rendered], 4 * 1024 * 1024, 600_000, { signal: options.signal });
@@ -13,7 +13,13 @@ type TransformSource = {
13
13
  aspect: number;
14
14
  matrix: string;
15
15
  /** Project-frame sampling and range filters. Still images need neither. */
16
- sampling?: string;
16
+ sampling?: {
17
+ filter: string;
18
+ seek?: {
19
+ seconds: number;
20
+ fallbackFilter: string;
21
+ };
22
+ };
17
23
  };
18
24
  export interface TransformLayerOptions {
19
25
  width: number;
@@ -1,15 +1,18 @@
1
+ import { rm } from 'node:fs/promises';
1
2
  import { spawn } from 'node:child_process';
2
3
  import { pipeline } from 'node:stream/promises';
3
4
  import { evaluateVisual, drawMediaLayer, gradePixels, transformTextLayer, transitionOpacity, visualGeometry, } from '@opencut/shared';
4
5
  import { checkRenderSignal, MediaError } from './process.js';
5
6
  import { renderToolCommand, trackRenderProcess } from './render-budget.js';
7
+ import { indexedSeekArgs } from './video-filter.js';
6
8
  function rawSource(source, frames) {
7
9
  const { path, stream, width, height, matrix, sampling } = source;
8
10
  const limit = Math.min(1, 8192 / width, 8192 / height, Math.sqrt((3840 * 2160) / (width * height)));
9
11
  const decodeWidth = Math.max(1, Math.floor(width * limit));
10
12
  const decodeHeight = Math.max(1, Math.floor(height * limit));
11
13
  const filters = [
12
- sampling,
14
+ sampling?.filter,
15
+ sampling?.seek ? 'setpts=PTS-STARTPTS' : undefined,
13
16
  `scale=${decodeWidth}:${decodeHeight}:in_color_matrix=${matrix}`,
14
17
  'format=rgba',
15
18
  ];
@@ -21,6 +24,9 @@ function rawSource(source, frames) {
21
24
  args: [
22
25
  '-threads',
23
26
  '1',
27
+ ...(sampling?.seek
28
+ ? ['-copyts', ...indexedSeekArgs(sampling.seek.seconds)]
29
+ : []),
24
30
  '-i',
25
31
  path,
26
32
  '-map',
@@ -90,8 +96,32 @@ async function* decodedFrames(stream, pixels) {
90
96
  if (used)
91
97
  throw new MediaError('FFmpeg returned a partial transform frame.');
92
98
  }
99
+ class IncompleteTransformFrames extends MediaError {
100
+ }
93
101
  /** Stage one alpha-preserving layer. Only the current input and output frames are held in memory. */
94
102
  export async function stageTransformLayer(options, destination) {
103
+ const { source, signal } = options;
104
+ try {
105
+ await writeTransformLayer(options, destination);
106
+ }
107
+ catch (error) {
108
+ if (source.kind !== 'media' ||
109
+ !(error instanceof IncompleteTransformFrames))
110
+ throw error;
111
+ const seek = source.sampling?.seek;
112
+ if (!seek)
113
+ throw error;
114
+ checkRenderSignal(signal);
115
+ // A demuxer can seek by DTS to a keyframe that starts after the requested
116
+ // presentation tick. Discard the short stage and sample from the origin.
117
+ await rm(destination, { force: true });
118
+ await writeTransformLayer({
119
+ ...options,
120
+ source: { ...source, sampling: { filter: seek.fallbackFilter } },
121
+ }, destination);
122
+ }
123
+ }
124
+ async function writeTransformLayer(options, destination) {
95
125
  checkRenderSignal(options.signal);
96
126
  const { createCanvas, ImageData, loadImage } = await import('@napi-rs/canvas');
97
127
  const { width, height, rate, source, frameCount, startFrame, visual, animation, } = options;
@@ -145,7 +175,7 @@ export async function stageTransformLayer(options, destination) {
145
175
  signal.throwIfAborted();
146
176
  if (media && decoded && (!media.still || i === 0)) {
147
177
  if ((await decoded.next()).done)
148
- throw new MediaError('FFmpeg returned fewer transform frames than expected.');
178
+ throw new IncompleteTransformFrames('FFmpeg returned fewer transform frames than expected.');
149
179
  if (options.grade)
150
180
  gradePixels(media.pixels.data, options.grade);
151
181
  sourceCtx.putImageData(media.pixels, 0, 0);
@@ -9,3 +9,5 @@ export declare function fitVisual(geometry: {
9
9
  cropX: number;
10
10
  cropY: number;
11
11
  }, colorMatrix: string): string;
12
+ /** Seek by input timestamp and pass preroll through to the sampler. */
13
+ export declare function indexedSeekArgs(seconds: number): string[];
@@ -12,4 +12,8 @@ export function fitVisual(geometry, colorMatrix) {
12
12
  : '') +
13
13
  'setsar=1');
14
14
  }
15
+ /** Seek by input timestamp and pass preroll through to the sampler. */
16
+ export function indexedSeekArgs(seconds) {
17
+ return seconds ? ['-ss', seconds.toFixed(6), '-noaccurate_seek'] : [];
18
+ }
15
19
  //# sourceMappingURL=video-filter.js.map
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opencut/media",
3
- "version": "0.1.0",
3
+ "version": "0.1.3",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -10,7 +10,7 @@
10
10
  },
11
11
  "dependencies": {
12
12
  "@napi-rs/canvas": "1.1.0",
13
- "@opencut/shared": "0.1.0",
13
+ "@opencut/shared": "0.1.3",
14
14
  "lru-cache": "11.5.3",
15
15
  "sharp": "0.35.5"
16
16
  },