Command-Line Interface#

TorchFX includes a full-featured CLI for audio processing directly from your terminal. Install the CLI dependencies with:

pip install torchfx[cli]

All commands are available under the torchfx entry-point.

torchfx --help

Global Options #

Every sub-command inherits these global flags:

Flag	Short	Default	Description
`--verbose`	`-v`	off	Enable DEBUG-level logging
`--device`	`-d`	`cpu`	Processing device (`cpu` or `cuda`)
`--config`	`-c`	—	Path to a TOML configuration file
`--version`	`-V`	—	Print version and exit

torchfx -d cuda process in.wav out.wav -e normalize
torchfx --version

Effect Specifications #

Many commands accept --effect / -e flags. The format is:

name                        # defaults
name:value                  # single positional parameter
name:k1=v1,k2=v2           # keyword parameters
name:pos,k1=v1              # mixed

Examples:

-e normalize
-e "gain:0.5"
-e "reverb:decay=0.6,mix=0.3"
-e "lowpass:cutoff=1000,q=0.707"
-e "parametriceq:frequency=2000,q=1.5,gain=6"

Run torchfx interactive and type effects to see the full list.

Core Commands #

`process`#

Apply an effect chain to one or more audio files.

# Single file
torchfx process input.wav output.wav -e normalize -e "reverb:decay=0.6"

# Batch processing (glob pattern)
torchfx process "*.wav" --output-dir ./processed/ -e gain:0.5

# From a TOML config
torchfx process input.wav output.wav --config chain.toml

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

Option	Description
`--effect` / `-e`	Effect specification (repeatable)
`--output-dir` / `-O`	Output directory for batch mode
`--config` / `-c`	TOML config with `[[effects]]`
`--chunk-size`	Samples per processing chunk (default 65 536)
`--overlap`	Overlap samples between chunks
`--format` / `-f`	Pipe format: `wav` or `raw`
`--rate` / `-r`	Sample rate for raw pipe input
`--channels`	Channel count for raw pipe input

`info`#

Display metadata for an audio file.

torchfx info recording.wav

`play`#

Play an audio file through the default output device (requires sounddevice).

torchfx play song.wav
torchfx play recording.wav -e normalize -e "reverb:decay=0.4"

`record`#

Record audio from a microphone (requires sounddevice).

torchfx record output.wav --duration 10
torchfx record output.wav -t 5 -r 48000 -C 2
torchfx record output.wav -t 10 -e normalize -e "reverb:decay=0.3"

Sox-Compatible Commands #

These commands mirror common SoX workflows, with GPU acceleration under the hood.

`convert`#

Convert between formats, sample rates, and channel layouts.

torchfx convert input.wav output.flac
torchfx convert song.wav mono.wav --channels 1 --rate 16000
torchfx convert hi-res.wav cd.wav -r 44100 -b 16

Option	Description
`--rate` / `-r`	Target sample rate (Hz)
`--channels` / `-c`	Target channel count
`--bits` / `-b`	Bit depth (8, 16, 24, 32)

`trim`#

Extract a time range from an audio file.

torchfx trim input.wav clip.wav --start 1.5 --end 4.0
torchfx trim input.wav clip.wav -s 10 -d 5

Option	Description
`--start` / `-s`	Start time in seconds (default 0)
`--end` / `-e`	End time in seconds
`--duration` / `-d`	Duration in seconds (alternative to `--end`)

`concat`#

Concatenate multiple audio files into one (must share sample rate and channels).

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

`stats`#

Display signal statistics: peak/RMS levels, crest factor, DC offset, dynamic range — with per-channel breakdown.

torchfx stats recording.wav

Preset Management #

Presets let you save and reuse effect chains. They are stored as TOML files in ~/.config/torchfx/presets/.

`preset save`#

torchfx preset save mastering -e normalize -e "reverb:decay=0.4,mix=0.2"
torchfx preset save loud --from chain.toml
torchfx preset save mastering -e normalize --force   # overwrite

`preset list`#

torchfx preset list

`preset show`#

torchfx preset show mastering

`preset apply`#

torchfx preset apply mastering input.wav output.wav

`preset delete`#

torchfx preset delete mastering

