Install & Compatibility
Where this runs
tested against v2.0.14 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.111s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.099s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vad
✓ import webrtcvad
vad = webrtcvad.Vad()
✗ from webrtcvad import Vad
The `Vad` class is accessed as an attribute of the imported `webrtcvad` module, not directly from it.
Initializes the VAD, sets its aggressiveness, and demonstrates checking a silent audio frame for speech. The audio must be 16-bit mono PCM, with a specific sample rate and frame duration.
import webrtcvad
# Create a VAD object
vad = webrtcvad.Vad()
# Set aggressiveness mode (0-3, 0 is least aggressive, 3 is most aggressive)
vad.set_mode(1)
# Define audio parameters
sample_rate = 16000 # Must be 8000, 16000, 32000, or 48000 Hz
frame_duration_ms = 10 # Must be 10, 20, or 30 ms
# Generate a silent frame (16-bit mono PCM)
frame_size_bytes = int(sample_rate * frame_duration_ms / 1000) * 2 # 2 bytes per 16-bit sample
silent_frame = b'\x00\x00' * (frame_size_bytes // 2)
# Check if the frame contains speech
is_speech = vad.is_speech(silent_frame, sample_rate)
print(f"Contains speech: {is_speech}")
# Example with a slightly more aggressive mode
vad_aggressive = webrtcvad.Vad(3)
is_speech_aggressive = vad_aggressive.is_speech(silent_frame, sample_rate)
print(f"Contains speech (aggressive mode): {is_speech_aggressive}")
Debug
Known issues
gotchaThe WebRTC VAD has strict requirements for audio input: it must be 16-bit mono PCM, with a sample rate of 8000, 16000, 32000, or 48000 Hz, and frames must be exactly 10, 20, or 30 ms in duration. Mismatching these parameters will lead to errors.fixEnsure your audio frames are pre-processed to meet these specifications before passing them to `vad.is_speech()`. Calculate frame size precisely: `bytes_per_frame = int(sample_rate * frame_duration_ms / 1000) * 2`.
affects: All versions
breakingOlder versions of `webrtcvad-wheels` (prior to 2.0.13) had a known memory leak when constructing `Vad` objects repeatedly. While less common, this could lead to performance degradation or crashes in long-running applications.fixUpgrade to `webrtcvad-wheels` version 2.0.13 or newer (`pip install --upgrade webrtcvad-wheels`) to benefit from the memory leak fix.
affects: < 2.0.13
gotchaMany users mistakenly try to install the older, non-wheel `webrtcvad` package, which often fails to compile due to missing C/C++ development tools (e.g., Visual C++ Build Tools on Windows, `gcc` on Linux).fixAlways use `pip install webrtcvad-wheels` to get the pre-compiled binary wheels, which generally resolves compilation issues.
affects: All versions when trying to install the original `webrtcvad`
Errors
Common errors & fixes
Failed building wheel for webrtcvad / error: command 'gcc' failed: No such file or directory
Attempting to install the original `webrtcvad` package which requires local compilation with C/C++ development tools that are often missing or misconfigured on the system.
fixInstall `webrtcvad-wheels` instead: `pip install webrtcvad-wheels`. This package provides pre-compiled binaries (wheels) and avoids the need for local compilation.
webrtcvad.Error: Invalid sample rate: XXXXX
The audio data passed to `vad.is_speech()` has a sample rate that is not supported by the WebRTC VAD. Only 8000, 16000, 32000, or 48000 Hz are allowed.
fixResample your audio to one of the supported rates (8kHz, 16kHz, 32kHz, or 48kHz) before passing it to the VAD. Libraries like `scipy.io.wavfile` or `pydub` can help with resampling.
ValueError: frame length must be 10, 20 or 30 ms
The length of the audio frame (in milliseconds) provided to `vad.is_speech()` does not match the strict requirements of 10, 20, or 30 ms.
fixEnsure your audio data is chunked into precise 10ms, 20ms, or 30ms segments. Calculate the number of bytes for a frame using `(sample_rate * frame_duration_ms / 1000) * 2`.
Upgrade
Version history
2.0.14latest on PyPI · released Sep 5, 2024
Audit
Dependencies
No dependency data recorded yet.