Bitwig Studio Control Surface API  5.0.11
ControllerHost Interface Reference
+ Inheritance diagram for ControllerHost:

Public Member Functions

void restart ()
 
void loadAPI (int version)
 
void useBetaApi ()
 
boolean shouldFailOnDeprecatedUse ()
 
void setShouldFailOnDeprecatedUse (boolean value)
 
void load (String path)
 
boolean platformIsWindows ()
 
boolean platformIsMac ()
 
boolean platformIsLinux ()
 
void defineController (String vendor, String name, String version, String uuid, String author)
 
void defineMidiPorts (int numInports, int numOutports)
 
MidiIn getMidiInPort (int index)
 
MidiOut getMidiOutPort (int index)
 
HardwareDevice hardwareDevice (int index)
 
void addDeviceNameBasedDiscoveryPair (String[] inputs, String[] outputs)
 
void defineSysexIdentityReply (String reply)
 
Preferences getPreferences ()
 
DocumentState getDocumentState ()
 
NotificationSettings getNotificationSettings ()
 
Project getProject ()
 
Transport createTransport ()
 
Groove createGroove ()
 
Application createApplication ()
 
Arranger createArranger ()
 
Arranger createArranger (final int window)
 
Mixer createMixer ()
 
Mixer createMixer (final String panelLayout)
 
Mixer createMixer (final int window)
 
Mixer createMixer (final String panelLayout, final int window)
 
DetailEditor createDetailEditor ()
 
DetailEditor createDetailEditor (final int window)
 
TrackBank createTrackBank (final int numTracks, final int numSends, final int numScenes)
 
TrackBank createTrackBank (final int numTracks, final int numSends, final int numScenes, final boolean hasFlatTrackList)
 
TrackBank createMainTrackBank (final int numTracks, final int numSends, final int numScenes)
 
TrackBank createEffectTrackBank (final int numTracks, final int numSends, final int numScenes)
 
TrackBank createEffectTrackBank (final int numTracks, final int numScenes)
 
MasterTrack createMasterTrack (final int numScenes)
 
CursorTrack createArrangerCursorTrack (final int numSends, final int numScenes)
 
CursorTrack createCursorTrack (final String name, final int numSends, final int numScenes)
 
CursorTrack createCursorTrack (final String id, String name, final int numSends, final int numScenes, boolean shouldFollowSelection)
 
SceneBank createSceneBank (final int numScenes)
 
CursorDevice createEditorCursorDevice ()
 
CursorDevice createEditorCursorDevice (int numSends)
 
Clip createCursorClip (final int gridWidth, final int gridHeight)
 
Clip createLauncherCursorClip (final int gridWidth, final int gridHeight)
 
Clip createArrangerCursorClip (final int gridWidth, final int gridHeight)
 
UserControlBank createUserControls (final int numControllers)
 
void scheduleTask (Object callback, Object[] args, long delay)
 
void scheduleTask (Runnable callback, long delay)
 
void requestFlush ()
 
void println (String s)
 
void errorln (String s)
 
void showPopupNotification (String text)
 
RemoteSocket createRemoteConnection (String name, int defaultPort)
 
void connectToRemoteHost (String host, int port, ConnectionEstablishedCallback callback)
 
void sendDatagramPacket (String host, int port, byte[] data)
 
boolean addDatagramPacketObserver (String name, int port, DataReceivedCallback callback)
 
void defineController (String vendor, String name, String version, String uuid)
 
Transport createTransportSection ()
 
CursorTrack createCursorTrack (final int numSends, final int numScenes)
 
Groove createGrooveSection ()
 
Application createApplicationSection ()
 
Arranger createArrangerSection (final int screenIndex)
 
Mixer createMixerSection (final String perspective, final int screenIndex)
 
TrackBank createTrackBankSection (final int numTracks, final int numSends, final int numScenes)
 
TrackBank createMainTrackBankSection (final int numTracks, final int numSends, final int numScenes)
 
TrackBank createEffectTrackBankSection (final int numTracks, final int numScenes)
 
CursorTrack createCursorTrackSection (final int numSends, final int numScenes)
 
Track createMasterTrackSection (final int numScenes)
 
Clip createCursorClipSection (final int gridWidth, final int gridHeight)
 
CursorDevice createCursorDeviceSection (final int numControllers)
 
CursorDevice createCursorDevice ()
 
UserControlBank createUserControlsSection (final int numControllers)
 
void defineSysexDiscovery (String request, String reply)
 
PopupBrowser createPopupBrowser ()
 
BeatTimeFormatter defaultBeatTimeFormatter ()
 
void setDefaultBeatTimeFormatter (BeatTimeFormatter formatter)
 
BeatTimeFormatter createBeatTimeFormatter (final String separator, final int barsLen, final int beatsLen, final int subdivisionLen, final int ticksLen)
 
HardwareSurface createHardwareSurface ()
 
HardwareActionMatcher createOrHardwareActionMatcher (HardwareActionMatcher matcher1, HardwareActionMatcher matcher2)
 
RelativeHardwareValueMatcher createOrRelativeHardwareValueMatcher (RelativeHardwareValueMatcher matcher1, RelativeHardwareValueMatcher matcher2)
 
AbsoluteHardwareValueMatcher createOrAbsoluteHardwareValueMatcher (AbsoluteHardwareValueMatcher matcher1, AbsoluteHardwareValueMatcher matcher2)
 
MidiExpressions midiExpressions ()
 
default HardwareActionBindable createCallbackAction (final Runnable runnable, final Supplier< String > descriptionProvider)
 
