Install & Compatibility
Where this runs
tested against v1.5.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.298s · 91.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.6s · import 0.294s · 88MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sox
✓ import sox
✗ import pysox
While the GitHub repository is named 'pysox', the installed Python package and its top-level import name is `sox`.
Transformer
✓ from sox import Transformer
✗ from sox.transform import Transformer
Common classes like Transformer are directly available under the top-level 'sox' module, not nested under a 'transform' submodule.
This quickstart demonstrates how to use `sox.Transformer` to apply effects and convert an audio file. It includes checks for the external SoX command-line tool and generates a dummy input file if one isn't present to make the example runnable.
import sox
import os
import subprocess
input_file = "input_audio.wav"
output_file = "output_processed.wav"
# --- Pre-requisite Check: SoX command-line tool ---
try:
subprocess.run(["sox", "--version"], check=True, capture_output=True)
except (subprocess.CalledProcessError, FileNotFoundError):
print("WARNING: The SoX command-line tool is not found. Please install it first.")
print(" (e.g., `sudo apt-get install sox` on Debian/Ubuntu, `brew install sox` on macOS)")
# Exit or provide placeholder if SoX isn't installed. For quickstart, we'll print and continue
# to show the Python API, but expect actual failure if SoX isn't present.
# --- Generate a dummy input file if it doesn't exist ---
if not os.path.exists(input_file):
print(f"Generating dummy '{input_file}' for the example...")
try:
# Use SoX itself to create a 1-second sine wave file
subprocess.run(["sox", "-n", input_file, "synth", "1", "sine", "440"], check=True)
print(f"Successfully generated '{input_file}'.")
except (subprocess.CalledProcessError, FileNotFoundError):
print(f"Failed to generate '{input_file}'. Please ensure SoX is installed and accessible in PATH, or provide your own '{input_file}'.")
# --- SoX Transformation Example ---
if os.path.exists(input_file):
# Initialize a Transformer object
tfm = sox.Transformer()
# Apply some audio effects
tfm.trim(0.1, 0.9) # Trim from 0.1s to 0.9s
tfm.set_output_format(rate=16000, channels=1) # Resample to 16kHz mono
tfm.compand(attack=0.3, decay=0.8, soft_knee=6, threshold=-40, ratio=5) # Apply dynamic range compression
# Build the output file. The 'build' method executes the SoX command.
try:
tfm.build(input_file, output_file)
print(f"Transformation complete! Output saved to '{output_file}'.")
print(f"Original file size: {os.path.getsize(input_file)} bytes")
print(f"Processed file size: {os.path.getsize(output_file)} bytes")
except sox.SoxError as e:
print(f"Error during SoX transformation: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
else:
print("Skipping transformation: Input file not found.")
# --- Clean up (optional) ---
# if os.path.exists(output_file):
# os.remove(output_file)
# if os.path.exists(input_file):
# os.remove(input_file)
Errors
Common errors & fixes
sox.SoxError: SoX program not found! Make sure it is installed and available in the PATH.
The underlying SoX command-line utility is not installed on the system, or its executable is not accessible via the system's PATH environment variable.
fixInstall the SoX command-line tool for your operating system (e.g., `sudo apt-get install sox` on Debian/Ubuntu, `brew install sox` on macOS, or download the installer for Windows) and ensure it's included in your system's PATH.
ModuleNotFoundError: No module named 'sox'
The `sox` Python package has not been installed in the current Python environment.
fixInstall the Python package using pip: `pip install sox`
sox.SoxError: SoX returned a non-zero exit status: 1
The SoX command-line program encountered an error during audio processing, often due to invalid input files, unsupported formats, or incorrect parameters passed to SoX effects.
fixReview the input/output file paths and parameters passed to `sox.Transformer` or other `sox` functions for correctness, ensuring input files exist, are valid audio, and are supported by SoX.
sox.exceptions.SoxError: Input file does not exist: /path/to/your/audio.wav
The specified input audio file provided to `sox.Transformer.set_input()` or `sox.file_info()` does not exist at the given path.
fixVerify that the path to the input audio file is correct and that the file exists on your filesystem before attempting to process it.
Upgrade
Version history
1.5.0latest on PyPI · released Mar 20, 2024
Audit
Dependencies
No dependency data recorded yet.