Normalize audio volume
Scale an audio (or video's audio track) so its loudest sample hits a target peak level: a two-pass peak scan followed by a gain-scaled re-encode, both through WebCodecs, so this runs in the browser only, like video-convert (src/tools/video-convert.ts). Always outputs MP4 with an unchanged video track (if any). Nothing is uploaded.
Runs on your device. The file is never uploaded.
Normalize audio volume scans every sample for the loudest one, then rescales the whole file so that peak lands on targetDb, -1 dBFS by default. A file whose measured peak is 0 gets a message and no output file at all. Both passes run through WebCodecs, which Node lacks, so the command line refuses this one.
Questions
Is this peak normalisation or loudness normalisation?
Peak. The tool scans every sample to find the single loudest one, then scales the whole file by one fixed gain so that peak lands exactly on your target. It is not LUFS or ReplayGain, so two files normalised to the same target can still feel different in loudness. Nothing is compressed or limited, and the dynamics are untouched.
What is targetDb and what should I use?
It is the target peak level in dBFS, where 0 is full scale, and it defaults to -1 to leave a little headroom. It must be a number of zero or less; a positive value is refused. Because the gain is computed as target divided by the measured peak, the loudest sample lands exactly on your target and nothing clips past it.
Why does it take two passes over my file?
Because a single gain figure cannot be known until the loudest point in the whole file has been found. The first pass decodes every sample and tracks the peak. The second pass re-encodes, multiplying each sample by the gain. That means the audio is decoded twice, which is why long files take a while.
What does it give me back?
Always an MP4, named after your input with -normalized.mp4 on the end. A video track in the source is carried through unchanged, so normalising a video gives you the same picture with louder sound. The result text reports the measured peak in dBFS, the gain factor applied and the target you asked for.
What happens with a silent file?
Nothing is written. If the measured peak is zero the tool reports "audio is silent (peak is 0)" and stops, because scaling silence by any factor is still silence. You get the message and no output file rather than a pointless copy.
Why will it not run on the command line?
Because both the scan and the re-encode go through WebCodecs, which Node has no equivalent of. The CLI and MCP surfaces refuse it with "audio-normalize needs a browser (OffscreenCanvas). Use it at /video/audio-normalize instead." The file stays on your device in either case.