@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
@@ -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.2.0",
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.2.0",
14
14
  "lru-cache": "11.5.3",
15
15
  "sharp": "0.35.5"
16
16
  },
@@ -1,4 +1,4 @@
1
- export { batchRenderVideo, compileVideo, defineVideo, inspectVideoBuild, inspectVideoRecipes, OnlineMediaError, OnlineMediaLibrary, packageVideo, parseSubtitles, parseSubtitleTime, previewVideo, readSubtitleFile, renderCompiledVideo, renderVideo, serializeSubtitles, VideoDefinitionError, verifyVideoPackage, videoId, videoParams, watchVideo, writeSubtitleFile, } from '@opencut/core/video';
2
- export type { CompiledVideo, CompiledVideoRenderOptions, OnlineMediaPage, OnlineMediaResult, OnlineMediaSearch, PreviewPosition, VideoBatchOptions, VideoBatchProgress, VideoBatchResult, VideoBuild, VideoBuildInspection, VideoCompileOptions, VideoDefinition, VideoParameters, VideoPackageManifest, VideoPackageOptions, VideoRecipe, VideoRecipeInspection, VideoProcessingOptions, VideoProcessingProgress, VideoPreviewOptions, VideoPreviewRange, VideoRenderBuild, VideoRenderOptions, VideoVariant, VideoVariantResult, VideoWatchOptions, VideoWatchRevision, VideoWatchStatus, } from '@opencut/core/video';
1
+ export { analyzeVideoMix, batchRenderVideo, compileVideo, defineVideo, inspectVideoBuild, inspectVideoRecipes, OnlineMediaError, OnlineMediaLibrary, packageVideo, parseSubtitles, parseSubtitleTime, previewVideo, readSubtitleFile, renderCompiledVideo, renderVideo, serializeSubtitles, VideoDefinitionError, verifyVideoPackage, videoId, videoParams, watchVideo, writeSubtitleFile, } from '@opencut/core/video';
2
+ export type { AudioMixAnalysisOptions, AudioMixReport, AudioRole, DeliveryPreset, DialoguePreset, MixAutomation, MixGainPoint, ProfessionalMix, VideoMixEdit, CompiledVideo, CompiledVideoRenderOptions, OnlineMediaPage, OnlineMediaResult, OnlineMediaSearch, PreviewPosition, VideoBatchOptions, VideoBatchProgress, VideoBatchResult, VideoBuild, VideoBuildInspection, VideoCompileOptions, VideoDefinition, VideoParameters, VideoPackageManifest, VideoPackageOptions, VideoRecipe, VideoRecipeInspection, VideoProcessingOptions, VideoProcessingProgress, VideoPreviewOptions, VideoPreviewRange, VideoRenderBuild, VideoRenderOptions, VideoVariant, VideoVariantResult, VideoWatchOptions, VideoWatchRevision, VideoWatchStatus, } from '@opencut/core/video';
3
3
  export { decodeStillFrame, extractFrame, MediaError, probeMedia, RenderCancelledError, separateDialogue, } from '@opencut/media';
4
4
  export type { MediaMetadata, RenderProgress, RenderQuality, VideoTimelineResult, } from '@opencut/media';
@@ -1,3 +1,3 @@
1
- export { batchRenderVideo, compileVideo, defineVideo, inspectVideoBuild, inspectVideoRecipes, OnlineMediaError, OnlineMediaLibrary, packageVideo, parseSubtitles, parseSubtitleTime, previewVideo, readSubtitleFile, renderCompiledVideo, renderVideo, serializeSubtitles, VideoDefinitionError, verifyVideoPackage, videoId, videoParams, watchVideo, writeSubtitleFile, } from '@opencut/core/video';
1
+ export { analyzeVideoMix, batchRenderVideo, compileVideo, defineVideo, inspectVideoBuild, inspectVideoRecipes, OnlineMediaError, OnlineMediaLibrary, packageVideo, parseSubtitles, parseSubtitleTime, previewVideo, readSubtitleFile, renderCompiledVideo, renderVideo, serializeSubtitles, VideoDefinitionError, verifyVideoPackage, videoId, videoParams, watchVideo, writeSubtitleFile, } from '@opencut/core/video';
2
2
  export { decodeStillFrame, extractFrame, MediaError, probeMedia, RenderCancelledError, separateDialogue, } from '@opencut/media';
