TDAbleton System Components

From TouchDesigner Documentation
Jump to: navigation, search

The TDAbleton System Components provide the real-time data to and from Ableton. To use these Components, simply copy them into your project from tdAbletonSystem. 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.

To use TDAbleton Components, you must first set up TDAbleton properly.

See also: Creating Custom TDAbleton Components and TDAbletonCompBaseExt Extension

The tdAbleton Master Component[edit]

The tdAbleton master component maintains the communication between TouchDesigner and Ableton Live. It will be in a state of error if it is not connected to Live, so that you can easily know when TDAbleton is having connection problems.

You will generally only interact with the master component through the TDAbleton custom parameter page. The following parameters are available:

  • Help Page: Opens the TDAbleton wiki page.
  • Update Ableton Comps: this will Update every TDAbleton component in your .toe file.
  • Connect: connects/disconnects from Ableton Live.
  • Listen Only: when on, TDAbleton will not allow outgoing changes to the Ableton Set.
  • Report Duplicate Names: control what kind of warnings are displayed when duplicate names are found in the Ableton Set. Duplicate names will cause problems in TDAbleton.
  • In Port: the UDP port number used by TouchDesigner to receive messages from Ableton.
  • Ableton Address: the IP address of the computer running Ableton Live. Also accepts "localhost".
  • Ableton Port: the port used by Ableton Live for receiving messages.
  • Max Port: the port used by TDAbleton Max devices for receiving messages.
  • Ping: for testing connection. Reports ping results in Textport.
  • Open Console: opens a simple Python console into the TouchDesigner Ableton Remote Script.
  • Ableton Log File: set this to allow easy access to the Ableton Live log file, where Remote Script errors are reported. See this Ableton help page.
  • Log TDA Debug Msgs: when on, the TouchDesigner Remote Script will log extra debug information in the Ableton log file.
  • Open Log File: open the log file set up above.

Common TDAbleton Component Features[edit]

Because TDAbleton Components are built on a common framework, they will almost always share the following features:

CHOP output[edit]

Output from Ableton via TDAbleton Components is provided through a CHOP output. The channels names will provide source information. In certain cases there may be multiple outputs. Additional outputs are the result of customization.

TDAbleton Parameter Page[edit]

This page holds information about the TDAbleton system as well as common utility parameters used by (almost) all TDAbleton Components.

System Parameters[edit]
  • TDAbleton Comp: Location of the associated tdAbleton master component.
  • TDAbleton Version: The TDAbleton version number that this component has been updated to.
  • Update: If the tdAbleton master has a different version number from this component, this parameter will be enabled. Pressing Update will clone the Component from its clone source, update the version number, and do any other special tasks necessary for update.
  • Help Page: Opens this wiki page.
Utility Parameters[edit]
  • Connect: When on, connect this component to Ableton. When off, all Ableton listeners will be disabled.
  • Clear CHOP: Clears the standard output CHOP for this component. If a TDAbleton Component has other output CHOPs (e.g. abletonMIDI), they will have their own clearing pulse parameters.
  • Strip CHOP Prefix Segments: Because CHOP channel names are automatic and can be long, this gives you the option of stripping off address segments. Of course, deeper customization can be achieved with a Rename CHOP, but this will generally be slower.
  • Timeslice OSC Chops: Turning timeslicing on causes CHOP output to cook constantly, but the cook time may be faster. Turning this off makes output only cook when data is incoming. Different settings will be better for different projects.
  • Send Only: When on, the component only sends control data to Live, it doesn't receive anything back. This turns off OSC inputs completely.

Live Object Model parameters[edit]

Live Object Model parameters are found on a TDAbleton Component's main parameter page. Track, Device, and Parameter custom parameters use the TDAbleton system to provide menu access to objects in your Ableton Set. In addition, the parameters Chain 1-4, Chain 1-4 Device allow deeper access into nested chains. Generally, only valid options will be available. The system will keep "Not Found" selections around until another option is selected. This "Not Found" state can happen if the object in Ableton is deleted, or if a Live Set is loaded that doesn't contain the given object.

