TorchFX 0.4.0: Production-Ready Audio DSP 🚀#

I’m thrilled to announce TorchFX 0.4.0, the biggest release yet. This version transforms TorchFX from a research library into a audio DSP toolkit with real-time processing, and a powerful CLI interface.

This release represents months of work implementing the core features needed for v1.0.0. Let’s dive into what’s new!

🎯 Release Highlights#

2. Interactive REPL with Live Performance Mode#

The REPL enables real-time audio manipulation with instant effect changes:

torchfx> load song.wav
torchfx> live
▶ Live playback started (looping)

torchfx> add reverb:decay=0.8,mix=0.5
✓ [1] Added reverb:decay=0.8,mix=0.5
# ← Effect applies while playing

torchfx> preset load mastering
✓ Loaded preset 'mastering' (3 effects)
# ← Entire chain switches in real-time

Key features:

  • Lock-free circular buffer for glitch-free playback

  • Effect hot-swapping at buffer boundaries (~46ms latency)

  • prompt_toolkit with tab completion and persistent history

  • Perfect for sound design, education, and live performance

Read the REPL blog post for the full story.

3. Input Validation Layer (torchfx.validation)#

Error handling with context-aware messages:

Exception hierarchy:

  • TorchFXError (base — catch all library errors)

  • InvalidParameterError

  • InvalidSampleRateError

  • InvalidRangeError

  • InvalidShapeError

  • InvalidTypeError

  • AudioProcessingError

  • CoefficientComputationError

  • FilterInstabilityError

Validator functions:

  • validate_sample_rate() — Ensure valid sampling rates

  • validate_positive() — Check positive numbers

  • validate_range() — Verify parameter bounds

  • validate_in_set() — Enum-like validation

  • validate_tensor_ndim() — Tensor shape checking

  • validate_audio_tensor() — Audio-specific validation

  • validate_type() — Type checking with suggestions

  • validate_cutoff_frequency() — Filter cutoff validation

  • validate_filter_order() — Order constraints

  • validate_q_factor() — Q parameter validation

Example:

from torchfx.validation import validate_sample_rate, InvalidSampleRateError

try:
    validate_sample_rate(48000)  # OK
    validate_sample_rate(-100)   # Raises with helpful message
except InvalidSampleRateError as e:
    print(e)  # "Invalid sample rate: -100 (must be positive)"

All exceptions include:

  • Parameter name

  • Actual value

  • Expected value/range

  • Suggestion for fixing

4. Logging Infrastructure (torchfx.logging)#

Production-grade logging following Python best practices:

import torchfx.logging as tfx_log

# Enable logging (NullHandler by default)
tfx_log.enable_logging()        # INFO level
tfx_log.enable_debug_logging()  # DEBUG level

# Get module-specific loggers
logger = tfx_log.get_logger("torchfx.filter")

# Performance profiling
with tfx_log.log_performance("Heavy operation"):
    # ... code ...
    pass  # Logs execution time at INFO level

# Or as decorator
from torchfx.logging import LogPerformance

@LogPerformance("My function")
def process_audio():
    pass

Features:

  • Hierarchical loggers: torchfx, torchfx.performance, torchfx.<module>

  • Opt-in by default (follows Python logging conventions)

  • Performance utilities for profiling

  • DEBUG logs include detailed parameter info

5. Real-Time Processing Module (torchfx.realtime)#

Complete real-time audio infrastructure:

Core classes:

  • RealtimeProcessor — Orchestrates backend + effect chain

  • StreamProcessor — Chunk-based file processing

  • TensorRingBuffer — Lock-free SPSC ring buffer

  • SoundDeviceBackend — PortAudio integration

  • StreamConfig — Stream configuration

  • AudioBackend — Abstract backend interface

Example:

from torchfx.realtime import RealtimeProcessor, StreamConfig, SoundDeviceBackend
from torchfx.effect import Gain, Reverb

