Skip to content

Creating a Custom Mod

Jump to bottom
Andy Shand edited this page Oct 31, 2020 · 10 revisions

Contents

What are mods?

Modwig mods add to the core modwig functionality by adding extra shortcuts and features using simple Javascript scripts. They can be individually enabled/disabled in preferences (disabled by default).

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. The default-mods folder is also monitored, but should not be used to store user-defined mods as it will be replaced whenever you download a new modwig version.

Mods come in two types - Modwig-side (*.js) and Bitwig-side (*.bitwig.js). These are basically equivalent to client and server-side respectively. It is possible for a mod to use both types of script, and use them to communicate with one and other.

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.

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

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",
    id: "must-be-unique",
    category: "global", // optional, takes on category of mod by default
    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.

Saving/loading data

You can associate data with the currently selected track in Bitwig using the following functions on the Db object. These will be persisted between runs. Note that we use the track name internally to uniquely identify tracks, so renaming tracks will lose data. Not the best solution - but Bitwig doesn't provide a unique id (afaik?).

const mySaveData = { myField: true }
await Db.setCurrentTrackData(mySaveData)
const { myField } = await Db.getCurrentTrackData()

Get and set the data associated with a specific named track using Db.getTrackData(trackName) and Db.setTrackData(trackName, data).

API Documentation

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

Clone this wiki locally