Batchy documentation

Open Settings → Audio Settings... to choose your audio device, sample rate and buffer size. A larger buffer can help with playback dropouts; a smaller buffer reduces playback latency. Use your device's working defaults to begin.

Batchy's built-in nodes work without a plugin scan. To configure your own VST3 plugins, or Audio Units on macOS, open Settings → Plugin Settings.... Use Settings → Rescan Plugins when you need to refresh the available plugins.

A preset that uses third-party plugins needs those plugins installed and available on the machine where it runs.

The file list holds the source audio. NODE GRAPH defines the processing route, and each Output node defines an export. A .batchyfx preset saves the setup for reuse. Start with one Output; add more when you need different deliveries from the same sources.

Audition one file, check the destination preview, and render a small batch before processing a large folder.

Sample Rates

Buffer Sizes

Bit Depths

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

Date/Time

File & System

Path Tokens

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

User-Defined

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

Metadata Tokens (filled in automatically; write underscore names in braces)

${sample_rate}, ${bit_depth}, $duration, $channels, ${channel_count}, ${source_file_modified}, ${source_file_created}, ${source_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

Windows

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

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

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

Output Configuration

Processing Options

General Options

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 state as the GUI. Start a 7-day free trial with your email address from the welcome screen or Manage License, or purchase and activate a license. Marketing emails are optional. An active trial also permits headless exports on the same machine; the CLI does not start trials. Legacy trials retain their original terms.

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:

• 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 (including a preset set to overwrite source files), Batchy fails unless --in-place explicitly permits replacement; --overwrite-outputs only replaces earlier outputs and never overwrites a source file. The error explains the fix, including when an empty token made the names match. 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, OGG
• MP3: written with the LAME encoder that ships with Batchy on macOS and Windows. If that encoder is missing, MP3 is not listed; run --help on the target machine to check.

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

Date & Time Tokens

Counter Token

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

System Tokens

Path Tokens

For use in templates that include directory structure:

User-Defined Tokens

Set via CLI arguments:

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

Removed Tokens

The deliverable tokens $version, $mix, $language, $territory and $deliverable were removed. Older presets that still use them render the word as literal text; supply a value with --user-token (for example --user-token version=v2) to fill one in.

Metadata Tokens

Filled in automatically for every file. Write names that contain an underscore in braces: a bare token stops at the first _, so $sample_rate is read as $sample followed by _rate.

• Source file: ${source_file_modified}, ${source_file_created}, ${source_parent_folder}
• Audio (the file being written): ${sample_rate}, ${bit_depth}, $duration, $channels, ${channel_count}

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.

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

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

Render Control

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:

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

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)
• “Refusing to render: the output for … would overwrite the source file itself” — choose a separate --output-dir or a different --output-filename, or pass --in-place only when source replacement is intentional (--overwrite-outputs is not enough)

Log Locations

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 Settings → 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 (Settings → Audio Settings...)
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: Settings → Rescan 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: Settings → Plugin Settings...
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: Batchy is notarized by Apple. If macOS still blocks it, make sure the installer came from batchyandfriends.com and contact support.
2. Windows: SmartScreen may warn about a new release. Make sure the installer came from batchyandfriends.com, then choose "More info" → "Run anyway".
3. Try deleting license file and re-activating

Download, try or activate Batchy

Download Batchy and start a 7-day free trial with all features. An email address is required to start; no payment is required. After seven days, purchase and activate a license to continue processing and exporting. Downloading does not start the trial. New trials begin when started in the app and cannot be extended or restarted.

1. Download the installer for your platform and install Batchy.
2. Select Start 7-day free trial on the welcome screen or in Manage License, then enter your email address. Marketing emails are optional. Already purchased? Paste the license key from your purchase email.
3. If you entered a license key, select Activate.

"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

Fresh installations offer a 7-day trial or license activation. If existing license data cannot be read, the recovery screen requires license activation; it does not grant a replacement trial. Contact support if you need help recovering access.

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

Batchy is notarized by Apple, so this message usually means the download was interrupted or came from somewhere other than batchyandfriends.com. Download the installer again from the downloads page. If macOS still blocks it, contact support.

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: [email protected]

Typically within 24 hours (business days).