TDBitwig User Guide Export Testedit

---

Table of Contentsedit

---

Introductionedit

TDBitwig is a set of TouchDesigner components that enables bi-directional communication between Bitwig Studio and TouchDesigner. The TDBitwig functionality enables users to create custom audio-visual performances by integrating real-time visuals with live audio output.

With TDBitwig, TouchDesigner can control Bitwig Studio parameters, such as tempo, track properties, clip launching, and device parameters. Conversely, Bitwig Studio can also control TouchDesigner parameters for creating tightly integrated audio-visual environments.

Bitwig supports a wide array of hardware controllers for live performances and show control. TouchDesigner can now deeply connect with these devices through Bitwig. TouchDesigner is an interoperability platform that provides access to a wide array of hardware devices, APIs, the internet etc. Read more about TouchDesigner interoperability. Bitwig artists can interface with a wider range of systems through TouchDesigner. Bitwig controlling TouchDesigner can operate as an advanced show controller for live theatre, environmental experiences and music performances.

TDBitwig is a powerful tool that enables the creation of generative, immersive audio-visual performances and installations by combining the real-time audio processing capabilities of Bitwig Studio with the real-time 3D rendering capabilities of TouchDesigner. With its ability to generate audio visual effects simultaneously, TDBitwig empowers artists to craft complex and captivating experiences that seamlessly blend sound and vision.

For information about Bitwig Studio go here… (https://www.bitwig.com/)

---

Overviewedit

---

Bitwig APIedit

TDBitwig’s ability to read and control information in a Bitwig session relies entirely on the Bitwig Studio Control Surface API. The TouchDesigner controller script serves to extend the functionality of this API and achieve the full capability of the TDBitwig System.

The Control Surface API is widely used to support a variety of hardware controllers like MIDI devices, and enables users to expand the level of interactivity in their recording and performance workflows.

Much of the inspiration for the TDBitwig Controller extension comes from the well documented library of Bitwig Studio controller scripts as well as the DrivenByMoss extension collection written by Jurgen Mossgraber.

Open Sound Control (OSC)edit

The communication between TouchDesigner and Bitwig Studio relies on Open Sound Control (OSC), a message-based protocol using UDP. The use of OSC allows for communication between any number of devices on a network, and enables the TDBitwig System to send high-resolution data between separate devices running TouchDesigner and Bitwig Studio respectively.

System Designedit

The design for the TDBitwig System was largely motivated by the popular application of the Bitwig API to support hardware controllers. Similarly, the TDBitwig Component Set can be thought of as a collection of software-based controllers; each component communicates with it’s respective part of the Bitwig session and has its own set of buttons and sliders for controlling certain Bitwig parameters. What distinguishes software-based controllers from their physical counterparts is the increased ability to access and control Bitwig session information in a programmatic environment like TouchDesigner.

---

Getting Startededit

---

Installationedit

System Requirements:

• Bitwig Studio Version 5.0 +
• TouchDesigner 2022.20K +

Setupedit

1. Open TouchDesigner.
2. Locate the TDBitwigExtension.bwextension file.
   • Help Menu → Browse Samples → TDBitwig → Bitwig5 → ExtensionScripts
3. Place a copy of the file in folder.
   • /Documents/Bitwig Studio/Extensions
4. Open Bitwig Studio.
5. Setup your newly imported controller extension.
   • Open Dashboard → Settings → Controllers → + Add Controller
   • Choose Hardware Vendor : Derivative.
   • Choose Product: TouchDesigner.
   • Click Add.
6. In TouchDesigner, import the bitwigMain COMP.
   • Open the palette.
   • Click on the TDBitwig folder.
   • Drag the bitwigMain COMP into your project.
7. If you are using the system on one computer, a connection should be established at this point since the OSC ports are set to match by default. If you are working on 2 computers or wish to use different OSC port numbers, refer to the Configuring OSC section below.
8. You can verify the connection status with the “connected” channel in the bitwigMain COMP’s OP view. If properly connected the value should be 1 and you can begin using the system. If a connection is not established, refer to the Troubleshooting section below.

Configuring OSCedit

You can locate the settings to configure your OSC connection in the following areas:

• TouchDesigner:
  • Click on the bitwigMain Component in your project,
  • In the parameter window, navigate to the Setup parameter page.
• Bitwig Studio:
  • Open the Dashboard, and in the Settings Pane, scroll to the Controllers Section.
  • You should see the controller settings for the TouchDesigner controller extension.
  • Make sure the active icon for the controller is on to view the settings window.

TouchDesigner

Bitwig

To properly setup your OSC connection, make sure of the following:

• The Bitwig IP Address setting in TouchDesigner matches the IP address of the device running Bitwig
• The TouchDesigner IP Address setting in Bitwig matches the IP address of the device running TouchDesigner
• The TouchDesigner In Port number in TouchDesigner matches the TouchDesigner Port number in Bitwig
• The Bitwig Port number in TouchDesigner matches the Bitwig In Port number in Bitwig

Note:

In Bitwig, you will need to restart the controller extension every time you change the TouchDesigner IP Address or TouchDesigner Port setting since they cannot be changed at run time.

To restart the extension, de-activate and re-activate the controller by clicking the power icon in the top left of the controller window.

Troubleshootingedit

If you are experiencing any problems, the most useful tool for troubleshooting will be the Textport. Be sure to have it open while troubleshooting, as most errors will be reported there.

The most common issues with TDBitwig will involve connections. The most important connection will be the network connection between the bitwigMain Component and the TouchDesigner controller extension in Bitwig. To test this connection, use the Ping parameter belonging to the bitwigMain Component, located in the Debug parameter page. Once pressed, you should see a “ping sent” message followed by a “ping reply received” message in the Textport. If the reply message does not appear, it may indicate that your OSC network is not configured properly or your device’s firewall is blocking the connection.

The TouchDesigner controller extension in Bitwig is also equipped with a Send Ping button which will send a ping message to the specified IP and port. This functionality can serve useful for testing the connection from Bitwig to TouchDesigner.

In addition to the ping test, all of the TDBitwig Components have a Connect parameter which can be used to manually reset connections. In the bitwigMain Component it is located in the Setup page, for all others it exists in the TDBitwig page. Toggling the parameter off and on will restart a connection and may reveal useful error messages indicating the problem.

If connectivity issues persist, try closing your external text editor and any other sub-processes of TouchDesigner. For some reason, OSC ports can be associated with these sub-processes and the ports will not reopen until the applications are closed. Also, if two projects running TDBitwig are open and are using identical ports, it will cause port conflict issues.

For more verbose descriptions of lower-level activity, you can enable the following parameters in the bitwigMain COMP:

1. Log Messages: print to Textport all incoming and outgoing OSC Messages
2. Debug Messages: print to Texport information about calls to the python extension methods belonging to this Component. All TDBitwig Components come with this toggle and in most use cases will not be necessary.

Note:

There is a 3rd party application called Protokol, which provides a user-friendly OSC network checker. This may serve useful for network troubleshooting.

---

Component Conceptsedit

---

Cursorsedit

The ability of Components to navigate Bitwig and select which object they are interested in (Track, Device, Clip Slot, or Parameter Page) relies on the concept of Cursors. In Bitwig, Cursors are used to point to a particular object, and there are different ways users can decide how a cursor selects an object. Any TDBitwig Component which communicates with a non-global Bitwig object has a corresponding cursor(s) within Bitwig.

Components using Cursors:

bitwigTrack:

• CursorTrack

bitwigClipLauncher

• CursorTrack
  • CursorClip

bitwigDeviceRemotes

• CursorTrack
  • CursorDevice
    • CursorRemoteControlsPage

bitwigTrackRemotes

• CursorTrack
  • CursorRemoteControlsPage

bitwigProjectRemotes

• CursorRemoteControlsPage

bitwigNote:

• CursorTrack

One way to think about cursors is that if the object I am interested in is or belongs to a specific object, then I will use a cursor to select that object. For example, to access a specific device’s remote controls page, I will use the CursorTrack to select the track that the device belongs to, use the CursorDevice to select the device that the remotes page belongs to, then use the CursorRemoteControlsPage to select the remotes page. Note that the selection of objects via cursors will almost always begin by choosing the Track, with the exception of the bitwigProjectRemotes, because the project remotes are global.

Cursor Navigationedit

Pinning:

By default, the cursor selection will follow whichever object is currently selected in the Bitwig User Interface unless it is pinned. The pinning functionality applies only to CursorTracks and CursorDevices. If a Cursor Object is un-pinned, you can change the selection of the Cursor by clicking on the desired object in the Bitwig UI.

Example:

Let’s say a CursorTrack is currently pointing to track “Instrument 2” and is un-pinned. If I click on “Instrument 1” in Bitwig Studio, my CursorTrack will follow the UI selection, and now points to “Instrument 1”.

If the Cursor is pinned, it’s selection will not change even if a different object is selected in the Bitwig UI.

Going back to our example:

If a CursorTrack is currently pointing to track “Instrument 2” and is pinned; if I click on “Instrument 1” in Bitwig Studio, my CursorTrack selection will remain, and still point to “Instrument 2”.

The use of pinning and un-pinning becomes a convenient way to select objects in TDBitwig by interacting with the Bitwig UI. The Component parameters “Pin Track” and “Pin Device” allow users to pin and unpin Cursors within TouchDesigner.

Scrolling:

In addition to the pinning functionality, you can also use the scroll feature of Cursors to change their selection. The idea of scrolling is much more straightforward; cursors provide the ability to select the next or previous object based on the order in the Bitwig UI.

In TDBitwig, this functionality is realized for CursorTracks with the “Prev Track” and “Next Track” parameters, or in the case of CursorDevices, the “Prev Device” and “Next Device” parameters. Pressing these will change the current cursor selection to either the previous or next object.

Observersedit

Observers (aka listeners) define which attributes belonging to a Bitwig object we are interested in. Each TDBitwig Component has a set of observers associated with it, which defines the attribute scope it has access to and can control.

If an observer is active, any update to the attribute associated with that observer in Bitwig will trigger a callback that sends an OSC message to TouchDesigner informing the updated value. In the TDBitwig system, Component parameters are “linked” to observers, such that if an OSC message containing an updated value is received, it will change the parameter value to match the updated value from Bitwig.

Conversely, when an update to a parameter occurs in TouchDesigner, a callback will send an OSC message to Bitwig containing the updated observed value, and the controller extension will update the Bitwig attribute associated with the observer accordingly. The use of observers allows for bi-directional control of parameters/attributes between the 2 applications in this way.

Limitationsedit

Because Bitwig Observers cannot be added after controller initialization, we are limited to a finite number of objects we are observing as well as the properties of the object we are observing. This limitation is most relevant to the amount of Cursor Objects made available to the TDBitwig system, particularly the amount of CursorTracks and Project CursorRemoteControlPages.

The system is designed such that any Component with Track Selection functionality has a one-to-one relationship with a CursorTrack. Therefore, the total number of these TDBitwig Components in a project will be limited to the number of CursorTracks available. The same relationship exists between the bitwigProjectRemotes COMP and the Project CursorRemoteControlsPage.

Currently the system supports:

256 CursorTracks:

i.e. the total number of bitwigTrack, bitwigClipLauncher, bitwigDeviceRemotes, bitwigTrackRemotes, and bitwigNote COMPs may not exceed 256

64 Project CursorRemoteControlsPages:

i.e. the number of bitwigProjectRemotes COMPs may not exceed 64

Cursor Mappingedit

The correspondence between TDBitwig Object Components and their respective Bitwig Cursor is established by a mapping of the Component to the index of the Cursor it is listening to. When a Component requiring a Cursor is created, it will request a cursor index from the bitwigMain COMP; the bitwigMain COMP will find the next available Cursor and assign its index to the Object Component which made the request. This mapping allows the TDBitwig system to route incoming and outgoing information between TDBitwig Components and the Bitwig Objects they are communicating with.

The Bitwig COMPs which use a Bitwig Cursor will have a Listener Index parameter representing the cursor index they have been assigned. This index will also exist as a header for the Out CHOP channels within the Component. Once a Component has been created and successfully assigned a cursor index, its mapping will never change as long as that Component Object exists. The only instances in which cursor mappings will change is when a new Component is created or a Component is deleted.

---

Component Setedit

---

System Componentsedit

---

bitwigMainedit

Description:

The bitwigMain COMP serves as the central communication hub for the TDBitwig system, and is responsible for relaying most of the information between the Bitwig session and TDBitwig Object Components in a project. This COMP is necessary for every connection to a Bitwig Studio Session; for most use cases only one is required but there are real situations which may require more.

The interaction with the Component will mainly pertain to connection configuration, users can locate the configuration settings in the Setup Parameter Page. A detailed explanation of the configuring process is provided in the above Configuring OSC section. Once connected, all the TDBitwig Object Components referencing this COMP will be enabled for use.

Refer to the bitwigMain documentation page to find a detailed description of this Component and its parameters.

tdBitwigPackageedit

Description:

The tdBitwigPackage COMP allows users to update their TDBitwig Components in a project to the most recent released version. To bring your TDBitwig project up-to-date, locate this Component in the TouchDesigner Palette, within the TDBitwig folder. Drag this Component into your project, and press the Update parameter located in the About parameter page. Once pressed, all the existing TDBitwig Components existing in the current project will be updated to the version associated with the tdBitwigPackage COMP.

---

Object Componentsedit

---

Common Featuresedit

The TDBitwig Object Components rely on a common framework, and therefore will share a set of common features.

Chop Output:

The first (and sometimes only) output of the Object Components will be a CHOP Out. The CHOP will contain numeric data corresponding to the properties that the Component is listening to. Each property value will have its own channel, and the channel name will contain the type of object and name of the property that the value belongs to. Some Components have multiple outputs; these will be described in their respective sections.

TDBitwig Parameter Page:

This parameter page will contain information and functionality pertaining to the TDBitwig system.

• TDBitwig Comp : A reference to the Bitwig Main COMP
• Connect : A toggle to manually enable or disable listeners associated with this COMP.
• Debug Messages : Print information about extension method calls for the Component
• Timeslice OSC Chop : TODO
• Clear Chop : Clear the channels in the OSC In CHOP
• Strip CHOP Prefix Segments : Strip off the given number of address segments in the output CHOP channel names

About Page:

This parameter page will contain information and functionality pertaining to version and updates.

• Help : Opens the Component documentation page
• Version : The TDBitwig version that the Component is updated to
• .tox Save Build : The TouchDesigner build version that the Component was saved in
• Update : If the tdBitwigPackage COMP is present in the TouchDesigner project, pressing pulse will update the Component to the newest version

Track/Device Navigation:

Because many of the objects in Bitwig are associated with a track, users will commonly begin object navigation by selecting a track object, followed by the object belonging to the track (device, clip, remoteControlPage, etc.). For an in-depth explanation of object selection, read the Cursors section above.

bitwigSongedit

Description:

The bitwigSong COMP acts as a bi-directional interface for Bitwig’s global transport; including timing, playback, and recording functionality. It also stores information about scenes and cues, and supports control for their playback.

Extra Outputs:

• beatCHOP : simulates the Beat CHOP operator
• cueInfo : a table of cueMarker info
• sceneInfo : a table of scenes
• currentCueInfo : provides info about the nearest cue marker left of the playhead

Promoted Methods:

TODO

Callbacks:

• onCuePassed(info) :

  The playhead location is on the cue marker’s position

  info : dictionary containing cue info

  index : index of cue

  name : name of cue

• onCueChanged(info) :

  The nearest cue marker left of the playhead has changed

  info : dictionary containing cue info

  index : index of cue

  name : name of cue

• onPlay(info) :

  Transport starts playback

• onStop(info) :

  Transport stops playback

• onLoopStartPassed :

  playhead location is on the loop start position

---

bitwigTrackedit

Description:

The bitwigTrack COMP acts as an interface for accessing and controlling the attributes of a given Bitwig Track object. It allows users to choose the specific track they are interested in and perform any actions accordingly.

---

bitwigClipLauncheredit

Description:

The bitwigClipLauncher COMP serves as an interface for controlling clip playback and clip attributes in Bitwig’s clip launcher context. Users begin by choosing which track they are interested in; from there they can access the clip slots associated with that track, and subsequently decide to perform actions or read/modify the properties of a given launcher clip.

Extra Outputs:

• clipInfo : a table of clip slot information for the given track
• clipStatusInfo : provides the current playing clip and current queued for playback clip

Promoted Methods:

TODO

Callbacks:

• onPlayingClipChanged(info)

  The current playing clip has changed

  info : dictionary containing clip info

  index : index of clip slot

  name : name of clip slot

• onQueuedClipChanged(info)

  The current queued for playback clip has changed

  info : dictionary containing clip info

  index : index of clip slot

  name : name of clip slot

---

bitwigDeviceRemotesedit

Description:

The bitwigDeviceRemotes COMP serves as an interface for accessing and controlling Device Remote Controls in Bitwig. Navigation to controls begins by selecting a track, followed by the device within that track, and ending with the desired page. The 8 Remote Control Parameters on this Component will correspond to the 8 Remote Controls on a single page.

---

bitwigTrackRemotesedit

Description:

The bitwigTrackRemotes COMP serves as an interface for accessing and controlling Track Remote Controls in Bitwig. Navigation to controls begins by selecting a track, followed by the desired page. The 8 Remote Control Parameters on this Component will correspond to the 8 Remote Controls on a single page.

---

bitwigProjectRemotesedit

Description:

The bitwigProjectRemotes COMP serves as an interface for accessing and controlling global Project Remote Controls in Bitwig. Navigation to controls begins by selecting the desired page. The 8 Remote Control Parameters on this Component will correspond to the 8 Remote Controls on a single page.

---

bitwigNoteedit

Description:

The bitwigNote COMP allows users to read a live stream of note events on a given Bitwig Track. The incoming notes will correspond to the track’s note input source, whether it be output from a midi device or side-chained from another track or device within Bitwig. Users will use the navigation controls to specify which track’s input source they want to monitor.

Callbacks:

• onNoteEvent(info) :

  A note event has occurred, includes note on, note off, or velocity change

  info : dictionary containing note event info

  pitch : pitch index of the note

  velocity : velocity of the note

---

Synchronization & Timingedit

---

TBD

---

Audio IOedit

---

Bitwig’s Gridedit

Single Computeredit

Macedit

PCedit

Two Computersedit

Macedit

PCedit