HardwareActionBindable createAction (Runnable runnable, Supplier< String > descriptionProvider)
 
default HardwareActionBindable createPressureCallbackAction (final DoubleConsumer actionPressureConsumer, final Supplier< String > descriptionProvider)
 
HardwareActionBindable createAction (DoubleConsumer actionPressureConsumer, Supplier< String > descriptionProvider)
 
RelativeHardwarControlBindable createRelativeHardwareControlStepTarget (HardwareActionBindable stepForwardsAction, HardwareActionBindable stepBackwardsAction)
 
RelativeHardwarControlBindable createRelativeHardwareControlAdjustmentTarget (DoubleConsumer adjustmentConsumer)
 
AbsoluteHardwarControlBindable createAbsoluteHardwareControlAdjustmentTarget (DoubleConsumer adjustmentConsumer)
 
void deleteObjects (String undoName, DeleteableObject... objects)
 
void deleteObjects (DeleteableObject... objects)
 
DeviceMatcher createInstrumentMatcher ()
 
DeviceMatcher createAudioEffectMatcher ()
 
DeviceMatcher createNoteEffectMatcher ()
 
DeviceMatcher createBitwigDeviceMatcher (UUID id)
 
DeviceMatcher createVST2DeviceMatcher (int id)
 
DeviceMatcher createVST3DeviceMatcher (String id)
 
DeviceMatcher createActiveDeviceMatcher ()
 
DeviceMatcher createFirstDeviceInChainMatcher ()
 
DeviceMatcher createLastDeviceInChainMatcher ()
 
DeviceMatcher createOrDeviceMatcher (DeviceMatcher... deviceMatchers)
 
DeviceMatcher createAndDeviceMatcher (DeviceMatcher... deviceMatchers)
 
DeviceMatcher createNotDeviceMatcher (DeviceMatcher deviceMatcher)
 
- Public Member Functions inherited from Host
int getHostApiVersion ()
 
String getHostVendor ()
 
String getHostProduct ()
 
String getHostVersion ()
 
PlatformType getPlatformType ()
 
void setErrorReportingEMail (String address)
 
OscModule getOscModule ()
 
MemoryBlock allocateMemoryBlock (int size)
 
Bitmap createBitmap (int width, int height, BitmapFormat format)
 
FontFace loadFontFace (String path)
 
FontOptions createFontOptions ()
 
Image loadPNG (String path)
 
Image loadSVG (String path, double scale)
 

Detailed Description

An interface representing the host application to the script. A singleton instance of this interface is available in the global scope of each script. The methods provided by this interface can be divided in different categories:

  1. functions for registering the script in Bitwig Studio, so that it can be listed, detected and configured in the controller preferences. The methods that belong to this group are defineController, defineMidiPorts, defineSysexIdentityReply and addDeviceNameBasedDiscoveryPair.
  2. functions for creating objects that provide access to the various areas of Bitwig Studio to the script. The name of those methods typically start with create... 3. functions for printing to the Control Surface Console, which can be opened from the View menu of Bitwig Studio. 4. functions for determining the name of the host application, API version, the host operating system and such.

The first group of methods should be called on the global scope of the script. The function in the second and third group are typically called from the init method of the script or other handler functions. The last group is probably only required in rare cases and can be called any time.

Since
API version 1

Member Function Documentation

◆ addDatagramPacketObserver()

boolean addDatagramPacketObserver ( String  name,
int  port,
DataReceivedCallback  callback 
)

Adds an observer for incoming UDP (User Datagram Protocol) packets on the selected port.

Parameters
namea meaningful name that describes the purpose of this observer.
portthe port that should be used
callbackthe callback function that gets called when data arrives. The function receives a single parameter that contains the data byte array.
Returns
{@true} if was possible to bind the port, false otherwise
Since
API version 1

◆ addDeviceNameBasedDiscoveryPair()

void addDeviceNameBasedDiscoveryPair ( String[]  inputs,
String[]  outputs 
)

Registers patterns which are used to automatically detect hardware devices that can be used with the script.

When the user clicks on the detect button in the Bitwig Studio controller preferences dialog, Bitwig Studio searches for connected controller hardware by comparing the parameters passed into this function are compared with the port names of the available MIDI drivers. Found controller scripts are automatically added with their input/output ports configured.

Calling this function is optional, but can also be called multiple times in the global script scope in order to support alternative driver names.

Parameters
inputsthe array of strings used to detect MIDI input ports, must not be null.
outputsthe array of strings used to detect MIDI output ports, must not be null.
Since
API version 1

◆ connectToRemoteHost()

void connectToRemoteHost ( String  host,
int  port,
ConnectionEstablishedCallback  callback 
)

Connects to a remote TCP (Transmission Control Protocol) socket.

Parameters
hostthe host name or IP address to connect to.
portthe port to connect to
callbackthe callback function that gets called when the connection gets established. A single RemoteConnection parameter is passed into the callback function.
Since
API version 1

◆ createAbsoluteHardwareControlAdjustmentTarget()

AbsoluteHardwarControlBindable createAbsoluteHardwareControlAdjustmentTarget ( DoubleConsumer  adjustmentConsumer)

Creates a AbsoluteHardwarControlBindable that can be used to adjust some value in an arbitrary way.

Parameters
adjustmentConsumerA consumer that will receive the absolute adjustment amount when bound to an AbsoluteHardwareControl.
Since
API version 10

◆ createAction() [1/2]

HardwareActionBindable createAction ( DoubleConsumer  actionPressureConsumer,
Supplier< String >  descriptionProvider 
)

Creates a HardwareActionBindable that can be bound to some HardwareAction (such as a button press) and when that action occurs the supplied Runnable will be run

Parameters
actionPressureConsumerConsumer that will be notified of the pressure of the action
descriptionProviderProvider that can provide a description of what the runnable does (used for showing onscreen feedback or help to the user).
Since
API version 10

◆ createAction() [2/2]

HardwareActionBindable createAction ( Runnable  runnable,
Supplier< String >  descriptionProvider 
)

Creates a HardwareActionBindable that can be bound to some HardwareAction (such as a button press) and when that action occurs the supplied Runnable will be run.

Parameters
runnableThe runnable to be run
descriptionProviderProvider that can provide a description of what the runnable does (used for showing onscreen feedback or help to the user).
Since
API version 10

◆ createActiveDeviceMatcher()

DeviceMatcher createActiveDeviceMatcher ( )

Creates a DeviceMatcher that will only match devices that are currently active.

Since
API version 12

◆ createAndDeviceMatcher()

DeviceMatcher createAndDeviceMatcher ( DeviceMatcher...  deviceMatchers)

Creates a DeviceMatcher that matches a device if all of the supplied matchers match the device.

Since
API version 12

◆ createApplication()

Application createApplication ( )

Returns an object that provides access to general application functionality, including global view settings, the list of open projects, and other global settings that are not related to a certain document.

Returns
an application object.
Since
API version 1

◆ createApplicationSection()

Application createApplicationSection ( )
Deprecated:
Use createApplication() instead.
Since
API version 1

◆ createArranger() [1/2]

Arranger createArranger ( )

Returns an object which provides access to the Arranger panel of Bitwig Studio. Calling this function is equal to createArranger(-1).

Returns
an arranger object
See also
createArranger(int)
Since
API version 1

◆ createArranger() [2/2]

Arranger createArranger ( final int  window)

Returns an object which provides access to the Arranger panel inside the specified window.

Parameters
windowthe index of the window where the arranger panel is shown, or -1 in case the first arranger panel found on any window should be taken
Returns
an arranger object
Since
API version 1

◆ createArrangerCursorClip()

Clip createArrangerCursorClip ( final int  gridWidth,
final int  gridHeight 
)

Returns a clip object that represents the cursor of the arranger clip selection. The gridWidth and gridHeight parameters specify the grid dimensions used to access the note content of the clip.

Parameters
gridWidththe number of steps spanned by one page of the note content grid.
gridHeightthe number of keys spanned by one page of the note content grid.
Returns
an object representing the currently selected cursor clip
Since
API version 1

◆ createArrangerCursorTrack()

CursorTrack createArrangerCursorTrack ( final int  numSends,
final int  numScenes 
)

Returns an object that represents the cursor item of the arranger track selection.

Parameters
numSendsthe number of sends for bank-wise navigation of the sends that are associated with the track selection
numScenesthe number of scenes for bank-wise navigation of the clip launcher slots that are associated with the track selection
Returns
an object representing the currently selected arranger track (in the future also multiple tracks)
Since
API version 1
Deprecated:
Use createCursorTrack(int, int) instead.

◆ createArrangerSection()

Arranger createArrangerSection ( final int  screenIndex)
Deprecated:
Use createArranger(int) instead.
Since
API version 1

◆ createAudioEffectMatcher()

DeviceMatcher createAudioEffectMatcher ( )

Creates a DeviceMatcher that will match any audio effect.

Since
API version 12

◆ createBeatTimeFormatter()

BeatTimeFormatter createBeatTimeFormatter ( final String  separator,
final int  barsLen,
final int  beatsLen,
final int  subdivisionLen,
final int  ticksLen 
)

Creates a BeatTimeFormatter that can be used to format beat times.

Parameters
separatorthe character used to separate the segments of the formatted beat time, typically ":", "." or "-"
barsLenthe number of digits reserved for bars
beatsLenthe number of digits reserved for beats
subdivisionLenthe number of digits reserved for beat subdivisions
ticksLenthe number of digits reserved for ticks
Since
API version 2

◆ createBitwigDeviceMatcher()

DeviceMatcher createBitwigDeviceMatcher ( UUID  id)

Creates a DeviceMatcher that will match any Bitwig native device with the supplied id.

Since
API version 12

◆ createCallbackAction()

default HardwareActionBindable createCallbackAction ( final Runnable  runnable,
final Supplier< String >  descriptionProvider 
)

Creates a HardwareActionBindable that can be bound to some HardwareAction (such as a button press) and when that action occurs the supplied Runnable will be run.

This is exactly the same as createAction(Runnable, Supplier) but does not use parameter overloading so can be used from non type safe languages like JavaScript.

Parameters
runnableThe runnable to be run
descriptionProviderProvider that can provide a description of what the runnable does (used for showing onscreen feedback or help to the user).
Since
API version 18

◆ createCursorClip()

Clip createCursorClip ( final int  gridWidth,
final int  gridHeight 
)

◆ createCursorClipSection()

Clip createCursorClipSection ( final int  gridWidth,
final int  gridHeight 
)
Deprecated:
Use createCursorClip(int, int) instead.
Since
API version 1

◆ createCursorDevice()

CursorDevice createCursorDevice ( )
Deprecated:
Use createEditorCursorDevice() instead.
Since
API version 1

◆ createCursorDeviceSection()

CursorDevice createCursorDeviceSection ( final int  numControllers)
Deprecated:
Use createEditorCursorDevice() instead.
Since
API version 1

◆ createCursorTrack() [1/3]

