Batchy Documentation

1. Audio Device Setup

Configure your audio interface for optimal performance:

1. Go to Preferences → Audio Settings
2. Select your audio interface from the dropdown
3. Choose sample rate (44.1kHz, 48kHz, 96kHz, etc.)
4. Set buffer size:
   • Smaller (64-128 samples) = Lower latency, higher CPU usage
   • Larger (512-1024 samples) = Higher latency, lower CPU usage
   • Recommended: 256 samples for most systems

2. Plugin Scanning

Batchy automatically scans for plugins on first launch. Supported formats: VST3 and AU (macOS).

To rescan: Preferences → Plugin Management → Scan Plugins

Default Plugin Locations:

Platform	Format	Path
macOS	VST3	/Library/Audio/Plug-Ins/VST3
macOS	AU	/Library/Audio/Plug-Ins/Components
Windows	VST3	C:\Program Files\Common Files\VST3

Opening an Audio File

Drag and Drop: Drag an audio file from Finder/Explorer onto the Batchy window.

File Menu: Click File → Open Audio File (Cmd/Ctrl+O)

Supported Formats: WAV and AIFF are always available. FLAC, MP3, and OGG depend on readers registered in the build; M4A/AAC/CAF use Apple Core Audio, and WMA/ASF require Windows Media Format support. Run Batchy --help for the exact target-machine list.

Building Your First Processing Chain

1. Switch to Effect Chain View — Click the "Effect Chain" tab
2. Add Nodes — Drag a node from the left panel onto the canvas
3. Connect Nodes — Click and drag from an output pin (right side) to an input pin (left side)
4. Adjust Parameters — Click a node to select it, adjust in the right panel

Example chain:

Input → Gain (+3dB) → Parametric EQ (boost 5kHz) → Compressor → Output

Real-Time Playback

Control	Shortcut
Play/Pause	Space
Stop	Cmd/Ctrl + .
Toggle Loop	L
Toggle Bypass (A/B)	B

1. Click File → Save Preset
2. Enter a name for your preset
3. Add description (optional but recommended)
4. Choose a category (e.g., "Mastering", "Dialogue", "Music")
5. Add tags for easy searching
6. Click "Save"

Your preset is saved as a .batchyfx file and can be recalled via File → Load Preset, used for batch processing, shared with colleagues, and used cross-platform.

1. Load Files — Add multiple files to the file list (drag and drop) or File → Add Files to Batch
2. Configure Output — Right-click Output node, set filename template, format, sample rate, bit depth
3. Start Processing — Click Process → Batch Process Files, review and click "Process"

For command-line processing, see the CLI / Headless section.

Waveform View

• Dual-channel stereo display
• Zoom: Mouse wheel or pinch gesture
• Toggle between original and processed views
• Loop regions: Click and drag to set A-B loop points

Spectrogram View

Enable via View → Show Spectrogram

Setting	Options
Color Scheme	RX-Style, Classic, Heat, Blue
Frequency Scale	Logarithmic (music), Linear (technical), Mel (vocals), Bark (psychoacoustic)
Dynamic Range	Adjustable (default: 70dB)

Node	Purpose	Key Parameters
Gain	Level control	Gain (dB)
Parametric EQ	Frequency shaping	Frequency, Q, Gain per band
Compressor	Dynamic control	Threshold, Ratio, Attack, Release
Limiter	Loudness maximization	Ceiling, Release
Delay	Echo effects	Time, Feedback, Mix
Reverb	Spatial effects	Room Size, Damping, Mix
Spectrum Analyzer	Frequency visualization	FFT Size, Display Mode
Level Meter	Loudness metering	Peak, RMS, LUFS

Performance

• Adjust buffer size — increase if you experience dropouts
• Batch processing automatically uses multiple CPU cores
• Complex chains can be bounced to audio for better performance

Workflow

• Save commonly-used chains as presets
• Right-click node → Rename to label complex graphs
• Use sticky notes and arrows to document routing
• Always test with a single file before batch processing

Task	How
Load Audio File	Drag & drop onto window, or File → Open (Cmd/Ctrl+O)
Build Processing Chain	Effect Chain tab → drag nodes → connect pins
Save Preset	File → Save Preset (Cmd/Ctrl+S)
Load Preset	File → Load Preset, or double-click .batchyfx file
Batch Process (GUI)	Add files → configure Output node → Process → Batch Process
Batch Process (CLI)	./Batchy --batch-process --input <path> --preset <file>

