Blob Export Tool - User Guide

The blob-export tool allows .inst files and associated samples to be packed into a binary .blob file for distribution and protection.

Additional options are available compared to those in Gorilla Editor to facilitate automated builds and exact configuration of the blob file contents.

Basic use

blob-export [options] <gorilla instrument files ...> <blobfile>

Place all options before the input instrument paths. Standard exports create two files, MyBlob_part1.blob and MyBlob_part2.blob, from an output argument such as MyBlob.blob. The default preload is 0 ms, compression is off, and exposed script parameters are reset to their defaults. Use --reset-params 0 to preserve their saved values.

For example, export an instrument with compressed sample data and a 100 ms preload:

blob-export --compress --preload 100 "instrument/MyInst.inst" "plugin_assets/MyBlob.blob"

It is possible to include more than one .inst file in a single blob, either by listing them all:

blob-export Inst1.inst Inst2.inst Inst3.inst MyBlob.blob

or using wildcards:

blob-export MyInstsFolder/*.inst MyBlob.blob

Options

-a or –align <bytes>

Align sample data in the file to this number of bytes. This can make loading of data from disk slightly faster, but wastes space between each sample. The default value is 4 but other power-of-two values can be used. For example 4096 will align well with disk block and memory page sizes, but will be wasting on average 2 KB of disk space per sample.

Example: blob-export --align 16 MyInst.inst MyBlob.blob

-b or –max-bits <value>

Reduce bit depth of samples to a maximum of 16 or 24. If the value is 24 then any 32-bit floating point samples will be reduced to 24-bit resolution, possibly resulting in clipping if the floating point values exceed +/- 1.0. If the value is 16 then both 32-bit and 24-bit samples will be reduced to 16 bits resolution. The bit reduction operation is correctly dithered but if you want more control of how bit depth is reduced then you can perform it youself on the individual samples.

Example: blob-export --max-bits 24 MyInst.inst MyBlob.blob

-c or –compress

Compress the audio data in the blob file. This reduces the size of the blob file - typically by 50% or more, but the amount of compression reduces as the volume and brightness of the audio increases so decaying bass sounds can compress a lot but loud white noise may not compress at all. On playback, decompression happens when the audio is loaded from disk, resulting in increased RAM use but no noticable increase in CPU load.

Example: blob-export --compress MyInst.inst MyBlob.blob

-cv or –content-version <ver>

Add custom version or timestamp text to both blob file parts. If you have large blob files you may want to update on users’ systems in the future, it can be useful to include your own versioning system to check if the installed files are up to date and if the two blob file parts can be used together. This option is equivalent to using --toc content_version <ver> but in addition writes the version to the part 2 blob file. Do not change the length of the version text in the rare situation that you want to update blob part 2 only!

Example: blob-export --content-version "2024-06-12" MyInst.inst MyBlob.blob

-d or –define <define>

Set a “script define” for instrument(s) to pass to their instrument scripts. This allows parts of the instrument script to be enabled and disabled, for example to disable debugging text output when making a release build - see USE_CODE_IF in the Gorilla Script reference.

More than one define can be set, but adding any defines will overwrite defines saved in the instrument. This can be helpful for example adding a RELEASE define which has no effect to disable an existing DEBUG define in the instrument. Defines must not include space characters.

Example: blob-export --define RELEASE --define FILTER_BUGFIX MyInst.inst MyBlob.blob

-e or –trim-sample-ends

Don’t include sample data that will never be played because it is after the loop end point or end marker in all zones that use the sample. Do not use this option if your instrument will edit those zone settings in use.

Example: blob-export --trim-sample-ends MyInst.inst MyBlob.blob

-f or –max-freq <freq>

Reduce the sample rate of samples to a maximum value in Hertz. Any samples with a sample rate higher than the maximum will be resampled to the maximum sample rate, reducing their size in the blob file. While the resampling is of high quality and attempts to preserve sample loop points, it’s possible that audible artifacts will occur, and phase coherence between multiple samples may not be preserved. It’s probably a bad idea to use this option with short synthesizer waveform loops.

Example: blob-export --max-freq 44100 MyInst.inst MyBlob.blob

-h or –help

Show a summary of the information in this document and exits the blob export tool.

Example: blob-export --help

-i or –update-inst

Replace the instrument(s) in an existing part 1 blob file without re-exporting the sample content. Use this only when the samples have not changed. Loading options such as --modules-path, --reload-scripts, --define, and --reset-params can be used when preparing the replacement instruments. Perform a full export if sample content or its layout must change, including preload, compression, alignment, bit depth, or sample rate.

Example: blob-export --update-inst MyInst.inst MyBlob.blob (where MyBlob_part1.blob and MyBlob_part2.blob already exist)

-m or –modules-path <path>

Search for custom modules at the specified path. If your instrument uses custom C++ effects or filters, the tool needs their native libraries to load it. On macOS, the command-line tool defaults to $HOME/Library/Application Support/UJAM/Gorilla Editor/PlugIns. Set this option explicitly in automated builds or when your libraries are installed elsewhere. On Windows, specify the required module directory explicitly.

Example: blob-export --modules-path "MyCustomModule/build/Release" MyInst.inst MyBlob.blob

-o or –reload-scripts

Forces the instrument to reload its scripts from disk. This can be useful when making a series of instruments that use the same scripts, to avoid having to open each instrument to load the script and resave.

Example: blob-export --reload-scripts MyInstruments/*.inst MyBlob.blob

-o2 or –reload-scripts-update

Reload scripts from disk for the export and also update the embedded scripts in the input .inst files. Unlike --reload-scripts, this option can modify your source instrument files. Use it when you intentionally want to synchronize their embedded scripts; prefer --reload-scripts for exports that should leave source files unchanged.

Example: blob-export --reload-scripts-update MyInst.inst MyBlob.blob

-p1 or –part1 <key> <path>

Include a file (or multiple files) in the part 1 blob file. The size and location of the file data in the blob is stored under the specified key in the table of contents (TOC) using the filename with path and extension removed.

Example: blob-export --part1 credits credits.txt MyInst.inst MyBlob.blob

-p2 or –part2 <key> <path>

Include a file (or multiple files) in the part 2 blob file. The size and location of the file data in the blob is stored under the specified key in the table of contents (TOC) using the filename with path and extension removed.

Example: blob-export --part2 presets "Presets/*.preset" MyInst.inst MyBlob.blob

Quote wildcard paths passed to --part1 or --part2 so the tool expands them as one option argument rather than the shell passing multiple arguments.

-pi or –parameter-info

Print instrument parameter information as JSON to standard output instead of exporting a blob. This is useful for generating parameter typings or other developer tooling. Provide an input .inst path without an output blob path. If several instruments match, the current implementation inspects only the first one.

blob-export --parameter-info MyInst.inst > parameter-info.json

-p or –preload <msec>

Length of each sample in milliseconds to include in the part 1 blob file. By default all sample data is stored in the part 2 blob file, but if you want to encrypt part of each sample along with the instrument data in the part 1 blob file this option can be used to move the start of each sample into the part 1 file.

Example: blob-export --preload 250 MyInst.inst MyBlob.blob

For CI/CD exports, set this option explicitly and match it to the runtime preload passed to GorillaEngine.setActiveInstrument(), whose second argument is in seconds. For example, --preload 250 corresponds to a runtime value of 0.25. See CI/CD Blob Exports for the encryption workflow and guidance on keeping export and runtime settings in sync.

-q or –quiet

Disable unnecessary text output while the tool is running.

Example: blob-export --quiet MyInst.inst MyBlob.blob

-r or –reset-params <value>

Control how parameters exposed by instrument scripts are initialized:

• 0: Preserve the saved parameter values without resetting them.
• 1 (default): Set exposed parameters to their defaults. This applies even when the option is omitted.
• 2: Re-apply the current parameter values to synchronize the instrument’s internal state with those values.

Example: blob-export --reset-params 1 MyInst.inst MyBlob.blob

-rs or –resources <path>

Add a Resources JSON file to the blob’s table of contents. Use this when your project supplies a resource manifest that must be included with the instrument. The export fails if the resources file cannot be added.

Example: blob-export --resources Resources.json MyInst.inst MyBlob.blob

-t or –toc

Add a custom item to the table of contents in the blob file. This can later be read by the plugin. Repeat the option to add multiple items. Quote values containing spaces.

Example: blob-export --toc build_number 137 --toc build_date "2024-06-12 10:36" MyInst.inst MyBlob.blob

-u or –uuid

Provide unique identifier in the form ########-####-####-####-############ for this blob. By default a random UUID is generated and stored in both the part 1 and part 2 files to check that they belong together, but if you plan to use the --content-version option you should also set a consistent UUID for future versions. If needed the UUID can be read from the start of an existing blob file using a hex editor.

Example: blob-export --uuid 811d9bb4-6b8c-4d77-a860-2a9b6f07d347 MyInst.inst MyBlob.blob

-v or –verbose

Print additional information while exporting.

Example: blob-export -v MyInst.inst MyBlob.blob

-vv or –verbosex2

Print extremely detailed information while exporting.

Example: blob-export -vv MyInst.inst MyBlob.blob

-x or –exportAllParams

This option does not create blob files and should not be combined with other options. Instead it creates a copy of the input .inst file including values for every parameter of every module in the instrument. Normally parameters set to their default value don’t need to be saved in the instrument file as they will already have the correct value when the instrument is loaded, but in some situations it’s useful to have the complete set of parameters and their values - for example when comparing two versions of the same instrument.

Example: blob-export --exportAllParams MyInst.inst MyInst_detail.inst

Legacy blob files

When creating a Rack Extension plugin an alternative blob file format must be used. The -l or --legacy option selects this format. Blob files are also usually given a number instead of a name:

Example: blob-export --legacy MyRackExtension.inst 1.blob

The --compress option can also be used with legacy blob files, but a simpler compression algorithm is used which means that fewer samples may reduce in size.

Lastly the --split option can be used with legacy blob files. This writes a separate file for each mapping in the instrument, with the first blob file containing any samples that are used in more than mapping or as impulse responses. This makes it possible for the Rack Extension to load and unload mappings separately to save RAM.