@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,9 +1,11 @@
1
+ import { prepareProfessionalMix } from './professional-mix.js';
2
+ import { audioSampleAtFrame, buildAudioGraph } from './audio-graph.js';
1
3
  import { decodeStillFrame } from './frame.js';
2
- import { canvasColorPattern, opaqueCanvasColor, visualGeometry, sourceColorMatrix, usesLayerTransform, maximumVisualScale, roomEchoes, } from '@opencut/shared';
4
+ import { canvasColorPattern, opaqueCanvasColor, visualGeometry, sourceColorMatrix, usesLayerTransform, maximumVisualScale, } from '@opencut/shared';
3
5
  import { access, link, lstat, mkdtemp, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
4
6
  import { constants } from 'node:fs';
5
7
  import { dirname, extname, join, resolve } from 'node:path';
6
- import { probeMedia, isStillImage, videoSourceDuration, audioSourceDuration, } from './probe.js';
8
+ import { probeMedia, isStillImage, videoSourceDuration } from './probe.js';
7
9
  import { checkRenderSignal, MediaError, runMediaTool } from './process.js';
8
10
  import { accountRenderBytes, accountRenderFile } from './render-budget.js';
9
11
  import { renderQualities, renderQualityProfiles } from '@opencut/shared';
@@ -94,27 +96,6 @@ function validateOptions(options) {
94
96
  !validAudioFades(clip, numerator, denominator)))
95
97
  throw new MediaError('Invalid video render plan: use positive integer frame counts, even sides up to 3840 (at most 3840x2160 pixels), 1–120 fps, at most 64 non-subtitle visual/audio clips (or 128 legacy segments), valid transforms and #RRGGBB[AA]/transparent background, and 600 seconds.');
96
98
  }
97
- function gainExpression(keys) {
98
- const first = keys[0];
99
- const intervals = [{ end: first.sample, value: String(first.value) }];
100
- for (let i = 1; i < keys.length; i++) {
101
- const left = keys[i - 1];
102
- const right = keys[i];
103
- if (right.sample > left.sample)
104
- intervals.push({
105
- end: right.sample,
106
- value: `${left.value}+(${right.value}-${left.value})*(n-${left.sample})/${right.sample - left.sample}`,
107
- });
108
- }
109
- intervals.push({ end: Infinity, value: String(keys.at(-1).value) });
110
- function build(start, end) {
111
- if (end - start === 1)
112
- return intervals[start].value;
113
- const middle = Math.floor((start + end) / 2);
114
- return `if(lt(n,${intervals[middle - 1].end}),${build(start, middle)},${build(middle, end)})`;
115
- }
116
- return build(0, intervals.length);
117
- }
118
99
  function validRational(time) {
119
100
  return (!!time &&
120
101
  Number.isSafeInteger(time.numerator) &&
@@ -366,6 +347,7 @@ async function prepareTimeline(options, mode = 'mp4', scratch, checkPictureSeek)
366
347
  stagedInputs,
367
348
  encoders,
368
349
  pictureRanges: undefined,
350
+ audioMix: undefined,
369
351
  };
370
352
  const filters = [];
371
353
  const sources = new Map(options.sourceMetadata);
@@ -757,207 +739,43 @@ async function prepareTimeline(options, mode = 'mp4', scratch, checkPictureSeek)
757
739
  args.push('-map_metadata', '-1', '-an', '-c:v', 'ffv1', '-level', '3', '-threads', '2', '-fps_mode', 'passthrough', '-enc_time_base:v', `1/${numerator}`, '-f', 'nut');
758
740
  return prepared;
759
741
  }
