Install & Compatibility
Where this runs
tested against v0.7.2 · 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
py 3.10
✕ build_error
✓ 101.73s
py 3.11
✕ build_error
✓ 96.7s
py 3.12
✕ build_error
✓ 92.1s
py 3.13
✕ build_error
✓ 80.78s
py 3.9
✕ build_error
✕ timeout
5504MB installed
● package 5504MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AudioSignal
✓ from audiotools import AudioSignal
✗ import audiotools.AudioSignal
AudioSignal is a class directly exported from the top-level package.
audiotools
✓ import audiotools
This quickstart demonstrates how to create a basic `AudioSignal` object, apply a simple audio transformation (low-pass filter), and print its properties. For actual audio playback using `signal.play()`, the `ffplay` utility (part of the FFmpeg suite) needs to be installed and accessible in your system's PATH. The example generates a dummy sine wave for immediate execution without external audio files.
import audiotools
import numpy as np
# Create a dummy AudioSignal (e.g., a sine wave)
sample_rate = 44100
duration = 3 # seconds
frequency = 440 # Hz
t = np.linspace(0, duration, int(sample_rate * duration), endpoint=False)
sine_wave = 0.5 * np.sin(2 * np.pi * frequency * t)
# AudioSignal expects a torch.Tensor, so convert numpy array
signal = audiotools.AudioSignal(sine_wave[np.newaxis, :], sample_rate)
print(f"Original signal sample rate: {signal.sample_rate}")
print(f"Original signal duration: {signal.duration} seconds")
# Apply a low-pass filter
filtered_signal = signal.low_pass(8000)
print(f"Filtered signal duration: {filtered_signal.duration} seconds")
# To play back audio, ffplay (part of FFmpeg) must be installed.
# signal.play()
# filtered_signal.play()
Debug
Known issues
breakingVersion 0.7.2 of `descript-audiotools` has a strict dependency on `protobuf<3.20,>=3.9.2`. Installing with newer `protobuf` versions (e.g., 4.x or 5.x) will lead to dependency conflicts and prevent installation or cause runtime errors.fixEnsure your environment uses `protobuf` within the `3.9.2` to `3.19.x` range. You may need to downgrade `protobuf` if other packages require a newer version, or consider installing `audiotools` directly from GitHub if a newer, compatible version exists there (e.g., `pip install git+https://github.com/descriptinc/audiotools@main`).
affects: 0.7.2 and potentially earlier/later versions if not updated.
gotchaThe `AudioSignal.play()` method relies on the external `ffplay` command-line utility for audio playback. If `ffplay` (part of FFmpeg) is not installed on your system or not in your system's PATH, `signal.play()` calls will fail silently or with an error about the command not being found.fixInstall FFmpeg (which includes `ffplay`) on your operating system and ensure its executables are accessible via your system's PATH. Common installation methods include `brew install ffmpeg` on macOS, `sudo apt-get install ffmpeg` on Debian/Ubuntu, or downloading from the official FFmpeg website for Windows.
affects: All versions utilizing `signal.play()`.
Upgrade
Version history
0.7.2latest on PyPI · released Jul 19, 2023
Audit
Dependencies
protobufrequiredSpecific version range required, commonly causes conflicts.