@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
@@ -0,0 +1,169 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { opaqueCanvasColor } from '@opencut/shared';
3
+ import { MediaError, checkRenderSignal, runMediaTool } from './process.js';
4
+ import { isStillImage, probeMedia } from './probe.js';
5
+ function digest(value) {
6
+ return createHash('sha256').update(value).digest('hex');
7
+ }
8
+ function relativeTime(time, frame, rate) {
9
+ const n = BigInt(time.numerator) * BigInt(rate.numerator) -
10
+ BigInt(frame) * BigInt(rate.denominator) * BigInt(time.denominator);
11
+ const d = BigInt(time.denominator) * BigInt(rate.numerator);
12
+ let a = n < 0n ? -n : n;
13
+ let b = d;
14
+ while (b)
15
+ [a, b] = [b, a % b];
16
+ return [(n / a).toString(), (d / a).toString()];
17
+ }
18
+ /** Use render inputs and clip-local sample positions as the identity of a range. */
19
+ export async function cachePicture({ options, cache, visualClips, byOwner, startFrame, endFrame, outputWidth, outputHeight, warnings, rasterize, encode, }) {
20
+ const { width, height, frameRate, signal } = options;
21
+ const boundaries = new Set([startFrame, endFrame]);
22
+ const include = (boundary) => {
23
+ if (boundary > startFrame && boundary < endFrame)
24
+ boundaries.add(boundary);
25
+ };
26
+ const sources = new Map(options.sourceMetadata);
27
+ const identities = new Map();
28
+ const layers = new Map();
29
+ const layerKey = async (clip, start) => {
30
+ let layer = layers.get(clip);
31
+ const { retiming, text, animation } = clip;
32
+ if (!layer) {
33
+ let sourceKey;
34
+ let still = !!text;
35
+ if (text) {
36
+ // Include the raster so font installation and fallback affect cache hits.
37
+ const { png, x, y, warning } = await rasterize(clip);
38
+ if (warning)
39
+ warnings.push(`Clip '${clip.clipId}': ${warning}`);
40
+ sourceKey = png && [digest(png), x, y];
41
+ }
42
+ else {
43
+ let identity = identities.get(clip.path);
44
+ if (!identity) {
45
+ identity = cache.sourceIdentity(clip.path);
46
+ identities.set(clip.path, identity);
47
+ }
48
+ let metadata = sources.get(clip.path);
49
+ if (!metadata) {
50
+ metadata = await probeMedia(clip.path, signal);
51
+ sources.set(clip.path, metadata);
52
+ }
53
+ const { freezeFrame } = clip;
54
+ still = !!freezeFrame || isStillImage(metadata);
55
+ sourceKey = [clip.path, identity, freezeFrame];
56
+ }
57
+ layer = {
58
+ still,
59
+ key: digest(JSON.stringify([
60
+ sourceKey,
61
+ clip.x,
62
+ clip.y,
63
+ clip.scale,
64
+ clip.opacity,
65
+ clip.rotation,
66
+ clip.fit,
67
+ clip.crop,
68
+ clip.grade,
69
+ animation?.keyframes,
70
+ ])),
71
+ };
72
+ layers.set(clip, layer);
73
+ }
74
+ const offset = start - clip.timelineStartFrame;
75
+ return [
76
+ layer.key,
77
+ animation && relativeTime(animation.start, start, frameRate),
78
+ layer.still
79
+ ? null
80
+ : retiming
81
+ ? [
82
+ offset,
83
+ retiming.speed,
84
+ retiming.localSourceOriginNs ?? [
85
+ retiming.sourceOriginNs,
86
+ clip.timelineStartFrame,
87
+ ],
88
+ ]
89
+ : clip.sourceStartFrame + offset,
90
+ ];
91
+ };
92
+ const active = (start, end, frame) => start <= frame && frame < end;
93
+ for (const clip of visualClips) {
94
+ include(clip.timelineStartFrame);
95
+ include(clip.timelineStartFrame + clip.frameCount);
96
+ for (const { layers } of byOwner.get(clip.clipId) ?? []) {
97
+ const { startFrame, endFrame } = layers[0].ramp;
98
+ include(startFrame);
99
+ include(endFrame);
100
+ }
101
+ }
102
+ const edges = [...boundaries].sort((a, b) => a - b);
103
+ let concat = '';
104
+ const ranges = [];
105
+ const settings = [
106
+ cache.backend,
107
+ width,
108
+ height,
109
+ frameRate,
110
+ outputWidth,
111
+ outputHeight,
112
+ opaqueCanvasColor(options.backgroundColor ?? '#000000'),
113
+ ];
114
+ for (let i = 1; i < edges.length; i++) {
115
+ checkRenderSignal(signal);
116
+ const start = edges[i - 1];
117
+ const end = edges[i];
118
+ const count = end - start;
119
+ const composition = [];
120
+ for (const clip of visualClips) {
121
+ const at = clip.timelineStartFrame;
122
+ if (active(at, at + clip.frameCount, start))
123
+ composition.push(['layer', await layerKey(clip, start)]);
124
+ for (const { layers } of byOwner.get(clip.clipId) ?? []) {
125
+ const { startFrame, endFrame } = layers[0].ramp;
126
+ if (active(startFrame, endFrame, start))
127
+ composition.push([
128
+ 'transition',
129
+ start - startFrame,
130
+ endFrame - startFrame,
131
+ await Promise.all(layers.map(async (layer) => [
132
+ layer.ramp.direction,
133
+ await layerKey(layer, start),
134
+ ])),
135
+ ]);
136
+ }
137
+ }
138
+ const key = digest(JSON.stringify([settings, count, composition]));
139
+ const { path, reused } = await cache.materialize(key, async (destination) => {
140
+ await encode(start, end, destination);
141
+ const packets = await runMediaTool('ffprobe', [
142
+ '-v',
143
+ 'error',
144
+ '-count_packets',
145
+ '-select_streams',
146
+ 'v:0',
147
+ '-show_entries',
148
+ 'stream=nb_read_packets',
149
+ '-of',
150
+ 'csv=p=0',
151
+ destination,
152
+ ], undefined, 600_000, { signal });
153
+ if (Number(packets.toString().trim()) !== count)
154
+ throw new MediaError(`Picture range [${start}, ${end}) has an unexpected frame count.`);
155
+ return probeMedia(destination, signal);
156
+ });
157
+ if (/[\r\n]/.test(path))
158
+ throw new MediaError('Picture cache paths cannot contain line breaks.');
159
+ const duration = (count * frameRate.denominator) / frameRate.numerator;
160
+ concat += `file '${path.replaceAll("'", "'\\''")}'\nduration ${duration.toFixed(6)}\n`;
161
+ ranges.push({
162
+ startFrame: start,
163
+ endFrame: end,
164
+ status: reused ? 'reused' : 'rendered',
165
+ });
166
+ }
167
+ return { concat, ranges };
168
+ }
169
+ //# sourceMappingURL=picture-cache.js.map
@@ -0,0 +1,4 @@
1
+ export declare function pictureSeekCheck(signal?: AbortSignal): (path: string, stream: number, seekSeconds: number, firstFrame: number, rate: {
2
+ numerator: number;
3
+ denominator: number;
4
+ }) => Promise<boolean>;
@@ -0,0 +1,77 @@
1
+ import { checkRenderSignal, runMediaTool } from './process.js';
2
+ import { indexedSeekArgs } from './video-filter.js';
3
+ async function firstPictureTimestamp(path, stream, seekSeconds, signal) {
4
+ try {
5
+ // Use the same decoder and input seek as the compositor. A packet's DTS
6
+ // can precede the target even when the first decoded picture's PTS does not.
7
+ const result = await runMediaTool('ffmpeg', [
8
+ '-v',
9
+ 'error',
10
+ '-nostdin',
11
+ '-xerror',
12
+ '-copyts',
13
+ '-threads',
14
+ '1',
15
+ ...indexedSeekArgs(seekSeconds),
16
+ '-i',
17
+ path,
18
+ '-map',
19
+ `0:${stream}`,
20
+ '-filter_threads',
21
+ '1',
22
+ '-vf',
23
+ 'scale=2:2,format=yuv420p',
24
+ '-frames:v',
25
+ '1',
26
+ '-c:v',
27
+ 'rawvideo',
28
+ '-threads',
29
+ '1',
30
+ '-fps_mode',
31
+ 'passthrough',
32
+ '-enc_time_base:v',
33
+ 'demux',
34
+ '-avoid_negative_ts',
35
+ 'disabled',
36
+ '-f',
37
+ 'framecrc',
38
+ 'pipe:1',
39
+ ], undefined, undefined, { signal });
40
+ const output = result.toString();
41
+ const timeBase = /^#tb 0: ([1-9]\d*)\/([1-9]\d*)$/m.exec(output);
42
+ const frame = /^0,\s*-?\d+,\s*(-?\d+),/m.exec(output);
43
+ if (timeBase && frame)
44
+ return {
45
+ pts: BigInt(frame[1]),
46
+ numerator: BigInt(timeBase[1]),
47
+ denominator: BigInt(timeBase[2]),
48
+ };
49
+ }
50
+ catch {
51
+ // If the probe is inconclusive, the normal sequential path owns decoding errors.
52
+ checkRenderSignal(signal);
53
+ }
54
+ }
55
+ export function pictureSeekCheck(signal) {
56
+ const origins = new Map();
57
+ return async (path, stream, seekSeconds, firstFrame, rate) => {
58
+ const key = JSON.stringify([path, stream]);
59
+ let hasZeroOrigin = origins.get(key);
60
+ if (!hasZeroOrigin) {
61
+ // Sequential sampling rebases the first decoded frame. An indexed decode
62
+ // uses the original PTS, so both clocks must share an actual zero origin.
63
+ hasZeroOrigin = firstPictureTimestamp(path, stream, 0, signal).then((timestamp) => timestamp?.pts === 0n);
64
+ origins.set(key, hasZeroOrigin);
65
+ }
66
+ if (!(await hasZeroOrigin))
67
+ return false;
68
+ const first = await firstPictureTimestamp(path, stream, seekSeconds, signal);
69
+ // round=up must place the first decoded picture strictly before the first
70
+ // requested project tick. This retains its predecessor across VFR gaps.
71
+ return (!!first &&
72
+ first.pts > 0n &&
73
+ first.pts * first.numerator * BigInt(rate.numerator) <=
74
+ BigInt(firstFrame - 1) * BigInt(rate.denominator) * first.denominator);
75
+ };
76
+ }
77
+ //# sourceMappingURL=picture-seek.js.map
@@ -3,6 +3,7 @@ import type { MediaMetadata } from './probe.js';
3
3
  import type { RenderQuality } from '@opencut/shared';
