Video audio operations (FFmpeg)

Mux, strip, duck, and normalize existing audio on video via createVideo. mixAudio accepts path/URL/buffer overlays — including WAV Buffers from painter.createAudio.

Procedural SFX (generate WAV in code): Advanced → createAudio · Audio hub. Editor stacks: Video pipeline.

#extractAudio

What it does: Saves only the first audio stream to a file. Fails if the container has no audio.

##Options

1await painter.createVideo({2  source: './zoom-recording.mp4',3  extractAudio: {4    outputPath: './meeting.wav',5    format: 'wav',6  },7});

#removeAudio

What it does: Copies video streams only (-an -c:v copy) — shortest path to a silent MP4.

1await painter.createVideo({2  source: './captures.mp4',3  removeAudio: { outputPath: './captures-video-only.mp4' },4});

#mute

##Full mute

Omit ranges → same as removeAudio (-an).

##Partial mute

ranges lists [start, end] in seconds. Audio volume 0 only inside those windows; video unchanged (-c:v copy).

1await painter.createVideo({2  source: './podcast.mp4',3  mute: {4    outputPath: './podcast-redacted.mp4',5    ranges: [6      { start: 45, end: 52 },7      { start: 180, end: 190 },8    ],9  },10});

#adjustVolume

##Whole-track gain

Omit ranges. volume is percent: 100 = unity, 50 = half loudness, 200 = double.

1await painter.createVideo({2  source: './quiet.mp4',3  adjustVolume: {4    outputPath: './louder.mp4',5    volume: 160,6  },7});

##Interval automation

ranges entries apply volume inside [start, end] only.

If speed or pitchSemitones differ from neutral on a range, FFmpeg rubberband is appended — requires FFmpeg built with librubberband.

1await painter.createVideo({2  source: './mix.mp4',3  adjustVolume: {4    outputPath: './ducked.mp4',5    ranges: [6      { start: 0, end: 10, volume: 100 },7      { start: 10, end: 40, volume: 35 },8      { start: 40, end: 99999, volume: 100 },9    ],10  },11});

#normalizeAudio — detailed

What it does: Adjusts loudness so playback levels are more consistent without you hand-tuning volume.

##Options

Supports onProgress.

##Method lufs (recommended for podcasts / dialogue)

What it means: LUFS measures perceived loudness over time. normalizeVideoAudio runs FFmpeg loudnorm:

• I= integrated loudness target (targetLevel).
• TP=-1.5 true peak ceiling (fixed in code).
• LRA=11 loudness range parameter (fixed).

Default targetLevel: -23 — common broadcast/podcast target (EBU R128 style).

Effect: Quiet passages get boosted; hot passages pulled down; overall more consistent listening level on speakers and earbuds.

Example — podcast to streaming loudness

1await painter.createVideo({2  source: './raw-podcast.mp4',3  normalizeAudio: {4    method: 'lufs',5    targetLevel: -16,6    outputPath: './podcast-loud.mp4',7  },8  onProgress: (p) => console.log(`${p.percent}%`),9});

Note: -16 LUFS is louder than -23 (smaller negative = louder). Pick -23 for conservative broadcast; -14 to -16 is common for YouTube-style dialogue — taste + platform guidelines.

##Methods peak and rms

In videoHelpers.ts today, peak and rms both map to:

1-af "volume=${targetLevel}dB"

So targetLevel is treated as a fixed dB offset, not a measured-normalise step.

Default targetLevel: -1 when using those branches.

What that feels like: -6 cuts roughly half perceived loudness; +6 boosts (watch clipping).

Limitation: There is no separate RMS-detector path in code despite the type name — if you need true RMS-based levelling, use lufs or post-process with dedicated mastering tools.

1await painter.createVideo({2  source: './clip.mp4',3  normalizeAudio: {4    method: 'peak',5    targetLevel: -3,6    outputPath: './clip-gain.mp4',7  },8});

#mixAudio — **MixAudioOperation

What it does: Places multiple external audio files on a timeline over your video’s duration. Optional keep original mix or replace with silence + overlays.

##Top-level fields

##Each MixAudioOverlayClip

Clips entirely outside usable window are skipped.

##Example — score under VO

1await painter.createVideo({2  source: './voiceover.mp4',3  mixAudio: {4    outputPath: './cinematic.mp4',5    keepOriginalAudio: true,6    originalVolume: 1,7    overlays: [8      {9        source: './score.mp3',10        startTime: 0,11        duration: 180,12        sourceStart: 0,13        volume: 0.25,14      },15    ],16  },17});