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>

Here is a specific example that creates the .blob files for the Basic Synth example:

cd "/Applications/Gorilla Engine SDK"
./Tools/blob-export "Examples/Basic Synth/instrument/Basic Synth.inst" "Examples/Basic Synth/plugin_assets/Basic Synth Example.blob"`

After running this command the blob files in the specified plugin_assets folder should be updated.

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 user’s 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 togeher. This option is equivalent to using -toc content_version but in addition writes the version to the part 2 blob file.

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. This only works if the samples have not changed so the part 2 blob file does not need to be updated. Do not combine this option with any other options except for --define.

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 the blob export tool will need to find them to be able to load the instrument. If not specified, the custom module location for Gorilla Editor is used (/Library/Application Support/UJAM/Gorilla Editor/PlugIns on macOS).

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

-p or –preload <msec>

Length of each sample in miilseconds 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

-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>

Optionally set all the parameters exposed by the instrument scripts. If this option is not used or the value is 0, instruments are used as-is. If the value is 1 all parameters are set to their default values, which can be useful if the instrument may be in an edited state which is not wanted as the initial state when it loads in the plugin. If the value is 2 all parameters are set to their current values, which doesn’t sound useful but can solve problems if the internal state of the instrument has been edited and no longer matches the parameter settings.

Example: blob-export --reset-params 1 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. Multiple items can be added. If the value is purely numeric it doesn’t have to be enclosed in quotes. The key should only include lower-case letters and

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.