https://github.com/42atomys/voxlevel
normalize volume level to -6dB by DC removal, VAD and AGC
https://github.com/42atomys/voxlevel
Last synced: 4 days ago
JSON representation
normalize volume level to -6dB by DC removal, VAD and AGC
- Host: GitHub
- URL: https://github.com/42atomys/voxlevel
- Owner: 42atomys
- License: mit
- Created: 2026-04-09T11:16:10.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T11:56:20.000Z (4 months ago)
- Last Synced: 2026-07-07T11:32:29.435Z (17 days ago)
- Language: Python
- Homepage:
- Size: 156 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# voxlevel
Normalize WAV voice recordings so all speakers sound at the same volume level (-6 dB by default), regardless of their distance from the microphone.
Handles real-world scenarios: background noise, wind, echo, multiple speakers, and speakers moving during recording.
## Installation
```bash
pip install voxlevel
```
## Usage
### Python API
```python
import voxlevel
# From a WAV file
voxlevel.normalize("input.wav", "output.wav")
# From a numpy array
import numpy as np
result = voxlevel.normalize(audio_array, sample_rate=16000)
# With custom parameters
voxlevel.normalize(
"input.wav",
"output.wav",
target_db=-6.0,
max_gain_db=30.0,
rms_window_ms=400.0,
smooth_window_ms=200.0,
)
```
### CLI
```bash
# Single file
voxlevel input.wav -o output.wav
# Batch processing
voxlevel *.wav -o normalized/
# Custom target level
voxlevel input.wav -o output.wav --target-db -3.0
```
## How it works
voxlevel uses a two-pass offline approach (not real-time compression):
1. **Preprocessing** -- DC removal + 80 Hz high-pass filter to cut wind noise, handling noise, and plosives
2. **Voice Activity Detection** -- Silero-VAD (ONNX) identifies speech vs. silence segments
3. **Automatic Gain Control** -- Sliding RMS envelope computes the gain needed at each sample to reach the target level, with interpolation across silence gaps and bidirectional smoothing
4. **Lookahead limiter** -- 5 ms lookahead prevents peaks from exceeding the target, reducing transient distortion compared to brick-wall clipping
The two-pass design means gain is correct from sample 0 -- no lag or adaptation artifacts that real-time compressors exhibit.
## Constraints
- 16-bit mono WAV at 8 kHz or 16 kHz
- Offline processing only (no streaming)
## License
MIT