Sample Rates

Rate	Use
44.1 kHz	CD quality
48 kHz	Video/film standard
96 kHz	Hi-res audio
192 kHz	Ultra hi-res (high CPU)

Buffer Sizes

Size	Latency	CPU
64-128 samples	3-6ms	High
256 samples	~6ms	Balanced (Recommended)
512-1024 samples	12-23ms	Low
2048 samples	Very high	Minimal

Bit Depths

Depth	Use
16-bit	CD quality, smaller files
24-bit	Professional standard
32-bit float	Maximum headroom, no clipping

Input

WAV and AIFF are always available. FLAC, MP3, and OGG depend on readers registered in the build; M4A/AAC/CAF use Apple Core Audio, and WMA/ASF require Windows Media Format support. Run Batchy --help for the exact target-machine list.

Output

Format	Type
WAV	Uncompressed PCM (16/24/32-bit)
AIFF	Uncompressed PCM (16/24/32-bit)
FLAC	Lossless compression
OGG	Compressed (lossy)
MP3	Compressed (lossy)

Date/Time

Token	Example
$year, $month, $day	2026, 04, 02
$date	2026-04-02
$timestamp	20260402-143022

File & System

Token	Description
$filename	Original name without extension
$counter{N}	Auto-incrementing (N = zero-padding digits)
$outputnode	Name of the output node
$user	System username
$computer	Hostname

Path Tokens

$documents, $music, $desktop, $home, $source, $working

User-Defined

$project, $author, $client, $engineer, $studio, $show

Metadata Tokens (require MetadataProvider nodes)

$sample_rate, $bit_depth, $duration, $channels, $file_size, $file_created, $parent_folder

Common Templates

$filename_processed           → mysong_processed.wav
$date/$filename              → 2026-04-02/mysong.wav
$client/$project/$filename   → ABC Studios/Album 2025/mysong.wav

macOS

Type	Path
Presets	~/Library/Application Support/Batchy/Presets/
Logs	~/Library/Application Support/Batchy/Batchy.log (GUI); .../Batchy/Logs/batch_process_*.log (CLI)
Settings	~/Library/Application Support/Batchy/Settings/
Plugin Cache	~/Library/Application Support/Batchy/pluginList.xml

Windows

Type	Path
Presets	%APPDATA%\Batchy\Presets\
Logs	%APPDATA%\Batchy\Batchy.log (GUI); %APPDATA%\Batchy\Logs\batch_process_*.log (CLI)
Settings	%APPDATA%\Batchy\Settings\
Plugin Cache	%APPDATA%\Batchy\pluginList.xml

Code	Meaning
0	Success — the requested operation completed
1	Processing failed — a render/fatal processing error occurred, result accounting was inconsistent, or a requested report could not be written
2	Configuration error — invalid arguments, missing input/preset, nothing to process, or another pre-processing validation failure
130	Cancelled or interrupted — for example Ctrl+C, SIGINT, SIGTERM, or an internal cancellation deadline

1. Use appropriate buffer size — balance latency vs. CPU
2. Process similar files together — same format/rate = faster
3. Use multi-threading for batches — set --max-threads to CPU core count
4. Test with dry run — validate before processing large batches
5. Use local storage — network drives slow processing
6. Close other audio apps — prevent interface conflicts

Shortcut	Action
Space	Play/Pause
Cmd/Ctrl + .	Stop (return to start)
L	Toggle Loop
B	Toggle Bypass (A/B)
Home	Jump to Start
End	Jump to End

Shortcut	Action
Cmd/Ctrl + O	Open Audio File
Cmd/Ctrl + S	Save Preset
Cmd/Ctrl + Shift + S	Save Preset As
Cmd/Ctrl + W	Close Window
Cmd/Ctrl + Q	Quit Application

Shortcut	Action
Cmd/Ctrl + Z	Undo
Cmd/Ctrl + Shift + Z	Redo
Cmd/Ctrl + X	Cut
Cmd/Ctrl + C	Copy
Cmd/Ctrl + V	Paste
Cmd/Ctrl + D	Duplicate
Delete	Delete Selected
Cmd/Ctrl + A	Select All
Escape	Clear Selection

