halionbridge

halionbridge is a cross-platform automation bridge for Steinberg HALion 7, packaged as a command-line tool and reusable C++ library. It loads the HALion 7 VST3 plugin, runs Lua build scripts inside HALion, and lets HALion's own runtime save the resulting .vstpreset artifacts.

The goal is reproducible batch preset and instrument generation without reverse-engineering HALion's file formats and without manually driving the HALion GUI.

Why This Exists

HALion preset files are written by HALion itself rather than generated by reimplementing Steinberg's binary file formats. halionbridge provides the missing command-line automation layer around that workflow: converter tools or authors can generate Lua build scripts, halionbridge runs those scripts inside the actual HALion 7 plugin, and HALion's savePreset() path writes the final presets.

This makes scripted instrument builds practical while keeping the file-writing logic inside HALion's supported runtime.

How It Works

1. A build directory contains halionbridge_build.lua and the Lua build script modules listed by that file.
2. halionbridge loads the HALion 7 VST3 plugin in a headless host process.
3. It applies an embedded bootstrap preset that starts the generic Lua builder inside HALion.
4. The builder loads each build script module in order and passes it a documented context API.
5. Build scripts create HALion objects such as layers, zones, sample mappings, parameters, and presets.
6. HALion saves the requested output presets and writes success or failure marker presets that halionbridge observes.

For source formats such as SFZ, halionbridge can also generate the Lua build directory first. The generated Lua remains normal, inspectable build source that can be edited before running the HALion build.

What This Is

• A batch automation host for HALion Lua build scripts.
• A C++23 library interface with a command-line frontend for running the same builder workflow.
• Infrastructure for converters and scripted HALion instrument builds.
• A way to produce real HALion .vstpreset artifacts through HALion itself. The original HALion plugin is required and must be installed.

What This Is Not

• A general-purpose VST host.
• A graphical preset authoring tool.
• A direct writer for undocumented HALion preset file internals.

Use Cases

• Programmatic Instrument Creation: Build sample-mapped instruments—including layers, zones, key ranges, velocity ranges, sample assignments, and parameters—directly via Lua instead of manually assembling them in the HALion GUI.
• Automated Converter Workflows: Generate .vstpreset files automatically from structured data (e.g., CSV databases) or existing source formats (like SFZ) by bridging them through Lua build scripts.
• Reproducible Preset Libraries: Treat HALion presets as reliable build artifacts that can be entirely regenerated from source Lua scripts and sample files.
• CI and Headless Automation: Execute scripted HALion builds seamlessly on build servers or CI pipelines without opening an audio device.
• Script Debugging: Visually inspect scripted builds by using --gui or --nokill flags to keep the HALion GUI open after a run.

Features

• Headless & Offline Processing Loop: Runs as an embeddable standalone console app. It utilizes an offline manual processing loop to keep the HALion plugin alive while Lua scripts execute, completely bypassing the need for an active audio device.
• Native Format Conversion Setup: Commands like halionbridge convert sfz parse source directories and generate a flat or explicitly routed halionbridge build directory. Users can review or edit these generated Lua scripts before triggering the final build.
• Marker-Based Status Detection: Tracks build progress and completion by waiting for HALion to write .vstpreset status markers into the build directory. Temporary progress markers are automatically cleaned up, while failure markers are preserved for diagnostics.
• Embedded Bootstrap: Automatically applies the bundled HALion bootstrap .vstpreset internally, meaning users only ever need to pass their target build directory to the CLI.
• Generic Script Delegation: The embedded builder acts as a blank slate; it simply loads the modules listed in halionbridge_build.lua, leaving the actual decision of what to build entirely to the Lua scripts.

Usage

Before running the generic builder, open HALion's Options Editor, go to Scripting, and make sure the HALion user scripts directory is listed in Library Search Paths:

• Windows: C:\Users\<username>\Documents\Steinberg\HALion\Library\scripts
• macOS: /Users/<username>/Documents/Steinberg/HALion/Library/scripts

halionbridge looks for the HALion 7 VST3 plugin at the normal Steinberg install locations unless --plugin is provided:

• Windows: C:\Program Files\Common Files\VST3\Steinberg\HALion 7.vst3
• macOS: /Library/Audio/Plug-Ins/VST3/Steinberg/HALion 7.vst3

The packaged macOS CLI is signed for plugin hosting so it can load the installed HALion VST3 under macOS hardened runtime rules.

The build directory must contain halionbridge_build.lua and the Lua build script files referenced from that file. You can find examples in examples. If you already have Lua build scripts in a directory, run halionbridge init <directory> to create a simple sorted halionbridge_build.lua for them. Review the generated file before building: init lists every top-level non-infrastructure .lua file, so helper modules that are required by build scripts but are not build entrypoints should be removed from the list. Converter-owned infrastructure helpers such as halionbridge-sfz.lua are excluded automatically.

# Show command-line help
./halionbridge --help

# Show the Git-derived build version
./halionbridge --version

# Generate halionbridge_build.lua from top-level Lua files and exit
./halionbridge init /path/to/build-directory

# Generate halionbridge Lua build files next to top-level .sfz files
./halionbridge convert sfz /path/to/sfz-source-directory

# Or write generated build files to a separate directory
./halionbridge convert sfz /path/to/sfz-source-directory /path/to/generated-build-directory

# Include nested .sfz files below the source directory; generated Lua stays flat in the build root
./halionbridge convert sfz /path/to/sfz-source-directory --recursive

# Run the generic HALion Lua builder against a build directory
./halionbridge /path/to/build-directory

# Builds time out after 3600 seconds by default.
./halionbridge /path/to/build-directory --timeout-seconds 1800

# Explicitly wait forever when manually inspecting a problematic build.
./halionbridge /path/to/build-directory --no-timeout

# Build scripts run up to 15 scripts per HALion process by default and continue after failed chunks.
# Use --build-chunk-size 1 for maximum isolation, or tune chunk size when desired.
./halionbridge /path/to/build-directory --build-chunk-size 30
./halionbridge /path/to/build-directory --fail-fast

# Override the default HALion 7 VST3 plugin search path
./halionbridge /path/to/build-directory --plugin /path/to/custom/HALion 7.vst3

# Open the HALion editor and keep running until the window is closed
./halionbridge /path/to/build-directory --gui

# Open the HALion editor and keep running no matter what the lua script returned.
# Close the GUI window or press Ctrl+C to stop inspection and clean up.
./halionbridge /path/to/build-directory --gui --nokill

The SFZ converter is a setup step: it generates normal Lua build files and does not launch HALion. When no output directory is passed, generated files are written flat beside the source .sfz files; otherwise they are written to the requested build directory. Existing generated files are refused unless --overwrite is supplied, and conversion fails before writing if two inputs would produce the same output preset name. Generated build files are staged before commit so a write failure does not leave a half-updated build directory.

Generated SFZ output includes an inspectable helper module, halionbridge-sfz.lua, plus one build entrypoint script per source .sfz. The current converter covers the common sample-mapping path: sample filenames, key/velocity ranges, root keys, playback ranges, sustain loops, gain, pan, static amplitude envelopes, static pitch/tuning, a simple static pitch-envelope subset, and rough static filter approximations. Unsupported or unverified SFZ features are reported as warnings instead of being silently treated as exact conversions. Detailed mapping notes and current parity limits live in DEVELOPMENT.md.

halionbridge prints timestamped console logs. The default log level is info, which keeps build script progress and important state changes visible while hiding host internals. Set HALIONBRIDGE_LOGLEVEL=debug when you need plugin loading, VST3 preset, and cleanup diagnostics. Supported values are trace, debug, info, warn, error, and off.

Only one halionbridge build can run at a time for a user account. HALion resolves temporary runtime modules from the shared HALion user script directory, so a second overlapping run exits with a clear error instead of corrupting build output.

Press Ctrl+C to stop a run. Conversion commands stop at converter checkpoints before writing more generated files. Normal headless HALion builds stop the active worker process and do not start later chunks. GUI and --nokill inspection runs remain cooperative so HALion can clean up normally.