4
4
  import type { RenderProgress } from './render-progress.js';
5
5
  import { rasterizeTextLayer } from './text.js';
6
+ import type { PictureCache, PictureRange } from './picture-cache.js';
6
7
  interface VisualTimelineProperties {
7
8
  crop?: NonNullable<import('@opencut/shared').VisualTransform['crop']>;
8
9
  grade?: import('@opencut/shared').ColorGrade;
@@ -12,6 +13,7 @@ interface VisualTimelineProperties {
12
13
  frameCount: number;
13
14
  retiming?: RenderTimeMapping & {
14
15
  sourceOriginNs: number;
16
+ localSourceOriginNs?: number;
15
17
  };
16
18
  x?: number;
17
19
  y?: number;
@@ -85,6 +87,7 @@ interface RenderAudioFade {
85
87
  export interface VideoTimelineOptions extends RenderControls {
86
88
  /** Serialize build provenance in a custom MP4 format tag. */
87
89
  buildMetadata?: string;
90
+ pictureCache?: PictureCache | undefined;
88
91
  /** Parent for private scratch on the destination filesystem. */
89
92
  scratchDirectory?: string;
90
93
  /** Record a verified file before publication so a caller can reconcile a crash. */
@@ -170,10 +173,11 @@ export interface VideoTimelineResult {
170
173
  durationSeconds: number;
171
174
  metadata: MediaMetadata;
172
175
  warnings?: string[];
176
+ pictureRanges?: PictureRange[];
173
177
  }
174
178
  type Rational = RenderTimeMapping['sourceIn'];
175
179
  export declare function validateSubtitleBurnIn(clips: readonly Pick<VisualTimelineClip, 'subtitle' | 'subtitleCueId' | 'clipId'>[]): void;
176
- /** Full preflight uses the exact same plan, media probes and filters as execution. */
180
+ /** Validate the composition and required encoders without populating the picture cache. */
177
181
  export declare function validateVideoTimeline(options: VideoTimelineOptions): Promise<{
178
182
  width: number;
179
183
  height: number;