node-liveosc

node.js integration with Ableton Live via LiveOSC

Prerequisites

You will need to have LiveOSC installed and running. For best results, please use this version:

https://github.com/dinchak/LiveOSC

Usage

Basic usage is as follows:

// load LiveOSC classvarLiveOSC=require('liveosc');// create new instance of LiveOSC, starts OSC listenervarliveosc=newLiveOSC({debug: true});// triggered when Live is loaded and readyliveosc.song.on('ready',function(){// start the song playingliveosc.song.play();});

Reference

See the API docs for full usage information.

Song Structure

The LiveOSC object has a song property that contains a full object map of the current Live set. The organization of the object is as follows:

Song

{tempo: 120.0,tracks: [{Track},{Track}, ...],returns: [{Return},{Return}, ...],devices: [{Device},{Device}, ...],volume: 0.0,pan: 0.0,scene: 0,beat: 0,playing: 1}

Track

{id: 0,name: '1-MIDI',clips: [{Clip},{Clip}, ...],sends: [{id: 0,value: 1.0},{id: 1,value: 1.0}, ...],devices: [{Device},{Device}],audio: 0,solo: 0,mute: 0,arm: 0,volume: 0,pan: 0,numScenes: 0}

Clip

{id: 0,name: '',track: {Track},state: 0,coarse: 0,fine: 0,loopstart: 0,loopend: 0,loopstate: 0,warping: 0,length: 0}

Return

{id: 0,name: 'A-Reverb',sends: [{id: 0,value: 1.0},{id: 1,value: 1.0}, ...],devices: [{Device},{Device}],solo: 0,mute: 0,volume: 0,pan: 0}

Device

{id: 0,name: 'Reverb',track: {Track},type: 'return',params: [{id: 0,value: 1,name: 'Device On',min: 0,max: 1},{id: 1,value: 0.5555555820465088,name: 'PreDelay',min: 0,max: 1},
...
]}

Changing Parameters

Most parameters have a corresponding set function that can be called to change them. For example, to set a clip's pitch, use the setPitch function:

clip.setPitch(12);

There are also a number of events that can be triggered, such as playing a clip:

clip.play();

See the API docs for a full reference.

Events

Each object emits various events that can be listened for. For example, to listen for changes to a clip's playing state (ie. the clip was started or stopped):

clip.on('state',function(param){// do something with param});

param will contain the new and previous values of the parameter, for example:

{value: 1,prev: 0}

Events can be listened at a global level as well. Each clip, track, device, and return will prefix its events with the type (clip:state for example) and broadcast them through the song event emitter. To listen for all clip state changes:

liveosc.song.on('clip:state',function(param){// do something with param});

Additional parameters including the id of the object will be passed at the global level:

{id: 0,// the clip idtrackId: 0,// the track id the clip is onvalue: 1,prev: 0}

See the API docs for a full reference.

Using the REPL

A REPL is included to help with exploring the object model and how LiveOSC behaves:

$ node repl
LiveOSC> song.tracks[2].name;
'3-Audio'
LiveOSC> song.tracks[2].clips[1].name;
'test'
LiveOSC> song.tracks[2].clips[1].on('name', function (param) { console.log(param) });
undefined
LiveOSC> song.tracks[2].clips[1].setName('fresh jams');
undefined
{ value: 'fresh jams', prev: 'test' }
LiveOSC> song.tracks[2].clips[1].name;
'fresh jams'
LiveOSC>