CursorTrack createCursorTrack ( final int  numSends,
final int  numScenes 
)
Since
API version 1

◆ createCursorTrack() [2/3]

CursorTrack createCursorTrack ( final String  id,
String  name,
final int  numSends,
final int  numScenes,
boolean  shouldFollowSelection 
)

Returns an object that represents a named cursor track, that is independent from the arranger or mixer track selection in the user interface of Bitwig Studio.

Parameters
namethe name of the track cursor
numSendsthe number of sends for bank-wise navigation of the sends that are associated with the track selection
numScenesthe number of scenes for bank-wise navigation of the clip launcher slots that are associated with the track selection
Returns
an object representing the currently selected arranger track (in the future also multiple tracks).
Since
API version 1

◆ createCursorTrack() [3/3]

CursorTrack createCursorTrack ( final String  name,
final int  numSends,
final int  numScenes 
)

Returns an object that represents a named cursor track, that is independent from the arranger or mixer track selection in the user interface of Bitwig Studio.

Parameters
namethe name of the track cursor
numSendsthe number of sends for bank-wise navigation of the sends that are associated with the track selection
numScenesthe number of scenes for bank-wise navigation of the clip launcher slots that are associated with the track selection
Returns
an object representing the currently selected arranger track (in the future also multiple tracks).
Since
API version 1
Deprecated:
use createCursorTrack(String, String, int, int, boolean) instead.

◆ createCursorTrackSection()

CursorTrack createCursorTrackSection ( final int  numSends,
final int  numScenes 
)
Deprecated:
Use createArrangerCursorTrack instead.
Since
API version 1

◆ createDetailEditor() [1/2]

DetailEditor createDetailEditor ( )

Returns an object which provides access to the DetailEditor panel of Bitwig Studio. Calling this function is equal to createDetailEditor(-1).

Returns
a detail editor object
See also
createDetailEditor(int)
Since
API version 14

◆ createDetailEditor() [2/2]

DetailEditor createDetailEditor ( final int  window)

Returns an object which provides access to the DetailEditor panel inside the specified window.

Parameters
windowthe index of the window where the detail editor panel is shown, or -1 in case the first detail editor panel found on any window should be taken
Returns
a detail editor object
Since
API version 14

◆ createEditorCursorDevice() [1/2]

CursorDevice createEditorCursorDevice ( )

Returns an object that represents the cursor device in devices selections made by the user in Bitwig Studio. Calling this method is equal to the following code:

var cursorTrack = createArrangerCursorTrack(numSends, numScenes);
var cursorDevice = cursorTrack.createCursorDevice();

To create a custom device selection that is not connected to the main device selection in the user interface, call cursorTrack.createCursorDevice(String name).

Returns
an object representing the currently selected device.
See also
Track::createCursorDevice()
Track::createCursorDevice(String)
createEditorCursorDevice(int numSends)
Since
API version 1
Deprecated:

◆ createEditorCursorDevice() [2/2]

CursorDevice createEditorCursorDevice ( int  numSends)

Returns an object that represents the cursor device in devices selections made by the user in Bitwig Studio. Calling this method is equal to the following code:

var cursorTrack = createArrangerCursorTrack(numSends, numScenes);
var cursorDevice = cursorTrack.createCursorDevice();

To create a custom device selection that is not connected to the main device selection in the user interface, call cursorTrack.createCursorDevice(String name).

Parameters
numSendsthe number of sends that are simultaneously accessible in nested channels.
Returns
an object representing the currently selected device.
Deprecated:
Use cursorTrack.createCursorDevice().
See also
Track::createCursorDevice()
Track::createCursorDevice(String)
Since
API version 1

◆ createEffectTrackBank() [1/2]

TrackBank createEffectTrackBank ( final int  numTracks,
final int  numScenes 
)

Returns a track bank with the given number of effect tracks and scenes. Only effect tracks are considered. For more information about track banks and the bank pattern in general, see the documentation for createTrackBank.

Parameters
numTracksthe number of tracks spanned by the track bank
numScenesthe number of scenes spanned by the track bank
Returns
an object for bank-wise navigation of tracks, sends and scenes
See also
Track::createEffectTrackBank
createTrackBank
createMainTrackBank
Since
API version 1

◆ createEffectTrackBank() [2/2]

TrackBank createEffectTrackBank ( final int  numTracks,
final int  numSends,
final int  numScenes 
)

Returns a track bank with the given number of effect tracks, sends and scenes. Only effect tracks are considered. For more information about track banks and the bank pattern in general, see the documentation for createTrackBank.

Parameters
numTracksthe number of tracks spanned by the track bank
numSendsthe number of sends spanned by the track bank
numScenesthe number of scenes spanned by the track bank
Returns
an object for bank-wise navigation of tracks, sends and scenes
See also
Track::createEffectTrackBank
createTrackBank
createMainTrackBank
Since
API version 18

◆ createEffectTrackBankSection()

TrackBank createEffectTrackBankSection ( final int  numTracks,
final int  numScenes 
)
Deprecated:
Use createEffectTrackBank(int, int) instead.
Since
API version 1

◆ createFirstDeviceInChainMatcher()

DeviceMatcher createFirstDeviceInChainMatcher ( )

Creates a DeviceMatcher that will only match devices if it is the last device in the chain.

Since
API version 12

◆ createGroove()

Groove createGroove ( )

Returns an object for controlling and monitoring the Groove section in Bitwig Studio. This function should be called once during initialization of the script if groove control is desired.

Returns
an object that represents the Groove section in Bitwig Studio.
Since
API version 1

◆ createGrooveSection()

