Creating a Custom Mod

What are mods?

Mods are stored under your <Your Bitwig User Library>/Modwig/Mods. Modwig will watch this folder for changes and refresh the controller script as necessary to inject code.

Mods are written in Javascript and come in two types - Modwig-side (*.js) and Bitwig-side (*.bitwig.js). These are basically equivalent to client and server-side respectively.

Modwig-side scripts are run as part of the electron app and can be used to monitor keyboard & mouse events, among other things. If you want to add your own assignable "actions" as part of your mod, these can be registered here too.

Bitwig-side scripts are injected into the controller script and have access to all of the standard Bitwig API. These can be used to add features that require access to the Bitwig API. There is also a custom, simplified API available.

It is possible for a mod to use both types of script, and use them to communicate with each other.

Mod header comment

Every mod must have a comment section at the top of the file like so:

/**
 * @name Remember Device View Scroll
 * @id device-view-scroll
 * @description Return to previous scroll position when switching between tracks. Scroll position is currently tracked by listening for middle click drags on the device view portion of the screen. May not work for non-standard scaling/screen layouts.
 * @category devices
 */

Only @id and @name are required, but @category and @description will probably be useful. The @id must be unique across all mods.

If your mod has the same id as one of the built-in mods, it will override its functionality. This can be used to keep a custom implementation of a mod around, incase the default doesn't work the way you want.

Bitwig-side and Modwig-side scripts intended to work together should use the same header.

Registering Actions (Not Yet Supported)

Mods can register "actions" - additional routines that can be assigned to keyboard shortcuts within the Modwig UI. To do so, add the following in your Modwig-side script:

Mod.registerAction({
    title: "Create instant banger",
    description: "", // optional
    defaultSetting: { // optional
        // The default or "recommended" shortcut for your action
        keys: ["Meta", "Shift", "B"]
    },
    action: () => {
        // Do what you need to do here
    }
})

Running Other Actions (Not Yet Supported)

You can reuse built-in actions or actions other mods by using Mod.runAction("the-action-id"). You can use this to create simple "macro" scripts, like this one that adds an EQ to the current track.

/**
 * @name My Macros
 * @id my-macros
 */

Mod.registerAction({
    title: "Add EQ",
    defaultSetting: {   
        keys: ["Meta", "Shift", "E"]
    },
    action: () => {
        Mod.runAction("insertDeviceAtEnd")
        Keyboard.keyPress('E')
        Keyboard.keyPress('Q')
        Mod.runAction("selectBrowserTab1")
        Mod.runAction("clearBrowserFilters")
        Mod.runAction("confirmBrowser")
    }
})

Mod activation/deactivation

When the user turns your mod on or off, it can take some time to refresh the controller script and for Bitwig to pick it up, interrupting creative flow. In which case, you may prefer to keep your mod loaded but handle the "disabled" state within your own logic. To do so, there are two steps:

1. Add the @noReload tag to the comment section at the top of the file
2. Add a check for Mod.enabled at relevant sections in your mod code

This is only relevant for Bitwig-side scripts.

API Documentation

The complete APIs for each side are currently undocumented, however you can view the default mods here to see usage examples.