Audio Declip / Overload Repair

Sometimes MiniMax Music 3 hands you a track that looks like a tablesaw blade: the peaks hit near zero and sit there, flat on top. That's hard clipping, and it's the worst possible thing to feed into a super-resolution stage, because FlashSR will happily sharpen those chopped corners into buzzing, grating distortion. Audio Declip / Overload Repair is the safety net you put between the generator and the enhancer. It finds short near-ceiling flat-topped regions and rebuilds plausible peak curvature before FlashSR can exaggerate them.

The name overpromises slightly. Digital clipping destroys information - the node can't recover what's gone, only reconstruct a plausible curve. That's the whole design philosophy of this pack: conservative, batch-safe, and honest about limits. It's not a compressor, not a limiter, and it won't add "vibe." It quietly makes the source a better starting point.

Where it sits

This is the first audio stage in the pack's production chain: generated audio → declip repair → PRE low-pass → FlashSR → hybrid crossover → HF repair → POST low-pass → release prep. The README calls it a "conservative reconstruction" stage. Run it before any filtering or resampling, right after the MiniMax output node.

How it works

The node scans each channel for near-ceiling plateaus: regions where the sample-to-sample change stays below plateau_tolerance_percent of the channel peak, at or above detection_threshold_percent of it. Short enough plateaus get the missing curvature rebuilt with cubic-Hermite interpolation, using the slope_context_samples of clean audio around each region to estimate entry and exit slopes. Then one optional whole-track safety gain brings the result under output_ceiling_dbfs - a single constant gain, never a limiter and never time-varying. That's a deliberate choice; this pack refuses to secretly pump your level.

Inputs that matter

The default Auto / conservative mode is what you want for unattended batches. It only repairs strong, short plateau evidence and leaves ordinary rounded peaks alone. The other modes exist for when you've actually listened and diagnosed something:

• Analyze only - the underrated one. It runs detection and reports what it found without changing a sample. Use this first if you're not sure your source is even clipped.
• Standard / Strong - wider detection, longer repairs, more aggressive. Strong will reshape merely limited peaks, which is why the tooltip warns you off it.
• max_repair_ms (default 8 ms) - the ceiling on how long a clipped region it's willing to rebuild. Longer flat tops carry too little information, so they're skipped and counted. Don't raise it unless you can actually hear long hard-clipped crests.
• mix - wet/dry blend, useful when a repair sounds too "reconstructed." Going below 1.0 also blends clipping distortion back in, so it's a compromise, not a free lunch.

Outputs are audio, plus two STRINGs: declip_json (a JSON report of detection, repaired/skipped regions, effective parameters) and info. Wire the JSON into MiniMax Song Metadata later if you want it in the reproducibility sidecar.

Installing it

This is one node in Johannes Plenio's MiniMax Music Production Toolkit. ComfyUI Manager (search "MiniMax Music Production Toolkit") is the easy path; manually:

cd ComfyUI/custom_nodes
git clone https://github.com/jplenio/ComfyUI-MiniMax-Music-Production-Toolkit.git
cd ComfyUI-MiniMax-Music-Production-Toolkit
python -m pip install -r requirements.txt

Use the same Python that runs ComfyUI. The package needs scipy, soundfile, imageio-ffmpeg, mutagen and Pillow - no model weights are bundled. Restart ComfyUI and hard-refresh the browser once.

Gotchas

If nothing seems to change, you're probably feeding it audio that isn't hard-clipped - check Analyze only first. Long flat tops get skipped by design, so a track that's clipped in big blocks won't fully "unclip." And remember the honest caveat from the docs: reconstruction is plausible, not exact. If your source is genuinely mangled, nothing this pack ships will fully fix it - but this node keeps FlashSR from turning the damage into something worse.