Groove createGrooveSection ( )
Deprecated:
Use createGroove() instead.
Since
API version 1

◆ createHardwareSurface()

HardwareSurface createHardwareSurface ( )

Creates a HardwareSurface that can contain hardware controls.

Since
API version 10

◆ createInstrumentMatcher()

DeviceMatcher createInstrumentMatcher ( )

Creates a DeviceMatcher that will match any instrument.

Since
API version 12

◆ createLastDeviceInChainMatcher()

DeviceMatcher createLastDeviceInChainMatcher ( )

Creates a DeviceMatcher that will only match devices if it is the last device in the chain.

Since
API version 12

◆ createLauncherCursorClip()

Clip createLauncherCursorClip ( final int  gridWidth,
final int  gridHeight 
)

Returns a clip object that represents the cursor of the launcher clip selection. The gridWidth and gridHeight parameters specify the grid dimensions used to access the note content of the clip.

Parameters
gridWidththe number of steps spanned by one page of the note content grid.
gridHeightthe number of keys spanned by one page of the note content grid.
Returns
an object representing the currently selected cursor clip
Since
API version 1

◆ createMainTrackBank()

TrackBank createMainTrackBank ( final int  numTracks,
final int  numSends,
final int  numScenes 
)

Returns a track bank with the given number of tracks, sends and scenes. Only audio tracks, instrument tracks and hybrid tracks are considered. For more information about track banks and the bank pattern in general, see the documentation for createTrackBank.

Parameters
numTracksthe number of tracks spanned by the track bank
numSendsthe number of sends spanned by the track bank
numScenesthe number of scenes spanned by the track bank
Returns
an object for bank-wise navigation of tracks, sends and scenes
See also
Track::createMainTrackBank
createTrackBank
createEffectTrackBank
Since
API version 1

◆ createMainTrackBankSection()

TrackBank createMainTrackBankSection ( final int  numTracks,
final int  numSends,
final int  numScenes 
)
Deprecated:
Use createMainTrackBank(int, int, int) instead.
Since
API version 1

◆ createMasterTrack()

MasterTrack createMasterTrack ( final int  numScenes)

Returns an object that represents the master track of the document.

Parameters
numScenesthe number of scenes for bank-wise navigation of the master tracks clip launcher slots.
Returns
an object representing the master track.
See also
Track::createMasterTrack
Since
API version 1

◆ createMasterTrackSection()

Track createMasterTrackSection ( final int  numScenes)
Deprecated:
Use createMasterTrack(int) instead.
Since
API version 1

◆ createMixer() [1/4]

Mixer createMixer ( )

Returns an object which provides access to the Mixer panel of Bitwig Studio. Calling this function is equal to createMixer(-1, null).

Returns
a Mixer object
Since
API version 1

◆ createMixer() [2/4]

Mixer createMixer ( final int  window)

Returns an object which provides access to the Mixer panel inside the specified window. Calling this function is equal to createMixer(window, null).

Parameters
windowthe index of the window where the mixer panel is shown, or -1 in case the first mixer panel found on any window should be taken
Returns
a Mixer object
Since
API version 1

◆ createMixer() [3/4]

Mixer createMixer ( final String  panelLayout)

Returns an object which provides access to the Mixer panel that belongs to the specified panel layout. Calling this function is equal to createMixer(-1, panelLayout).

Parameters
panelLayoutthe name of the panel layout that contains the mixer panel, or null in case the selected panel layout in Bitwig Studio should be followed. Empty strings or invalid names are treated the same way as null. To receive the list of available panel layouts see Application#addPanelLayoutObserver.
Returns
a Mixer object
Since
API version 1

◆ createMixer() [4/4]

Mixer createMixer ( final String  panelLayout,
final int  window 
)

Returns an object which provides access to the Mixer panel that matches the specified parameters.

Parameters
panelLayoutthe name of the panel layout that contains the mixer panel, or null in case the selected panel layout in Bitwig Studio should be followed. Empty strings or invalid names are treated the same way as null. To receive the list of available panel layouts see Application#addPanelLayoutObserver.
windowthe index of the window where the mixer panel is shown, or -1 in case the first mixer panel found on any window should be taken
Returns
a Mixer object
Since
API version 1

◆ createMixerSection()

Mixer createMixerSection ( final String  perspective,
final int  screenIndex 
)
Deprecated:
Use createMixer(String, int) instead.
Since
API version 1

◆ createNotDeviceMatcher()

DeviceMatcher createNotDeviceMatcher ( DeviceMatcher  deviceMatcher)

Creates a DeviceMatcher that matches a device if the supplied matcher does not match the device.

Since
API version 12

◆ createNoteEffectMatcher()

DeviceMatcher createNoteEffectMatcher ( )

Creates a DeviceMatcher that will match any note effect.

Since
API version 12

◆ createOrAbsoluteHardwareValueMatcher()

AbsoluteHardwareValueMatcher createOrAbsoluteHardwareValueMatcher ( AbsoluteHardwareValueMatcher  matcher1,
AbsoluteHardwareValueMatcher  matcher2 
)

Creates a AbsoluteHardwareValueMatcher that is matched by either of the 2 supplied action matchers.

Since
API version 10

◆ createOrDeviceMatcher()

DeviceMatcher createOrDeviceMatcher ( DeviceMatcher...  deviceMatchers)

Creates a DeviceMatcher that matches a device if any of the supplied matchers match the device.

Since
API version 12

◆ createOrHardwareActionMatcher()

HardwareActionMatcher createOrHardwareActionMatcher ( HardwareActionMatcher  matcher1,
HardwareActionMatcher  matcher2 
)

