Back to top
Important!
 3D Graphics components has been deprecated in Rack Extension SDK 4.2.0. Use older versions of the SDK to support your existing 3D GUI REs.

Requirements

Important!
 Products created with this SDK can run in Reason 10.1 and later.

Jukebox SDK System Requirements

macOS

  • Internet connection for uploading Rack Extensions to Reason Studios build server

  • Intel Mac with dual core processor

  • 4 GB RAM or more (8 GB recommended)

  • 15 GB free hard disk space (Rack Extension Designer may use several GB of scratch space)

  • macOS 10.8 or later (64 bits only)

  • Monitor with at least 1280×768 resolution

  • 1 GB NVidia or ATI/AMD graphics card recommended

  • Core Audio compliant audio interface or built-in audio hardware

  • MIDI interface and a MIDI keyboard recommended

Windows

  • Internet connection for uploading Rack Extensions to Reason Studios build server

  • Intel or AMD processor with dual cores

  • 4 GB RAM or more (8 GB recommended)

  • 15 GB free hard disk space (Rack Extension Designer may use several GB of scratch space)

  • Windows 7 or later (64 bits only)

  • Monitor with at least 1280×768 resolution

  • 1 GB NVidia or ATI/AMD graphics card recommended

  • Audio Interface with ASIO driver

  • MIDI interface and a MIDI keyboard recommended

Where to get help

Online Forum

http://developer.reasonstudios.com/

If you cannot find the answer to your question on the developer forum, do not hesitate to contact

development@reasonstudios.com.

If you need support related to your developer account or financial issues, please contact

developer.admin@reasonstudios.com.

If you think you have found a bug in Jukebox or Reason, please contact

mrjukebox@reasonstudios.com.

Getting started

The Jukebox SDK contains three major components:

Reason Recon - The development version of Reason for testing locally built Rack Extensions, based on Reason Intro. This version of Reason Recon is distributed as a beta build, which means that it includes test code, asserts and extensive logging.

SDK - Header files, compiler toolchain and example projects.

RE2DRender - A tool for compiling hi-res 2D GUI definitions into a format suitable for Reason.

To get started, do the following:

1. Read the Rack Extensions Developer’s Guide document

If you haven’t already, spend a little time reading through the Rack Extensions Developer’s Guide. This will give you an essential overview of the Rack Extensions system, which really helps understanding the different concepts and terms that will be introduced when getting started with Rack Extensions development.

2. Install Reason

It is assumed that a full version of Reason is installed on your computer.

3. Install Reason Recon

On Windows, run the Install Reason Recon Beta.exe installer. On macOS, mount the ReasonReconBeta.dmg disk image and do a regular drag-drop install to your Applications folder.

4. Install python (Windows only)

The build scripts need python 3 or 2.7 installed. (Python comes preinstalled on macOS.) After installing, make sure python is in your PATH.

Python can be downloaded from

http://www.python.org/download/

5. Documentation and example projects

SDK documentation can be found on http://developer.reasonstudios.com/.

A number of example projects can be found in the SDK/Examples folder.

6. Compile a test project

You should now be ready to try the Jukebox APIs as well as getting to know the GUI design process!

The SDK example projects can be built from a command prompt. On Windows, open a Visual Studio Command Prompt, on macOS, open a Terminal window. Navigate to one of the example project folders, e.g.,

…​/SDK/Examples/SimpleInstrument …​/SDK/Examples/VerySimpleSampler

To build a testing version, you say:

python build45.py local45 Testing

Run the build45.py script without parameters to see all options.

When building a local45 the code is always compiled for 64 bits. You can do all testing using the local45 version of your Rack Extension. Sidenote: Both 64 and 32 bits code is still built and uploaded as part of your universal45 archives.

Important!
 On Windows, the command line prompt that you use to invoke the python build script must be specific to compiling for 64 bits.

Built Rack Extensions are automatically put in:

Windows: %APPDATA%\Propellerhead Software\RackExtensions_Dev

macOS: ~/Library/Application Support/Propellerhead Software/RackExtensions_Dev

Reason Recon will scan these folders for new Rack Extensions when it is restarted.

If you make changes to a Rack Extension that does not involve changing its name or its 2D GUI resources you can reload it from within Reason without quitting: remove all instances of the device from the rack, recompile the project, and create a new instance of the device.

Tip!
 A simple pattern for testing is to create a device in the rack, connect it to other devices for testing (if needed), make changes to the source code, delete the device from the rack, rebuild it and then add it again in the rack by invoking "undo". This will recreate the device with all connections and settings intact.
Important!
 For 2D GUIs, the the Rack Extension project folder (e.g., VerySimpleSampler) must contain a folder called GUI2D (e.g., VerySimpleSampler/GUI2D) that contains the high-resolution 2D graphics resources. When you compile the hi-res resources to lo-res images for the local 45 using RE2DRender, you must instruct it to put them in the GUI folder (VerySimpleSampler/GUI). This will create a new folder called Output (VerySimpleSampler/GUI/Output) with the lo-res 2D resources and gui.lua. The build script assumes that this folder exists and contains 2D assets when it compiles the Rack Extension. See the 2D GUI Designer Manual for details.

IDE projects

The SDK examples also include Visual Studio and Xcode projects.

The Visual Studio projects require Visual Studio 2013, 2015, or 2017.

The Xcode projects require Xcode 9.2 or later.

The Visual Studio projects comes with the following build configurations:

  • Debugging,

  • Testing,

  • Deployment, and

  • Universal45.

The Debugging configuration can be used for local debugging. If you compile the Debugging configuration and then attach the debugger to Reason Recon, you can debug your Rack Extension as normal, setting breakpoints and so on.

The Xcode projects have two build schemes:

  • Local 45, and

  • Universal 45

By building the Local 45 target for debugging, it is possible to debug your Rack Extension locally by attaching the Xcode debugger to Reason Recon.

The Universal45 target builds the project using the LLVM toolchain and packages the 45 for submitting to Reason Studios. The resulting .u45 archive is put in the Output folder in the project folder, e.g.,

…​/SDK/Examples/SimpleInstrument/Output

Creating a new project

macOS

When you create a new project, it is easiest to start from a copy of one of the example projects.

  1. Duplicate the entire folder and rename it to whatever you want to call your Rack Extension.

  2. Then rename the Xcode project file inside the folder.

  3. Open the project file in Xcode. Note that you can rename files inside Xcode to better match your new Rack Extension name.

If you don’t want to keep your Rack Extension projects inside the Examples folder in the SDK, you can move them somewhere else. You will, however, need to fix a few things to help the Xcode project find the SDK.

  1. Move the project folder to wherever you want to put it.

  2. Edit build45.py to point to the correct SDK folder: the JUKEBOX_SDK_DIR must be a relative or absolute path to the SDK folder. If you make the path relative, it must be relative to the Xcode project file for your Rack Extension.

  3. Open the Xcode project file. The reference to the SDK folder, and everything within it, will be broken. Repair it by right-clicking (or control-clicking) on the SDK folder in the project file list, and select Get Info. In the Info panel that appears, click on the Choose…​ button to select where the SDK folder resides on disk. Navigate to where you have the SDK folder and click Choose. This should repair all the broken file references in the project.

Windows

When you create a new project, e.g., MyRackExtension, it is easiest to start from a renamed copy of one of the example projects, e.g., SimpleInstrument:

  1. Rename SimpleInstrument.sln to MyRackExtension.sln.

  2. Rename SimpleInstrument.vcproj to MyRackExtension.vcproj

  3. Open MyRackExtension.sln in a text editor and replace all instances of SimpleInstrument with MyRackExtension.

  4. Open MyRackExtension.vcproj in a text editor and replace all instances of SimpleInstrument with MyRackExtension.

If you don’t want to keep your Rack Extension projects inside the Examples folder in the SDK, you can move them somewhere else. You will, however, need to fix a few things to help the Visual Studio project find the SDK.

  1. Move the project folder to wherever you want to put it.

  2. Edit build45.py to point to the correct SDK folder: the JUKEBOX_SDK_DIR must be a relative or absolute path to the SDK folder. If you make the path relative, it must be relative to the Visual Studio project file for your Rack Extension.

Debugging and logging

On macOS, logs from Recon are written to

~/Library/Logs/Propellerhead Software/Reason Recon Logs

On Windows, Recon logs are written to

Documents/Propellerhead Logs/Reason Recon Logs

The JBOX_TRACE() function can be used to write debug strings from a Rack Extension. On macOS, the output is written to

~/Library/Logs/Propellerhead Software/Rack Extension Logs

On Windows, the output is written to

Documents/Propellerhead Logs/Rack Extension Logs

Using macOS, you can use the Xcode debugger to set breakpoints in your DSP code, inspect variables and step through your code etc. To do this, you need to build a local 45 using the Debugging configuration. Either build using the command line:

python build45.py local45 Debugging

or from Xcode by selecting the "Local 45" scheme and then do Build For Running: Click the "Product" menu, then "Build For…​", "Running". Next you need to tell Xcode to use Reason Recon as the executable for debugging. You do this by adding a "custom executable" to your project, or by attaching to Reason Recon while it is running.

The procedure for Windows is similar: choose the Debugging configuration and attach the debugger to a running Reason Recon.

Tip!
 Turn on "break on exception" to get a call stack if there is a DSP error.

Recon tools menu

Reason Recon has a menu called "Recon Tools". It allows you to do the following:

  • Inspect the state of the Motherboard for a running Rack Extension.

  • Inspect the tail end of the device log for a running Rack Extension.

  • Send a reset audio request to all Rack Extensions currently in the rack.

  • Instruct Recon to blow the fuse when a Jukebox C++ API call results in a warning (warnings are printed to the device log).

  • Output custom display rendering benchmark data to the device log.

More information about the Motherboard, reset audio requests, the device fuse, and custom displays can be found elsewhere in the SDK documentation.

Running automated acceptance tests

When you submit a 45 to the Reason Studios build server, the server will run a number of automated tests in Reason Recon. It is possible to run these tests on a local 45 before you submit to the server.

macOS

On macOS, open a Terminal and navigate to the folder containing the Reason Recon executable, e.g.,

cd /Applications/Reason Recon/Reason Recon 11 RESDK41 Logging.app/Contents/MacOS

Then start Recon like this:

./"Reason Recon" "--validate_re" "--re_dir=RE_DIR" "--re_log=RE_LOG" "--re=RE"

where

RE_DIR is the absolute path to the folder containing the Rack Extension, e.g.,

/Users/johndoe/Library/Application Support/
	Propellerhead Software/RackExtensions_Dev/SimpleInstrument

RE_LOG is the absolute path to a file where Recon should write the results of the tests, e.g.,

/Users/johndoe/Desktop/test.log

and RE is the product ID of the Rack Extension, e.g.,

se.propellerheads.SimpleInstrument

Windows

On Windows, open a command prompt and navigate to the Reason Recon executable, e.g.,

cd c:\Program Files\Propellerhead\Reason Recon

Then start Recon like this:

"Reason Recon" "/validate_re" "/re_dir=RE_DIR" "/re_log=RE_LOG" "/re=RE"

where

RE_DIR is the absolute path to the folder containing the Rack Extension, e.g.,

C:\Users\johndoe\AppData\Roaming\
	Propellerhead Software\RackExtensions_Dev\SimpleInstrument

RE_LOG is the absolute path to a file where Recon should write the results of the tests, e.g.,

C:\Users\johndoe\Desktop\test.log

and RE is the product ID of the Rack Extension, e.g.,

se.propellerheads.SimpleInstrument

Known issues

  • Some example projects in the RE SDK have left overs in the project files due to deprecating 3D support.

  • Some examples contain code that will not pass tests on the build servers, specifically storing pointers into native objects, which point memory allocated in a different call to CreateNativeObject. See Jukebox C++ API reference under Functions/JBox_Export_CreateNativeObject: “There must be no pointers pointing outside of the native object’s allocations.“

  • Due to a bug in a third-party library that RE2DRender relies on, compiling 2D GUIs may fail if the source or destination paths contain unicode characters, or begin with a numeric character. If this happens, rename the folder paths for your Rack Extension project so that they only contain non-numerical ASCII characters.

  • Unicode characters in patch file names are not fully supported by the Reason Studios build server.

  • Due to a bug in a third-party library that Rack Extension Designer relies on, filmstrip generation (and/or device icon generation) may fail if the Rack Extension Designer executable and/or the Rack Extension project file is in a folder path that contains unicode characters. If this happens, rename the folder paths for Rack Extension Designer and your Rack Extension project so that they only contain ASCII characters.

What’s new in SDK 4.3.0?

  • Reason Recon updated to correspond to Reason 12

  • RE2D tools updated with hi-res support

  • Hi-res images for built in elements included

  • Example updated with hi-res custom display background

  • Example GUIs pre-rendered in hi-res

  • Build script fix for working with the latest Xcode version

What’s new in SDK 4.2.0?

  • 3D GUI support has been deprecated

  • Updated Recon to work in debug mode on MacOS Catalina

  • All included binaries are signed and notarized for MacOS Catalina

  • RE2DRender fixes for issues introduced when migrating from python 2 to 3

What’s new in SDK 4.1.0?

  • Updated software license model

  • Build scripts upgraded to python 3

  • MacOS Catalina support for Recon, RE2DRender and RE2DPreview

  • Reason Recon updated to correspond to Reason 11

  • Post-build validation (Recon ValidateRE) working for all platforms and build servers

  • Fixed memory scanning issue in post build validation (Recon ValidateRE)

  • Fix where big integers would be written in a lossy format in patches

  • Included reduced Factory Sound Bank for Recon to reduce SDK package size

  • Documentation moved from downloadable archive to http://developer.reasonstudios.com

What’s new in SDK 4.0.0?

  • Compiler toolchain is now based on LLVM 7.0

  • Support for C++17

  • Support for source level debugging with the LLVM compiler

  • Updated example projects for Visual Studio 2013/2015/2017 and Xcode 9.2

What’s new in SDK 3.0.0?

  • Support for Players

  • Support for pattern lane automation

  • Sample drop zones

  • Additional sequencer information, such as: loop points, bar position, and run/stop events

  • Reason Recon updated to correspond to Reason 10.1 and Reason Intro 10.1

  • Reason Recon updated with more built-in devices

What’s new in SDK 2.5.0?

  • Support for RT owned strings, which enables displays drawing DSP data

  • Support for user samples, browsable by the end user

  • Support for modifier keys in custom display gestures

  • Hideable widgets enabling panels and tabs

  • Popup menus in custom displays

  • Reason Recon updated to correspond to Reason 9.2 and Reason Essentials 9.2

What’s new in SDK 2.2.0?

  • GUIs may now be defined using high resolution 2D images

  • Reason Recon updated to correspond to Reason 8.2 and Reason Essentials 8.2

  • Added example project files for Visual Studio 2012

What’s new in SDK 2.1.0?

Reason Recon

  • Reason Recon updated to correspond to Reason 8.1 and Reason Essentials 8.1

  • Added Thor

  • Added RPG8

  • Added Spectrum Analyzer window

  • Faster custom display sandboxing

  • New Recon Tools menu (see above)

  • Bug fixes

Rack Extension Designer

  • Significantly reduced project loading/reloading time

  • Significantly reduced filmstrip rendering time

  • Significantly reduced temporary storage requirements when rendering filmstrips

  • New <fresnelAmount> parameter in the Phong, Anisotropic, and Glass materials that can be used to reduce or completely remove Fresnel reflection

  • 3D engine updated to use OpenGL 3.2

  • New menu option for rendering a single widget

  • New menu option for showing front and back panels together

  • New menu option for toggling the scenegraph view

  • New menu options for showing widget hit boxes

  • New menu options for saving/loading current camera state

  • Removed "Clamp to zoom" menu option: clamping now happens automatically when dynamic LOD switching is enabled

  • Increased zoom speed for orthographic views

  • Automatic checks for invalid widget bounds

  • XML attributes can now be specified in any order in scenegraph and material files

  • New tweak window slider for moving the back plane of the shadow camera (this allows the entire device to be shadowed when showing the front and back panels together)

  • Improved error handling and error reporting

  • Bug fixes

  • Added sections on texturing and normal mapping to GUI Designer Manual

LLVM and compiler toolchain

  • Compiler toolchain is now based on LLVM 3.5

  • Jukebox now offers limited support for vector (SIMD) instructions (see Jukebox Scripting Specification for details)

  • Compiler toolchain tweaked to produce faster LLVM bitcode

Acceptance testing

  • Level-of-detail meshes (and/or materials) are no longer required

Part Library

  • Lots of new assets, including knobs, buttons, and decorative elements

  • New UV mapping for front panels that minimizes texture stretching

  • New individual thumbnails for each asset with correct relative sizes and transparent backgrounds

  • Various visual tweaks and bug fixes

What’s new in SDK 2.0.1?

  • Reason Recon updated to correspond to Reason 7.1.1 and Reason Essentials 2.1.1.

  • Fixed minor errors, typos, and omissions in documentation.

What’s new in SDK 2.0.0?

  • New custom display widget

  • New static decoration widget

  • Faster math functions (requires rebuilding with SDK 2.0.0 and re-submitting to Reason Studios).

  • Tighter Lua parsing in Jukebox hosting; more errors are now reported instead of accepted quietly.

  • Changed memory alignment requirements: all new/malloc-allocated memory is now 16-byte-aligned. Added new toolbox function for querying optimal alignment for FFT functions. Deprecated old memory alignment querying functions.

  • Improved performance when updating rt_owner properties from Realtime.

  • Improved stability of build server pipeline.

  • It is now possible to animate the color and intensity of <lightNode>:s in scenegraphs.

  • Many under-the-hood improvements in Jukebox.

  • Rack Extension Designer: Intermediate folder is now deleted after compiling 2D resources

  • Completely rewritten documentation

  • Various bug fixes