Shortcut	Action
Space + Drag	Pan Canvas
Middle Mouse + Drag	Pan Canvas (alt)
Mouse Wheel	Zoom In/Out
Cmd/Ctrl + +	Zoom In
Cmd/Ctrl + -	Zoom Out
Cmd/Ctrl + 0	Fit to Window
F	Frame Selection
H	Home View
Tab	Switch View (Waveform/Effect Chain)

Shortcut	Action
Double-Click Node	Open Editor
Cmd/Ctrl + Click	Add to Selection
Cmd/Ctrl + E	Bypass Selected
R	Rename Node
Cmd/Ctrl + I	Node Info

Shortcut	Action
Click + Drag	Adjust Value
Shift + Drag	Fine Adjust (10x slower)
Double-Click Slider	Reset to Default
Alt + Click	Type Numeric Value
Arrow Keys	Increment/Decrement
Page Up/Down	Large Adjust

Shortcut	Action
Mouse Wheel	Zoom Horizontal
Shift + Mouse Wheel	Zoom Vertical
Click + Drag	Set Loop Region
Double-Click	Clear Loop
S	Toggle Spectrogram
M	Toggle Mono/Stereo
G	Toggle Grid

Shortcut	Action
Cmd/Ctrl + B	Open Batch Window
Cmd/Ctrl + Enter	Start Processing
Escape	Cancel Processing
Cmd/Ctrl + R	Refresh Preview

Space       Play/Pause
Cmd/Ctrl+S  Save Preset
Cmd/Ctrl+Z  Undo
Delete      Delete Selected
B           Bypass (A/B)
Tab         Switch View
Cmd/Ctrl+0  Fit Graph

Process a single file:

./Batchy --batch-process \
  --input audio.wav \
  --preset my_effect.batchyfx \
  --output-dir ./processed

Process all files in a directory:

./Batchy --batch-process \
  --input /path/to/audio/folder \
  --preset my_effect.batchyfx \
  --output-dir /path/to/processed

Run ./Batchy --help for the exact options and formats supported by that build. ./Batchy --help-json writes one strict JSON document to stdout for automation and wrapper integrations; diagnostics are sent to stderr.

Executable Location

Platform	Path
macOS	/Applications/Batchy.app/Contents/MacOS/Batchy
Windows	C:\Program Files\Batchy\Batchy.exe

The Windows installer uses the path above by default; a custom install may use another folder. If you add the executable’s directory to PATH, invoke Batchy --batch-process ... directly.

Required Arguments

Option	Short	Description
--batch-process	--batch	Enable headless batch processing mode
--input <path>	-i	Input audio file or directory
--preset <file>	-p	Batchy preset file (.batchyfx) or catalog preset name. Use --list-presets to see available catalog presets.

Output Configuration

Option	Short	Description
--output-dir <path>	-o	Output directory (default: input directory). If the final path would equal the input, Batchy refuses unless you explicitly pass --in-place or --overwrite-outputs.
--output-format <fmt>		Output format: wav, aiff, flac; plus ogg or mp3 only when that encoder is registered. Run Batchy --help on the target machine for the exact list.
--output-sample-rate <rate>		Sample rate (22050, 44100, 48000, 88200, 96000, 192000) or “same” to match input
--output-bit-depth <depth>		Bit depth: 16, 24, 32, 32float, or “same”. (32 and 32float are equivalent — IEEE 754 single-precision float)
--output-channels <config>		Channel layout: mono, stereo, “same”, or “graph”
--output-filename <template>		Relative filename or safe subpath beneath --output-dir, with $tokens
--output <selector>		Select output nodes by ID, exact name, or a name glob using * and ?
--output-override <target:key:value>		Per-output setting override; repeat for multiple overrides (see Per-Output Overrides)

Processing Options

Option	Short	Description
--normalization <type>		Normalization mode: none, peak, rms, lufs. Also accepts --normalisation. LUFS uses EBU R128 integrated loudness measurement. Peak uses sample peak (not true peak).
--target-loudness <target>		Target for the selected normalization mode, from -60 to 0: LUFS for lufs, dBFS for peak/rms. Defaults when selecting a mode are -14 LUFS, -1 dBFS peak, and -20 dBFS RMS.
--tail-length <seconds>		Render additional tail after file ends, in seconds (for reverbs, delays). Without this flag, the preset’s tail settings are used.
--no-tail		Disable tail rendering — output is truncated at input file duration
--max-threads <count>		Parallel processing threads (default: min(4, CPU cores))
--fail-fast		Stop remaining batch work after the first render failure
--render-report <path>		Write a JSON report, including failures and cancellation; missing parent directories are created after validation
--session-name <name>		Name this batch session in the report
--preserve-format		Keep source file’s format when no override is specified. Also accepts --preserve-original-format.
--no-preserve-format		Force preset default format
--preserve-spaces		Keep spaces in output filenames, overriding the preset
--no-preserve-spaces		Replace spaces with underscores, overriding the preset; with neither flag, use the preset setting
--overwrite-outputs		Overwrite existing output files instead of skipping them
--in-place		Allow a resolved output to replace its input. Batchy renders to a temporary file and swaps only after a successful render; use only when replacement is intentional.

General Options

Option	Short	Description
--help	-h	Show help message
--help-json		Output help in JSON format — useful for building GUI wrappers or validating automation scripts
--list-override-keys		List all valid per-output override keys and accepted values
--list-presets		List available catalog presets and exit
--verbose	-v	Enable detailed logging
--log-file <path>		Write logs to a file; Batchy creates missing parent directories
--progress		Show progress bar. Also accepts --show-progress.
--dry-run		Validate inputs and configuration without processing

License Commands

These are standalone, mutually exclusive commands. They do not require --batch-process, --input, or --preset, and exit after the requested license operation. Headless exports use the same machine license or trial state as the GUI.

Option	Description
--license-status	Print the current license state and machine ID; returns 0 even when the machine is unlicensed or the trial has expired
--activate <license-key>	Activate this machine and exit; a rejected activation returns 1, while a missing key returns 2
--deactivate	Deactivate this machine and exit; returns 1 when no active license exists or deactivation fails

Batchy --license-status
Batchy --activate "YOUR-LICENSE-KEY"
Batchy --deactivate

Accepted Aliases

The canonical names above are recommended for new scripts. The parser also accepts these compatibility spellings:

Canonical option	Accepted aliases
--help	-h
--verbose	-v
--batch-process	--batch
--input	-i
--preset	-p
--output-dir	-o, --output-directory
--output-format	--format, --file-format
--output-sample-rate	--sample-rate, --samplerate, --rate
--output-bit-depth	--bit-depth, --bitdepth, --depth
--output-filename	--filename, --file-name, --filename-template, --output-filename-template
--normalization	--normalisation
--target-loudness	--loudness, --targetloudness
--output-channels	--channels
--progress	--show-progress
--preserve-format	--preserve-original-format
--output	--outputs
--output-override	--override

• Relative paths: file and directory arguments are resolved from the process’s current working directory, including --input, preset paths, --output-dir, --log-file, --render-report, GUI load paths, and positional audio paths. Paths beginning with ~ resolve from the user’s home directory.
• Validation before mutation: parser and mode-validation failures do not create user-requested output, log, or report directories. Each output destination is also safety-checked before its directory is materialized.
• Contained outputs: filename templates may create safe subdirectories but must remain relative beneath the resolved output root; absolute filenames and .. escapes are rejected. Output roots are canonicalized through symlinks, and blocked system locations or over-limit path components are rejected before writing.
• Existing files: a different existing output is skipped by default; pass --overwrite-outputs to replace it.
• Input replacement: if an output resolves to the input itself, Batchy fails unless --in-place or --overwrite-outputs explicitly permits replacement. In-place renders use a temporary sibling plus swap/rollback protection rather than writing directly over the source.

For automation, use distinct input/output directories and run --dry-run first. A dry run performs production path and output-collision validation without rendering or creating output directories.

--render-report <path> writes a deterministic JSON summary after a batch reaches processing, including failed, skipped, and cancelled counts. It creates missing report parent directories. Commands rejected before processing do not create a report; if a requested report cannot be written, the process returns exit code 1.

The stable top-level fields are session, summary, parameterOverrides, and files:

{
  "session": {
    "name": "nightly-mastering",
    "startTime": "...",
    "endTime": "...",
    "durationMs": 1234,
    "batchyVersion": "...",
    "preset": "mastering.batchyfx"
  },
  "summary": {
    "totalFiles": 2,
    "succeeded": 1,
    "failed": 1,
    "skipped": 0,
    "cancelled": 0,
    "exitCode": 1
  },
  "parameterOverrides": [],
  "files": [
    {
      "input": "...",
      "output": "...",
      "status": "success|failed|skipped",
      "error": "present when applicable",
      "durationMs": 0,
      "inputSize": 0,
      "outputSize": 0,
      "inputFormat": { "sampleRate": 48000, "bitDepth": 24, "channels": 2 },
      "outputFormat": { "sampleRate": 48000, "bitDepth": 24, "channels": 2 },
      "peakLevelDb": 0,
      "warnings": []
    }
  ]
}