Creates a HardwareActionMatcher that is matched by either of the 2 supplied action matchers.

Since
API version 10

◆ createOrRelativeHardwareValueMatcher()

RelativeHardwareValueMatcher createOrRelativeHardwareValueMatcher ( RelativeHardwareValueMatcher  matcher1,
RelativeHardwareValueMatcher  matcher2 
)

Creates a RelativeHardwareValueMatcher that is matched by either of the 2 supplied action matchers.

Since
API version 10

◆ createPopupBrowser()

PopupBrowser createPopupBrowser ( )

Creates a PopupBrowser that represents the pop-up browser in Bitwig Studio.

Since
API version 2

◆ createPressureCallbackAction()

default HardwareActionBindable createPressureCallbackAction ( final DoubleConsumer  actionPressureConsumer,
final Supplier< String >  descriptionProvider 
)

Creates a HardwareActionBindable that can be bound to some HardwareAction (such as a button press) and when that action occurs the supplied Runnable will be run.

This is exactly the same as createAction(DoubleConsumer, Supplier) but does not use parameter overloading so can be used from non type safe languages like JavaScript.

Parameters
actionPressureConsumerConsumer that will be notified of the pressure of the action
descriptionProviderProvider that can provide a description of what the runnable does (used for showing onscreen feedback or help to the user).
Since
API version 18

◆ createRelativeHardwareControlAdjustmentTarget()

RelativeHardwarControlBindable createRelativeHardwareControlAdjustmentTarget ( DoubleConsumer  adjustmentConsumer)

Creates a RelativeHardwarControlBindable that can be used to adjust some value in an arbitrary way.

Parameters
adjustmentConsumerA consumer that will receive the relative adjustment amount when bound to a RelativeHardwareControl.
Since
API version 10

◆ createRelativeHardwareControlStepTarget()

RelativeHardwarControlBindable createRelativeHardwareControlStepTarget ( HardwareActionBindable  stepForwardsAction,
HardwareActionBindable  stepBackwardsAction 
)

Creates a RelativeHardwarControlBindable that can be used to step forwards or backwards when a RelativeHardwareControl is adjusted. A step is defined by the RelativeHardwareControl#setStepSize(double).

Parameters
stepForwardsActionThe action that should happen when stepping forwards
stepBackwardsActionThe action that should happen when stepping backwards
Since
API version 10

◆ createRemoteConnection()

RemoteSocket createRemoteConnection ( String  name,
int  defaultPort 
)

Opens a TCP (Transmission Control Protocol) host socket for allowing network connections from other hardware and software.

Parameters
namea meaningful name that describes the purpose of this connection.
defaultPortthe port that should be used for the connection. If the port is already in use, then another port will be used. Check RemoteSocket#getPort() on the returned object to be sure.
Returns
the object that represents the socket
Since
API version 1

◆ createSceneBank()

SceneBank createSceneBank ( final int  numScenes)

Returns a scene bank with the given number of scenes.

A scene bank can be seen as a fixed-size window onto the list of scenes in the current document, that can be scrolled in order to access different parts of the scene list. For example a scene bank configured for 8 scenes can show scene 1-8, 2-9, 3-10 and so on.

The idea behind the bank pattern is that hardware typically is equipped with a fixed amount of channel strips or controls, for example consider a mixing console with 8 channels, but Bitwig Studio documents contain a dynamic list of scenes, most likely more scenes than the hardware can control simultaneously. The scene bank returned by this function provides a convenient interface for controlling which scenes are currently shown on the hardware.

Parameters
numScenesthe number of scenes spanned by the track bank
Returns
an object for bank-wise navigation of scenes
Since
API version 1

◆ createTrackBank() [1/2]

TrackBank createTrackBank ( final int  numTracks,
final int  numSends,
final int  numScenes 
)

Returns a track bank with the given number of tracks, sends and scenes.

A track bank can be seen as a fixed-size window onto the list of tracks in the current document including their sends and scenes, that can be scrolled in order to access different parts of the track list. For example a track bank configured for 8 tracks can show track 1-8, 2-9, 3-10 and so on.

The idea behind the bank pattern is that hardware typically is equipped with a fixed amount of channel strips or controls, for example consider a mixing console with 8 channels, but Bitwig Studio documents contain a dynamic list of tracks, most likely more tracks than the hardware can control simultaneously. The track bank returned by this function provides a convenient interface for controlling which tracks are currently shown on the hardware.

Creating a track bank using this method will consider all tracks in the document, including effect tracks and the master track. Use createMainTrackBank or createEffectTrackBank in case you are only interested in tracks of a certain kind.

Parameters
numTracksthe number of tracks spanned by the track bank
numSendsthe number of sends spanned by the track bank
numScenesthe number of scenes spanned by the track bank
Returns
an object for bank-wise navigation of tracks, sends and scenes
See also
Track::createTrackBank
createMainTrackBank
createEffectTrackBank
Since
API version 1

◆ createTrackBank() [2/2]

TrackBank createTrackBank ( final int  numTracks,
final int  numSends,
final int  numScenes,
final boolean  hasFlatTrackList 
)

Returns a track bank with the given number of child tracks, sends and scenes.

A track bank can be seen as a fixed-size window onto the list of tracks in the connected track group including their sends and scenes, that can be scrolled in order to access different parts of the track list. For example a track bank configured for 8 tracks can show track 1-8, 2-9, 3-10 and so on.