config = StreamConfig(
    sample_rate=48000,
    buffer_size=512,
    channels_in=1,
    channels_out=1,
)

processor = RealtimeProcessor(
    effects=[Gain(0.8), Reverb()],
    backend=SoundDeviceBackend(),
    config=config,
)

with processor:
    # Real-time processing active
    processor.set_parameter("0.gain", 0.5)  # Thread-safe parameter update
    # ... processing continues ...

Features:

  • <10ms latency at 48kHz, 512 buffer

  • Thread-safe parameter updates at buffer boundaries

  • GPU/CPU hybrid processing

  • Ring buffer for smooth I/O

  • Automatic fs propagation to effects

6. Biquad Filter Suite#

Six new biquad implementations with Audio EQ Cookbook formulas:

  • BiquadLPF — Lowpass filter

  • BiquadHPF — Highpass filter

  • BiquadBPF — Bandpass filter (constant skirt gain)

  • BiquadBPFPeak — Bandpass filter (constant 0 dB peak gain)

  • BiquadNotch — Notch filter

  • BiquadAllPass — All-pass filter

All support:

  • Stateful processing (IIR state management)

  • Stateless processing (for one-shot operations)

  • Device transfer (CPU ↔ GPU)

  • Standard cutoff and q parameters

7. TOML Configuration & Preset System#

Reproducible effect chains with TOML:

# mastering.toml
device = "cuda"
chunk_size = 131072

[[effects]]
name = "normalize"
peak = 0.9

[[effects]]
name = "parametriceq"
frequency = 2000
q = 1.5
gain = 3

[[effects]]
name = "reverb"
decay = 0.5
mix = 0.2

Use with CLI:

torchfx process input.wav output.wav --config mastering.toml

Or save as preset:

torchfx preset save mastering --from mastering.toml
torchfx preset apply mastering input.wav output.wav

Presets stored in ~/.config/torchfx/presets/ for easy sharing.

8. Effect Chain Parser#

30+ effects/filters registered with intuitive CLI syntax:

# Simple effect
-e normalize

# Positional parameter
-e "gain:0.5"

# Keyword parameters
-e "reverb:decay=0.6,mix=0.3"

# Mixed
-e "parametriceq:frequency=2000,q=1.5,gain=6"

Registered effects include:

  • Effects: gain, normalize, reverb, delay

  • Biquad filters: lowpass, highpass, bandpass, notch, allpass

  • IIR filters: lobutterworth, hibutterworth, butterworth, lochebyshev1, hichebyshev1, chebyshev1, lochebyshev2, hichebyshev2, chebyshev2, loelliptic, hielliptic, elliptic

  • Shelving/EQ: loshelving, hishelving, parametriceq, peaking

📊 Test Coverage#

393 tests across the codebase with >90% coverage:

  • Wave class: 72 tests

  • Filters (IIR/FIR/Biquad): 85+ tests

  • Effects: 43 tests

  • Real-time processing: 62 tests

  • Validation: 76 tests

  • Logging: 25 tests

  • CLI: 71 tests

All tests pass on Linux, macOS, and Windows with Python 3.10-3.13.

📚 Documentation Updates#

Complete overhaul of documentation:

  • CLI Guide: Comprehensive tutorial with examples for all commands

  • API Reference: Complete docstrings with examples

  • Developer Guides: Roadmap, style guide, contributing guide

🔧 Installation#

# Core library
pip install torchfx

# With CLI tools
pip install torchfx[cli]

# With real-time audio (for play/record/REPL live mode)
pip install torchfx[realtime]

# Everything
pip install torchfx[cli,realtime]

📈 Project Status#

With 0.4.0, we’ve completed Phase 1 and Phase 2 of the roadmap to v1.0.0:

✅ Phase 1 (Foundation): Core stabilization, API stability, error handling, testing
✅ Phase 2 (Major Features): Real-time processing, CLI application, documentation

