Skip to main content

SoundGraft

SoundGraft

Replace video clip audio with matched segments from a dedicated audio recording.

When you record an event with both a camera and a separate high-quality audio recorder, SoundGraft automatically aligns each video clip to the audio timeline and swaps in the better audio track. It also cleans up the replacement audio by attenuating applause and impulse noise, then peak-normalizes the result.

How it works

  1. File classification — Scans the input directory and sorts files into audio recordings and video clips by extension.
  2. Event grouping — Groups consecutive audio segments into events using a file-size heuristic (a short segment followed by a full-length one marks an event boundary).
  3. Alignment — Cross-correlates Chromaprint fingerprints to find where each video clip overlaps the audio timeline, at any relative offset (the audio need not contain the whole clip). Metadata timestamps provide a search hint when available. The output video is trimmed to the audio-covered overlap, snapped to a keyframe so the video stream is copied without re-encoding.
  4. Audio processing — For each matched clip:
    • Cuts the corresponding segment from the audio recording
    • Detects and attenuates applause sections (spectral flatness analysis)
    • Detects and attenuates impulse noise (transient peak analysis)
    • Peak-normalizes to 0 dBFS
  5. Muxing — Replaces the video's audio track with the processed audio using ffmpeg.

Per-clip .log files are written to the output directory with alignment, applause, impulse, and normalization details.

Installation

pip install soundgraft

You also need these system tools:

  • ffmpeg / ffprobe
  • sox
  • fpcalc (from libchromaprint-tools)

On Debian/Ubuntu:

sudo apt install ffmpeg sox libchromaprint-tools

Usage

soundgraft --input <input_dir> --output <output_dir> [options]

Place all raw audio recordings and video clips in a single input directory. Output videos (with replaced audio) and per-clip log files are written to the output directory.

Options

Flag Description
--input DIR Directory containing raw audio and video files (required)
--output DIR Directory for output files (required)
--clip N Process only video clip number N (1-indexed)
--from-clip N Process video clips from N onwards
--it-is-what-it-is Include low-confidence matches instead of skipping them
--no-hint Skip metadata timestamp heuristic, always do full scan
--keep-original-audio Keep the original video audio as a second track
--shotgun N Emit N candidate outputs per clip (different alignment offsets) instead of auto-picking one; use to recover from a bad match. Output files are named <clip>_cand<k>_<offset>s.<ext>.
--min-overlap SEC Minimum seconds of audio/video overlap required to emit a clip (default: 10). Clips with less overlap are skipped.
--offset-correction SEC Seconds added to the chromaprint-derived audio offset to correct its fixed bias (default: -0.19). Lower it if the replaced audio plays late, raise it if early.
--no-cleanup Skip applause and impulse detection/attenuation (peak normalization still applied).
--save-audio Also save each clip's final audio (the exact audio muxed into the video, before the container's lossy encode) as a 16-bit PCM WAV next to the output video, named <clip>.wav (with the candidate suffix under --shotgun).
--temp-dir DIR Directory for temporary files (default: system temp)

Supported formats

  • Audio: .wav, .flac, .mp3, .ogg, .aac
  • Video: .mp4, .mov, .avi, .mkv, .mts

Example

soundgraft --input ./concert-raw --output ./concert-fixed

This scans concert-raw/ for audio and video files, aligns each video clip to the audio recording, processes the audio, and writes the final videos to concert-fixed/.

License

Apache-2.0

Metadata

Release files for soundgraft 0.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for soundgraft 0.3.4
File Size Uploaded Provenance Actions
soundgraft-0.3.4.tar.gz 735.1 kB Without provenance Details for soundgraft-0.3.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for soundgraft 0.3.4
File Interpreter ABI Platform Actions
soundgraft-0.3.4-py3-none-any.whl Python 3 none any Details for soundgraft-0.3.4-py3-none-any.whl

Total release size: 756.7 kB

Release files / soundgraft-0.3.4.tar.gz

Download URL soundgraft-0.3.4.tar.gz
Size 735.1 kB
Tags Source
SHA-256 checksum
How to use checksums
9c29e7b26b49277e88a7b1778d4a77b34117b63503e45747cbb11f34f0445847
BLAKE2b-256 checksum
How to use checksums
9b91e8d3039e7c3d4c43f26a09d87836ec1ea87515aa06ddadc1cc42e3380441
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / soundgraft-0.3.4-py3-none-any.whl

Download URL soundgraft-0.3.4-py3-none-any.whl
Size 21.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f529a6db03af4e65614d32ecb7ab9a1b520481f76393fd08a752cdadbe3babb7
BLAKE2b-256 checksum
How to use checksums
5db2f410345f0073e40e9f89a72d0b7a698b0602e541672198d420f903f901af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for soundgraft 0.3.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page