Interactive REPL #

The interactive command launches a REPL powered by prompt_toolkit with tab completion and persistent history.

torchfx interactive

Inside the REPL:

torchfx> load song.wav
✓ Loaded song.wav  (2 ch, 44100 Hz, 180.50s)

torchfx> add normalize
✓ [1] Added normalize

torchfx> add reverb:decay=0.5,mix=0.2
✓ [2] Added reverb:decay=0.5,mix=0.2

torchfx> list
Effect Chain:
  1. normalize
  2. reverb:decay=0.5,mix=0.2

torchfx> play
▶ Playback complete (processed).

torchfx> play raw
▶ Playback complete (raw).

torchfx> save output.wav
✓ Saved → output.wav

torchfx> preset save my-chain
✓ Preset 'my-chain' saved → ~/.config/torchfx/presets/my-chain.toml

torchfx> clear
✗ Cleared 2 effect(s).

torchfx> preset load my-chain
✓ Loaded preset 'my-chain' (2 effects).

torchfx> exit
Goodbye!

Live Performance Mode #

The REPL includes a live playback mode for real-time effect changes — perfect for live music performance or sound design experimentation.

The live mode uses a lock-free circular buffer pattern where:

Audio playback runs in a real-time callback thread
Effect chain modifications happen on the main REPL thread
Each audio buffer sees a consistent snapshot of the effect chain
Changes apply at the next buffer boundary (~46ms latency at 44.1kHz)

torchfx> live
▶ Live playback started  (2 ch, 44100 Hz, looping)
Change effects with 'add', 'remove', or 'preset load' — changes apply immediately!
Use 'live stop' to end playback.

torchfx> add reverb:decay=0.8,mix=0.5
✓ [1] Added reverb:decay=0.8,mix=0.5
# ← reverb starts immediately

torchfx> preset load vocal-cleanup
✓ Loaded preset 'vocal-cleanup' (3 effects).
# ← entire chain switches instantly

torchfx> remove 2
✗ Removed [2] lowpass:cutoff=8000
# ← filter removed in real-time

torchfx> live stop
⏹ Live playback stopped.

Key features:

Audio loops continuously
Effect changes apply immediately at the next buffer boundary
Add/remove effects, load presets, clear the chain — all in real-time
Lock-free reads ensure glitch-free playback even during effect swaps
Perfect for live performance, DJ sets, or iterative sound design

REPL Commands #

Command	Description
`load <file>`	Load an audio file
`add <spec>`	Add an effect to the chain
`remove <n>`	Remove effect at index n (1-based)
`list`	Show the current effect chain
`effects`	List all available effect names
`info`	Show loaded file metadata
`play`	Play processed audio (blocks until complete)
`play raw`	Play unprocessed audio
`live`	Start live playback (non-blocking, loops)
`live stop`	Stop live playback
`save <file>`	Save processed audio to file
`preset save <name>`	Save chain as a preset
`preset load <name>`	Load a preset into the chain
`preset list`	List saved presets
`clear`	Clear the effect chain
`help`	Show help
`exit` / `quit`	Exit the REPL

Watch Mode #

Monitor a directory for new or modified audio files and automatically apply effects. Ideal for DAW integration where you export to a watched folder.

torchfx watch ./input/ ./output/ -e normalize -e "reverb:decay=0.4"
torchfx watch ./bounces/ ./mastered/ --config master.toml
torchfx watch ./raw/ ./processed/ --preset vocal-cleanup --recursive

Option	Description
`--effect` / `-e`	Effect specification (repeatable)
`--config` / `-c`	TOML config file
`--preset` / `-p`	Named preset to apply
`--recursive` / `-r`	Watch subdirectories
`--existing`	Process existing files on startup

Press Ctrl-C to stop watching.

TOML Configuration #

Instead of passing --effect flags, you can define chains in TOML files:

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

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

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

[[effects]]
name = "lowpass"
cutoff = 8000
q = 0.707

Use with any command that accepts --config:

torchfx process input.wav output.wav --config chain.toml
torchfx watch ./input/ ./output/ --config chain.toml

Or save as a preset:

torchfx preset save mastering --from chain.toml

Command-Line Interface#

This Page