Auto Sync Parameters[edit]

On the page with Live Object Model parameters, you will usually find these Auto Sync parameters to help control outgoing data:

  • Auto Sync Pars To CHOP: Many TDAbleton Components will have custom parameters whose values will be sent to Ableton. This parameter (when on) keeps those outgoing parameters synced to incoming values. Because this can decrease speed and in certain cases may create network echo, auto-syncing is optional. Note: when an Ableton value is changed by an outgoing TouchDesigner parameter, auto sync of that parameter will be disabled for one second.
  • Sync Pars To CHOP: When auto-syncing is off, the Sync parameter becomes available, which will do a one time synchronization of output parameters.

TDAbleton Components[edit]

The following is individual information for each of the standard TDAbleton Components:

abletonSong[edit]

Provides access to the current Ableton Live Set. It provides big picture song info including timeline, scene, and cue point (a.k.a. locators, a.k.a. markers) data. It also provides an interface to the TDA Master Device. This component also provides callbacks for triggered scenes and passed cue points. Note: cue point callbacks and updates are only performed when the Include Time Data toggle is on.

Extra outputs: cuePoints is a table of cue points and scenes is a table of scenes.

The abletonSong Component provides this function for controlling playback:

FireScene(scene=None)

Fire a scene.
scene: if int, number of the scene to fire. If str, name of scene to fire. If None, scene selected in Scene To Fire parameter.

StopAllClips()

Stops all clips in the song. Note that the abletonTrack Component has control over individual clip playback.

JumpToCuePoint(cuePoint)

Jump to a selected cue point
cuePoint: index or name of cue point to jump to.

GetCuePointByName(name)Cue point info dict

Get info about a cue point
name: name of cue point

abletonTrack[edit]

Provides access to the selected (via Track parameter) Ableton Live Track. Some of the custom output parameters may be disabled if the selected track does not have those features. This component is where you will find information about clips and clipSlots as well, including playhead position and loop points. This component provides callbacks when clips are triggered and playing.

Extra outputs: clips is a table of clip information for the track, including source files. clip_status is a table showing triggered and playing clips

Controlling Clips[edit]

The abletonTrack Component provides these functions for controlling playback of clips:

FireClipSlot(index)

Fires the clip at the given index.

StopClipSlot(index)

Stops the clip at the given index.

StopAllClips()

Stops all clips on the track. Note that the abletonSong Component has a version of this function that will stop all clips in the song.

abletonChain[edit]

Similar to abletonTrack Component, but allows access to nested chains, such as those in Ableton Racks and Drum Pads. Note that chains provide less information than tracks, due to more limited access through the Live Object Model.

abletonClipSlot[edit]

Provides access to Tracks' clip slots. Select a Track on the Ableton Track parameter page, then a clip slot on the Ableton Clip Slot page. This component provides callbacks when clips are triggered and playing.

Extra outputs: clips is a table of clip information for the track, including source files. clip_status is a table showing triggered and playing clips. When a midi clip slot is selected, the midiClip output gives a list of midi notes in the range named in the MIDI Clip Time Range and MIDI Clip Note Range parameters.

Clip Functions[edit]

The abletonClipSlot Component provides these functions for working with clips:

SetNotes(notes)

Send a set notes command to the chosen clip.
notes: a tuple of tuples in the form (pitch, time, duration, velocity, mute)
pitch: MIDI (0-127 int)
time: Beat (0-4 float)
duration: in beats
velocity: MIDI (0-127 int)
mute: 1 to mute, 0 to play

RemoveNotes(timeStart, pitchStart, timeEnd, pitchEnd)

Remove all notes that start in the given range. Time is in beats, pitch is in midi values (0-127)
timeStart: Beat (0-4 float)
pitchStart: MIDI (0-127 int)
timeEnd: number of beats from timeStart to end of removal area (0-4 float)
pitchEnd: number of notes from pitchStart to bottom of removal area (0-127 int)

