---
blogpost: true
date: Feb 15, 2026
author: Matteo Spanio
category: releases
tags: release, cli, validation, logging, real-time
---

# 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

### 1. Full-Featured CLI Application

The crown jewel of 0.4.0 is a **complete command-line interface** that brings GPU-accelerated audio processing to your terminal:

**11 Commands:**
- `process` — Apply effects to audio (single/batch/pipes)
- `info` — Display file metadata
- `play` — Play audio with effects
- `record` — Record from microphone
- `convert` — Format/rate/channel conversion (sox-compatible)
- `trim` — Extract time ranges (sox-compatible)
- `concat` — Join multiple files (sox-compatible)
- `stats` — Signal statistics (sox-compatible)
- `preset` — Manage reusable effect chains (save/load/list/show/delete/apply)
- `interactive` — Launch the REPL
- `watch` — Monitor directories for auto-processing

**Example workflows:**

```bash
# Batch processing on GPU
torchfx --device cuda process "*.wav" -O ./processed/ -e normalize

# Unix pipes
cat input.wav | torchfx process - - -e normalize | aplay

# Watch DAW export folder
torchfx watch ./bounces/ ./mastered/ --preset mastering

# Interactive mode with live performance
torchfx interactive
```

See the [CLI blog post](2026-02-15-cli-interface.md) for full details.

### 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](2026-02-15-repl-live-performance.md) 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:**

```python
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:

```python
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:**

```python
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:

```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:

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

Or save as preset:

```bash
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:

```bash
# 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

```bash
# 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

```bash
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

- **GitHub**: [matteospanio/torchfx](https://github.com/matteospanio/torchfx)
- **Issues**: Report bugs, request features
- **Discussions**: Ask questions, share workflows
- **Contributing**: See [CONTRIBUTING.md](https://github.com/matteospanio/torchfx/blob/dev/CONTRIBUTING.md)

---

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

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

*Happy audio processing! 🎵*