Field Debreath

Detect and reduce breaths in narration without cutting time or silencing the whole background.

Field Debreath is an offline Python tool for recordings where speech shares a microphone with footsteps, birds, wind and other location sound. It uses Respiro-en to locate likely breaths, then applies local spectral attenuation. The repair estimates the surrounding background and limits attenuation of short transient peaks.

It is breath reduction, not breath isolation. Overlapping sounds can still be affected. Listen to the result before replacing any audio in your edit.

Install

Requires Python 3.11+ and FFmpeg on your PATH. Python 3.12 on Windows was used for the initial field-recording trial. A GPU is not required.

git clone https://github.com/timcarpe/field-debreath.git
cd field-debreath
python -m venv .venv

Activate the environment with .venv\Scripts\Activate.ps1 on Windows PowerShell, or source .venv/bin/activate on macOS/Linux. Then:

python -m pip install ".[detect]"
field-debreath download-model

The download command fetches the pinned 35 MB Respiro-en checkpoint and verifies its SHA-256. By default it lives in ~/.cache/field-debreath/. Processing stays local and does not upload audio. The model download and package installation need internet access; subsequent processing does not.

If FFmpeg is not on PATH, set FIELD_DEBREATH_FFMPEG to its executable. Use --model /path/to/respiro-en.pt to select another location for the same checkpoint.

Process and listen

field-debreath process narration.wav --out output/take-01
field-debreath process morning.wav afternoon.mp4 --out output/day-review

Open review.html in the output folder. It has a clip selector, original/repaired switch and playback speed control. Playback advances through the clips. Switching versions keeps the current position.

Each clip produces:

• original.wav and repaired.wav: 48 kHz stereo, 32-bit float working audio and master.
• candidates.json: editable breath intervals, scores and source identity.
• audit.json: applied/skipped edits, background estimates, hashes and integrity checks.
• original.mp3 and repaired.mp3: 320 kbps listening previews; no normalization.
• scores.npy: frame scores on the detector's 10 ms grid.

Input files are never overwritten. Output directories must be new. The first audio stream is used; mono inputs are converted to stereo. Sample identity outside repairs refers to the decoded 48 kHz working audio, not the original compressed file. MP3 previews are lossy; use the WAV masters for editing.

Adjust the pass

The default repair depth is 3.2, the stronger setting used in the initial trial. Try --depth 1 for a gentler pass. Depth changes the spectral mask; it is not a dB value. --threshold 0.5 makes detection stricter than the default 0.064, but may miss breaths.

To inspect detections before processing:

field-debreath detect narration.wav --out output/detection

Edit output/detection/candidates.json: set a candidate's enabled to false to leave it alone, or adjust its start and end in seconds. Enabled intervals must not overlap and must be at least 20 ms long. Then:

field-debreath repair output/detection --out output/revised --depth 3.2

The repair command checks the original audio hash and does not rerun the model. You can also repair an edited clip folder from a previous process run. Installing with pip install . is sufficient for repair-only use; the detection dependencies are optional.

What to expect

This started with outdoor, walking narration from a GoPro. The working scripts processed 132 clips across 29 timelines; the full listening review is still in progress. That is an operational trial, not a general accuracy benchmark.

• Detection was trained upstream on audiobook speech, not this type of recording. False positives and missed breaths are possible.
• Sustained nature sounds, speech edges and overlapping footsteps may be reduced. Transient protection is a heuristic, not a guarantee.
• Busy surrounding audio can give the repair a poor background estimate. Regions without enough context on either side are skipped and logged.
• Long files use chunked inference, but working audio is held in memory. Start with narration clips rather than an entire feature-length mix.
• This is not a VST or a Resolve plug-in. It does not read or change timelines, apply native mix effects, or automatically replace media. Export the narration you want to treat, then bring the repaired WAV back into your editor.

See the method for the processing details and third-party notices for model/code provenance. No field recordings or model weights are bundled.

Development

python -m pip install -e .
python -m unittest discover -s tests -v

Tests cover edit bounds, transient retention on synthetic audio, candidate handling and a small FFmpeg round trip. They do not certify listening quality. Please include the command, version and a short description of the audible problem when filing an issue. Share audio only if you have permission.

Original code is MIT licensed. Vendored components retain their own notices.