@dantea/opencut 0.1.3 → 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 (76) hide show
  1. package/dist/commands.d.ts +8 -1
  2. package/dist/commands.js +30 -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 +21 -3
  10. package/docs/AUDIO_MIX.md +132 -0
  11. package/docs/CLI.md +6 -0
  12. package/docs/INSTALL.md +1 -1
  13. package/docs/SDK.md +4 -0
  14. package/docs/VIDEO_DEFINITIONS.md +4 -0
  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 +4 -1
  23. package/node_modules/@opencut/core/dist/render-plan.js +6 -0
  24. package/node_modules/@opencut/core/dist/render-sources.d.ts +3 -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-compiler.d.ts +3 -0
  29. package/node_modules/@opencut/core/dist/video-compiler.js +20 -1
  30. package/node_modules/@opencut/core/dist/video-definition.d.ts +121 -0
  31. package/node_modules/@opencut/core/dist/video-definition.js +6 -1
  32. package/node_modules/@opencut/core/dist/video-files.d.ts +55 -0
  33. package/node_modules/@opencut/core/dist/video-package-format.d.ts +53 -0
  34. package/node_modules/@opencut/core/dist/video-preview.d.ts +56 -1
  35. package/node_modules/@opencut/core/dist/video-preview.js +7 -2
  36. package/node_modules/@opencut/core/dist/video-render.d.ts +11 -4
  37. package/node_modules/@opencut/core/dist/video-render.js +16 -3
  38. package/node_modules/@opencut/core/dist/video-watch.d.ts +5 -0
  39. package/node_modules/@opencut/core/dist/video-watch.js +18 -2
  40. package/node_modules/@opencut/core/dist/video.d.ts +5 -0
  41. package/node_modules/@opencut/core/dist/video.js +2 -0
  42. package/node_modules/@opencut/core/package.json +3 -3
  43. package/node_modules/@opencut/media/dist/audio-graph.d.ts +88 -0
  44. package/node_modules/@opencut/media/dist/audio-graph.js +292 -0
  45. package/node_modules/@opencut/media/dist/audio-mastering.d.ts +29 -0
  46. package/node_modules/@opencut/media/dist/audio-mastering.js +205 -0
  47. package/node_modules/@opencut/media/dist/deepfilter.d.ts +4 -0
  48. package/node_modules/@opencut/media/dist/deepfilter.js +76 -0
  49. package/node_modules/@opencut/media/dist/dialogue-analysis.d.ts +32 -0
  50. package/node_modules/@opencut/media/dist/dialogue-analysis.js +214 -0
  51. package/node_modules/@opencut/media/dist/index.d.ts +3 -1
  52. package/node_modules/@opencut/media/dist/index.js +1 -1
  53. package/node_modules/@opencut/media/dist/process-memory +0 -0
  54. package/node_modules/@opencut/media/dist/process.d.ts +2 -1
  55. package/node_modules/@opencut/media/dist/process.js +13 -4
  56. package/node_modules/@opencut/media/dist/professional-mix.d.ts +34 -0
  57. package/node_modules/@opencut/media/dist/professional-mix.js +411 -0
  58. package/node_modules/@opencut/media/dist/render-budget.d.ts +1 -1
  59. package/node_modules/@opencut/media/dist/render-budget.js +7 -5
  60. package/node_modules/@opencut/media/dist/render.d.ts +28 -46
  61. package/node_modules/@opencut/media/dist/render.js +78 -224
  62. package/node_modules/@opencut/media/dist/video-enhance +0 -0
  63. package/node_modules/@opencut/media/dist/video-interpolate +0 -0
  64. package/node_modules/@opencut/media/package.json +2 -2
  65. package/node_modules/@opencut/sdk/dist/index.d.ts +2 -2
  66. package/node_modules/@opencut/sdk/dist/index.js +1 -1
  67. package/node_modules/@opencut/sdk/package.json +3 -3
  68. package/node_modules/@opencut/shared/dist/index.d.ts +1 -0
  69. package/node_modules/@opencut/shared/dist/index.js +1 -0
  70. package/node_modules/@opencut/shared/dist/professional-mix.d.ts +98 -0
  71. package/node_modules/@opencut/shared/dist/professional-mix.js +30 -0
  72. package/node_modules/@opencut/shared/package.json +1 -1
  73. package/package.json +5 -5
  74. package/skills/video-editor/SKILL.md +6 -0
  75. package/skills/video-editor/references/cli.md +7 -0
  76. package/skills/video-editor/references/sdk.md +4 -0