The idea behind the bank pattern is that hardware typically is equipped with a fixed amount of channel strips or controls, for example consider a mixing console with 8 channels, but Bitwig Studio documents contain a dynamic list of tracks, most likely more tracks than the hardware can control simultaneously. The track bank returned by this function provides a convenient interface for controlling which tracks are currently shown on the hardware.

Creating a track bank using this method will consider all tracks in the document, including effect tracks and the master track. Use createMainTrackBank or createEffectTrackBank in case you are only interested in tracks of a certain kind.

Parameters
numTracksthe number of child tracks spanned by the track bank
numSendsthe number of sends spanned by the track bank
numScenesthe number of scenes spanned by the track bank
hasFlatTrackListspecifies whether the track bank should operate on a flat list of all nested child tracks or only on the direct child tracks of the connected group track.
Returns
an object for bank-wise navigation of tracks, sends and scenes
See also
createMainTrackBank
createEffectTrackBank
Since
API version 1

◆ createTrackBankSection()

TrackBank createTrackBankSection ( final int  numTracks,
final int  numSends,
final int  numScenes 
)
Deprecated:
Use createTrackBank(int, int, int) instead.
Since
API version 1

◆ createTransport()

Transport createTransport ( )

Returns an object for controlling and monitoring the elements of the Transport section in Bitwig Studio. This function should be called once during initialization of the script if transport access is desired.

Returns
an object that represents the Transport section in Bitwig Studio.
Since
API version 1

◆ createTransportSection()

Transport createTransportSection ( )
Deprecated:
Use createTransport instead.
Since
API version 1

◆ createUserControls()

UserControlBank createUserControls ( final int  numControllers)

Returns an object that is used to define a bank of custom user controls. These controls are available to the user for free controller assignments and are typically used when bank-wise navigation is inconvenient.

Parameters
numControllersthe number of controls that are available for free assignments
Returns
An object that represents a set of custom user controls.
Since
API version 1

◆ createUserControlsSection()

UserControlBank createUserControlsSection ( final int  numControllers)
Deprecated:
Use createUserControls(int) instead.
Since
API version 1

◆ createVST2DeviceMatcher()

DeviceMatcher createVST2DeviceMatcher ( int  id)

Creates a DeviceMatcher that will match any VST2 plug-in with the supplied id.

Since
API version 12

◆ createVST3DeviceMatcher()

DeviceMatcher createVST3DeviceMatcher ( String  id)

Creates a DeviceMatcher that will match any VST3 plug-in with the supplied id.

Since
API version 12

◆ defaultBeatTimeFormatter()

BeatTimeFormatter defaultBeatTimeFormatter ( )

BeatTimeFormatter used to format beat times by default. This will be used to format beat times when asking for a beat time in string format without providing any formatting options. For example by calling BeatTimeStringValue#get().

Since
API version 2

◆ defineController() [1/2]

void defineController ( String  vendor,
String  name,
String  version,
String  uuid 
)

◆ defineController() [2/2]

void defineController ( String  vendor,
String  name,
String  version,
String  uuid,
String  author 
)

Registers a controller script with the given parameters. This function must be called once at the global scope of the script.

Parameters
vendorthe name of the hardware vendor. Must not be null.
namethe name of the controller script as listed in the user interface of Bitwig Studio. Must not be null.
versionthe version of the controller script. Must not be null.
uuida universal unique identifier (UUID) string that is used to distinguish one script from another, for example 550e8400-e29b-11d4-a716-446655440000. Must not be null. For generating random UUID strings several free web tools are available.
authorthe name of the script author
Since
API version 1

◆ defineMidiPorts()

void defineMidiPorts ( int  numInports,
int  numOutports 
)

Defines the number of MIDI ports for input and output that the device uses. This method should be called once in the global scope if the script is supposed to exchange MIDI messages with the device, or if the script adds entries to the MIDI input/output choosers in Bitwig Studio. After calling this method the individual port objects can be accessed using getMidiInPort(int index) and getMidiInPort(int index).

Parameters
numInportsthe number of input ports
numOutportsthe number of output ports
Since
API version 1

◆ defineSysexDiscovery()

void defineSysexDiscovery ( String  request,
String  reply 
)
Deprecated:
Use defineSysexIdentityReply(String) instead.
Since
API version 1

◆ defineSysexIdentityReply()

void defineSysexIdentityReply ( String  reply)

Registers the Identity Reply Universal SysEx message (if any) that the MIDI device sends after receiving the Identity Request Universal SysEx message (F0 7E 7F 06 01 F7), as defined in the MIDI standard.

This function may be called at the global scope of the script, but is optional. Please note that this function is only applicable to scripts with one MIDI input and one MIDI output. Also note that not all MIDI hardware supports SysEx identity messages.

Parameters
replythe Identity Reply Universal SysEx message. Must not be null
Deprecated:
Since
API version 1

◆ deleteObjects() [1/2]

void deleteObjects ( DeleteableObject...  objects)

It will delete multiple object within one undo step.

Since
API version 10

◆ deleteObjects() [2/2]

void deleteObjects ( String  undoName,
DeleteableObject...  objects 
)

It will delete multiple object within one undo step.

Since
API version 10

◆ errorln()

void errorln ( String  s)

Prints the given string in the control surface console window using a text style that highlights the string as error. The console window can be opened in the view menu of Bitwig Studio.

Parameters
sthe error string to be printed
Since
API version 1

◆ getDocumentState()

DocumentState getDocumentState ( )

Creates a document state object that can be used to insert settings into the Studio I/O Panel in Bitwig Studio.

Returns
an object that provides access to custom document settings
Since
API version 1

◆ getMidiInPort()

MidiIn getMidiInPort ( int  index)

Returns the MIDI input port with the given index.

Parameters
indexthe index of the MIDI input port, must be valid.
Returns
the requested MIDI input port
Since
API version 1

◆ getMidiOutPort()

MidiOut getMidiOutPort ( int  index)

Returns the MIDI output port with the given index.

Parameters
indexthe index of the MIDI output port, must be valid.
Returns
the requested MIDI output port
Since
API version 1

◆ getNotificationSettings()

NotificationSettings getNotificationSettings ( )

Returns an object that is used to configure automatic notifications. Bitwig Studio supports automatic visual feedback from controllers that shows up as popup notifications. For example when the selected track or the current device preset was changed on the controller these notifications are shown, depending on your configuration.

Returns
a configuration object used to enable/disable the various automatic notifications supported by Bitwig Studio
Since
API version 1

◆ getPreferences()

Preferences getPreferences ( )

Creates a preferences object that can be used to insert settings into the Controller Preferences panel in Bitwig Studio.

Returns
an object that provides access to custom controller preferences
Since
API version 1

◆ getProject()

Project getProject ( )

Returns an object for controlling various aspects of the currently selected project.

Since
API version 1

◆ hardwareDevice()

HardwareDevice hardwareDevice ( int  index)

Gets the HardwareDevice at the specified index. This index corresponds to the index of the HardwareDeviceMatcher specified in the ControllerExtensionDefinition#listHardwareDevices(java.util.List)

Since
API version 7

◆ load()

void load ( String  path)

Loads the script defined by the supplied path. This is only intended to be called from a controller script. It cannot be called from a Java controller extension.

◆ loadAPI()

void loadAPI ( int  version)

Loads the supplied API version into the calling script. This is only intended to be called from a controller script. It cannot be called from a Java controller extension.

◆ midiExpressions()

MidiExpressions midiExpressions ( )

An object that can be used to generate useful MIDI expression strings which can be used in MidiIn#createActionMatcher(String) and other related methods.

Since
API version 10

◆ platformIsLinux()

boolean platformIsLinux ( )

Indicates if the host platform is Linux.

Returns
true if the host platform is Linux, false otherwise.
Since
API version 1

◆ platformIsMac()

boolean platformIsMac ( )

Indicates if the host platform is Apple Mac OS X.

Returns
true if the host platform is Mac, false otherwise.
Since
API version 1

◆ platformIsWindows()

boolean platformIsWindows ( )

Indicates if the host platform is Windows.

Returns
true if the host platform is Windows, false otherwise.
Since
API version 1

◆ println()

void println ( String  s)

Prints the given string in the control surface console window. The console window can be opened in the view menu of Bitwig Studio.

Parameters
sthe string to be printed
Since
API version 1

◆ requestFlush()

void requestFlush ( )

Requests that the driver's flush method gets called.

Since
API version 2

◆ restart()

void restart ( )

Restarts this controller.

Since
API version 7

◆ scheduleTask() [1/2]

void scheduleTask ( Object  callback,
Object[]  args,
long  delay 
)

Schedules the given callback function for execution after the given delay. For timer applications call this method once initially and then from within the callback function.

Parameters
callbackthe callback function that will be called
argsthat array of arguments that gets passed into the callback function, may be null
delaythe duration after which the callback function will be called in milliseconds
Deprecated:
Since
API version 1

◆ scheduleTask() [2/2]

void scheduleTask ( Runnable  callback,
long  delay 
)

Schedules the given callback function for execution after the given delay. For timer applications call this method once initially and then from within the callback function.

Parameters
callbackthe callback function that will be called
delaythe duration after which the callback function will be called in milliseconds
Since
API version 2

◆ sendDatagramPacket()

void sendDatagramPacket ( String  host,
int  port,
byte[]  data 
)

Sends a UDP (User Datagram Protocol) packet with the given data to the specified host.

Parameters
hostthe destination host name or IP address
portthe destination port
datathe data to be send. When creating a numeric byte array in JavaScript, the byte values must be signed (in the range -128..127).
Since
API version 1

◆ setDefaultBeatTimeFormatter()

void setDefaultBeatTimeFormatter ( BeatTimeFormatter  formatter)

Sets the BeatTimeFormatter to use by default for formatting beat times.

See also
defaultBeatTimeFormatter()
Since
API version 2

◆ setShouldFailOnDeprecatedUse()

void setShouldFailOnDeprecatedUse ( boolean  value)

Sets whether the calling script should fail if it calls a deprecated method based on the API version that it requested. This is only intended to be called from a controller script. It cannot be called from a Java controller extension.

◆ shouldFailOnDeprecatedUse()

boolean shouldFailOnDeprecatedUse ( )

Determines whether the calling script should fail if it calls a deprecated method based on the API version that it requested.

◆ showPopupNotification()

void showPopupNotification ( String  text)

Shows a temporary text overlay on top of the application GUI, that will fade-out after a short interval. If the overlay is already shown, it will get updated with the given text.

Parameters
textthe text to be shown
Since
API version 1

◆ useBetaApi()

void useBetaApi ( )

Call this method to allow your script to use Beta APIs.

Beta APIs are still on development and might not be available in a future version of Bitwig Studio.

Turning this flag to true, will flag your extension as being a beta extension which might not work after updating Bitwig Studio.

Since
API version 7

The documentation for this interface was generated from the following file:
com.bitwig.extension.controller.api.ControllerHost.createArrangerCursorTrack
CursorTrack createArrangerCursorTrack(final int numSends, final int numScenes)