Controller Defaults

Cantabile supports various ways of mapping controllers (typically MIDI CC controllers) to binding targets. For example a CC may be interpreted as a regular continuous controller, a button, a switch, a rotary encoder etc... Normally you configure how a controller is interpreted as part of configuring the binding however you can also create a file that defines how these bindings should be created automatically.

This page describes how to configure these controller defaults and should be considered an advanced topic that most users shouldn't need to bother with.

This feature requires Cantabile build 3624 or later

controllerDefaults.json

Controller defaults are configured in a special file called "controllerDefaults.json" which should be placed in Cantabile's settings folder and must be a valid JSON file.

The controller defaults file should have the following structure:

{
    "controllerDefaults": 
    [
        {
            // settings for controller defaults 1
        },
        {
            // repeat as many times as necessary
        },
    ]
}

Match Settings

Within the inner-most braces of the above section the following settings can be configured and specify the kind of incoming MIDI event this controller default applies to.

portName

The port name the controller is received from. This must exactly match (case sensitive) the MIDI port name as configured in Cantabile Options → MIDI Ports

sourceMidiEventKind

The MIDI Event kind that these defaults apply to and should be one of the following values.

Note that if this is set Controller, ControllerButton, ControllerNonEdgeButton or ControllerSwitch then this will match any of controller kinds and will cause the binding to acquire the controller type specified in the controller defaults file.

For example suppose you configure a controller default as "ControllerButton" then created a binding of type "ControllerSwitch" then the binding will be forced to "ControllerButton" (assuming all other match settings match).

• Note
• Controller
• ProgramChange
• PitchBend
• ChannelPressure
• NoteOff
• NoteSwitch
• ControllerButton
• ControllerNonEdgeButton
• ControllerSwitch
• FineController
• BankedProgramChange
• RpnCoarse
• RpnFine
• NRpnCoarse
• NRpnFine
• MasterVolume
• MasterBalance
• MmcBase
• MmcStop
• MmcPlay
• MmcDeferredPlay
• MmcFastForward
• MmcRewind
• MmcRecordPunchIn
• MmcRecordPunchOut
• MmcRecordReady
• MmcPause
• MmcEject
• MmcChase
• MmcReset
• TransportPlay
• TransportStop
• TransportPause
• SongSelect
• ClockStart
• ClockContinue
• ClockStop

sourceControllers

An array of source controller numbers that should be matched against.

Assignment Settings

If a binding matches all of the above "match settings" then the following settings (all optional) will be applied to the binding to configure it:

controllerEncoding

The controller encoding mode, one of the following:

• Absolute
• AbsoluteWithJumpPrevention
• RelativeMode1
• RelativeMode2
• RelativeMode3

relativeScaling

The scaling factor for relative encoders, where 1.0 = 100%

sourceRangeMin and sourceRangeMax

The source range of the controller

curveKind and curveAmount

The curve kind and amount to apply to this binding. The curveKind setting can be one of the following:

• None
• ExpandCompress
• Enhance
• InverseExpandCompress
• InverseEnhance

Example

For example, suppose CC controllers 16, 17, 18 and 19 on your main keyboard are all rotary encoders, creating a controller defaults file similar to the following would cause bindings against those controllers to always be configured as rotary encoder with a scaling of 130%.

{
    "controllerDefaults": 
    [
        {
            "portName": "Main Keyboard",
            "sourceMidiEventKind": "Controller",
            "sourceControllers": [ 16, 17, 18, 19 ],
            "controllerEncoding": "RelativeMode1",
            "relativeScaling": 1.3
        }
    ]
}

Error Logging

If there are syntax errors in the controllerDefaults.json file, an error will be logged to Cantabile's log file and none of the controller defaults will be loaded nor used.