Registry / ai-ml / sox
library1.5.0pypypi✓ verified 21d ago

The `sox` library provides a Python wrapper around the SoX (Sound eXchange) command-line tool, enabling Python programs to perform audio processing tasks such as format conversion, effects application, and mixing. The current version is 1.5.0, released in late 2023, and it generally follows a release cadence tied to significant feature additions or Python version support updates.

pip install sox
INSTALL
IMPORT
SIG · SOX
S
sox
ai-mlpythonv1.5.0
Install
4.6s avg
Import
296ms
Disk
91MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.298s · 91.4MB
glibc
py 3.103.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)
Debug
Known issues
breakingPython 3.7 and earlier are no longer supported as of `sox` version 1.5.0. Users on these older Python versions must upgrade to Python 3.8+ or pin `sox` to an earlier version (e.g., `<1.5.0`).
fix
Upgrade Python to 3.8 or newer, or specify `sox<1.5.0` in your dependencies.
affects: >=1.5.0
gotchaThe `sox` Python library is a wrapper for the *external* SoX command-line tool. You MUST have the SoX executable installed and accessible in your system's PATH for this library to function. The library itself does not bundle the SoX executable.
fix
Install the SoX command-line tool via your system's package manager (e.g., `sudo apt-get install sox` on Debian/Ubuntu, `brew install sox` on macOS, or download from the SoX homepage for Windows).
affects: All versions
gotchaPrior to version 1.5.0, `sox` primarily expected string paths for file operations. While string paths still work, version 1.5.0 and later added explicit support for `pathlib.Path` objects. Mixed usage or assuming `Path` objects on older versions may lead to errors.
fix
For `sox<1.5.0`, always convert `pathlib.Path` objects to strings using `str(path_obj)` before passing them to `sox` functions. For `sox>=1.5.0`, `pathlib.Path` objects can be used directly.
affects: <1.5.0
gotchaErrors during SoX command execution (e.g., malformed input, unsupported effects, missing codecs) are wrapped in `sox.SoxError`. It's good practice to catch this specific exception to handle issues gracefully, rather than relying on generic `Exception` catches.
fix
Wrap calls to `tfm.build()` (and similar methods that execute SoX) in a `try...except sox.SoxError:` block to specifically handle SoX-related failures.
affects: All versions
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.
fix
Install 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.
fix
Install 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.
fix
Review 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.
fix
Verify 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.

Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources