bitwig-websocket-rpc
JSON-RPC 2.0 implementation over WebSockets for Bitwig Studio.
Installation
In your project directory:
npm install bitwig-websocket-rpc --save
Install Bitwig Studio Extension
npx bws-rpc install [options]
Configuration and Helper Tool
npx bws-rpc <cmd> [options]
Options
$ npx bws-rpc
Usage: bws-rpc [options] [command]
Configuration and helper tools for bitwig-websocket-rpc.
Options:
-V, --version output the version number
-h, --help output usage information
Commands:
install [options] Install Bitwig Studio WebSockets RPC server extension.
config [options] Configure RPC modules.
report [options] Report accessible RPC methods and evnets of current configuration as JSON.
actions [options] Report result of Application#getActions() as JSON.
events [options] Monitor events.
logs [options] Trace controller script logs.
$ npx bws-rpc install --help
Usage: install [options]
Install Bitwig Studio WebSockets RPC server extension.
Options:
-e, --extension-dir <path> Bitwig Studio Extension directory
(default: "<Platfom Specific>/Extensions")
-h, --help output usage information
$ npx bws-rpc config --help
Usage: config [options]
Configure RPC modules.
Options:
-u, --url <URL> Bitwig Studio WebSockets URL (default: "ws://localhost:8887")
-f, --file <path> config file(.js|.json) path.
-a, --all enable all RPC methods and events.
this option is ignored by -f, --file option.
-b, --abbrev enable abbreviated method and event name (experimental),
this option is ignored by -f, --file option.
-p, --print dry run, print current or intended configuration as JSON.
-h, --help output usage information
Module Use
Usage
const bitwig = ;const WebSocket = Client; const wait = { return ;}; async // configure interesting modules. // this function trigger restart of extension. // so all client connections will be closed by server. await ; // recommended client library. // https://github.com/elpheria/rpc-websockets const ws = 'ws://localhost:8887' autoconnect: true reconnect: true ; ws;;
API
const bitwig = ;;// or inside async functionasync { await ;};
bitwig(url, config)
Configure RPC modules.
Return:
- {
Promise
}: resolve value is undefined.
Parameters:
url
{String
}: The URL of the WebSocket server.config
{Object
}: The configuration of RPC modules. see section below for details.
This configuration is not session scoped. It's stored as JSON file in your home diretory.
${HOME}/.bitwig.extension.WebSocket\ RPC-x.x.x
Configuration Defaults
{ "webSocketPort": 8887, "useAbbreviatedMethodNames": false, "useProject": false, "useApplication": false, "useTransport": false, "useArranger": false, "arrangerCueMarkerSize": 16, "useGroove": false, "useMixer": false, "useArrangerCursorClip": false, "arrangerCursorClipGridWidth": 16, "arrangerCursorClipGridHeight": 16, "useLauncherCursorClip": false, "launcherCursorClipGridWidth": 16, "launcherCursorClipGridHeight": 16, "useCursorTrack": false, "cursorTrackNumSends": 2, "cursorTrackNumScenes": 8, "cursorTrackShouldFollowSelection": true, "useSiblingsTrackBank": false, "siblingsTrackBankNumTracks": 8, "siblingsTrackBankIncludeEffectTracks": false, "siblingsTrackBankIncludeMasterTrack": false, "useChildTrackBank": false, "childTrackBankNumTracks": 8, "childTrackBankHasFlatList": false, "useCursorDevice": false, "cursorDeviceNumSends": 2, "cursorDeviceFollowMode": "FOLLOW_SELECTION", "useChainSelector": false, "useCursorDeviceLayer": false, "useCursorRemoteControlsPage": false, "cursorRemoteControlsPageParameterCount": 8, "useDeviceLayerBank": false, "deviceLayerBankNumChannels": 8, "useDrumPadBank": false, "drumPadBankNumPads": 16, "useSiblingsDeviceBank": false, "siblingsDeviceBankNumDevices": 4, "useChainDeviceBank": false, "chainDeviceBankNumDevices": 4, "useSceneBank": false, "sceneBankNumScenes": 8, "useMainTrackBank": false, "mainTrackBankFollowCursorTrack": true, "mainTrackBankNumTracks": 8, "mainTrackBankNumSends": 2, "mainTrackBankNumScenes": 8, "useEffectTrackBank": false, "effectTrackBankNumTracks": 2, "effectTrackBankNumScenes": 8, "useMasterTrack": false, "masterTrackNumScenes": 8, "useBrowser": false, "browserSmartCollectionRows": 32, "browserLocationRows": 32, "browserDeviceRows": 32, "browserCategoryRows": 32, "browserTagRows": 32, "browserDeviceTypeRows": 16, "browserFileTypeRows": 16, "browserCreatorRows": 32, "browserResultsRows": 32}
You can get a default configuration as follows:
- Push [reset to default] button in preferences panel.
- Execute command.
npx bws-rpc --printConfig
RPC Module Dependencies
bitwig-websocket-rpc
├── application
├── arranger
├── arrangerCursorClip
├── browser
├── cursorTrack
│ ├── childTrackBank
│ ├── cursorDevice
│ │ ├── chainDeviceBank
│ │ ├── chainSelector
│ │ ├── cursorDeviceLayer
│ │ ├── cursorRemoteControlsPage
│ │ ├── deviceLayerBank
│ │ ├── drumPadBank
│ │ └── siblingsDeviceBank
│ └── siblingsTrackBank
├── effectTrackBank
├── groove
├── host
├── launcherCursorClip
├── mainTrackBank
├── masterTrack
├── mixer
├── rpc (core module for tools and supporting client library)
├── sceneBank
├── test (for testing)
└── transport
Notes
-
useAbbreviatedMethodNames
option is experimental. I don't gurantee to maintain the same method and event names for future. -
Currently calling
Bank#setSizeOfBank()
method doesn't support extending or reducing fire events. -
WebsocketRpcServer.bwextension calls following API methods from outside of Control Surface Session thread. It maybe dangerous.
Host#println()
Host#errorln()
Host#requestFlush()
License
All source codes of this git repository are licensed under MIT.
Bitwig Extension module contains following libraries: