Jukebox has been designed with focus on portability, robustness and longevity. We want any implementation based on Jukebox technology to be able to run on all platforms that Reason Studios currently supports, but also on future platforms that we are not running on today.

It should be hard to make mistakes that bring the whole host down, and if bad things do happen, the end user’s working document should be kept safe.

Jukebox isolates implementers from operating system and other platform issues and makes it the responsibility of the host to keep up with system updates and changing runtime dependencies.

A device in the Jukebox world is called a "45". 45’s have a number of audio inputs and audio outputs, a piece of C++ code that performs some kind of signal processing and a set of properties that control how this processing is performed. To be able to tweak and visualize the current value of properties, there is a GUI system that ties user gestures and graphical representations to properties in a portable manner.

A Jukebox 45 can be divided into three major parts, from user end to the actual signal processing: GUI, data model and processing code.

The different design goals described earlier put demands on the feature set of each of these parts, but also limitations in terms of flexibility.

Jukebox 45’s are hosted in a sandboxed environment that provides much of the functionality needed to get a fully functional 45. A data driven approach has been used for major parts of the data model and GUI, and it is the responsibility of the host to provide robust handling of that data and to maintain platform compatibility.

The native code that makes up the realtime part runs in a sandboxed environment, which is both limited in terms of functionality and keeps 45’s under close supervision. There is for example no direct access to OS libraries, and a 45 that tries to allocate memory while rendering audio will be shut down.

A special version of Reason called Reason Recon is provided with the Jukebox SDK for testing and debugging purposes.

The data model in Jukebox is called the Motherboard and is defined using the Lua scripting language. The Motherboard holds properties that are organized into property set objects. Some of the objects are built-in and defined by the host; others are defined specifically for each 45 implementation. 45-specific properties are known as custom properties.

The Motherboard also contains information about other things, such as input and output sockets, MIDI CC and Remote™ mappings, and automatic routing hints.

Once defined, the Motherboard is under complete control of the host, even though some parts can be customized by the use of Lua scripts. Because of this, the host can provide complete undo handling, generic patch handling and so on.

The Jukebox design goals put special demands on the GUI side. A Jukebox GUI must have:

In Jukebox, a GUI is defined as a set of high resolution 2D images that are connected to the motherboard via Lua scripts. The panels and parts that make up a device are represented by 2D images.

For performance reasons, data processing is done in native code, but must still live up to the Jukebox design goals. All data processing in Jukebox is done in portable C++ by implementing two functions:

The C++ code runs in a limited environment with no access to operating system functions or external libraries other than those compiled from source code or provided by Jukebox.

A Jukebox 45 can include any number of files that are either private to the 45 or publically available to other devices or subsystems in the same host. An example of a private resource could be a wavetable that will be loaded as a BLOB (Binary Large Object) and interpreted by 45 specific code. There is no need for that resource to be exposed to other devices. Obvious examples of public resources are the patches that come with a 45. These must be publically available, as the host will expose them for browsing, etc. Public resources live in the Resources/Public resource subfolder of a Jukebox project and private in the Resources/Private resource subfolder. Assets that do not live in any of these folders are internal to the Jukebox system and will only be accessed by the host. When referring to resources in scripts, a forward slash separated resource path is used.

With a few exceptions, all strings that are shown in the GUI of a 45 must be localized, including property names and values. In situations where you refer to a localized string, you provide a UI text key rather than the string itself. The host uses the key to fetch the appropriate string for the currently selected language from the 45’s set of localized text databases. There is one database for each language; English is required. The other languages are German, French, and Japanese. See the Jukebox Scripting Specification for information about the format and location of the database files.

All Jukebox devices share a common patch format, which is a simple XML-based format. The file extension for patch files is .repatch. See the Jukebox Scripting Specification document for details.

The supports_patches boolean setting in info.lua controls whether a 45 uses patches or not. To allow the user to browse for patches, add a patch_browse_group and a patch_name GUI widget pair to the front and folded front panels. See the GUI Designer Manual and the Jukebox Scripting Specification for details.

It is not necessary for a 45 to support patches. If it does, however, the Public resources folder must contain a default patch (which is specified in info.lua). Creating a default patch manually (by editing an XML file) is not recommended. Instead, set default_patch in info.lua to any patch and create an instance of the 45 in Reason. Reason will fail to load the patch (and show an error message) but will not blow the fuse. Since your 45 is now running, it is now straightforward to create a patch, save it to the Public resources folder, and point to it in info.lua.

If you you wish to create patches that use references to samples you will supply, you need to include the samples in your Public folder and build the 45 first. After building the 45, load the samples from the devices public folder by navigating to Rack Extensions ⇒ 45 in the Reason/Recon browser in order to get the correct references in the patch. The same goes for building combi-patches that reference samples that should be included in your 45.

Devices that support patches must include a reasonable number of well organized patches.

All properties in a property set object have an owner scope. The owner scope defines which part of the 45 that is allowed to write to the property. There are four owners:

The Jukebox property system is strictly typed. These are the types:

When you read a value from a property in C++, the value is represented as an opaque type called TJBox_Value. You use toolbox functions to access the actual contents of the TJBox_Value instance. Conversely, when you update the value of a property in C++, you construct a TJBox_Value using toolbox functions and send it to the host.

In Lua, number, boolean, and string property values are represented by the corresponding built-in Lua types. The other property types are represented by opaque types. For these types, there exist Lua functions for accessing the contents and for constructing new values.

All property types have a well-defined default value. Some property types require that you supply a default value explicitly when you create the property (see Jukebox Scripting Specification for details).

If the host responds to MIDI Continuous Controller messages, it may require special handling for messages for modulation wheel, pitch bend, sustain pedal, expression, breath control, and aftertouch. Therefore, these messages use special-purpose property types. In the example above, the properties named modWheel and pitchBend are defined as performance properties. See the Jukebox Scripting Specification for details.

A device with user samples takes part in the native host features to browse for audio sample files, and create new files by sampling, bouncing or editing (sample editor). Optionally, the device can also specify to include one or more sample meta-data properties (the Sample Parameters) in its patch data. User samples also enable host properties under the /device_host object, which the device can use to integrate with the user samples hosting.

Example:

This example defines properties for a user browsable sample item and all of its sample parameters. The property path of the sample item is /user_samples/0/item, and each of the sample parameters are members/fields of the same object instance (e.g. /user_samples/0/root_key). See the Jukebox Scripting Specification for details.

The user interface name (ui_name) of a property is a localized string that contains the name of the property. It is used by the host to identify the property in its GUI. Since the string is localized, the jbox.ui_text() function is used to fetch the appropriate string from the localized text database. In the example above, the UI name for the volume property uses the "Volume_UI" key, which means that the localized text databases would all have entries like this:

Resources/English/texts.lua:

Resources/German/texts.lua:

etc.

The user interface type (ui_type) entry in a property definition specifies how the value of the property should be presented in the host’s GUI. The host may allow the user to enter values for the property, so the user interface type may be used for both input and output. See the Jukebox Scripting Specification for details on how to set up UI types.

The host will automatically populate the MOM with a collection of property set objects that it uses to expose internal state to the 45. These properties are called host properties. See the Jukebox Scripting Specification for details.

The midi_implementation_chart section in motherboard_def.lua contains MIDI-related configuration settings for the 45. In the current version of Jukebox, it has one entry, the MIDI CC chart. This chart associates properties in the document_owner scope with MIDI Continuous Controllers. When such an association is in place, the user can modify the property via MIDI CC messages (if this is supported by the host).

The MIDI Implementation Chart document (which can be found in the Reason documentation folder) contains the MIDI CC associations for all legacy devices in Reason. If your 45 is similar to one of the legacy devices, we strongly recommended to use similar associations if possible.

The Remote™ protocol is designed to simplify communication between Reason and third-party hardware keyboards and controllers. The protocol translates MIDI messages into messages that are specific to Reason. In order to integrate properly with the Remote system, the 45 must provide the Jukebox host with information about how its various controls (knobs, faders, etc.) should be mapped to Remote-enabled hardware controllers.

From the user’s perspective, a Remote-enabled hardware controller is "wired" to work with Reason: when a Reason device is selected in the rack, for example, the hardware control surface items (such as physical knobs and faders) are automatically associated with the appropriate controllers on the rack device. Status indicators on the rack device or other indicators in Reason can be mirrored on lamps and LEDs on the hardware controller (e.g., the status of the SOLO and MUTE buttons in the Reason mixer). If the hardware controller contains a display, the Remote protocol allows the hardware controller to show the values of a rack device parameter, or the location of the song position, etc.

The ui_groups table of motherboard_def.lua allows you to create groups of logically related motherboard properties for UI display purposes. The host may use the grouping information in any way it sees fit, including changing the order of the the groups and the properties in each group. In the current version of the Reason combinator, for example, groups are not shown if the motherboard contains fewer than ten automatable properties.

See the Jukebox Scripting Specification for details on how to set up property UI groups.

A Jukebox 45 can communicate with the outside world via MIDI, and audio/CV inputs and outputs. These input and output sockets are defined in motherboard_def.lua and are read from and written to by the C++ Realtime code. For receiving and sending MIDI, see section Receiving and sending notes.

Each input/output are individual property set objects. For example, the motherboard definition above has two audio outputs, left and right, and two CV inputs, note_cv and gate_cv. Both outputs have two properties, buffer (the DSP buffer that the Realtime writes to) and connected (a boolean property that the host sets to true when a cable is connected to the socket). The property path to, say, the left socket’s buffer is

/audio_outputs/left/buffer

Jukebox allows devices to connect to each other via their input and output sockets. The host may offer different kinds of automatic routing functionality to improve the user experience. In Reason, for example, such functionality come into play when the user connects cables manually (connecting the left socket in an audio stereo pair will automatically connect the right socket), when the "Auto-route" menu option is invoked for a selected device, when a device is added to or deleted from the rack, etc.

In order to facilitate automatic routing, your Jukebox device may provide information about how it should be routed. If it does not provide routing information, the host may not be able to offer automatic routing functionality for the device (in which case the user must connect all sockets manually). The exact automatic routing behavior depends on the host and the current connection state of all involved devices.

To set up automatic routing, you need to provide the following information:

The motherboard_def.lua example above defines automatic routing hints suitable for a stereo instrument.

See the Jukebox Scripting Specification for details on how to set up automatic routing.

Rack Extensions that have an internal sequencer (what we call pattern devices), should implement the Run behaviour. In general, pattern devices should start and stop in sync with master sequencer transport. With Run, the user can start/stop the internal sequencer independently of Reason’s sequencer:

A good example of the Run behaviour is the Redrum, so give it a spin to get a feel for the behaviour! There are some issues to consider with Run:

Players can be disabled in two different ways:

These two settings are somewhat overlapping, and how the device is designed can make difference to how it handles the two states. In general it can be thought of like this:

The ON/OFF button should work like turning the power on and off for the device. In OFF mode, the device should only bypass incoming MIDI, and not generate any MIDI or CV of its own. It is recommended that custom displays are cleared or “unlit” to make the device look inactive.

In Bypass All mode, the device should still be responsive (power on, custom displays can be editable), but it is disconnected from the MIDI chain by Reason. It should not generate or process any MIDI or CV, or Run when Reasons transport is running. Even if the device is still ON, we recommend indicating somehow that it is bypassed (for example by writing “Bypassed” in a display or similar).

An update to a released 45 must keep patches and songs from earlier versions sound and function exactly the same as before. In other words, the default settings of new properties must not affect the sound. In addition, certain rules must be followed to ensure motherboard compatibility:

The RTC can be used to set up properties that change their value as a result of changes in one or several other properties. For example, let’s say that we want to reload a sample when the host changes the sample rate. To do this, we would create an association between the /environment/system_sample_rate property and our sample property, e.g., /custom_properties/my_sample. That way, the my_sample property will be automatically updated whenever system_sample_rate changes. Such derived properties (which must be rtc_owner, since they are modified by the RTC) are updated via Lua functions that you specify in realtime_controller.lua.

For example:

The only information that can be accessed inside a RTC function is:

A RTC function can not have any side-effects, except for updating properties in the Motherboard. This means that all creation and updating of global data in the Lua virtual machine is forbidden. If you need to communicate information between two RTC functions, you must do so via rtc_owner properties.

See the Jukebox Scripting Specification for further details.

All 45s must support the following sample rates: 22050, 44100, 48000, 88200, 96000, and 192000 Hz. At least one of these must be supported natively. If the 45 does internal resampling to support one of these rates, that rate should be declared as converted. This allows the host to do sample rate conversion to one of the native sample rates if needed.

See the Jukebox Scripting Specification for details.

When the Realtime signal processing code is called upon to render audio, it can read any property in the Motherboard (except those in the gui_owner scope). However, the Realtime code is often only interested in those properties that have changed their values since the last render callback. One of the arguments to JBOX_Export_RenderRealtime() (the audio rendering function that your 45 makes available and the host calls) is a list of such property diffs.

For efficiency reasons, the RTC must tell the host which of the properties in the MOM that the Realtime should receive diffs for. Those properties are listed in the rt_input_setup section of the RTC configuration script. See the Jukebox Scripting Specification for details.

The Jukebox C++ toolchain is based on a Jukebox-specific variation of the LLVM Clang compiler (see http://llvm.org/) and a collection of supporting tools. This toolchain is used to create LLVM bitcode, which is submitted to Reason Studios as part of the Universal 45. The bitcode is translated to binary format for the various supported native platforms (e.g., Windows and macOS) on the Reason Studios servers before it is being distributed to end-users. This means that the 45 is running platform-specific code on the end user’s machine. To allow the code to run at the required speed for realtime operation, there are limits to the kinds of errors the realtime sandbox can detect.

These errors are caught in realtime (which blows the fuse):

However, during testing and validation, Reason Studios will build submitted 45’s with extra instrumentation code that validates all memory references. This makes it possible to catch a larger amount of bugs during non-realtime stress tests. This means that a 45 built for testing (you select this when you upload the Universal 45 to the Reason Studios servers) will run at a slower speed than a 45 built for deployment.

The Jukebox SDK provides a limited version of the C/C++ standard libraries. The limitations are mostly due to the requirements of the runtime environment (no direct access to files, etc.) and long term portability issues.

Memory that you allocate with malloc() and new will be aligned to 16 bytes. However, certain toolbox functions will perform faster if the memory you provide to them is aligned on other address boundaries. See the Jukebox Scripting Specification and the C++ Specification documents for details.

To ensure portability, robustness, and performance, Jukebox enforces a specific floating point contract. See the Jukebox Scripting Specification for details.

If a 45 introduces DSP latency, for example by doing buffered processing such as FFT, the 45 should tell the host what the current latency is for each relevant audio and CV output. The current latency is a per output setting that specifies the latency in frames. All output sockets have a rtc_owner property called dsp_latency for this purpose. Note that both audio and CV sockets can have DSP latency specified and that latency can differ between outputs.

It is allowed to initiate a change of the latency from within JBox_Export_RenderRealtime() (this requires defining a rt_owner property in the MOM and creating a binding to that property in realtime_controller.lua), but note that doing so may introduce audible clicks or breakups in the sound output.

All 45:s must handle silence, i.e., stop rendering when all inputs are silent (or shortly after inputs become silent). An audio input is considered to be silent when all values in the buffer are smaller than or equal to the C++ constant kJBox_SilentThreshold. If a 45 does not touch any of the values in the DSP buffer of the buffer property in an audio output socket during a batch, the host considers the socket to be silent. Note that filling the buffer with zeros does not constitute silence in this sense. If the 45 does choose to write to the DSP buffer, then all values must be written to. It is not permitted to write nan:s or inf:s to the buffer. See the "Silence Detection Demo" example for details.

It is important that Rack Extensions do not waste computational resources. A device that uses excessive computational resources may be rejected by Reason Studios.

Here are some basic recommendations for improving performance:

All Jukebox devices are able to receive MIDI notes, with one exception (see "Combinator issues" below). There are 128 MIDI notes [0, 127]. By default, note number 69 corresponds to A440 (i.e., 440 Hz for Middle-A on a standard piano keyboard), but this can be offset by +/- one semitone by the user via the Master Tune setting (see below).

Each MIDI note has a corresponding Jukebox property in the

/note_states

property set object. The property key for each note is set to the note number, i.e.,

The property tag for each note is also set to the note number, so the simplest way to detect note changes is by doing something similar to

As the example above illustrates, the property value is the velocity of the note. The velocity is a discrete value in the range [0, 127], where a value of 0 means note off and a value of 127 means maximum velocity.

As of Jukebox version 3.0, there is also a C++ toolbox function for converting property values to note events:

Note that in order to receive note update notifications, you must subscribe to note_state changes, i.e., you must say

in realtime_controller.lua.

Player devices have the ability to send note events using the function JBox_OutputNoteEvent.

Player devices, for certain product designs, should forward incoming MIDI note events to the next device (another Player or the instrument). Player devices in off mode should always forward incoming note events. The following example shows how to forward incoming MIDI note events:

As of version 3.0, Jukebox supports sequence-based and pattern-based Rack Extensions. A 45 can receive information about the current master transport play position, tempo, loop positions, bar start position, and whether the sequencer is running or not. This makes it possible to create Rack Extensions with tempo-synced LFOs, patterns, and similar.

However, it is very difficult or even impossible to create Rack Extensions that react correctly to the absolute master transport position.

The 45 can obtain the master transport play position at the start of each batch (of 64 frames). The reason is, quite simply, that JBox_Export_RenderRealtime() is only called once per batch, and that any property value that it obtains from Jukebox (with the exception of notes) is from a "snapshot" of the MOM as it was at the start of the batch.

The notes that are received within a batch are normally located just to the right of the master transport play position in the sequencer. But if the sequencer happened to reached a loop point during the batch, or if the user has moved the transport position explicitly, the play position may actually have jumped during the batch. If so, the notes reported to JBox_Export_RenderRealtime() may actually originate from completely different locations in the sequencer. Indeed, although unlikely, the play position may actually have jumped more than once during the batch.

As a result, a 45 can only "react" to transport play position jumps "after the fact". In practice, this often leads to artefacts like dropped notes or "untight" triggering of notes.

CV sockets contain a floating point value that represents the CV signal for the current batch. For compatibility with other Reason devices, it is important to follow the CV level standards used by Reason.

The range specified for a CV type represents the signal level needed for nominal full range modulation of the corresponding parameter. That is, a full range LFO producing standard Matrix bipolar output should result in a signal in range [-1.0, 1.0] on the corresponding CV output.

Typically, the nominal full range corresponds to 100% modulation, but it is up to the receiving device to decide what levels are usable. A CV mixer might allow signals greater than 1.0 for instance, and some devices might allow modulating filter frequencies to 130%.

Devices with CV inputs are responsible for clamping incoming CV signals to a useful range before mapping to internal parameters.

It is common for CV inputs to have a trim knob that can be used to scale the signal before clamping and mapping. The scaling applied by trim knobs ranges from 0.0 to 1.0. By default, trim knobs are set to 1.0.

As described above, note and velocity values in Jukebox have the same range as in the MIDI standard, [0, 127]. To convert from a note or velocity value to CV, divide the value by 127:

For historical reasons, the conversion from CV to note or velocity must be done slightly differently. Please use the following conversion to ensure consistency with Reason’s legacy devices:

Velocity CV is commonly called "Gate" since it is used for monophonic triggering as well as transferring velocity information. Jukebox devices that react to gate should trigger on the positive flank of the velocity signal’s corresponding integer value. That is, when the value of the gate CV changes from below 1/127 to 1/127 and above.

Here is a code snippet that illustrates how notes are triggered in the built-in Reason devices:

The standard for pitch control in Thor is slightly different, and is used internally for both controlling the pitch of oscillators and the cutoff frequency of filters. Thor uses a 7 octave per volt mapping where zero volts corresponds to middle C.

Sometimes, the host may want to re-initialize the 45 to a "silent" state. The most common situation is just before a song or loop is exported to an audio file. In such situations, any still-sounding reverb tails or synthesizer voices should be silenced immediately. (Otherwise, the tail or voice release will be heard at the beginning of the exported audio.) Note that the host may request an audio reset in other situations, such as when the device is first created, or when the sample rate changes.

To signal that a 45 should reset itself, the host sets the property /transport/request_reset_audio to new value. The property is an integer counter with an unspecified non-negative initial value. The 45 should reset itself at the batch frame where the property was updated, and then continue processing as normal for the following frames in the batch.

When a custom display is redrawn, it is sent a snapshot of the Motherboard state, i.e., it is sent a local copy of the values of all properties that are bound to the display. Jukebox does not guarantee any specific update rate for custom displays, nor does it guarantee that all values in the Motherboard snapshot originated in the same JBox_Export_RenderRealtime() batch.

For example, if an rt_owner property is bound to a custom display and it is modified by JBox_Export_RenderRealtime(), the host flags the display as dirty (assuming the modified value is different from the last time the display was redrawn). The property may be modified several times before the host has time to actually redraw the display. The snapshot of the Motherboard is taken just before the display is redrawn.

A custom display has a virtual "video memory" that consists of a rectangular buffer of "virtual pixels" that the 45 can modify. The width and height of the video memory cannot change at run-time. When the display (or a part of it) must be repainted, the corresponding area in the video memory is cleared to black, or to a (static) bitmap that the 45 provides. It is not possible to read from the video memory.

To create a custom display, you first need to add a flat, rectangular surface to the device’s front or folded front panel (custom displays cannot be added to the back panels), and assign a custom display material to it (see the GUI Designer Manual and Jukebox Scripting Specification for details). Then, you create a custom display widget in hdgui_2D.lua similar to this:

The graphics entry is the same as all other widgets, except that it cannot have boundaries or hit_boundaries modifiers.

The display_width_pixels and display_height_pixels entries are the dimensions of the "video memory".

The invalidate_function is the name of an Lua function in a file called display.lua (that you provide). The host will call this function whenever one or several of the properties that have been bound to the display have changed. The invalidate function is responsible for informing the host about which areas of the display that need to be repainted, based on the property changes. This is done by calling the Lua toolbox function jbox_display.invalidate() once for each rectangle in the display that needs to be redrawn. For example:

If the invalidate function does not make any calls to jbox_display.invalidate(), the host will assume that the display does not have to be repainted.

The draw_function is the name of a Lua function (also in display.lua) that the host calls if the display must be repainted. The host passes the rectangle that needs to be repainted (the "dirty rect") to the function. Note that the dirty rect may not be the same rectangle that the invalidate_function provided (the entire display has to be repainted when it is drawn for the first time, for example). The display function is also provided with the current values for all properties that are bound to the display. For example:

The invalidate function and the draw function may not have any side-effects, except for updating the virtual video memory. You cannot pass information between the invalidate and draw functions, or between them and the rest of Jukebox, except via Motherboard properties.

The gesture_function responds to user gestures; it is described in detail below.

The values entry is an indexed-based table that contains the Motherboard properties (in the gui_owner or document_owner scopes) that the display should "listen to" and/or update.

As mentioned above, it is possible to configure a custom display to receive user gestures. The display does not work directly with window system events, this is the host’s responsibility. Instead, the host will interpret incoming window system events as more abstract gestures that it then forwards to the custom display.

To receive user input, you provide the host with the name of a gesture recognizer function, which is a Lua function that you define in display.lua. If the gesture recognizer function decides that the custom display should respond to the gesture, it returns a gesture definition table. (If not, the gesture recognizer function must return nil.)

The gesture definition table contains two entries:

The gesture handler callbacks are allowed to update any number, string, or boolean property in the gui_owner or document_owner scope in the custom_properties property set object, assuming that the property has been bound to the custom display. (Performance properties cannot be modified by custom displays.)

Here is an example. We begin by specifying a gesture recognizer function in hdgui_2D.lua:

In this example, the display always responds to tap/clicks (it doesn’t use any custom data):

The gesture handler, handle_tap, updates one of the properties that are bound to the custom display:

The gesture_ui_name is a localized string that the host uses to present the gesture to the user, e.g., in its undo system.

The details of how undo works is host-specific. Here is how it currently works in Reason: