HISE DSP Module API
Author
Christoph Hart
Version
1.0

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.

A DSP Module has this features:

For a detailed documentation, take a look at the DspBaseObject class.

In order to maximise ABI compatibility, crossing library boundaries is only done purely in C.

Getting Started

Setting up the project

There is a template project for the Introjucer that contains all settings needed to build a library:

Example Project Repository

You can use this as starting point for your library as it contains the correct compiler settings & dependencies to get started.

Implement the library

You need to subclass DspBaseObject, overwrite its virtual functions and register it in the initialise() method:

class MyEffect: public DspBaseObject
{
// ... Implement everything needed
};
{
// Register your module (you can register as many classes as you want.
HelperFunctions::registerDspModule<MyEffect>();
// ...
// Return success!
};

Installing & using the library in HISE / HISE Player

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

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
{
Engine.showErrorMessage("The library nonexistent can't be found", true);
}

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

The error code can be checked by calling

if(ex_lib.getErrorCode() != ex_lib.LoadingSucessful)
{
handleMissingLibrary();
}

Using the library in Javascript

A library can create multiple DSP Modules. There are two functions:

var moduleList = ex_lib.getModuleList(); // Returns an array containing all module IDs.
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.

©2017 HISE. This documentation is autogenerated from the HISE source code using Doxygen.