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, AIFF, FLAC, MP3, OGG, M4A, WMA

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, AIFF, FLAC, MP3, OGG Vorbis, M4A, WMA

Output

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

Date/Time

Token	Example
$year, $month, $day	2025, 10, 19
$date	2025-10-19
$timestamp	20251019-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              → 2025-10-19/mysong.wav
$client/$project/$filename   → ABC Studios/Album 2025/mysong.wav

macOS

Type	Path
Presets	~/Library/Application Support/Batchy/Presets/
Logs	~/Library/Logs/Batchy/
Settings	~/Library/Application Support/Batchy/Settings/
Plugin Cache	~/Library/Application Support/Batchy/pluginList.xml

Windows

Type	Path
Presets	%APPDATA%\Batchy\Presets\
Logs	%APPDATA%\Batchy\Logs\
Settings	%APPDATA%\Batchy\Settings\
Plugin Cache	%APPDATA%\Batchy\pluginList.xml

Code	Meaning
0	Success — all files processed
1	Partial failure — some files failed
2	Complete failure — configuration error or all files failed

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

Process all files in a directory:

./Batchy --batch-process --input /path/to/audio/folder --preset my_effect.batchyfx

Required Arguments

Option	Description
--batch-process	Enable headless batch processing mode
--input <path>	Input audio file or directory
--preset <file>	Batchy preset file (.batchyfx)

Output Configuration

Option	Description	Example
--output-dir <path>	Output directory	--output-dir /exports
--output-format <fmt>	Format: wav, aiff, flac	--output-format flac
--output-sample-rate	Sample rate or "same"	--output-sample-rate 48000
--output-bit-depth	16, 24, 32float, or "same"	--output-bit-depth 24
--output-filename	Filename template	--output-filename '$filename_processed'
--output <sel>	Select output nodes	--output "Master"
--output-override	Per-output settings	--output-override "Master:format:flac"

Processing Options

Option	Description
--normalization <type>	none, peak, rms, lufs
--target-loudness <dB>	LUFS target (e.g., -16)
--max-threads <count>	Parallel threads (default: min(4, cores))
--progress	Show progress bar
--verbose	Detailed logging
--dry-run	Validate without processing

Built-in Tokens

Token	Description	Example
$filename	Original name (no extension)	mysong
$outputnode	Output node name	Master
$date	YYYY-MM-DD	2025-10-17
$timestamp	Full timestamp	20251017-143022
$counter{N}	Zero-padded counter	001, 002, ...
$user	System username	johndoe

Path Tokens

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

User-Defined Tokens

Set via CLI arguments: --project, --author, --client, --engineer, --studio, --show

batchy --batch-process \
  --input ./audio \
  --preset mypreset.batchyfx \
  --project "Album 2025" \
  --author "Artist Name" \
  --output-filename '$project/$author/$filename'
# Produces: Album 2025/Artist Name/mysong.wav

Metadata Tokens

Require MetadataProvider nodes in your preset:

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

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"

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

Watch folder automation

#!/bin/bash
WATCH_DIR="/audio/incoming"
PRESET="/presets/auto_process.batchyfx"
OUTPUT="/audio/processed"

inotifywait -m "$WATCH_DIR" -e create -e moved_to |
while read dir action file; do
    if [[ "$file" =~ \.(wav|aiff|flac)$ ]]; then
        ./Batchy --batch-process \
          --input "$WATCH_DIR/$file" \
          --preset "$PRESET" \
          --output-dir "$OUTPUT"
    fi
done

Script integration

#!/bin/bash
if ./Batchy --batch-process --input "$1" --preset effect.batchyfx; then
    echo "Processing completed successfully"
else
    echo "Processing failed with code $?"
fi

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.

Exit Codes

Code	Meaning
0	Success: All files processed
1	Partial failure: Some files failed
2	Complete failure: Configuration error or all failed

Limitations

• Real-time plugin parameters cannot be automated during batch processing
• Maximum file size limited by available RAM
• Some plugin formats may not be available in headless mode

Verbose Logging

./Batchy --batch-process --input file.wav --preset preset.batchyfx --verbose

Logs at: macOS ~/Library/Logs/Batchy/ • Windows %APPDATA%\Batchy\Logs\

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 — Supported: WAV, AIFF, FLAC, MP3, OGG, M4A, WMA
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. Ensure output directory exists and is writable
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: Preferences → License
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

Trial Expired

Visit the website to purchase a full license. One trial per email address — reinstalling won't reset the trial.

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 %APPDATA%\Batchy\Logs\

Email: support@batchyandfriends.com

Typically within 24 hours (business days).

Status: RESOLVED (2026-01-31)

Resolution: Migrated from global CoreRegistry singleton to per-graph core ownership. Each graph now owns its cores, eliminating cross-graph interference.

Impact

• 100-file batch processing with 8 threads: 100% reliable (was ~60% failure rate)
• No more SIGSEGV/SIGABRT crashes from concurrent core access
• Simpler mental model: cores are scoped to their owning graph