This API allows building DSP libraries that can load different DSP modules into a script processor. A DSP Module is a little class that contains common functions / callbacks found in typical effect processing APIs.

Installing & using the library in HISE / HISE Player

The library must be placed in the OS-specific subfolder:

Windows: APPDATA%/HISE/dll

OSX: ~/Library/Application Support/HISE/lib

There are some naming conventions for Windows .DLLs: use the suffix _x86.dll for 32bit builds and _x64.dll for 64bit builds. (The OSX libraries are universal binaries so they don't need to be named separately.)

If you use the above template, the build location will be adjusted automatically to these folders, but you might want to know what's going on when building an installer that contains your library...

Installing & using the library in a compiled plugin

If you want to use the library in a compiled plugin, you have two options:

Dynamic Library

The plugin will look for the dynamic library at the following locations:

If you distribute the dynamic library along with your plugin, you should handle the case that the library can't be located (eg. because of an installer issue). The recommended way for this is to call Engine.showErrorMessage(message, true) which creates a dark overlay with the given message to make it pretty clear that something is missing:

const var lib = Libraries.load("nonexistent");

if(lib.getErrorCode() == lib.MissingLibrary) // the other cases should not occur in production

Now if you want to compile an iOS app (which doesn't allow dynamic libraries) or don't want to distribute the library seperately, you can also embed the library into the plugin as static library.

Static library

Recompile the library as static library (make sure you use the same projucer settings as the plugin), and add the class name of your factory to the Project Settings (it will autogenerate the code that adds the factory to the list of available factories) and paste the static libraries into the OS-specific field.

Loading the library in Javascript

Libraries can be loaded in all script processors that process audio data (Script Time Variant Modulator, Script Envelope, Script Synth and Script FX).

You load a library by using the library name stripped of all platform specific information:

// Filename: 'example_library_x64.dll' (Win 64bit dynamic library)

var ex_lib = Libraries.load("example_library");

// Filename: 'example_library_x86.dll' (Win 32bit dynamic library)

var ex_lib = Libraries.load("example_library");

// Filename: 'example_library.dylib' (Win 32bit dynamic library)

var ex_lib = Libraries.load("example_library");

The Libraries.load() function has a second argument which is supposed to be a string and is passed to the initialise method. You can use this for two things:

Version checking

Simply pass a version string and check if it matches the defined version number in your Library

Copy protection

Libraries can be protected against unlicenced loading by supplying a String key as second argument. In this case, it will be passed to your initialise() method and you can check if the key is valid. If you don't care about it, leave it empty. If you just want minimum security against occasional dudes trying to rip your precious algorithms, just pass a string and compare it (it won't stand a chance against even the dumbest cracker tough).

If you are really protective, you might want to create a RSA Key Pair along with some hash string and go crazy on the cryptography...

Using the library in Javascript

const var module = ex_lib.load("ModuleName"); // Loads the module with the given name.

Notice the const keyword when assigning a module. This allows faster code because reference to this variable will be resolved on compile time.

That's it. Take a look at the DspBaseObject documentation on how to use the modules in Javascript.

Copyright

This header (and its included files) are less restrictively licenced than the rest of the HISE codebase. This allows close source development of HISE DSP modules without the restrictions of the GPL v3 licence-. You'll need the juce_core module to build DSP modules (but it is also licenced pretty liberately). A amalgamated compatible version can be found in the Github Repository of this API.

The MIT License (MIT) Copyright (c) 2016 Hart Instruments

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.