Difference between revisions of "TDAbleton"

From TouchDesigner Documentation
Jump to: navigation, search
m (Reverted edits by Ivan (talk) to last revision by Markus Heckmann)
(Tag: Rollback)
Line 12: Line 12:
==== System Requirements ====
==== System Requirements ====
*TouchDesigner version 099 2019.19050 and up. (Some features may work on older versions)
*TouchDesigner version 099 2018.26590 and up. (Some features may work on older versions)
*Ableton Live 9.7.2 and up.
*Ableton Live 9.7.2 and up.
*Max for Live 7.3.3 and up. (Note: Max 7.3.3 has a MIDI pitch bend bug. Use 7.3.4!)
*Max for Live 7.3.3 and up. (Note: Max 7.3.3 has a MIDI pitch bend bug. Use 7.3.4!)
Line 34: Line 34:
# If the <code>tdAbleton</code> Component does not have a disconnected error flag, the connection is successful. (If you see error messages or are not connected, check the [[#Troubleshooting|Troubleshooting]] section below.)
# If the <code>tdAbleton</code> Component does not have a disconnected error flag, the connection is successful. (If you see error messages or are not connected, check the [[#Troubleshooting|Troubleshooting]] section below.)
# Use the '''Add TDA Master Device''' parameter on the <code>abletonSong</code> Component to add a master Max device to the master track in your Live set. Some features of TDAbleton will work without this, but functionality will be limited.
# Use the '''Add TDA Master Device''' parameter on the <code>abletonSong</code> Component to add a master Max device to the master track in your Live set. Some features of TDAbleton will work without this, but functionality will be limited.
==== Connecting Ableton Live To Multiple TouchDesigner Instances ====
To connect Live to multiple instances of TouchDesigner, use the '''Broadcast''' feature. You can set Broadcast mode either on the [[TDAbleton#The_TDA_Master_Device|TDA Master Max Device]] or on the [[TDAbleton_System_Components#The_tdAbleton_Master_Component|tdAbleton Component]]. This will broadcast information from Live to all computers on the network. Be sure all tdAbleton devices' <code>TouchDesigner In Port</code> parameter is set to this port.
=== Upgrading TDAbleton ===
=== Upgrading TDAbleton ===
Line 58: Line 54:
* '''Scene''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component, channels <code>song/info/triggered_scene</code> and <code>song/info/last_started_scene</code>. Also available via callbacks.
* '''Scene''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component, channels <code>song/info/triggered_scene</code> and <code>song/info/last_started_scene</code>. Also available via callbacks.
* '''Time Data''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component, channels <code>song/info/bars</code>, <code>song/info/beats</code>, <code>song/info/sub_divisions</code>, <code>song/info/time</code>. '''Note''': Include Time Data parameter must be <code>On</code>.
* '''Time Data''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component, channels <code>song/info/bars</code>, <code>song/info/beats</code>, <code>song/info/sixteenths</code>, <code>song/info/time</code>. '''Note''': Include Time Data parameter must be <code>On</code>.
* '''Cue Points (a.k.a Timeline Locators)''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component property <code>LastLocatorPassed</code>. Also available via callbacks.
* '''Cue Points (a.k.a Timeline Locators)''': <code>[[TDAbleton_System_Components#abletonSong|abletonSong]]</code> Component property <code>LastLocatorPassed</code>. Also available via callbacks.
* '''Output Levels''': <code>[[TDAbleton_System_Components#abletonTrack|abletonTrack]]</code> Component, channels <code>.../output_meter_left</code>, <code>.../output_meter_right</code>, <code>.../output_meter_level</code>. '''Note''': Due to a bug in Ableton Live Object Model, these are only updated when the meters are visible in the Ableton interface! Also, Include Audio Data parameter must be <code>on</code>.
* '''Output Levels''': <code>[[TDAbleton_System_Components#abletonTrack|abletonTrack]]</code> Component, channels <code>.../output_meter_left</code>, <code>.../output_meter_right</code>, <code>.../output_meter_level</code>. '''Note''': Due to a bug in Ableton Live Object Model, these are only updated when the meters are visible in the Ableton interface! Also, Include Audio Data parameter must be <code>on</code>.

Revision as of 10:49, 13 September 2019


TDAbleton is a tool for linking TouchDesigner tightly with Ableton Live. It offers full access to most everything going on in an Ableton set, both for viewing and setting. The TDAbleton system contains a number of components for 2 way communication, and a framework for building custom components and new features.

TDAbleton operates through Ableton's MIDI Remote Scripts system and, when necessary, Max for Live (M4L) devices. Communication with TouchDesigner is via OSC (using UDP). It is fully network-capable, so TouchDesigner can be running on a separate machine from Ableton.

See also: TDAbleton System Components, Creating Custom TDAbleton Components, and TDAbletonCompBaseExt Extension

Getting Started[edit]

System Requirements[edit]

  • TouchDesigner version 099 2018.26590 and up. (Some features may work on older versions)
  • Ableton Live 9.7.2 and up.
  • Max for Live 7.3.3 and up. (Note: Max 7.3.3 has a MIDI pitch bend bug. Use 7.3.4!)

Install the latest TDAbleton system[edit]

  1. Open the Samples/TDAbleton folder by choosing Browse Samples in the TouchDesigner Help menu, then entering the TDAbleton folder.
  2. Copy the TouchDesigner folder into your Ableton Remote Scripts folder. For Windows standard installation, this should be: \ProgramData\Ableton\Live x.x\Resources\MIDI Remote Scripts\. For Mac standard installation, this should be: /Contents/App-Resources/MIDI Remote Scripts/. See How to install a third party Remote Script to locate this folder and for more info on this.

Set up Ableton Live[edit]

  1. Start Ableton Live
  2. Drag the TouchDesigner Remote Script folder (the one you just copied above) into the "PLACES" section in Live's Browser sidebar (on the left). When you select this new folder in Live, you should see the TDA MIDI.amxd and TDA Master.amxd devices in the browser (on the right).
  3. Open Ableton preferences (in the Options menu) and select the Link MIDI tab on left. In one of the Control Surface dropdowns, select TouchDesigner. Input and Output should be set to None.
  4. Reload your Live Set

Set up TouchDesigner and Confirm the Connection[edit]

  1. In the Palette, you will find the tdAbletonPackage.tox in the TDAbleton section. Drop this in your project. It will have an error if it is not connecting to Ableton Live!
  2. If Ableton Live and TouchDesigner are running on the same computer, no additional network setup is necessary. If they are running on different computers, you must set TouchDesigner to connect to Live's address. On the tdAbletonPackage/tdAbleton Component, set the Ableton Address parameter to the network address of the computer running Ableton Live.
  3. If the tdAbleton Component does not have a disconnected error flag, the connection is successful. (If you see error messages or are not connected, check the Troubleshooting section below.)
  4. Use the Add TDA Master Device parameter on the abletonSong Component to add a master Max device to the master track in your Live set. Some features of TDAbleton will work without this, but functionality will be limited.

Upgrading TDAbleton[edit]

All TDAbleton components have a version number on their TDAbleton parameter page. You can check against the version numbers on palette and forum components to see if you have the latest. The latest updates will be available on the top entry of the TDAbleton Forum Thread. Installation instructions are there.

You can also upgrade to a new version from a new TouchDesigner installation:

  1. Follow the Install the latest TDAbleton system instructions above, re-copying the TouchDesigner remote script into the Ableton Remote Scripts folder and restarting your Live Set.
  2. Delete the tdAbletonPackage in your project.
  3. Copy a new tdAbletonPackage into your project from the palette.
  4. In the tdAbleton component in tdAbletonPackage, pulse the Update Ableton Comps parameter.

Important: When installing from either location, the TouchDesigner Max devices in your set (names start with TDA_) may have to be replaced with new versions if you have saved them out separately (using Collect All and Save or other means). You can tell if you are using the current ones (in the MIDI Remote Scripts/TouchDesigner) folder by looking at the path that shows up in the lower Ableton info bar when mousing over the devices' name in your set. Note also that the devices in the TDADemo set do not point there, so they have to be replaced if you based your Ableton set on that file. You can either recreate the devices in your set or replace the files in your set's file structure.

Common Ableton Tasks[edit]

The following is a list of commonly used data from Ableton Live and where to find it in TDAbleton.

  • Scene: abletonSong Component, channels song/info/triggered_scene and song/info/last_started_scene. Also available via callbacks.
  • Time Data: abletonSong Component, channels song/info/bars, song/info/beats, song/info/sixteenths, song/info/time. Note: Include Time Data parameter must be On.
  • Cue Points (a.k.a Timeline Locators): abletonSong Component property LastLocatorPassed. Also available via callbacks.
  • Output Levels: abletonTrack Component, channels .../output_meter_left, .../output_meter_right, .../output_meter_level. Note: Due to a bug in Ableton Live Object Model, these are only updated when the meters are visible in the Ableton interface! Also, Include Audio Data parameter must be on.
  • Track Slots: abletonTrack Component, channels .../playing_slot_index, .../fired_slot_index.
  • Clips: abletonTrack Component, out_clips DAT output. When the Include Playing Clip Data parameter is on, abletonTrack's CHOP output will also show clip time and loop information.
  • Device Parameter Values: abletonParameter or abletonChainParameter Components.
  • Control Ableton Parameters (without creating undo steps): abletonParameter Component.
  • MIDI Data: abletonMIDI Component.
  • MIDI Notes in a Clip: abletonClipSlot Component.
  • Audio Levels: abletonLevel Component. This includes level data on a per-track basis, and can be combined with filters to provide spectrum analysis.
  • Sending/Receiving Rack Macro data: abletonRack Component. This is also the smoothest way to receive parameter data.

TDAbleton Feature Tour[edit]

The easiest way to learn the basics of TDAbleton is to explore the provided demo. To get started, run the TDAbletonDemo.toe file in the /Samples/TDAbleton folder (choose Browse Samples from TouchDesigner Help menu). In the same folder you'll find the TDADemo Live Set for Ableton Live. Inside that folder, open the TDADemo Set.als Ableton Set. Press play in Ableton Live and you should immediately see CHOP data moving in the TouchDesigner demo TDAbleton Components. If you don't, be sure you have properly set up Ableton Live (see Getting Started).

The TDA Master Device[edit]


On the Master track of the TDADemo Set, you'll find the TDA Master Max Device. This device shows if Live is connected to TouchDesigner and allows you to apply some master settings for your Live Set. TouchDesigner does not have a way to access the file name loaded into Live, so the Song ID is provided as a numeric field you can use to identify your song. The name of your TDA Master device will be used as a text song name that is readable by TouchDesigner. The Ableton Port is the network port that will be used by the TouchDesigner remote script to receive messages from TouchDesigner. The Max In Port is the network port that will be used by TDA Max devices to receive messages from TouchDesigner.

Tip: you can add a TDA Master device to a Live Set using the Add TDA Master Device pulse parameter on an abletonSong Component (see below).

Anatomy of a TDAbleton Component[edit]

To look at the basic structure of a TDAbleton Component, we'll use abletonSong1 as an example.


Data from Ableton Live[edit]

You will notice that the data shown in the viewer reflects the current state of the Ableton Live Set. You can see a number of channels reflecting time data (e.g. song/info/beats) and a few others reflecting various states (e.g. song/info/play). Data coming in from Live is generally CHOP data, and can be accessed by wiring from the TDAbleton Component, as has been done with the nullSong CHOP. Look in the parameters of the circle1 SOP to see one way of using this incoming data. Some data from Live come in DAT format, and can be accessed similarly from outputs.

In certain cases, incoming data may also come via callback. Examples of this can be found in the abletonSong1_callbacks DAT. Python callbacks are beyond the scope of this guide, but if you know a little Python, looking in this DAT will reveal the examples which set the locatorByCallback and sceneByCallback textTOPs.

Sending Data to Ableton Live[edit]

Data to be sent out to Ableton is usually sent via parameters. If you go to the Ableton Song parameter page of abletonSong1 you will see the Play, Loop, and Tempo parameters which set the corresponding values in the Live Set. The abletonChainOrTrack1 and abletonChainParameter1 Components show examples of using CHOP exports to automatically change an outgoing parameter and thereby change a value in Live.

These parameter values are kept up to date with incoming Live data only if the Auto Sync Pars To CHOP toggle is on. This option is provided because in certain cases Auto Sync can cause echoing changes between TouchDesigner and Ableton.

Navigating your Live Set using the Live Object Model[edit]

The Ableton Live Object Model (or LOM) describes all the aspects of an Ableton Live Set, including Tracks, Devices, Parameters, Scenes, etc. For more information about the Live Object Model, see: LOM Python Reference and LOM Max For Live Reference.

For this section, we'll use abletonParameter1 as an example.


In the previous section, abletonSong1 shows data for the entire Live Set. Most TDAbleton Components are made for observing particular parts of a Set. For example, abletonParameter is used to get and set the value of a single Ableton Device Parameter. As you can see in the Component's parameters, this one is set to work with Track: 1 Muugy, Device: Pitch, and Parameter: Pitch. In Ableton Live, navigate to that device and you will see that its Pitch value is being mirrored in TouchDesigner.


TDAbleton uses menu parameters to navigate the Live Object Model. For example, all available Tracks, including Returns and the Master, will be shown in the Track parameter. Once you have selected a Track, its available Devices will be shown in the Device parameter, and so on down. To see other examples of this, take a look at the abletonTrack1 Component, which observes a single Track, and the abletonChainParameter1 Component, which gives access to Ableton Device Parameters within sub-chains such as those in an Instrument Rack.

Note: You can change the Pitch value in Ableton by changing the Value Send parameter on abletonParameter1, but notice that this stops Ableton's automation of that parameter. This is another reason why Auto Sync is not always desirable.

MIDI Data[edit]


The abletonMIDI1 Component has a unique feature: a Max For Live device is necessary in order to get MIDI data out of Ableton Live. Each abletonMIDI component is connected to a specific TDA MIDI device in Live. If you look on the 1 Muggy Track in the Ableton Set, you will see the TDA MIDI device.


TDA MIDI devices in your Live set should be created from TouchDesigner by using the Add TDA MIDI Device pulse parameter on an abletonMIDI Component. Just select the Track to put it on and press that button.

For more details about using TDAbleton MIDI features, see abletonMIDI.

Incoming MIDI[edit]

The TDA MIDI device transmits MIDI data back to TouchDesigner, based on its position in its Track. In the image, for example, the changes in MIDI notes created by the Pitch MIDI Device (just left of it in the Ableton Track) will be reflected in TouchDesigner.

Outgoing MIDI[edit]

The TDA MIDI device can also be used to send MIDI commands to Ableton Live. To see this, use the sendNote button and the pitchBend slider next to the abletonMIDI1 Component.

TDAbleton Rack Devices[edit]

The smoothest way to control and watch Live's parameter values from TouchDesigner is using the abletonRack component, and its corresponding Max devices in live. These racks can be created in Live using the pulse buttons on the abletonRack component. For an example, look at the device chain in the "2 Muggy" Track in the Demo Set.


The TDA Rack devices are Live presets that include standard Ableton Live Racks with a special Max device on the first chain that sends and receives data between TouchDesigner and the rack macros. In the image, this Max device is called "TDA_Rack_OSC". For the most part, you won't have to interact with this device, though it does have on/off controls for incoming and outgoing values.

The general strategy for using these racks is to put the Live device whose parameters you want to control and/or watch into the rack. Then map the appropriate rack macros to the parameters you want to interact with. This will create a fast connection between those parameters and the corresponding abletonRack device. For more information, see abletonRack.

Using TDAbleton Package[edit]


In tdAbletonPackage, you will see the tdAbleton master Component on the top-left. This master component maintains the connection to Ableton Live and will generally not need to be altered once your connection is in place.

The other TDAbleton Components provide the actual real-time data to and from Ableton. To use these Components, copy them into your project from tdAbletonPackage. In general, they use CHOP channels to transmit data from Ableton Live and custom parameters for Component set up and also for transmission of data to Live. For specific information about the Components see TDAbleton System Components.

The TDAbleton system also provides a number of features for creating your own custom Components. See Creating Custom TDAbleton Components for more information.

Setting Up Your Project[edit]

As you have seen, TDAbleton uses a separate Component for each aspect of the Live Object Model that you want TouchDesigner to interact with. To set up all your observers, just copy as many TDAbleton Components from tdAbletonPackage as you need and set them up appropriately. As always, using select CHOPs for duplicate data will be more efficient than creating duplicate Components.

Caveats and Gotchas[edit]

  • Most Importantly: the system will be confused by tracks with duplicate names and devices with duplicate names on the same track or in the same chain. In some cases, this is also true of names that are the same after being converted to valid TouchDesigner Channel names. TDAbleton will pop up a warning dialog if it finds duplicate names, and will give an option to automatically rename duplicates. This behavior can be controlled using the tdAbleton master Component's Report Duplicate Names parameter.
  • Ableton parameters that are being controlled by TouchDesigner are not disabled in the Ableton interface, as is common when a value is being controlled by another value. Once TouchDesigner has altered an Ableton parameter value, that value's Ableton automation can only be restored in the Ableton interface. Important: changing Ableton values from TouchDesigner will create Undo steps in Ableton, which can destroy your ability to undo if a value is constantly streaming into Live.
  • If Ableton Live objects are renamed when TDAbleton is not connected to Live, the connections will be broken when TDAbleton is reconnected. Connections will be maintained properly if renaming occurs while TDAbleton is connected.
  • Ableton parameters that are selected via Comp menus will always report their data as float values, even if they are integers in Ableton.
  • When using the TDAbleton Rack devices, you can't use spaces in Macro names.


Because TDAbleton is linked to Ableton Live's Python Remote Scripts via OSC and the Python Remote Scripts are linked to the Ableton app through a lower-level system, troubleshooting can be a bit tricky. If you are having problems, your most important tool is the Textport. Be sure to have it open while troubleshooting, as most errors will be reported there.

The most common issues with TDAbleton will have to do with connections. The simplest connection test is the Ping parameter on the tdAbleton master. Press that and you should see a response in the textport. If not, you may have incorrect address or port settings on tdAbleton. All TDAbleton Components, including the master, have a Connect parameter. Toggling that on and off will reset the connection and will often print useful error messages as to the problem.

If you are not connecting make sure that the Ableton Port (on the TDA_Master device on your Live master track) matches the Ableton Port parameter (on the tdAbleton component in TouchDesigner). If those are matching, you may have an OSC conflict with something else running on your system. Change them both to a different matching number. Unfortunately there is no way to tell if an OSC port is taken, so this must be done by trial and error.

If you are still not connecting 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.

TDAbleton will attempt to transmit any errors from the TouchDesigner Remote Script to the textport. In most cases this will be sufficient, but sometimes it may be necessary to look at the Ableton log file. To find your log file, see this Ableton help page. There is also an Ableton Log File parameter on tdAbleton where you can enter the location and then pulse the Open Log File parameter to get a view of the log inside TouchDesigner.

Tip: the Log TDA Debug Msgs parameter turns on and off verbose debugging in Ableton's log file. If this parameter is off, only errors and the most basic information will be put in the Ableton log.

A set of commands located in a Text DAT that are triggered to run under certain conditions. There are two scripting languages in TouchDesigner: Python and the original Tscript. Scripts and single-line commands can also be run in the Textport.

Unlike a Wire that connects nodes in the same Operator Family, a Link is the dashed lines between nodes that represent other data flowing between nodes, like CHOP Exports, node paths in parameters, and expressions in parameters referencing CHOP channels, DAT tables and other nodes.

TouchDesigner Component file, the file type used to save a Component from TouchDesigner.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

The panel at the bottom of TouchDesigner, it controls the current Time of the full system or just one component.

The component types that are used to render 3D scenes: Geometry Component contain the 3D shapes to render, plus Camera, Light, Ambient Light, Null, Bone, Handle and other component types.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.

An Operator Family which operate on Channels (a series of numbers) which are used for animation, audio, mathematics, simulation, logic, UI construction, and many other applications.

A Tscript-only script that executes one or more scripting language commands. The F1 to F12 keys run macros. The F1 macro puts you in Perform Mode. See also Script, DAT and Python.

TOuch Environment file, the file type used by TouchDesigner to save your project.

An Operator Family that reads, creates and modifies 3D polygons, curves, NURBS surfaces, spheres, meatballs and other 3D surface data.

Parameters in TouchDesigner are an operator's settings (numbers, menus, flags, strings, paths) which the user can alter. Parameters for any operator can be opened by right-clicking on the operator and selecting "Parameters..." A currently selected operator's parameters can be viewed in a Network Editor by pressing the keyboard shortcut 'p'.