Next up — Phase 3 (Optimization):

  • Custom CUDA kernels for IIR filters

  • Batch processing optimizations

  • Additional effects (compressor, phaser, pitch shift)

We’re now ~85% complete toward v1.0.0!

🚀 Try It Now#

pip install torchfx[cli,realtime]
torchfx interactive

Load a file, type live, and experience real-time audio magic.

📝 Complete Changelog#

Added#

  • Input validation layer with custom exception hierarchy (torchfx.validation module)

    • Base exception TorchFXError for catching all library errors

    • Specific exceptions: InvalidParameterError, InvalidSampleRateError, InvalidRangeError, InvalidShapeError, InvalidTypeError, AudioProcessingError, CoefficientComputationError, FilterInstabilityError

    • Validator functions for sample rates, parameter ranges, tensor shapes, types, and audio-specific validation

  • Logging infrastructure (torchfx.logging module)

    • Structured logging following Python best practices (NullHandler by default)

    • Convenience functions: enable_logging(), enable_debug_logging(), disable_logging(), get_logger()

    • Performance profiling: log_performance() context manager and LogPerformance decorator

    • Hierarchical logger support for fine-grained control

  • Realtime processing module (torchfx.realtime)

    • RealtimeProcessor with thread-safe parameter updates

    • StreamProcessor for chunk-based file processing

    • TensorRingBuffer with lock-free SPSC pattern

    • SoundDeviceBackend for PortAudio integration

    • StreamConfig and AudioBackend abstractions

  • Biquad filter implementations

    • BiquadLPF, BiquadHPF, BiquadBPF, BiquadBPFPeak, BiquadNotch, BiquadAllPass

    • Stateful and stateless processing paths

    • Audio EQ Cookbook formulas

  • CLI application (Epic 3 — Phase 1)

    • torchfx process: single-file, batch (glob + progress bar), and Unix pipe processing

    • torchfx info: display audio file metadata in Rich tables

    • torchfx play: play audio through speakers with optional effects

    • torchfx record: record from microphone

    • torchfx convert: format/rate/channel conversion (sox-compatible)

    • torchfx trim: extract time ranges (sox-compatible)

    • torchfx concat: join multiple files (sox-compatible)

    • torchfx stats: signal statistics (sox-compatible)

    • torchfx preset: save/load/list/show/delete/apply presets

    • torchfx interactive: launch REPL with live performance mode

    • torchfx watch: monitor directories for auto-processing

    • Effect-chain parser with 30+ registered effects/filters

    • TOML configuration file support

    • Preset management in ~/.config/torchfx/presets/

    • GPU acceleration via --device cuda

Changed#

  • Improved error messages throughout library with context and suggestions

  • Enhanced logging with performance profiling capabilities

  • Real-time processing now uses ring buffers for smooth I/O

Technical Details#

  • Lines of Code: ~12,000 (including tests and docs)

  • Test Count: 393 (up from 95 in v0.2.1)

  • Coverage: >90% (up from ~70%)

  • Documentation Pages: 50+ (up from ~20)

  • Supported Python: 3.10, 3.11, 3.12, 3.13

  • Optional Dependencies: sounddevice, typer, rich, prompt_toolkit, watchdog

🔮 What’s Next?#

v1.0.0 Release Candidate is the immediate goal. After community testing and final polish, we’ll ship v1.0.0 with:

  • Semantic versioning guarantees

  • Long-term API stability

  • Custom CUDA kernels for 2-3x speedup

Post-1.0 roadmap includes:

  • Advanced effects (compressor, phaser, pitch shift)

  • VST3 wrapper (long-term)

💬 Get Involved#

TorchFX 0.4.0 is available now. Install it, explore the CLI, try the REPL, and let us know what you think!

pip install torchfx[cli,realtime]
torchfx --help

Happy audio processing! 🎵

Interactive Audio Magic: The TorchFX REPL   TorchFX CLI: GPU-Accelerated Audio Processing from the Terminal