@@ -1,4 +1,8 @@
1
1
  declare const commands: {
2
+ 'mix analyze': {
3
+ args: string;
4
+ options: string[];
5
+ };
2
6
  package: {
3
7
  args: string;
4
8
  options: string[];
@@ -104,6 +108,9 @@ type Command = keyof typeof commands;
104
108
  export declare function parseCommandLine(args: string[]): {
105
109
  values: {
106
110
  'picture-cache'?: string;
111
+ 'mix-settings'?: string;
112
+ 'mix-comparison'?: string;
113
+ 'mix-cache'?: string;
107
114
  output?: string;
108
115
  root?: string;
109
116
  resource?: string[];
@@ -153,7 +160,7 @@ export declare function parseCommandLine(args: string[]): {
153
160
  export type CommandOptions = ReturnType<typeof parseCommandLine>['values'];
154
161
  export declare function commandUsage(command: Command): string;
155
162
  export declare function resolveCommand(positionals: string[], options: CommandOptions): {
156
- command: "package" | "package verify" | "build inspect" | "validate" | "inspect" | "recipes inspect" | "recipes validate" | "timeline inspect" | "render" | "batch" | "preview" | "preview frame" | "preview clip" | "preview contact-sheet" | "subtitles export" | "probe" | "extract-frame" | "separate-dialogue" | "online search" | "online download" | "doctor" | "models inspect" | "models install" | "models remove" | "system inspect";
163
+ command: "mix analyze" | "package" | "package verify" | "build inspect" | "validate" | "inspect" | "recipes inspect" | "recipes validate" | "timeline inspect" | "render" | "batch" | "preview" | "preview frame" | "preview clip" | "preview contact-sheet" | "subtitles export" | "probe" | "extract-frame" | "separate-dialogue" | "online search" | "online download" | "doctor" | "models inspect" | "models install" | "models remove" | "system inspect";
157
164
  file: string;
158
165
  };
159
166
  export declare function printHelp(positionals: string[], json: boolean | undefined): void;
package/dist/commands.js CHANGED
@@ -6,6 +6,9 @@ const optionTypes = {
6
6
  ...processingOptionTypes,
7
7
  ...renderOptionTypes,
8
8
  'picture-cache': { type: 'string' },
9
+ 'mix-settings': { type: 'string' },
10
+ 'mix-comparison': { type: 'string' },
11
+ 'mix-cache': { type: 'string' },
9
12
  output: { type: 'string', short: 'o' },
10
13
  root: { type: 'string' },
11
14
  resource: { type: 'string', multiple: true },
@@ -35,7 +38,20 @@ const definition = '<definition.video.ts>';
35
38
  const params = '[--params <params.json>]';
36
39
  const position = '(--frame <n> | --timestamp <time>)';
37
40
  const previewOptions = ['quality', ...Object.keys(processingOptionTypes)];
41
+ const mixOptions = ['mix-settings', 'mix-comparison', 'mix-cache'];
42
+ const mixUsage = '[--mix-settings <mix.json>] [--mix-comparison <before|after>] [--mix-cache <directory>]';
38
43
  const commands = {
44
+ 'mix analyze': {
45
+ args: `${definition} ${mixUsage} ${params}`,
46
+ options: [
47
+ 'params',
48
+ 'audio-rate',
49
+ 'audio-channels',
50
+ 'audio-bitrate',
51
+ ...mixOptions,
52
+ ...Object.keys(processingOptionTypes),
53
+ ],
54
+ },
39
55
  package: {
40
56
  args: `${definition} --output <new-directory> [--root <directory>] [--resource <path> ...] ${params}`,
41
57
  options: ['output', 'root', 'resource', 'params'],
@@ -66,11 +82,12 @@ const commands = {
66
82
  options: ['frame', 'timestamp', 'quality', 'params'],
67
83
  },
68
84
  render: {
69
- args: `${definition} --output <new.mp4> [--picture-cache <directory>] ${qualityOption} ${params}`,
85
+ args: `${definition} --output <new.mp4> [--picture-cache <directory>] ${qualityOption} ${mixUsage} ${params}`,
70
86
  options: [
71
87
  'output',
72
88
  'params',
73
89
  'picture-cache',
90
+ ...mixOptions,
74
91
  ...Object.keys(renderOptionTypes),
75
92
  ...Object.keys(processingOptionTypes),
76
93
  ],
@@ -90,8 +107,8 @@ const commands = {
90
107
  ],
91
108
  },
92
109
  preview: {
93
- args: `${definition} --watch [--size <64..1920>] ${qualityOption}`,
94
- options: ['watch', 'size', ...previewOptions],
110
+ args: `${definition} --watch [--size <64..1920>] ${qualityOption} ${mixUsage}`,
111
+ options: ['watch', 'size', ...previewOptions, ...mixOptions],
95
112
  },
96
113
  'preview frame': {
97
114
  args: `${definition} ${position} --output <new.png> [--size <64..1920>] ${qualityOption} ${params}`,
@@ -105,8 +122,16 @@ const commands = {
105
122
  ],
106
123
  },
107
124
  'preview clip': {
108
- args: `${definition} --from <n> --to <n> --output <new.mp4> [--size <64..1920>] ${qualityOption} ${params}`,
109
- options: ['from', 'to', 'output', 'size', 'params', ...previewOptions],
125
+ args: `${definition} --from <n> --to <n> --output <new.mp4> [--size <64..1920>] ${qualityOption} ${mixUsage} ${params}`,
126
+ options: [
127
+ 'from',
128
+ 'to',
129
+ 'output',
130
+ 'size',
131
+ 'params',
132
+ ...previewOptions,
133
+ ...mixOptions,
134
+ ],
110
135
  },
111
136
  'preview contact-sheet': {
112
137
  args: `${definition} --output <new.png> [--from <n>] [--to <n>] [--count <1..16>] [--columns <1..16>] [--size <64..640>] ${qualityOption} ${params}`,
package/dist/index.js CHANGED
@@ -28,6 +28,7 @@ async function run(args) {
28
28
  case 'recipes validate':
29
29
  case 'validate':
30
30
  case 'inspect':
31
+ case 'mix analyze':
31
32
  case 'render': {
32
33
  const { runVideoCommand } = await import('./video.js');
33
34
  return runVideoCommand(command, file, values);
@@ -5,6 +5,7 @@ import { commandUsage } from './commands.js';
5
5
  import { UsageError } from './usage.js';
6
6
  import { withCommandCancellation } from './cancellation.js';
7
7
  import { readParams } from './json-argument.js';
8
+ import { readMixControls } from './mix-options.js';
8
9
  import { loadVideo } from './video.js';
9
10
  function printWatchStatus({ current, ...event }, json) {
10
11
  if (json) {
@@ -46,6 +47,7 @@ export async function runInspectionCommand(command, file, values) {
46
47
  throw new UsageError('--size must be between 64 and 1920.');
47
48
  return withCommandCancellation(async (signal) => {
48
49
  const watcher = await watchVideo(file, {
50
+ ...(await readMixControls(values, signal)),
49
51
  maxDimension,
50
52
  quality,
51
53
  processing,
@@ -104,7 +106,9 @@ export async function runInspectionCommand(command, file, values) {
104
106
  : undefined;
105
107
  const requestedTo = command === 'preview clip' ? integer('to') : undefined;
106
108
  await withCommandCancellation(async (signal) => {
109
+ const { audioMixEdit, ...mixControls } = await readMixControls(values, signal);
107
110
  const video = await loadVideo(file, {
111
+ audioMixEdit,
108
112
  signal,
109
113
  preview: true,
110
114
  quality,
@@ -131,6 +135,7 @@ export async function runInspectionCommand(command, file, values) {
131
135
  })
132
136
  : await tools.clip({ startFrame, endFrame }, values.output, {
133
137
  ...options,
138
+ ...mixControls,
134
139
  onProgress: (progress) => process.stderr.write(values.json
135
140
  ? `${JSON.stringify(progress)}\n`
136
141
  : `${progress.phase}: ${progress.percent.toFixed(1)}%\n`),
@@ -0,0 +1,59 @@
1
+ import type { CommandOptions } from './commands.js';
2
+ export declare function readMixControls(values: CommandOptions, signal: AbortSignal): Promise<{
3
+ audioMixEdit: {
4
+ mix: {
5
+ preset: "natural-cinematic" | "clear-voiceover";
6
+ enabled?: boolean | undefined;
7
+ cleanup?: number | undefined;
8
+ warmth?: number | undefined;
9
+ clarity?: number | undefined;
10
+ consistency?: number | undefined;
11
+ dialogueLufs?: number | undefined;
12
+ highPassHz?: number | undefined;
13
+ eq?: {
14
+ frequency: number;
15
+ q: number;
16
+ db: number;
17
+ }[] | undefined;
18
+ deEsser?: number | undefined;
19
+ compressor?: {
20
+ thresholdDb: number;
21
+ ratio: number;
22
+ attackMs: number;
23
+ releaseMs: number;
24
+ } | undefined;
25
+ ai?: "deepfilternet" | undefined;
26
+ dereverb?: number | undefined;
27
+ matching?: {
28
+ amount: number;
29
+ referenceClip?: string | undefined;
30
+ } | undefined;
31
+ crossfadeMs?: number | undefined;
32
+ ducking?: {
33
+ depthDb?: number | undefined;
34
+ attackMs?: number | undefined;
35
+ holdMs?: number | undefined;
36
+ releaseMs?: number | undefined;
37
+ } | undefined;
38
+ delivery?: {
39
+ preset: "web" | "broadcast" | "film";
40
+ integratedLufs?: number | undefined;
41
+ truePeakDbtp?: number | undefined;
42
+ loudnessRange?: number | undefined;
43
+ } | undefined;
44
+ automation?: {
45
+ dialogue?: Record<string, {
46
+ sample: number;
47
+ db: number;
48
+ }[]> | undefined;
49
+ music?: {
50
+ sample: number;
51
+ db: number;
52
+ }[] | undefined;
53
+ } | undefined;
54
+ } | null;
55
+ roles?: Record<string, "dialogue" | "music" | "other"> | undefined;
56
+ } | undefined;
57
+ audioComparison: "before" | "after" | undefined;
58
+ audioMixCacheDirectory: string | undefined;
59
+ }>;
@@ -0,0 +1,23 @@
1
+ import { videoMixEditSchema } from '@opencut/core/video';
2
+ import { readJsonArgument } from './json-argument.js';
3
+ import { UsageError } from './usage.js';
4
+ export async function readMixControls(values, signal) {
5
+ const comparison = values['mix-comparison'];
6
+ if (comparison !== undefined &&
7
+ comparison !== 'before' &&
8
+ comparison !== 'after')
9
+ throw new UsageError('--mix-comparison must be before or after.');
10
+ const audioMixCacheDirectory = values['mix-cache'];
11
+ if (audioMixCacheDirectory !== undefined && !audioMixCacheDirectory.trim())
12
+ throw new UsageError('--mix-cache requires a directory.');
13
+ const path = values['mix-settings'];
14
+ const audioMixEdit = path === undefined
15
+ ? undefined
16
+ : videoMixEditSchema.parse(await readJsonArgument('mix-settings', path, signal));
17
+ return {
18
+ audioMixEdit,
19
+ audioComparison: comparison,
20
+ audioMixCacheDirectory,
21
+ };
22
+ }
23
+ //# sourceMappingURL=mix-options.js.map
package/dist/system-probe CHANGED
Binary file
package/dist/video.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { compileVideo } from '@opencut/core/video';
2
2
  import { type CommandOptions } from './commands.js';
3
- type VideoCommand = 'validate' | 'inspect' | 'render' | 'recipes inspect' | 'recipes validate';
3
+ type VideoCommand = 'validate' | 'inspect' | 'render' | 'mix analyze' | 'recipes inspect' | 'recipes validate';
4
4
  /** Route console output from trusted TypeScript to stderr during CLI compilation. */
5
5
  export declare function loadVideo(file: string, options: Parameters<typeof compileVideo>[1]): Promise<import("@opencut/core/video").CompiledVideo>;
6
6
  export declare function withDefinitionConsole<T>(run: () => Promise<T>): Promise<T>;
package/dist/video.js CHANGED
@@ -1,11 +1,12 @@
1
1
  import { Console } from 'node:console';
2
- import { compileVideo, inspectProject, inspectVideoRecipes, isVideoDefinitionPath, renderCompiledVideo, } from '@opencut/core/video';
2
+ import { analyzeVideoMix, compileVideo, inspectProject, inspectVideoRecipes, isVideoDefinitionPath, renderCompiledVideo, } from '@opencut/core/video';
3
3
  import { withCommandCancellation } from './cancellation.js';
4
4
  import { commandUsage } from './commands.js';
5
5
  import { parseProcessingControls } from './recipe-options.js';
6
6
  import { UsageError } from './usage.js';
7
7
  import { readParams } from './json-argument.js';
8
8
  import { parseRenderControls, parseRenderQuality } from './render-options.js';
9
+ import { readMixControls } from './mix-options.js';
9
10
  /** Route console output from trusted TypeScript to stderr during CLI compilation. */
10
11
  export function loadVideo(file, options) {
11
12
  return withDefinitionConsole(() => compileVideo(file, options));
@@ -29,7 +30,9 @@ export async function runVideoCommand(command, file, values) {
29
30
  const pictureCacheDirectory = values['picture-cache'];
30
31
  if (pictureCacheDirectory !== undefined && !pictureCacheDirectory.trim())
31
32
  throw new UsageError('--picture-cache requires a directory.');
32
- const controls = command === 'render' ? parseRenderControls(values) : {};
33
+ const controls = command === 'render' || command === 'mix analyze'
34
+ ? parseRenderControls(values)
35
+ : {};
33
36
  await withCommandCancellation(async (signal) => {
34
37
  const params = await readParams(values.params, signal);
35
38
  if (command === 'recipes inspect' || command === 'recipes validate') {
@@ -58,14 +61,24 @@ export async function runVideoCommand(command, file, values) {
58
61
  process.stderr.write(`recipe ${event.assetId} step ${event.step + 1}: ${event.status}${time}\n`);
59
62
  }
60
63
  };
64
+ const { audioMixEdit, ...mixControls } = await readMixControls(values, signal);
61
65
  const video = await loadVideo(file, {
62
66
  signal,
63
67
  params,
64
68
  preview: controls.burnSubtitles === false,
65
69
  quality: controls.quality,
66
70
  processing,
71
+ audioMixEdit,
67
72
  });
68
- if (command === 'validate') {
73
+ if (command === 'mix analyze') {
74
+ const report = await analyzeVideoMix(video, {
75
+ ...controls,
76
+ ...mixControls,
77
+ signal,
78
+ });
79
+ console.log(JSON.stringify(report, null, 2));
80
+ }
81
+ else if (command === 'validate') {
69
82
  const result = {
70
83
  ok: true,
71
84
  path: video.path,
@@ -85,6 +98,7 @@ export async function runVideoCommand(command, file, values) {
85
98
  const result = await renderCompiledVideo(video, output, {
86
99
  ...controls,
87
100
  pictureCacheDirectory,
101
+ ...mixControls,
88
102
  signal,
89
103
  ...(!values.json && {
90
104
  onProgress: (event) => {
@@ -104,6 +118,10 @@ export async function runVideoCommand(command, file, values) {
104
118
  for (const { startFrame, endFrame, status } of result.pictureRanges ??
105
119
  [])
106
120
  console.log(`Picture [${startFrame}, ${endFrame}): ${status}`);
121
+ if (result.audioMix) {
122
+ const { integratedLufs, truePeakDbtp } = result.audioMix.output;
123
+ console.log(`Audio ${integratedLufs ?? 'unmeasurable'} LUFS / ${truePeakDbtp ?? 'unmeasurable'} dBTP`);
124
+ }
107
125
  console.log(`Saved ${result.frameCount} frames to ${result.path}`);
108
126
  }
109
127
  }
@@ -0,0 +1,132 @@
1
+ # Professional Dialogue Mix
2
+
3
+ Enable the mixer by adding `professionalMix` to a `.video.ts` definition. Assign `audioRole: 'dialogue'` to spoken tracks and `audioRole: 'music'` to music tracks. Audio and video tracks both support roles. Unassigned tracks and tracks marked `other` retain their original mix routing. Authored mute, gain, fades, effects and playback speed still apply.
4
+
5
+ **Natural Cinematic Dialogue** uses lighter cleanup and dynamics processing suitable for interviews and narrative work. **Clear Professional Voiceover** uses stronger cleanup, presence, consistency and music ducking.
6
+
7
+ In OpenCut Review, select **Create dialogue mix** to choose dialogue recordings,
8
+ optional music and an optional picture. The import writes a new definition
9
+ that references your original files. Open **Professional Dialogue Mix** to
10
+ adjust routing and settings, then select **Apply to preview**.
11
+
12
+ **Compare before** targets the last applied mix’s measured loudness when
13
+ playing the original mix and honors the delivery true-peak ceiling.
14
+ **Compare after** returns to the applied mix. Both preserve your draft edits. **Export MP4** renders the
15
+ applied mix even while **Compare before** is playing.
16
+
17
+ Switch off **Enable mix** and apply to bypass processing. **Reset to definition**
18
+ restores the settings from the authored file. **Save mix settings** writes the
19
+ current draft to JSON. Use **Load mix settings** followed by **Apply to preview**
20
+ to use it in OpenCut Review, or pass the JSON to the CLI or SDK.
21
+
22
+ ## Definition
23
+
24
+ ```ts
25
+ import { defineVideo } from '@dantea/opencut/sdk';
26
+
27
+ export default defineVideo({
28
+ canvas: { width: 1920, height: 1080, frameRate: 30, durationFrames: 300 },
29
+ assets: {
30
+ spoken: { path: 'voice.wav', kind: 'audio' },
31
+ score: { path: 'music.flac', kind: 'audio' },
32
+ },
33
+ tracks: [
34
+ {
35
+ id: 'speech',
36
+ type: 'audio',
37
+ audioRole: 'dialogue',
38
+ clips: [{ id: 'voice-take', asset: 'spoken', at: 30, sourceOut: 210 }],
39
+ },
40
+ {
41
+ id: 'music',
42
+ type: 'audio',
43
+ audioRole: 'music',
44
+ volume: 0.5,
45
+ clips: [{ asset: 'score', at: 0, sourceOut: 300 }],
46
+ },
47
+ ],
48
+ professionalMix: {
49
+ preset: 'natural-cinematic',
50
+ cleanup: 0.45,
51
+ clarity: 0.35,
52
+ ducking: { depthDb: 12, attackMs: 180, holdMs: 300, releaseMs: 700 },
53
+ delivery: { preset: 'broadcast' },
54
+ },
55
+ });
56
+ ```
57
+
58
+ ## Advanced settings
59
+
60
+ | Field | Behavior |
61
+ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | `preset`, `enabled` | Choose `natural-cinematic` or `clear-voiceover`. Use `enabled: false` to bypass the mixer and delivery processing. |
63
+ | `cleanup`, `warmth`, `clarity`, `consistency` | Intensities from 0 to 1. Cleanup adapts spectral reduction to estimated floor and applies gentle downward expansion. The leveling intensity scales gain corrections in detected phrases. |
64
+ | `highPassHz`, `eq`, `deEsser` | High-pass cutoff in Hz (0–250, 0 disables it), up to eight parametric EQ bands (`frequency`, `q`, `db`), and de-essing intensity (0–1). |
65
+ | `compressor` | Set `thresholdDb`, `ratio`, `attackMs`, `releaseMs`. A ratio of 1 bypasses compression. Limiting and delivery headroom remain active. |
66
+ | `dialogueLufs`, `matching` | Set the internal phrase target or let the preset choose. `matching.amount` (0–1) scales tonal matching. Set `matching.referenceClip` to the ID of an audible dialogue clip to use its tone and inform the default leveling target. |
67
+ | `crossfadeMs` | Range 0–250 ms. Adjacent same-track dialogue clips use available source handles for equal-power overlap. OpenCut keeps the incoming dialogue in sync with its picture. When handles are unavailable it uses short edge fades. Authored fades take precedence. |
68
+ | `ducking` | `depthDb` (0–36), `attackMs` (20–2000), `holdMs` (0–5000) and `releaseMs` (50–5000). The music bus starts fading ahead of detected speech and stays down through short pauses. |
69
+ | `ai`, `dereverb` | `ai: 'deepfilternet'` selects local speech enhancement in place of spectral noise reduction. `dereverb` (0–1) attenuates low-level tails and can reduce light room sound. Strong reflections overlapping speech may remain. |
70
+ | `delivery` | Choose a delivery preset and optionally override `integratedLufs` (−40 to −8), `truePeakDbtp` (−8 to −0.1) and `loudnessRange` (1–50 LU). |
71
+ | `automation` | Save or edit the generated `dialogue` and `music` curves. |
72
+
73
+ Detection uses short K-weighted energy windows on tracks assigned to dialogue.
74
+ A brief phrase that rises clearly above steady room tone can trigger ducking
75
+ even when most of the clip is quiet. Overlapping speech from multiple dialogue
76
+ tracks contributes to the shared music curve. For whispers or other sounds near
77
+ the estimated noise floor, fine-tune the generated curves or author them directly.
78
+
79
+ The mixer reports `automation.dialogue` by clip ID and `automation.music` for the
80
+ whole music bus. Each point is `{ sample, db }` on a 48 kHz clock. Dialogue
81
+ samples are relative to the clip’s authored timeline start. Music samples are
82
+ relative to the start of the project. Keys interpolate in dB and hold the
83
+ closest value outside the key range. Supply a curve to replace automatic
84
+ analysis for that clip or bus. Supply `[]` to disable that curve. Omit the entry
85
+ to regenerate it. The mixer combines these curves with the original fades and
86
+ gain keys.
87
+
88
+ To reuse the generated curves, copy the report’s `automation` object into
89
+ `professionalMix.automation` in the definition or `mix.automation` in a mix
90
+ settings file. In OpenCut Review, select **Use analyzed curves** under
91
+ **Advanced settings and automation** to copy the curves into the draft.
92
+
93
+ ## Delivery and inspection
94
+
95
+ | Delivery | Integrated target | True-peak ceiling | Loudness range target |
96
+ | --------- | ----------------: | ----------------: | --------------------: |
97
+ | Web | −16 LUFS | −1.5 dBTP | 12 LU |
98
+ | Broadcast | −23 LUFS | −1 dBTP | 15 LU |
99
+ | Film | −24 LUFS | −2 dBTP | 20 LU |
100
+
101
+ OpenCut measures integrated loudness, loudness range and true peak, applies gain or second-pass dynamic normalization as needed, then checks true peak on decoded AAC. The render report contains the measured input and output, targets, normalization mode and any loudness deviations. Very short or silent mixes may lack a measurable integrated value. The peak ceiling takes precedence when the configured goals compete. Composition and delivery use the same full timeline in preview and export. A range preview trims the normalized audio to the requested interval. AAC output supports mono or stereo, 44.1 or 48 kHz, using FFmpeg’s normal channel conversion for other input layouts.
102
+
103
+ ```sh
104
+ opencut mix analyze lesson.video.ts --json
105
+ opencut render lesson.video.ts --output lesson.mp4 --json
106
+ opencut render lesson.video.ts --output comparison.mp4 --mix-comparison before
107
+ opencut preview clip lesson.video.ts --from 30 --to 150 --output preview.mp4
108
+ opencut render lesson.video.ts --output revision.mp4 --mix-settings mix.json
109
+ ```
110
+
111
+ `mix analyze` reports the same data as `render --json` without composing or encoding picture. `--mix-settings` accepts `{ "mix": { "preset": "natural-cinematic" }, "roles": { "speech": "dialogue" } }`. Set `mix` to `null` to render through the standard audio path. The settings file does not change the source definition. `--mix-comparison before` produces the loudness-matched original mix. The same controls apply to `preview --watch` and `preview clip`.
112
+
113
+ ```ts
114
+ import {
115
+ analyzeVideoMix,
116
+ compileVideo,
117
+ renderCompiledVideo,
118
+ } from '@dantea/opencut/sdk';
119
+
120
+ const video = await compileVideo('lesson.video.ts');
121
+ const report = await analyzeVideoMix(video);
122
+ const rendered = await renderCompiledVideo(video, 'lesson.mp4');
123
+ console.log(report.automation, rendered.audioMix?.output);
124
+ ```
125
+
126
+ Pass `audioMixEdit` to `compileVideo` or `renderVideo` for the same JSON override. Set `audioComparison: 'before'` on analysis, render or clip preview for A/B playback.
127
+
128
+ ## Local enhancement and caching
129
+
130
+ The two presets require only OpenCut’s existing FFmpeg installation. To enable [DeepFilterNet](https://github.com/Rikorose/DeepFilterNet), install its native `deep-filter` executable separately. OpenCut uses it on local 48 kHz audio with compensation for its model delay. The executable can be on PATH or set via the absolute `OPENCUT_DEEPFILTER` path. Set `OPENCUT_DEEPFILTER_MODEL` to use a compatible local model archive when the executable lacks a built-in model or when choosing a different one. The mixer runs without network access. An explicitly selected backend that cannot run produces an error so the same settings do not silently render with a different backend.
131
+
132
+ OpenCut reuses analyzed clip profiles within a process. For persistent AI-enhanced stems, pass `--mix-cache <directory>` to CLI commands or `audioMixCacheDirectory` to SDK analysis, render and video preview. Desktop previews reuse enhanced stems during an open review session. Cached stems contain processed audio. Keep the cache private when working with private recordings and remove it when it is no longer needed.
package/docs/CLI.md CHANGED
@@ -308,6 +308,8 @@ the batch budgets evenly across active slots. Recipe overrides may lower a
308
308
  slot's limits. The temporary budget covers staging for recipes and renders,
309
309
  including copied sources, layer intermediates, and the unfinished MP4.
310
310
  Published outputs and completed cache entries consume persistent disk space.
311
+ For Professional Dialogue Mix, DeepFilterNet counts toward the slot’s native RSS
312
+ budget, and the temporary file-size limit applies while it writes its staged WAV.
311
313
  OpenCut samples native child-process RSS with its bundled, unprivileged
312
314
  sampler on macOS and with `/bin/ps` on Linux. It also caps FFmpeg
313
315
  allocation sizes. If sampling fails, the render or recipe stops and
@@ -362,3 +364,7 @@ temporal comparison scores differences between consecutive pictures against
362
364
  the same differences in the reference. Review the MP4s for motion artifacts.
363
365
  Check each case's `exitCode` in `benchmark.json`. The harness records diagnostics
364
366
  for unsuccessful cases and runs the rest of the matrix.
367
+
368
+ ## Professional Dialogue Mix
369
+
370
+ Use `opencut mix analyze <definition.video.ts> --json` to obtain editable automation and measured loudness without rendering picture. `render`, `preview --watch` and `preview clip` use the mix authored in the definition. See [mix settings, overrides and comparison options](AUDIO_MIX.md#delivery-and-inspection).
package/docs/INSTALL.md CHANGED
@@ -17,7 +17,7 @@ pnpm dlx @dantea/opencut --help
17
17
  You can also install the packed archive directly.
18
18
 
19
19
  ```sh
20
- pnpm add -g ./opencut-cli-0.1.3-macos-arm64.tgz
20
+ pnpm add -g ./opencut-cli-0.2.0-macos-arm64.tgz
21
21
  ```
22
22
 
23
23
  Run the CLI from any directory. A definition can import `@opencut/sdk` and
package/docs/SDK.md CHANGED
@@ -207,3 +207,7 @@ to stop on a variant failure. An exception from `onProgress` cancels the batch
207
207
  and rejects the call after cleanup. Invalid manifests and duplicate output
208
208
  paths reject before the scheduler starts. See the [batch limits and file
209
209
  contract](CLI.md#batch-rendering).
210
+
211
+ ## Professional Dialogue Mix
212
+
213
+ Call `analyzeVideoMix(compiledVideo, options)` to generate dialogue and music curves and verify delivery loudness without rendering picture. Mix-enabled export and clip preview results include `audioMix`. See [definition and SDK examples](AUDIO_MIX.md).
@@ -530,3 +530,7 @@ under `project/`. Render the generated `opencut.bundle.video.ts` at the
530
530
  package root.
531
531
  A named font file travels with the bundle. The receiving machine supplies
532
532
  OpenCut, FFmpeg and any system AI backends required by the recipes.
533
+
534
+ ## Professional Dialogue Mix
535
+
536
+ `professionalMix` enables dialogue cleanup, editable gain automation, music ducking and output loudness management. Set `audioRole` on audio or video tracks to route them as `dialogue`, `music` or `other`. See [settings and examples](AUDIO_MIX.md).
@@ -28,3 +28,4 @@ export type { SubtitleCue, SubtitleCueInput, SubtitleStyle, SubtitleTrack, } fro
28
28
  export type { AnimatedProperty, KeyframeEasing, VisualKeyframe, VisualKeyframes, } from '@opencut/shared';
29
29
  export { defineVideo } from './video-definition.js';
30
30
  export type { VideoDefinition } from './video-definition.js';
31
+ export { deliveryTargets, dialoguePresetControls } from '@opencut/shared';
@@ -14,4 +14,5 @@ export { inspectProject, inspectTimeline, projectInspectionSchema, timelineInspe
14
14
  export { SubtitleError, parseSubtitles, serializeSubtitles, subtitleFormat, parseSubtitleTime, } from './subtitle-formats.js';
15
15
  export { effectiveSubtitleStyle, sortSubtitleCues, subtitleLanes, subtitleTextLayers, } from './subtitles.js';
16
16
  export { defineVideo } from './video-definition.js';
17
+ export { deliveryTargets, dialoguePresetControls } from '@opencut/shared';
17
18
  //# sourceMappingURL=index.js.map
@@ -71,6 +71,11 @@ export declare const projectInspectionSchema: z.ZodObject<{
71
71
  }, z.core.$strict>>;
72
72
  }, z.core.$strict>>;
73
73
  tracks: z.ZodArray<z.ZodObject<{
74
+ audioRole: z.ZodOptional<z.ZodEnum<{
75
+ dialogue: "dialogue";
76
+ music: "music";
77
+ other: "other";
78
+ }>>;
74
79
  volume: z.ZodOptional<z.ZodNumber>;
75
80
  muted: z.ZodOptional<z.ZodBoolean>;
76
81
  id: z.ZodString;
@@ -369,6 +374,64 @@ export declare const projectInspectionSchema: z.ZodObject<{
369
374
  frame: z.ZodInt;
370
375
  name: z.ZodString;
371
376
  }, z.core.$strict>>>;
377
+ professionalMix: z.ZodOptional<z.ZodObject<{
378
+ preset: z.ZodEnum<{
379
+ "natural-cinematic": "natural-cinematic";
380
+ "clear-voiceover": "clear-voiceover";
381
+ }>;
382
+ enabled: z.ZodOptional<z.ZodBoolean>;
383
+ cleanup: z.ZodOptional<z.ZodNumber>;
384
+ warmth: z.ZodOptional<z.ZodNumber>;
385
+ clarity: z.ZodOptional<z.ZodNumber>;
386
+ consistency: z.ZodOptional<z.ZodNumber>;
387
+ dialogueLufs: z.ZodOptional<z.ZodNumber>;
388
+ highPassHz: z.ZodOptional<z.ZodNumber>;
389
+ eq: z.ZodOptional<z.ZodArray<z.ZodObject<{
390
+ frequency: z.ZodNumber;
391
+ q: z.ZodNumber;
392
+ db: z.ZodNumber;
393
+ }, z.core.$strict>>>;
394
+ deEsser: z.ZodOptional<z.ZodNumber>;
395
+ compressor: z.ZodOptional<z.ZodObject<{
396
+ thresholdDb: z.ZodNumber;
397
+ ratio: z.ZodNumber;
398
+ attackMs: z.ZodNumber;
399
+ releaseMs: z.ZodNumber;
400
+ }, z.core.$strict>>;
401
+ ai: z.ZodOptional<z.ZodLiteral<"deepfilternet">>;
402
+ dereverb: z.ZodOptional<z.ZodNumber>;
403
+ matching: z.ZodOptional<z.ZodObject<{
404
+ amount: z.ZodNumber;
405
+ referenceClip: z.ZodOptional<z.ZodString>;
406
+ }, z.core.$strict>>;
407
+ crossfadeMs: z.ZodOptional<z.ZodNumber>;
408
+ ducking: z.ZodOptional<z.ZodObject<{
409
+ depthDb: z.ZodOptional<z.ZodNumber>;
410
+ attackMs: z.ZodOptional<z.ZodNumber>;
411
+ holdMs: z.ZodOptional<z.ZodNumber>;
412
+ releaseMs: z.ZodOptional<z.ZodNumber>;
413
+ }, z.core.$strict>>;
414
+ delivery: z.ZodOptional<z.ZodObject<{
415
+ preset: z.ZodEnum<{
416
+ web: "web";
417
+ broadcast: "broadcast";
418
+ film: "film";
419
+ }>;
420
+ integratedLufs: z.ZodOptional<z.ZodNumber>;
421
+ truePeakDbtp: z.ZodOptional<z.ZodNumber>;
422
+ loudnessRange: z.ZodOptional<z.ZodNumber>;
423
+ }, z.core.$strict>>;
424
+ automation: z.ZodOptional<z.ZodObject<{
425
+ dialogue: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
426
+ sample: z.ZodInt;
427
+ db: z.ZodNumber;
428
+ }, z.core.$strict>>>>;
429
+ music: z.ZodOptional<z.ZodArray<z.ZodObject<{
430
+ sample: z.ZodInt;
431
+ db: z.ZodNumber;
432
+ }, z.core.$strict>>>;
433
+ }, z.core.$strict>>;
434
+ }, z.core.$strict>>;
372
435
  inspectionVersion: z.ZodLiteral<1>;
373
436
  path: z.ZodString;
374
437
  duration: z.ZodObject<{
@@ -1519,6 +1582,7 @@ export declare function inspectProject(project: Project, path: string): {
1519
1582
  id: string;
1520
1583
  name: string;
1521
1584
  type: "video" | "audio";
1585
+ audioRole?: "dialogue" | "music" | "other" | undefined;
1522
1586
  volume?: number | undefined;
1523
1587
  muted?: boolean | undefined;
1524
1588
  }[];
@@ -1781,6 +1845,57 @@ export declare function inspectProject(project: Project, path: string): {
1781
1845
  frame: number;
1782
1846
  name: string;
1783
1847
  }[] | undefined;
1848
+ professionalMix?: {
1849
+ preset: "natural-cinematic" | "clear-voiceover";
1850
+ enabled?: boolean | undefined;
1851
+ cleanup?: number | undefined;
1852
+ warmth?: number | undefined;
1853
+ clarity?: number | undefined;
1854
+ consistency?: number | undefined;
1855
+ dialogueLufs?: number | undefined;
1856
+ highPassHz?: number | undefined;
1857
+ eq?: {
1858
+ frequency: number;
1859
+ q: number;
1860
+ db: number;
1861
+ }[] | undefined;
1862
+ deEsser?: number | undefined;
1863
+ compressor?: {
1864
+ thresholdDb: number;
1865
+ ratio: number;
1866
+ attackMs: number;
1867
+ releaseMs: number;
1868
+ } | undefined;
1869
+ ai?: "deepfilternet" | undefined;
1870
+ dereverb?: number | undefined;
1871
+ matching?: {
1872
+ amount: number;
1873
+ referenceClip?: string | undefined;
1874
+ } | undefined;
1875
+ crossfadeMs?: number | undefined;
1876
+ ducking?: {
1877
+ depthDb?: number | undefined;
1878
+ attackMs?: number | undefined;
1879
+ holdMs?: number | undefined;
1880
+ releaseMs?: number | undefined;
1881
+ } | undefined;
1882
+ delivery?: {
1883
+ preset: "web" | "broadcast" | "film";
1884
+ integratedLufs?: number | undefined;
1885
+ truePeakDbtp?: number | undefined;
1886
+ loudnessRange?: number | undefined;
1887
+ } | undefined;
1888
+ automation?: {
1889
+ dialogue?: Record<string, {
1890
+ sample: number;
1891
+ db: number;
1892
+ }[]> | undefined;
1893
+ music?: {
1894
+ sample: number;
1895
+ db: number;
1896
+ }[] | undefined;
1897
+ } | undefined;
1898
+ } | undefined;
1784
1899
  };
1785
1900
  /** Point inspection uses the exact evaluator consumed by the Project viewer. */
1786
1901
  export declare function inspectTimeline(project: Project, path: string, frame: number): {