760
- // Round absolute project boundaries to the nearest 48 kHz sample. Never sum
761
- // independently rounded durations: fractional frame rates must not accumulate drift.
762
- const sample = (frame, rate = frameRate, offset, sign = 1n) => {
763
- const scale = BigInt(offset?.denominator ?? 1);
764
- const divisor = BigInt(rate.numerator) * scale;
765
- const n = (BigInt(frame) * BigInt(rate.denominator) * scale +
766
- sign * BigInt(offset?.numerator ?? 0) * BigInt(rate.numerator)) *
767
- 48000n;
768
- return Number((2n * n + divisor) / (2n * divisor));
769
- };
770
- const sampleTime = (time, offset, sign = 1n) => sample(time.numerator, { numerator: time.denominator, denominator: 1 }, offset, sign);
771
- const totalSamples = options.range
772
- ? sample(frameCount)
773
- : sample(outputFrameCount, outputRate);
774
- const audioLabels = ['[silence]'];
775
- filters.push(`anullsrc=r=48000:cl=stereo,atrim=end_sample=${totalSamples},asettb=1/48000,asetpts=N[silence]`);
776
- const timelineSample = (clip, edge, fade) => {
777
- const sign = edge === 'start' ? 1n : -1n;
778
- if (clip.retiming) {
779
- const time = edge === 'start'
780
- ? clip.retiming.timelineStart
781
- : clip.retiming.timelineEnd;
782
- return sampleTime(time, fade, sign);
783
- }
784
- const frame = clip.timelineStartFrame + (edge === 'start' ? 0 : clip.frameCount);
785
- return sample(frame, frameRate, fade, sign);
786
- };
787
- const effectChain = (clip, count) => {
788
- const filters = [];
789
- const linear = (db) => 10 ** (db / 20);
790
- for (const effect of clip.effects ?? []) {
791
- switch (effect.type) {
792
- case 'eq':
793
- filters.push(`equalizer=f=${effect.frequency}:width_type=q:w=1:g=${effect.db}`);
794
- break;
795
- case 'compressor':
796
- filters.push(`acompressor=threshold=${linear(effect.threshold)}:ratio=${effect.ratio}:attack=5:release=100`);
797
- break;
798
- case 'limiter':
799
- filters.push(`alimiter=limit=${linear(effect.ceiling)}:level=0:latency=1`);
800
- break;
801
- case 'de-esser':
802
- if (effect.amount)
803
- filters.push(`deesser=i=${effect.amount}:m=0.5:f=0.5`);
804
- break;
805
- case 'reverb':
806
- if (effect.mix)
807
- filters.push(`aecho=1:1:${roomEchoes.map((echo) => echo.seconds * 1000).join('|')}:${roomEchoes.map((echo) => echo.gain * effect.mix).join('|')}`, `atrim=end_sample=${count}`);
808
- break;
809
- }
810
- }
811
- return filters.length ? filters.join(',') + ',' : '';
812
- };
813
- const envelope = (clip, start, end) => {
814
- const filters = [];
815
- if (clip.fadeIn) {
816
- const length = timelineSample(clip, 'start', clip.fadeIn.duration) - start;
817
- if (length > 0)
818
- filters.push(`afade=t=in:ss=0:ns=${length}:c=tri:silence=${clip.fadeIn.from}:unity=${clip.fadeIn.to}`);
819
- }
820
- if (clip.fadeOut) {
821
- const release = timelineSample(clip, 'end', clip.fadeOut.duration);
822
- if (end > release)
823
- filters.push(`afade=t=out:ss=${release - start}:ns=${end - release}:c=tri:silence=${clip.fadeOut.to}:unity=${clip.fadeOut.from}`);
824
- }
825
- filters.push(`volume=${clip.muted ? 0 : clip.volume}`);
826
- if (clip.gainKeys?.length) {
827
- const keys = clip.gainKeys.map(({ time, value }) => ({
828
- sample: timelineSample(clip, 'start', time) - start,
829
- value,
830
- }));
831
- const expression = gainExpression(keys);
832
- filters.push(`aeval='val(0)*${expression}|val(1)*${expression}':c=stereo`);
833
- }
834
- return filters.join(',');
835
- };
836
- const runs = [];
837
- for (const clip of options.audioClips ?? []) {
838
- const run = runs.at(-1);
839
- const previous = run?.at(-1);
840
- if (run &&
841
- previous?.retiming &&
842
- clip.retiming &&
843
- clip.tempoRunId !== undefined &&
844
- clip.tempoRunId === previous.tempoRunId &&
845
- clip.path === previous.path &&
846
- clip.required === previous.required &&
847
- clip.padAudio === previous.padAudio &&
848
- JSON.stringify(clip.effects ?? []) ===
849
- JSON.stringify(previous.effects ?? []) &&
850
- timeDifference(previous.retiming.timelineEnd, clip.retiming.timelineStart) === 0n &&
851
- timeDifference(previous.retiming.sourceOut, clip.retiming.sourceIn) ===
852
- 0n &&
853
- timeDifference(previous.retiming.speed, clip.retiming.speed) === 0n)
854
- run.push(clip);
855
- else
856
- runs.push([clip]);
742
+ const from = audioSampleAtFrame(startFrame, frameRate);
743
+ const to = options.range
744
+ ? from + audioSampleAtFrame(outputFrameCount, outputRate)
745
+ : audioSampleAtFrame(outputFrameCount, outputRate);
746
+ const mix = options.professionalMix;
747
+ let audioMap = '[audio]';
748
+ if (mix && mix.enabled !== false && scratch) {
749
+ const result = await prepareProfessionalMix(options, mix, await scratch.open(), readSource, {
750
+ base: audioSampleAtFrame(frameCount, frameRate),
751
+ from,
752
+ to,
753
+ });
754
+ prepared.audioMix = result.report;
755
+ warnings.push(...result.report.warnings);
756
+ args.push('-i', result.path);
757
+ audioMap = `${input++}:a:0`;
857
758
  }
858
- for (const [index, run] of runs.entries()) {
859
- const first = run[0];
860
- const last = run.at(-1);
861
- const source = await readSource(first);
862
- const { audio, video } = source;
863
- if (!audio) {
864
- if (first.required)
865
- throw new MediaError(`Clip '${first.clipId}' requires an audio stream. Re-import or relink the audio asset.`);
866
- continue;
867
- }
868
- const origin = video?.startTimeSeconds ??
869
- audio.startTimeSeconds ??
870
- source.startTimeSeconds ??
871
- 0;
872
- const offset = (audio.startTimeSeconds ?? origin) - origin;
873
- const duration = audioSourceDuration(source);
874
- if (last.required &&
875
- !last.padAudio &&
876
- (duration === null ||
877
- (last.retiming
878
- ? seconds(last.retiming.sourceOut)
879
- : ((last.sourceStartFrame + last.frameCount) * denominator) /
880
- numerator) >
881
- duration + 0.000001))
882
- throw new MediaError(`Clip '${last.clipId}' source out exceeds the current audio duration or its duration is unknown. Re-import the media and trim to a known audio range.`);
883
- const pieces = run
884
- .map((clip) => ({
885
- clip,
886
- start: timelineSample(clip, 'start'),
887
- end: timelineSample(clip, 'end'),
888
- }))
889
- .filter(({ start, end }) => end > start);
890
- if (!pieces.some(({ clip }) => !clip.muted && clip.volume > 0))
891
- continue;
892
- const start = pieces[0].start;
893
- const count = pieces.at(-1).end - start;
894
- const sourceStart = first.retiming
895
- ? sampleTime(first.retiming.sourceIn)
896
- : sample(first.sourceStartFrame);
897
- const sourceEnd = last.retiming
898
- ? sampleTime(last.retiming.sourceOut)
899
- : sourceStart + count;
900
- if (sourceEnd <= sourceStart)
901
- continue;
902
- let audioInput = inputs.get(first.clipId);
903
- if (audioInput === undefined) {
904
- audioInput = input++;
905
- args.push('-threads', '1', '-i', await inputPathFor(source.path));
906
- }
907
- const speed = first.retiming ? seconds(first.retiming.speed) : 1;
908
- // Keep one tempo filter across contiguous pieces. Only the run tail needs
909
- // padding to drain the tempo window, and each atempo pass stays within 0.5–2.
910
- const tempo = speed === 1
911
- ? ''
912
- : 'apad=pad_len=4800,' +
913
- (speed < 0.5
914
- ? `atempo=0.5,atempo=${speed * 2},`
915
- : speed > 2
916
- ? `atempo=2,atempo=${speed / 2},`
917
- : `atempo=${speed},`);
918
- const fitDuration = first.retiming
919
- ? `apad,atrim=end_sample=${count},asettb=1/48000,asetpts=N,`
920
- : '';
921
- const inputFilter = `[${audioInput}:${audio.index}]asetpts=PTS-STARTPTS+(${offset.toFixed(9)})/TB,` +
922
- 'aresample=48000:async=1:min_hard_comp=0:first_pts=0,aformat=sample_fmts=fltp:channel_layouts=stereo,' +
923
- `apad,atrim=start_sample=${sourceStart}:end_sample=${sourceEnd},asettb=1/48000,asetpts=N,` +
924
- tempo +
925
- fitDuration +
926
- effectChain(first, count);
927
- const delay = `adelay=${start}S:all=1[a${index}]`;
928
- if (pieces.length === 1) {
929
- const piece = pieces[0];
930
- filters.push(inputFilter +
931
- envelope(piece.clip, piece.start, piece.end) +
932
- ',' +
933
- delay);
934
- }
935
- else {
936
- // Route each sample to its piece once, apply that piece's envelope, then
937
- // join on the sample clock before mixing with other tracks.
938
- const labels = pieces.map((_, i) => `[run${index}p${i}]`);
939
- const boundaries = pieces.slice(1).map((piece) => piece.start - start);
940
- filters.push(inputFilter +
941
- `asegment=samples=${boundaries.join('|')}` +
942
- labels.join(''));
943
- const adjusted = pieces.map((piece, i) => {
944
- const label = `[run${index}g${i}]`;
945
- filters.push(labels[i] +
946
- 'asettb=1/48000,asetpts=N,' +
947
- envelope(piece.clip, piece.start, piece.end) +
948
- label);
949
- return label;
950
- });
951
- filters.push(adjusted.join('') +
952
- `concat=n=${pieces.length}:v=0:a=1,asettb=1/48000,asetpts=N,` +
953
- delay);
954
- }
955
- audioLabels.push(`[a${index}]`);
759
+ else {
760
+ await buildAudioGraph(options, {
761
+ filters,
762
+ readSource,
763
+ inputPathFor,
764
+ openInput: (clip, path) => {
765
+ const existing = inputs.get(clip.clipId);
766
+ if (existing !== undefined)
767
+ return existing;
768
+ args.push('-threads', '1', '-i', path);
769
+ return input++;
770
+ },
771
+ }, {
772
+ total: options.range
773
+ ? audioSampleAtFrame(frameCount, frameRate)
774
+ : audioSampleAtFrame(outputFrameCount, outputRate),
775
+ from,
776
+ to: options.range ? audioSampleAtFrame(endFrame, frameRate) : to,
777
+ });
956
778
  }
957
- // Stable linear gains, independent of the number of active sources. Match the
958
- // existing composer limiter, including latency compensation for sync markers.
959
- filters.push(`${audioLabels.join('')}amix=inputs=${audioLabels.length}:duration=first:normalize=0,` +
960
- `alimiter=limit=0.95:level=0:latency=1,atrim=start_sample=${sample(startFrame)}:end_sample=${options.range ? sample(endFrame) : totalSamples},asettb=1/48000,asetpts=N[audio]`);
961
779
  checkRenderSignal(options.signal);
962
780
  const metadataInput = options.buildMetadata === undefined ? -1 : input;
963
781
  if (options.buildMetadata !== undefined) {
@@ -977,11 +795,22 @@ async function prepareTimeline(options, mode = 'mp4', scratch, checkPictureSeek)
977
795
  },
978
796
  });
979
797
  }
980
- args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]', '-map', '[audio]', '-map_metadata', String(metadataInput), '-c:v', codec === 'h264' ? 'libx264' : 'libx265', '-preset', encoding.preset, ...(videoBitrateKbps === undefined
798
+ args.push('-filter_complex_threads', '1', '-filter_complex', filters.join(';'), '-map', '[video]', '-map', audioMap, '-map_metadata', String(metadataInput), '-c:v', codec === 'h264' ? 'libx264' : 'libx265', '-preset', encoding.preset, ...(videoBitrateKbps === undefined
981
799
  ? ['-crf', encoding.crf]
982
800
  : ['-b:v', `${videoBitrateKbps}k`]), ...(codec === 'hevc'
983
801
  ? ['-x265-params', 'pools=2:log-level=error', '-tag:v', 'hvc1']
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');
802
+ : []), '-pix_fmt', 'yuv420p', '-threads', '2', '-fps_mode', 'passthrough', '-enc_time_base:v', `1/${outputRate.numerator}`, '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-video_track_timescale', String(outputRate.numerator), ...(prepared.audioMix
803
+ ? ['-c:a', 'copy']
804
+ : [
805
+ '-c:a',
806
+ 'aac',
807
+ '-b:a',
808
+ `${audioBitrateKbps}k`,
809
+ '-ar',
810
+ String(audioSampleRate),
811
+ '-ac',
812
+ String(audioChannels),
813
+ ]), '-movflags', metadataInput < 0 ? '+faststart' : '+faststart+use_metadata_tags', '-f', 'mp4');
985
814
  return prepared;
986
815
  }
987
816
  /** Validate the composition and required encoders without populating the picture cache. */
@@ -1126,12 +955,37 @@ export async function renderVideoTimeline(options) {
1126
955
  metadata: { ...metadata, path },
1127
956
  ...(warnings.length ? { warnings } : {}),
1128
957
  ...(prepared.pictureRanges && { pictureRanges: prepared.pictureRanges }),
958
+ ...(prepared.audioMix && { audioMix: prepared.audioMix }),
1129
959
  };
1130
960
  }
1131
961
  finally {
1132
962
  await scratch.close();
1133
963
  }
1134
964
  }
965
+ /** Analyze and verify a mix without composing or encoding picture. */
966
+ export async function analyzeTimelineAudioMix(options) {
967
+ validateOptions(options);
968
+ const mix = options.professionalMix;
969
+ if (!mix || mix.enabled === false)
970
+ throw new MediaError('Enable Professional Dialogue Mix before analyzing.');
971
+ const scratch = renderScratch(options.output, '.opencut-mix-', options.scratchDirectory);
972
+ try {
973
+ const base = audioSampleAtFrame(options.frameCount, options.frameRate);
974
+ const sources = new Map(options.sourceMetadata);
975
+ const result = await prepareProfessionalMix(options, mix, await scratch.open(), async ({ path }) => {
976
+ let metadata = sources.get(path);
977
+ if (!metadata) {
978
+ metadata = await probeMedia(path, options.signal);
979
+ sources.set(path, metadata);
980
+ }
981
+ return metadata;
982
+ }, { base, from: 0, to: base });
983
+ return result.report;
984
+ }
985
+ finally {
986
+ await scratch.close();
987
+ }
988
+ }
1135
989
  /** Lossless frame output from the same RGB compositor used by video exports. */
1136
990
  export async function renderTimelineFrame(options) {
1137
991
  const scratch = renderScratch(options.output, '.opencut-frame-');
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opencut/media",
3
- "version": "0.1.3",
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.3",
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.3",
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.3",
13
- "@opencut/media": "0.1.3"
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.3",
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.3",
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.3",
43
- "@opencut/media": "0.1.3",
44
- "@opencut/sdk": "0.1.3",
45
- "@opencut/shared": "0.1.3",
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",
@@ -63,3 +63,9 @@ discover commands and `opencut render --help` for export controls.
63
63
  Start with the [complete example and visual review loop](references/workflow.md).
64
64
  See [definition fields](references/video-definitions.md), the
65
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).
@@ -65,3 +65,10 @@ after moving it, then render `BUNDLE/opencut.bundle.video.ts`. Keep that
65
65
  filename at the bundle root. Verification rejects symlinks at the entry and
66
66
  in packaged dependency paths. The new host needs a compatible OpenCut,
67
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).
@@ -40,3 +40,7 @@ Use `packageVideo(definition, destination, { root, resources, params, signal })`
40
40
  `verifyVideoPackage(destination)` to share a project. Pass the verified
41
41
  result's `entry` to `renderVideo` after relocation; it is already resolved
42
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).