ClipCommand(command)

Send this command to the selected clip.
command: a string to be sent to the Live clip object in the form <clip object>.<command>
For a list of clip commands, search for "Clip.Clip" at:
http://julienbayle.net/PythonLiveAPI_documentation/Live9.6.xml

abletonDeviceParameters[edit]

Provides read-only access to all parameters on the chosen device. The Parameters List allows you to filter the device parameters if you don't want all of them.

abletonParameter[edit]

Provides access to the selected Ableton Live Device Parameter. The outgoing Value Send parameter will always be a float, no matter what type the value in Ableton is.

abletonMIDI[edit]

Provides input/output access to MIDI events occurring in Ableton by interfacing with the TDA MIDI Max for Live device. That device can be created in Ableton or by clicking the Add TDA MIDI Device parameter on the Component.

MIDI Input[edit]

MIDI events are relayed from Live to TouchDesigner by the TDA MIDI device. It transmits all types of MIDI data including notes, control messages, program messages etc., all of which appear in the abletonMIDI CHOP output. For convenience, the last received midi note and the last received midi velocity is automatically tracked as well.

Because MIDI events can happen more rapidly than TouchDesigner frames, there is a potential for loss of data when using CHOP channels. To this end, the abletonMIDI Component provides a single callback in its callback system: onMIDIEvent, which provides address and args in its info dictionary. These callbacks will correspond exactly to incoming MIDI CHOP data, but will never miss an event due to frame-rate.

The TDA MIDI device's name in Ableton is part of the channel names that are created. That name can be changed in Ableton or via the Device Name parameter. Note: the device's placement in a chain of devices does matter if MIDI data is altered by other devices.

MIDI Output[edit]

MIDI events can be sent to the TDA MIDI device from TouchDesigner using Python. MIDI events sent to the TDA MIDI device will be reported back to TouchDesigner. In order to send a MIDI event, use the following abletonMIDI Component method:

  • SendMIDI (type, *data)
Send a MIDI command to the connected TDA MIDI device.
Arguments are a MIDI command string and 0-2 integer data items:
  • note <pitch value> <velocity>
  • pressure <aftertouch pressure> <pitch value>
  • control <control value> <controller number>
  • program <program change value>
  • aftertouch <aftertouch pressure>
  • pitchbend <pitchbend amount>
  • channel <MIDI channel>
  • flush (no arguments, stops all MIDI notes)
Note: pitchbend uses hi-res MIDI data -8192 to 8191

Important: you must have a TDA Master device on your Live master track in order to send MIDI events. You can use the abletonSong Component to add one.

abletonLevel[edit]

This component provides level data from Ableton Live by interfacing with the TDA Level Max for Live device. Levels are analyzed within the chain they appear in. This allows you to analyze the levels of individual tracks and sends or use the master track to analyze the song as a whole. Levels are measured within the chain, before track mixer levels are applied. Use the Mix/Raw settings to apply the mix for the device's track before level analysis. Note: the level device does not send full audio information, only the volume level it receives.

Output modes[edit]

The abletonLevel component can interface with a single TDA Level Max device, or multiple devices within a rack. Choose which mode to use with the Output parameter. In either mode, the devices can be created within Live or by using the Add TDA Level Device and Add TDA Audio Analyzer Rack parameters, respectively. Note: while you can only use these parameters to add devices to Ableton tracks, not to sub-chains, you can work within sub-chains by placing the devices manually in Live and then pointing to them with your TDAbleton components.

The rack mode is extremely useful for performing spectrum analysis. The default rack is a simple example, and has a typical low/mid/high arrangement using Live's EQ Three device. You are not limited to this, and within the rack you can use any Ableton Live filter or EQ device to choose frequencies, alter levels, or perform other operations to the audio before outputting levels to TouchDesigner. The abletonLevel Component will report data from all TDA Level devices in the rack's chains.

abletonRack[edit]