3
3
  //# sourceMappingURL=index.js.map
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opencut/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -9,8 +9,8 @@
9
9
  }
10
10
  },
11
11
  "dependencies": {
12
- "@opencut/core": "0.1.0",
13
- "@opencut/media": "0.1.0"
12
+ "@opencut/core": "0.2.0",
13
+ "@opencut/media": "0.2.0"
14
14
  },
15
15
  "license": "MIT"
16
16
  }
@@ -140,3 +140,4 @@ export { transitionOpacity } from './transition.js';
140
140
  export type { TransitionRamp } from './transition.js';
141
141
  export { renderQualities, renderQualityProfiles } from './render-quality.js';
142
142
  export type { RenderQuality } from './render-quality.js';
143
+ export * from './professional-mix.js';
@@ -122,4 +122,5 @@ export function transformTextLayer(ctx, width, height, visual) {
122
122
  }
123
123
  export { transitionOpacity } from './transition.js';
124
124
  export { renderQualities, renderQualityProfiles } from './render-quality.js';
125
+ export * from './professional-mix.js';
125
126
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,98 @@
1
+ export declare const audioRoles: readonly ["dialogue", "music", "other"];
2
+ export type AudioRole = (typeof audioRoles)[number];
3
+ export declare const dialoguePresets: readonly ["natural-cinematic", "clear-voiceover"];
4
+ export declare const deliveryPresets: readonly ["web", "broadcast", "film"];
5
+ export type DialoguePreset = (typeof dialoguePresets)[number];
6
+ export type DeliveryPreset = (typeof deliveryPresets)[number];
7
+ /** Linear interpolation in dB on the mixer's 48 kHz sample clock. */
8
+ export interface MixGainPoint {
9
+ sample: number;
10
+ db: number;
11
+ }
12
+ export interface MixAutomation {
13
+ /** Clip-local keys. An empty curve explicitly disables correction. */
14
+ dialogue?: Record<string, MixGainPoint[]> | undefined;
15
+ /** Project-time keys for the music bus. An empty curve disables ducking. */
16
+ music?: MixGainPoint[] | undefined;
17
+ }
18
+ export interface ProfessionalMix {
19
+ preset: DialoguePreset;
20
+ enabled?: boolean | undefined;
21
+ cleanup?: number | undefined;
22
+ warmth?: number | undefined;
23
+ clarity?: number | undefined;
24
+ consistency?: number | undefined;
25
+ dialogueLufs?: number | undefined;
26
+ highPassHz?: number | undefined;
27
+ eq?: {
28
+ frequency: number;
29
+ q: number;
30
+ db: number;
31
+ }[] | undefined;
32
+ deEsser?: number | undefined;
33
+ compressor?: {
34
+ thresholdDb: number;
35
+ ratio: number;
36
+ attackMs: number;
37
+ releaseMs: number;
38
+ } | undefined;
39
+ ai?: 'deepfilternet' | undefined;
40
+ dereverb?: number | undefined;
41
+ matching?: {
42
+ amount: number;
43
+ referenceClip?: string | undefined;
44
+ } | undefined;
45
+ crossfadeMs?: number | undefined;
46
+ ducking?: {
47
+ depthDb?: number | undefined;
48
+ attackMs?: number | undefined;
49
+ holdMs?: number | undefined;
50
+ releaseMs?: number | undefined;
51
+ } | undefined;
52
+ delivery?: {
53
+ preset: DeliveryPreset;
54
+ integratedLufs?: number | undefined;
55
+ truePeakDbtp?: number | undefined;
56
+ loudnessRange?: number | undefined;
57
+ } | undefined;
58
+ automation?: MixAutomation | undefined;
59
+ }
60
+ export interface VideoMixEdit {
61
+ mix: ProfessionalMix | null;
62
+ roles?: Record<string, AudioRole> | undefined;
63
+ }
64
+ export declare const deliveryTargets: {
65
+ web: {
66
+ integratedLufs: number;
67
+ truePeakDbtp: number;
68
+ loudnessRange: number;
69
+ };
70
+ broadcast: {
71
+ integratedLufs: number;
72
+ truePeakDbtp: number;
73
+ loudnessRange: number;
74
+ };
75
+ film: {
76
+ integratedLufs: number;
77
+ truePeakDbtp: number;
78
+ loudnessRange: number;
79
+ };
80
+ };
81
+ export declare const dialoguePresetControls: {
82
+ 'natural-cinematic': {
83
+ cleanup: number;
84
+ warmth: number;
85
+ clarity: number;
86
+ consistency: number;
87
+ dialogueLufs: number;
88
+ duckingDepth: number;
89
+ };
90
+ 'clear-voiceover': {
91
+ cleanup: number;
92
+ warmth: number;
93
+ clarity: number;
94
+ consistency: number;
95
+ dialogueLufs: number;
96
+ duckingDepth: number;
97
+ };
98
+ };
@@ -0,0 +1,30 @@
1
+ export const audioRoles = ['dialogue', 'music', 'other'];
2
+ export const dialoguePresets = [
3
+ 'natural-cinematic',
4
+ 'clear-voiceover',
5
+ ];
6
+ export const deliveryPresets = ['web', 'broadcast', 'film'];
7
+ export const deliveryTargets = {
8
+ web: { integratedLufs: -16, truePeakDbtp: -1.5, loudnessRange: 12 },
9
+ broadcast: { integratedLufs: -23, truePeakDbtp: -1, loudnessRange: 15 },
10
+ film: { integratedLufs: -24, truePeakDbtp: -2, loudnessRange: 20 },
11
+ };
12
+ export const dialoguePresetControls = {
13
+ 'natural-cinematic': {
14
+ cleanup: 0.38,
15
+ warmth: 0.42,
16
+ clarity: 0.32,
17
+ consistency: 0.6,
18
+ dialogueLufs: -22,
19
+ duckingDepth: 10,
20
+ },
21
+ 'clear-voiceover': {
22
+ cleanup: 0.65,
23
+ warmth: 0.28,
24
+ clarity: 0.58,
25
+ consistency: 0.8,
26
+ dialogueLufs: -19,
27
+ duckingDepth: 13,
28
+ },
29
+ };
30
+ //# sourceMappingURL=professional-mix.js.map
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opencut/shared",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dantea/opencut",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "OpenCut video-as-code CLI and TypeScript SDK for Apple Silicon",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -39,10 +39,10 @@
39
39
  "@img/sharp-libvips-darwin-arm64": "1.3.4",