Use --session-name to label the report. The report’s summary.exitCode matches the process result for the reported batch, including exit 130 for cancellation. Headless reports currently provide aggregate rows: their per-file path/format fields may contain the requested batch paths and zero/unknown metadata, with an aggregate-only warning. Do not treat those fields as a per-file manifest.

Input Formats

WAV and AIFF are always available. FLAC, MP3, and OGG depend on the readers registered in that build; M4A/AAC/CAF use Apple Core Audio, and WMA/ASF require Windows Media Format support. Run Batchy --help on the target machine for the exact list.

Output Formats

• Always available: WAV, AIFF, FLAC
• Runtime-gated: OGG and MP3 are listed only when a working encoder is registered. Run --help on the target machine.

Note: AAC/M4A output is not supported.

Important: Shell quoting. Templates containing $tokens must be single-quoted on macOS/Linux to prevent shell variable expansion:

--output-filename '$filename_$date'     # Correct (single quotes)
--output-filename "$filename_$date"     # WRONG — shell expands $filename and $date

On Windows CMD, $ is not special. In PowerShell, use single quotes or backtick escaping (`$filename).

Built-in Tokens

Token	Description	Example
$filename	Original filename (no extension)	mysong
$outputnode	Output node name	Master

Date & Time Tokens

Token	Description	Example
$date	YYYY-MM-DD	2026-03-26
$time	HH-MM-SS	14-30-22
$timestamp	Full timestamp	20260326-143022
$year	Four-digit year	2026
$yearshort	Two-digit year	26
$month	Two-digit month	03
$monthname	Month name	March
$day	Two-digit day	26
$hour	Two-digit hour (24h)	14
$minute	Two-digit minute	30
$second	Two-digit second	22

Counter Token

Token	Description	Example
$counter	Auto-incrementing counter	1, 2, 3, ...
$counter{N}	Zero-padded to N digits	001, 002, ...

Note: The {N} padding syntax only works with the $counter token.

System Tokens

Token	Description	Example
$user	System username	johndoe
$computer	Computer name	studio-mac

Path Tokens

For use in templates that include directory structure:

Token	Description
$documents	User’s Documents directory
$music	User’s Music directory
$desktop	User’s Desktop directory
$home	User’s home directory
$working	Current working directory
$source	Input file’s parent directory
$appdata	Application data directory
$temp	System temp directory

User-Defined Tokens

Set via CLI arguments:

Flag	Token	Description
--project <name>	$project	Project name
--author <name>	$author	Author/artist name
--client <name>	$client	Client name
--engineer <name>	$engineer	Engineer name
--studio <name>	$studio	Studio name
--show <name>	$show	Show/production name
--user-token <name=value>	${name}	Custom token; repeat the option for multiple values. Names must start with a letter and contain only letters, digits, and underscores.

batchy --batch-process \
  --input ./audio \
  --preset mypreset.batchyfx \
  --project "Album 2026" \
  --author "Artist Name" \
  --user-token rev=v2 \
  --output-filename '$project/$author/${rev}_$filename'
# Produces: Album 2026/Artist Name/v2_mysong.wav

Deliverable Metadata Tokens

These tokens resolve from the current processing context first, then fall back to values set in Batchy’s Preferences:

Token	Description
$version	Version identifier (e.g., “v2”, “final”)
$mix	Mix variant (e.g., “vocal up”, “instrumental”)
$language	Language tag (e.g., “en”, “es”)
$territory	Territory/region (e.g., “US”, “EU”)
$deliverable	Deliverable type (e.g., “master”, “stem”, “preview”)

Metadata Tokens

Require MetadataProvider nodes in your preset:

• File: $file_size, $file_modified, $file_created, $parent_folder
• Audio: $sample_rate, $bit_depth, $duration, $channels

When your preset has multiple outputs, you can customize settings per output node. Run --list-override-keys to see all valid keys and accepted values.

Syntax

Two equivalent syntaxes:

--output-override="<target>:<key>:<value>"
--output:<target>.<key>=<value>

Where <target> is an output node name or wildcard selector (e.g., Stems/*).

Override Precedence

1. Per-output overrides (--output-override, --output:) — highest
2. Global CLI overrides (--output-format, --output-sample-rate, etc.)
3. Preset defaults — lowest

Override Keys Reference

output-path-template is a scoped override key, not a standalone flag. Use --output-override='Master:output-path-template:$project/Masters' or --output:Master.output-path-template='$project/Masters'.

Examples

# Different format per output
--output-override="Master:format:wav" \
--output-override="Stems/*:format:flac"

# Different loudness targets for different delivery platforms
--output-override="Streaming:loudness:-14" \
--output-override="CD:loudness:-9"

# Using legacy syntax
--output:Master.format=wav \
--output:Stems/*.format=flac

Batchy supports presets with multiple output nodes. By default, all output nodes are rendered.

# Render specific outputs only
./Batchy --batch-process \
  --input audio.wav \
  --preset stems_preset.batchyfx \
  --output "Master,Vocals,Drums"

# Use wildcards
--output "Stems/*"

# Per-output format overrides
--output-override "Master:format:wav" \
--output-override "Stems/*:format:flac"

Sample Rate Conversion

When --output-sample-rate differs from the source, offline rendering uses the highest-quality 200-point windowed-sinc mode (approximately -120 dB aliasing rejection). Its group delay is compensated so converted files remain sample-aligned in duration.

Dithering

When enabled in the preset’s output node, TPDF (Triangular Probability Density Function) dithering is applied at the final write depth (for example, when delivering 16-bit audio). Configure it in the GUI when creating the preset.

Double-dithering is automatically prevented: any in-graph dithering is suppressed during batch rendering so only the final post-render dither is applied.

Loudness Measurement

LUFS normalization uses integrated programme loudness with ITU-R BS.1770-4/EBU R128 weighting and gating. LUFS and RMS normalization then use true-peak-aware limiting plus a final BS.1770-4 true-peak safety stage at -1.0 dBTP; peak normalization remains gain-only and targets sample peak. Uncommon channel layouts without a canonical BS.1770 table use a conservative flat-weight fallback and emit a warning.

Normalization mode	Default when selected from CLI
LUFS	-14 LUFS
Peak	-1 dBFS sample peak
RMS	-20 dBFS RMS

Pass --target-loudness to override these defaults. Delivery-platform recommendations change; follow the current specification from your distributor or broadcaster rather than treating Batchy’s defaults as a delivery mandate.

These flags launch Batchy in GUI mode with pre-loaded state — they require a display and are distinct from headless --batch-process mode. Do not combine GUI launch/automation flags with --batch-process; Batchy rejects mixed modes before opening the UI or creating requested output paths.

File & Preset Loading

Option	Description
--load-audio=<path>	Load audio file or directory into GUI (repeatable)
--load-preset=<name>	Load preset by name or path
--scan-plugin=<path>	Scan a single plugin file and exit

Positional arguments (bare audio file paths) are also loaded into the GUI. Relative GUI paths resolve from the current working directory, just like headless paths.

Automation Flags

Option	Description
--auto-play	Start playback automatically after loading
--auto-render	Open batch window and start rendering after loading
--auto-processed	Enable processed mode (show rendered waveform)

Render Control

Option	Description
--exit-after-render	Exit application after render completes
--output-dir <path>	Set the destination for GUI --auto-render; other batch-only output overrides require --batch-process

Example: Automated Render Pipeline

./Batchy \
  --load-audio=/audio/session \
  --load-preset="Mastering Chain" \
  --auto-render \
  --exit-after-render

To use third-party VST/AU plugins in batch mode, first run the GUI to scan your plugins. The cache is stored at:

Platform	Path
macOS	~/Library/Application Support/Batchy/pluginList.xml
Windows	%APPDATA%\Batchy\pluginList.xml

The CLI automatically loads this cache. Without it, only built-in effects are available.

Process with custom output settings

./Batchy --batch-process \
  --input /audio/masters \
  --preset mastering_chain.batchyfx \
  --output-dir /audio/output \
  --output-format flac \
  --output-sample-rate 96000 \
  --output-bit-depth 24 \
  --normalization lufs \
  --target-loudness -14 \
  --progress

Process with tail rendering

./Batchy --batch-process \
  --input /audio/vocals \
  --preset reverb_chain.batchyfx \
  --tail-length 3.0 \
  --output-format flac

Preserve original format during normalization

./Batchy --batch-process \
  -i /audio/mixed_formats \
  -p normalize.batchyfx \
  --preserve-format \
  --normalization lufs \
  --target-loudness -14

WAV-to-FLAC archival conversion

./Batchy --batch-process \
  -i /audio/session_masters \
  -p passthrough.batchyfx \
  --output-format flac \
  --output-bit-depth 24 \
  -o /archive/flac

Stem delivery with client naming

./Batchy --batch-process \
  -i session.wav \
  -p stems_export.batchyfx \
  --client "Acme Records" \
  --project "Album 2026" \
  --output-filename '$client/$project/$filename_$outputnode' \
  --output-format wav \
  --output-sample-rate 48000 \
  --output-bit-depth 24

Log to file for debugging

./Batchy --batch-process \
  -i audio.wav \
  -p effect.batchyfx \
  -v --log-file /tmp/batchy.log

Scheduled folder automation

Run the same command from macOS launchd or Windows Task Scheduler. Existing outputs are skipped by default, so a recurring job can safely revisit the incoming directory:

Batchy --batch-process \
  --input /audio/incoming \
  --preset /presets/auto_process.batchyfx \
  --output-dir /audio/processed \
  --render-report /audio/reports/latest.json \
  --fail-fast

Script integration

#!/bin/bash
./Batchy --batch-process \
  --input "$1" \
  --preset effect.batchyfx \
  --output-dir ./processed
status=$?

case "$status" in
  0)   echo "Processing completed successfully" ;;
  1)   echo "One or more processing operations failed" ;;
  2)   echo "Command or configuration error" ;;
  130) echo "Processing was cancelled or interrupted" ;;
  *)   echo "Unexpected exit code: $status" ;;
esac
exit "$status"

Exit Codes

Code	Meaning
0	Success: the requested operation completed
1	Processing failure: a render/fatal processing error occurred, result accounting was inconsistent, or a requested report could not be written
2	Configuration error: invalid or incompatible arguments, missing input/preset, nothing to process, or pre-processing validation failure
130	Cancelled or interrupted: Ctrl+C, SIGINT, SIGTERM, internal cancellation, or deadline expiry

Debugging Failed Runs

Combine --verbose, --log-file, and --dry-run to diagnose issues:

# Validate configuration without processing
./Batchy --batch-process -i /audio -p preset.batchyfx --dry-run --verbose

# Run with full logging to file
./Batchy --batch-process -i /audio -p preset.batchyfx --verbose --log-file debug.log

Common Errors

• “Preset not found” — use the full .batchyfx file path, or run --list-presets to see available catalog names
• “No audio files found” — run Batchy --help and check that the input directory contains a format supported by that platform build
• “Plugin not available in headless mode” — third-party plugins require a GUI scan first (see External Plugin Support above)
• “Output would overwrite the input” — choose a separate --output-dir, or pass --in-place only when source replacement is intentional

Log Locations

Platform	Path
macOS	~/Library/Application Support/Batchy/Logs/batch_process_*.log
Windows	%APPDATA%\Batchy\Logs\batch_process_*.log

Limitations

• Real-time plugin parameters cannot be automated during batch processing
• Rendering is streamed rather than buffered as a whole file, but source/output format limits, free disk space, path limits, plugin behavior, and the configured render deadline still apply
• Some plugin formats may not be available in headless mode

No Audio Output

1. Check Preferences → Audio Settings — verify correct interface selected
2. Ensure audio interface is connected and powered on
3. Check system audio settings (macOS: System Settings → Sound → Output)
4. Try increasing buffer size to 512 or 1024 samples
5. Ensure sample rate matches your interface
6. Press B to toggle bypass — if sound works, issue is in processing chain

Audio Dropouts / Glitches

1. Increase buffer size (Preferences → Audio → Buffer Size)
2. Close other audio applications and background apps
3. Bypass heavy plugins to identify CPU-heavy nodes
4. Use direct USB/Thunderbolt connection (avoid hubs)
5. Copy files to local SSD before processing

Distortion or Clipping

1. Check gain staging — aim for -6dB to -3dB peaks between nodes
2. Reduce limiter/compressor intensity
3. Bypass plugins one at a time to isolate culprit
4. Use 24-bit or 32-bit float output for maximum headroom

Plugin Not Found

1. Rescan: Preferences → Plugin Management → Scan Plugins
2. Verify plugin location:
   • macOS VST3: /Library/Audio/Plug-Ins/VST3
   • macOS AU: /Library/Audio/Plug-Ins/Components
   • Windows VST3: C:\Program Files\Common Files\VST3
3. Batchy supports VST3 and AU only — VST2 is not supported
4. Plugins must be 64-bit
5. Check blacklist: Preferences → Plugin Management → Blacklist
6. macOS: Check System Settings → Privacy & Security for unsigned plugins

Plugin Crashes Batchy

1. Note which plugin you added before the crash
2. Update the plugin to latest version from vendor
3. Send crash logs to support: macOS ~/Library/Logs/DiagnosticReports/

Plugin UI Not Appearing

1. Double-click plugin node to open editor
2. Check if plugin window is behind Batchy (Mission Control / taskbar)
3. Close and reopen plugin editor, or restart Batchy

"File Could Not Be Loaded"

1. Check format — use the platform-specific input list printed by Batchy --help
2. Verify file isn't corrupted (try opening in another app)
3. Very high sample rates (384kHz+) may not be supported
4. Check file permissions and path length

Large File Warnings

Batchy uses memory-mapped I/O — actual RAM usage is only 5-30 MB per file regardless of size. Warnings appear at files ≥ 2 GB and are informational only.

Adjust threshold: Preferences → File Limits → Warning Threshold (10-25%)

Drag and Drop Not Working

1. Drop directly onto waveform area, not toolbar
2. macOS: Check System Settings → Privacy → Files and Folders
3. Try using File → Open instead

Batch Processing Fails to Start

1. Verify preset file path and .batchyfx extension
2. Check input path exists and files have supported extensions
3. Choose a writable output location; Batchy creates missing directories only after the command and path checks pass
4. Use --dry-run to validate configuration

Some Files Fail

1. Use --verbose for detailed error messages
2. Use --output-sample-rate same to avoid resampling issues
3. Add $counter{3} to filename template to avoid conflicts
4. Check disk space and file permissions

Processing is Very Slow

1. Increase threads: --max-threads 8
2. Copy files to local SSD (network drives are slow)
3. Use --output-sample-rate same to skip resampling
4. Use --progress to monitor

Slow / Laggy UI

1. Close other applications to free RAM and CPU
2. Very complex graphs (50+ nodes) can impact UI — consider splitting presets
3. Increase buffer size for high-resolution files
4. Update graphics drivers

Batchy Crashes

1. Most crashes are plugin-related — disable recently added plugins
2. Try deleting preferences: macOS ~/Library/Application Support/Batchy/
3. Update your OS and Batchy to latest version
4. Send crash logs to support

Batchy Won't Launch

1. macOS Gatekeeper: Right-click → Open, or run xattr -cr /Applications/Batchy.app
2. Windows SmartScreen: Click "More info" → "Run anyway"
3. Try deleting license file and re-activating

"License Invalid" or "License Expired"

1. Check license status in Preferences → License, or run Batchy --license-status on a headless machine
2. Ensure internet connection for first activation
3. Copy-paste license key from email to avoid typos
4. Personal licenses allow 2 simultaneous activations — deactivate old machine first

Headless Activation

Batchy --activate "YOUR-LICENSE-KEY"
Batchy --license-status
# Before retiring or moving this machine:
Batchy --deactivate

Each command is standalone and exits immediately. Do not combine license commands with one another.

"Activation Required" on first launch

Batchy needs a purchased license to run. Enter the license key from your purchase confirmation email on the activation screen. If you don't have a license yet, buy one here — reinstalling or moving machines won't change this.

macOS: "Batchy is damaged and can't be opened"

xattr -cr /Applications/Batchy.app

Run in Terminal, then try launching again.

Windows: Missing DLL Error

Install Visual C++ Redistributable 2022 (x64) from Microsoft, then restart.

Windows: Audio Device Shows "ASIO4ALL"

Install proper ASIO drivers from your audio interface manufacturer.

Before contacting support, please gather:

1. Batchy version (Help → About Batchy)
2. Operating system version
3. Audio interface make and model
4. Steps to reproduce the issue
5. Screenshots of error dialogs
6. Crash logs: macOS ~/Library/Logs/DiagnosticReports/ • Windows %LOCALAPPDATA%\Batchy\CrashDumps\ and Event Viewer

Email: support@batchyandfriends.com

Typically within 24 hours (business days).