This component provides faster and more accurate OSC communication through the TDA Rack... Max for Live devices. It is also useful for controlling multiple Live parameters from TouchDesigner. The abletonRack Component uses Live racks, and specifically their Macros, to create sets of 8 deeply connected parameters. The best way to create the type of Rack that you want is by using one of the three pulse parameters: Add TDA Audio Effect Rack, Add TDA Instrument Rack, and Add TDA MIDI Effect Rack. You can also create the racks manually, but you will also have to manually add a TDA Rack... device (see below) and map its parameters to the rack's macros. Note: while you can only use these parameters to add devices to Ableton tracks, not to sub-chains, you can work within sub-chains by placing the devices manually in Live and then pointing to them with your TDAbleton components.

The component will report the values of the Rack's macros in it's CHOP output. The channels prefixed with rack are coming directly from Max using OSC and are slightly faster and smoother than TDAbleton values that come from the MIDI Remote Script. The abletonRack Component also provides control of the Rack's Macros on the Macros parameter page.

Important: When using TDAbleton Rack devices, do not use spaces in the Rack Macro names. TDAbleton cannot automatically correct this issue.

TDA Rack... Max devices[edit]

The abletonRack Component uses the TDA_Rack_OSC and TDA_Rack_MIDI_OSC Max devices to send and receive information. These are pre-placed in the racks when you create them from TouchDesigner. For full functionality, one (and only one) of these devices must exist in one of the Rack's device chains. These Max devices have no functionality outside of Racks.

Each Rack macro has a corresponding In and Out toggle on the rack OSC Max device. These control whether Ableton will receive data from and send data to TouchDesigner.

Sending CHOP Data to Live Rack Macros[edit]

The abletonRack component has a CHOP input and an OSC Input CHOP parameter for sending data to the rack's macros in a highly efficient manner. Incoming CHOP channels will be mapped to receiving macros in the order they appear in the CHOP. If you want to change this order, you can fill the Reorder parameter with the channel names in the order you want them to be mapped.

abletonMapper[edit]

Similar to the TDA Rack devices, this component provides faster and more accurate OSC communication through the TDA_Mapper Max for Live device. It is also useful for controlling multiple Live parameters from TouchDesigner, but unlike the Rack system, it uses the Ableton Live Mapping system which allows you to control any parameter in your Live Set. To set up the abletonMapper Component, you will have to use the Live application to map the parameters you want to control. The best way to create the abletonMapper device is to use the Add TDA Mapper Device pulse parameter.

Note: controlling parameters using this device does not add steps to Live's undo stack. This can be very useful when sending a constantly changing value from TouchDesigner.

TDA Mapper Max devices[edit]

The TDA Mapper Max device receives OSC data directly from TouchDesigner and assigns values to selected Live Parameters. To select a parameter to control, click a MAP button on the TDA Mapper device, then click the parameter you want to control in Live. To toggle control of the parameter between Live and TouchDesigner, click the button under the MAP button (it says either TD or Live). To unmap the parameter, click the Unmap button.

The data coming from TouchDesigner should be normalized between zero and one, but you can scale the output mapping using the Min and Max values, which can be controlled within Live or TouchDesigner.

Sending Data to TDA Mapper[edit]

The abletonMapper component has a CHOP input and an OSC Input CHOP parameter for sending data to the mapper in a highly efficient manner. Incoming CHOP channels will be mapped to receiving macros in the order they appear in the CHOP. If you want to change this order, you can fill the Reorder parameter with the channel names in the order you want them to be mapped. Any values not controlled by input CHOP can be controlled using the abletonMapper Component's parameters on the Map Values page.

abletonValueListener[edit]

This component provides parameter access for creating listeners to anything in the Ableton Live Object Model. You can select LOM objects via the LOM parameters, then append to the created LOM expressions. You can also specify an OSC return address. See also: Setting up listeners

abletonComp[edit]

This component is a starting point for building custom TDAbleton Components. It does nothing on its own, but contains all the necessary operators including the Live Object Model parameters above. See Creating Custom TDAbleton Components for more information.

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.

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.

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

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.

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.

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'.

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.