40
40
  "@napi-rs/canvas": "1.1.0",
41
41
  "@napi-rs/canvas-darwin-arm64": "1.1.0",
42
- "@opencut/core": "0.1.0",
43
- "@opencut/media": "0.1.0",
44
- "@opencut/sdk": "0.1.0",
45
- "@opencut/shared": "0.1.0",
42
+ "@opencut/core": "0.2.0",
43
+ "@opencut/media": "0.2.0",
44
+ "@opencut/sdk": "0.2.0",
45
+ "@opencut/shared": "0.2.0",
46
46
  "detect-libc": "2.1.2",
47
47
  "lru-cache": "11.5.3",
48
48
  "semver": "7.8.5",
@@ -22,6 +22,8 @@ discover commands and `opencut render --help` for export controls.
22
22
  transcoding. Use `interpolateFrames` to preserve duration at a higher
23
23
  frame rate or `smoothSlowMotion` to extend picture duration and mute it.
24
24
  Use `superResolution` for AI upscaling and `denoise` on supported hardware.
25
+ Preserve authored quality; never silently downsize a source or substitute a
26
+ lighter model to satisfy an unsupported processor.
25
27
  Check [AI recipe support and scene boundaries](references/video-definitions.md#media-recipes).
26
28
  2. Set canvas size, frame rate, ordered tracks, and clip ranges. Use integer
27
29
  frame positions or exact rationals as documented. Add subtitles, effects,
@@ -34,7 +36,11 @@ discover commands and `opencut render --help` for export controls.
34
36
  contact sheet from `opencut preview --help`. Preview defaults to `fast`.
35
37
  Use `--quality quality` to review offline AI processing, such as 4×
36
38
  super-resolution. A failed watch rebuild leaves the last valid preview
37
- available.
39
+ available. Desktop review keeps the playhead at the same timeline time
40
+ across rebuilds, including frame-rate changes, and clamps it to the last
41
+ frame if the revision ends earlier. Select a clip, subtitle, or transition
42
+ to pause on the first frame at or after its start. A selection made during
43
+ loading takes effect when the preview is ready.
38
44
  5. Deliver a new MP4 with `opencut render DEFINITION --output final.mp4`.
39
45
  The CLI defaults to `quality` and runs directly. Use `--quality maximum`
40
46
  for slower MP4 encoding with the same AI algorithms as `quality`.
@@ -57,3 +63,9 @@ discover commands and `opencut render --help` for export controls.
57
63
  Start with the [complete example and visual review loop](references/workflow.md).
58
64
  See [definition fields](references/video-definitions.md), the
59
65
  [CLI reference](references/cli.md), and [SDK usage](references/sdk.md).
66
+
67
+ For dialogue cleanup and automatic music ducking, route audio or video tracks
68
+ with `audioRole: 'dialogue'`, `'music'` or `'other'` and enable
69
+ `professionalMix` in the definition. Use `opencut mix analyze <file.video.ts> --json`
70
+ for editable curves and a loudness report before encoding picture. See the
71
+ [mix definition, delivery presets and offline AI options](../../docs/AUDIO_MIX.md).
@@ -24,6 +24,13 @@ automatically processes referenced recipes and reuses completed steps. The
24
24
  `--recipe-cache` to choose a cache and `--recipe-workers` and the other
25
25
  [recipe flags](../../../docs/CLI.md#media-recipes) to set processing limits.
26
26
 
27
+ For revisions, pass the same `--picture-cache <directory>` on the initial
28
+ export and each subsequent `render`. OpenCut can reuse lossless picture
29
+ ranges after a timeline shift, including ranges with captions that shift
30
+ together with picture. Audio is mixed on the revised timeline. Read
31
+ `pictureRanges` in JSON for the status of each half-open project-frame range.
32
+ See [picture cache options](../../../docs/CLI.md#reuse-picture-between-exports).
33
+
27
34
  On macOS, `opencut system inspect --json` reports the VideoToolbox processor
28
35
  and tested formats and dimensions. Recipe inspection checks declarations
29
36
  and input streams. Use normal `validate` with the same recipe limits as
@@ -58,3 +65,10 @@ after moving it, then render `BUNDLE/opencut.bundle.video.ts`. Keep that
58
65
  filename at the bundle root. Verification rejects symlinks at the entry and
59
66
  in packaged dependency paths. The new host needs a compatible OpenCut,
60
67
  FFmpeg, and any required native models.
68
+
69
+ For mix-enabled definitions, run `opencut mix analyze <definition.video.ts> --json`
70
+ to inspect loudness and get editable automation. To reuse the curves, copy the
71
+ report’s `automation` into `professionalMix.automation` in the definition or
72
+ `mix.automation` in a settings file passed to `--mix-settings <mix.json>`. Use
73
+ `--mix-comparison before` for a loudness-matched comparison and
74
+ `--mix-cache <directory>` to reuse AI-enhanced stems across runs. See [Professional Dialogue Mix](../../../docs/AUDIO_MIX.md).
@@ -10,6 +10,11 @@ Use `renderVideo` to compile and render in one call. If `renderCompiledVideo`
10
10
  reports that source media changed, recompile before retrying.
11
11
  See the repository's [SDK guide](../../../docs/SDK.md) for the public API.
12
12
 
13
+ For picture reuse, pass the same `pictureCacheDirectory` to `renderVideo`
14
+ or `renderCompiledVideo` on the initial export and revisions. Read
15
+ `pictureRanges` for the status of each range in project frames.
16
+ See [picture cache behavior](../../../docs/CLI.md#reuse-picture-between-exports).
17
+
13
18
  Use `inspectVideoRecipes(file)` for recipe validation and inspection without
14
19
  transcoding. `compileVideo`, `renderVideo`, and `watchVideo` accept `processing`
15
20
  options for the cache, worker limits, and step progress.
@@ -35,3 +40,7 @@ Use `packageVideo(definition, destination, { root, resources, params, signal })`
35
40
  `verifyVideoPackage(destination)` to share a project. Pass the verified
36
41
  result's `entry` to `renderVideo` after relocation; it is already resolved
37
42
  for the recorded parameters.
43
+
44
+ Use `analyzeVideoMix(compiledVideo)` to obtain editable automation and measured final
45
+ loudness. `compileVideo` and `renderVideo` accept `audioMixEdit`. Mix-enabled exports
46
+ include `audioMix` in the result. See [Professional Dialogue Mix](../../../docs/AUDIO_MIX.md).
@@ -145,14 +145,18 @@ enhancement to select a range on the source container's clock. A later
145
145
  `trim` uses the derived clock, where the first retained stream starts at
146
146
  zero and the relative audio delay is preserved. `fast` uses a size-dependent
147
147
  1.5× or 2× model.
148
- `quality` and `maximum` use Apple's temporal 4× model and resize to the target.
148
+ `quality` and `maximum` compute the temporal model's full 4× output before
149
+ resizing to the target. The model's input limit applies after earlier recipe
150
+ steps. OpenCut reports unsupported dimensions.
149
151
  For `denoise`, set `strength` to `light`, `medium`, or `strong` and check temporal
150
152
  noise-filter support before use. AI enhancement accepts constant-rate,
151
153
  progressive, square-pixel, 8-bit video-range SDR input. If the color matrix
152
154
  tag is missing, OpenCut resolves it from the input dimensions and codec
153
155
  before enhancement. Recipe order determines whether enhancement runs
154
- before or after interpolation. Compare
155
- the processed sequence with a Lanczos resize when judging detail and
156
+ before or after interpolation. Enhancing before doubling the frame rate halves
157
+ the number of enhanced frames, but requires interpolation support at the larger
158
+ size. Interpolating first keeps interpolation smaller and doubles enhancement
159
+ work. Compare the processed sequence with a Lanczos resize when judging detail and
156
160
  temporal consistency. See the [enhancement reference](../../../docs/VIDEO_DEFINITIONS.md#ai-enhancement).
157
161
 
158
162
  ## Parameterized composition
@@ -1,16 +0,0 @@
1
- import type { MediaMetadata } from '@opencut/media';
2
- import type { IdentifiedMedia } from './video-input.js';
3
- import type { RecipeFormat } from './video-recipe-schema.js';
4
- type RecipeEntry = IdentifiedMedia & {
5
- sha256: string;
6
- };
7
- export declare function materializeRecipeEntry(directory: string, key: string, format: RecipeFormat, signal: AbortSignal, encode: (output: string) => Promise<MediaMetadata>): Promise<{
8
- entry: RecipeEntry;
9
- reused: boolean;
10
- }>;
11
- /** Find validated media without publishing or removing anything. */
12
- export declare function findRecipeEntry(directory: string, key: string, format: RecipeFormat, signal?: AbortSignal): Promise<{
13
- directory: string;
14
- entry: RecipeEntry;
15
- } | undefined>;
16
- export {};