TorchFX CLI: GPU-Accelerated Audio Processing from the Terminal#

One of the most requested features for TorchFX has finally arrived: a full-featured command-line interface that brings GPU-accelerated audio processing directly to your terminal. Whether you’re a music producer, sound designer, or audio engineer, the new torchfx CLI tool streamlines your workflow with familiar commands and powerful new capabilities.

From Library to Tool#

While TorchFX started as a Python library for audio DSP research, we recognized that many users need quick, scriptable audio processing without writing Python code. The CLI bridges this gap, offering:

  • Sox-compatible commands for easy migration from existing workflows

  • GPU acceleration for batch processing hundreds of files

  • Unix pipe support for integrating with existing audio pipelines

  • TOML configuration files for reproducible effect chains

  • Preset management for reusable processing templates

Core Commands#

Process Audio Files#

The process command is your workhorse for applying effects:

# Single file with effects
torchfx process input.wav output.wav -e normalize -e "reverb:decay=0.6,mix=0.3"

# Batch processing with GPU acceleration
torchfx process "*.wav" --output-dir ./mastered/ --device cuda -e normalize

# Unix pipes for integration
cat raw.wav | torchfx process - - -e normalize | aplay

The effect syntax is intuitive: name:param1=val1,param2=val2. With 30+ built-in effects and filters registered (from gain to parametriceq), you have a complete DSP toolkit at your fingertips.

File Information#

Quickly inspect audio metadata with rich table output:

torchfx info recording.wav

This displays sample rate, channels, duration, encoding, and file size in a clean, formatted table — perfect for scripts that need to validate audio properties.

Playback & Recording#

Preview your processing with direct playback:

# Play with effects applied on-the-fly
torchfx play song.wav -e normalize -e "reverb:decay=0.4"

# Record from microphone
torchfx record output.wav --duration 10 -r 48000 -C 2

Both commands require the optional sounddevice package (pip install torchfx[realtime]), giving you instant audio I/O without leaving the terminal.

Sox-Compatible Commands#

For users migrating from SoX or needing familiar tools, we’ve implemented a subset of sox commands with GPU acceleration:

Convert#

Format, sample rate, and channel conversion:

torchfx convert input.wav output.flac
torchfx convert hi-res.wav cd-quality.wav -r 44100 -b 16
torchfx convert stereo.wav mono.wav --channels 1

Trim#

Extract time ranges with precision:

torchfx trim input.wav clip.wav --start 1.5 --end 4.0
torchfx trim long.wav first-30s.wav --duration 30

Concat#

Join multiple files seamlessly:

torchfx concat part1.wav part2.wav part3.wav -o full.wav

Stats#

Analyze signal characteristics:

torchfx stats recording.wav

Get detailed statistics including peak/RMS levels in dBFS, crest factor, DC offset, dynamic range, and per-channel breakdowns — all in a beautifully formatted table.

Configuration Files & Presets#

For complex effect chains, TOML configuration files provide reproducibility:

# mastering.toml
device = "cuda"

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

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

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

Use it with any command:

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

Preset Management#

Save and reuse your favorite chains:

# Save a preset
torchfx preset save mastering -e normalize -e "reverb:decay=0.5,mix=0.2"

# List all presets
torchfx preset list

# Apply a preset
torchfx preset apply mastering input.wav output.wav

# View preset contents
torchfx preset show mastering

Presets are stored as TOML files in ~/.config/torchfx/presets/, making them easy to share and version control.

Watch Mode: DAW Integration#

The watch command monitors directories for new or modified audio files and automatically applies your effect chain:

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

# Recursive watching with real-time updates
torchfx watch ./input/ ./output/ --recursive -e normalize -e "reverb:decay=0.4"

This is perfect for DAW workflows: export your tracks to a watched folder and get instant mastered versions. The watch mode runs continuously, showing rich status updates as files are processed.

Batch Processing at Scale#

One of the CLI’s killer features is GPU-accelerated batch processing. When processing hundreds of files, the difference is dramatic:

# Process an entire album on GPU
torchfx --device cuda process "album/*.wav" -O ./mastered/ -e normalize -e "reverb:decay=0.5"

You get a beautiful progress bar with ETA, per-file success/failure reporting, and processing speeds that scale with your GPU. On modern hardware, expect >100x real-time throughput.

Global Options#

Every command supports global flags:

  • --device cuda — GPU acceleration

  • --verbose — DEBUG-level logging

  • --config — Global configuration file

  • --version — Show version

Design Philosophy#

The CLI follows Unix philosophy:

  • Do one thing well: Each command has a clear, focused purpose

  • Composable: Pipe commands together for complex workflows

  • Scriptable: Predictable output formats for automation

  • Fast: GPU acceleration where it matters

But it also brings modern conveniences:

  • Rich output: Beautiful tables and progress bars

  • Smart defaults: Sensible parameter values

  • Helpful errors: Clear messages with suggestions

Installation#

Get started in seconds:

pip install torchfx[cli]

This installs all CLI dependencies (typer, rich, tomli for Python <3.11). For playback and recording:

pip install torchfx[realtime]

Real-World Workflows#

Podcast Cleanup#

#!/bin/bash
# podcast-cleanup.sh

torchfx process "$1" "${1%.wav}_cleaned.wav" \
  -e normalize \
  -e "highpass:cutoff=80" \
  -e "lowpass:cutoff=15000"

Batch Album Mastering#

torchfx --device cuda process "album/*.wav" \
  -O ./mastered/ \
  --config mastering-chain.toml

DAW Export Monitor#

torchfx watch ~/Music/Exports/ ~/Music/Mastered/ \
  --preset vocal-cleanup \
  --recursive

What’s Next?#

The CLI is just the beginning. Future releases will add:

  • Real-time parameter visualization

  • Spectrum analyzer integration

  • A/B comparison mode

  • Waveform preview in terminal

Try It Today#

The TorchFX CLI is available now in version 0.4.0. Install it, explore the commands, and let us know what you think!

pip install torchfx[cli]
torchfx --help

For complete documentation, see the CLI Guide.

Have questions or feature requests? Open an issue on GitHub or start a discussion!

TorchFX 0.4.0: Production-Ready Audio DSP 🚀