""" # Copyright (C) 2007 Nathan Ramella (nar@remix.net) # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public # License as published by the Free Software Foundation; either # version 2.1 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public # License along with this library; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # # For questions regarding this module contact # Nathan Ramella or visit http://www.liveapi.org RemixNet Module This module contains four classes that have been assembled to facilitate remote control of Ableton Live. It's been an interesting experience learning Python and has given me a lot of time to think about music and networking protocols. I used OSC as it's somewhat of an accepted protocol and at least more flexible than MIDI. It's not the quickest protocol in terms of pure ops, but it gets the job done. For most uses all you'll need to do is create an OSCServer object, it in turn creates an OSCClient and registers a couple default callbacks for you to test with. Both OSCClient and OSCServer create their own UDP sockets this is settable on initialization and during runtime if you wish to change them. Any input or feedback on this code will always be appreciated and I look forward to seeing what will come next. -Nathan Ramella (nar@remix.net) -Updated 29/04/09 by ST8 (st8@q3f.org) Works on Mac OSX with Live7/8 The socket module is missing on osx and including it from the default python install doesnt work. Turns out its the os module that causes all the problems, removing dependance on this module and packaging the script with a modified version of the socket module allows it to run on osx. """ import sys from Logger import Logger # Import correct paths for os / version if sys.platform == "win32": import socket else: # 10.5 try: file = open("/usr/lib/python2.5/string.pyc") except IOError: sys.path.append("/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5") import socket_live8 as socket else: sys.path.append("/usr/lib/python2.5") import socket import select import time import OSC import os import errno import thread if sys.platform != "win32": import fcntl class OSCClient: """ This is a helperclass for the OSCServer that will setup a simple method for sending OSC messages """ def __init__(self, touchAble, udpClient=None, tcpServer = None, address=None, msg=None): """ Initializes a RemixNet.OSCClient object. You can pass in a default address or default msg here. This is useful for making 'beacon' clients that you can attach as listeners on Live object attributes. """ self.touchAble = touchAble #self.touchAble.log_message("OSCClient logging from touchable?") if address is not None: self.address = address if msg: self.msg = msg else: self.msg = None if udpClient is not None: self.udpClient = udpClient if tcpServer is not None: self.tcpServer = tcpServer def setUDPClient(self, udpClient): """ If we create our OSCClient object without defining a udpClient we can set one after the fact here. If you don't and you try to send, you'll raise an exception. """ if udpClient: self.udpClient = udpClient def send(self, address=None, msg=None, udp = 0): """ Given an OSC address and OSC msg payload we construct our OSC packet and send it to its destination. You can pass in lists or tuples in msg and we will iterate over them and append each to the end of a single OSC packet. This can be useful for transparently dealing with methods that yield a variety of values in a list/tuple without the necessity of combing through it yourself. """ if self.udpClient is None: # SHOULD RAISE EXCEPTION #self.touchAble.log_message("self.udpClient is None:") return # If neither address or msg, we have nothing to do. if not address and not self.address: #self.touchAble.log_message("if not address and not self.address:") # SHOULD RAISE EXCEPTION return # I feel a little weird doing this, but I want to keep # the 'default' self.msg that the object was initialized # with, without playing Towers of Hanoi with another variable. if self.msg and self.msg is not None: msg = self.msg # I don't like doing it here any more than I did up there. if not address: if not self.address: # SHOULD RAISE EXCEPTION #self.touchAble.log_message("if not self.address:") return address = self.address oscMessage = OSC.OSCMessage() oscMessage.setAddress(address) # We need to check for msgs that are actually # instance methods here and do something with # them... # if type(msg) == instance method: # blahblah # By default OSC.py doesn't look like it'll process tuples # and pack them. So, we help it along by breaking them up # and appending each entity. if type(msg) in (str,int,float): oscMessage.append(msg) elif type(msg) in (list,tuple): for m in msg: if type(m) not in (str,int,float): #self.touchAble.log_message("if type(m) not in (str,int,float):") # SHOULD RAISE EXCEPTION return oscMessage.append(m) elif msg == None: self.udpClient.send(oscMessage.getBinary()) else: # SHOULD RAISE EXCEPTION # Likely, method or instancemethod object. We should # actually execute the code here and send the result, # but for now we'll just return. return # Done processing, send it off to its destination if udp: self.udpClient.send(oscMessage.getBinary()) else: self.tcpServer.send(oscMessage.getBinary()) class OSCServer: def __init__(self, touchAble = None, dst=None, dstPort=None, src=None, srcPort=None): self.touchAble = touchAble #self.touchAble.log_message("OSCServer logging from touchable?") """ This is the main class we the use as a nexus point in this module. - dst: destination/target host for OSC responses. If None will default to local network broadcast only. - src: Which local interface / ip to bind to, if unset defaults to all - srcPort: Source port to bind the server to for incoming OSC queries. Defaults to 9000 - dstPort: Destination port for OSC responses sent by callbacks. Defaults to 9001 By default we define and set callbacks for two utility functions that may be useful in testing. /remix/echo -> OSCServer.callbackEcho() - For responding to /remix/echo queries. /remix/time -> OSCServer.callbackTime() - Returns time.time() (time in float seconds) I chose OSC to deliver messages out of necessity, my opinion of OSC at this point is that its addressing system is heavyweight although the idea is a reasonable one. But taking into consideration the ratio of address:data it becomes somewhat unreasonable unless you take the route of making unreadable addresses. As an example I offer the following address, /ableton/track/1/volume/set float(0.98) To set a single 4 byte float value, we need to use a 27 byte string to get it routed to the correct area, and even then we need to make an O(N) comparison on the address since we don't have the luxury of a switch statement in Python. If you're trying to interact with devices in near-realtime the number of ops wasted on just getting things to the right place can take the wind out of your sails. But basically for this project to be accepted or useful to anyone it was important to me that we provide a method of accessing that other tools could use without having to introduce a new linewire protocol. It should be noted that performance even with the added ops isn't that bad. On my dualcore system I was able to process about 1380 OSC callbacks per second. Or, ~86 callbacks per 60ms tick. """ self.tcpServer = TCPServer(self, src, srcPort) self.udpClient = UDPClient(dst, dstPort) self.udpClient.open() self.oscClient = OSCClient(self.touchAble, self.udpClient, self.tcpServer, None, None) # Create our callback manager and register some utility # callbacks to show how its done. self.callbackManager = OSC.CallbackManager(self) self.callbackManager.add(self.callbackEcho, '/remix/echo') self.callbackManager.add(self.changeIP, '/setip') self.callbackManager.add(self.callbackEcho, '/remix/time') self.tcpServer.setCallbackManager(self.callbackManager) self.tcpServer.bind() #Should this method go here? #def attachToCurrentSongTime(self): def changeIP(self, msg=None): self.oscClient.send('/connected', 2) def callbackEcho(self, msg=None): """ When re recieve a '/remix/echo' OSC query from another host we respond in kind by passing back the message they sent to us. Useful for verifying functionality. """ self.oscClient.send('/remix/echo', msg[2]) def callbackTime(self, msg=None): """ When we recieve a '/remix/time' OSC query from another host we respond with the current value of time.time() This callback can be useful for testing timing/queue processing between hosts """ self.oscClient.send('/remix/time', time.time()) def sendOSC(self, address=None, msg=None): """ A convienence function so we don't have to dig into the objects every time we want to send an OSC packet. """ #self.touchAble.log_message(address) #self.touchAble.log_message(msg) if address != None and msg != None: self.oscClient.send(address, msg) def sendOSCUDP(self, address=None, msg=None): """ A convienence function so we don't have to dig into the objects every time we want to send an OSC packet. """ #self.touchAble.log_message(address) #self.touchAble.log_message(msg) if address != None and msg != None: self.oscClient.send(address, msg, 1) def sendUDP(self, data): """ A convienence function so we don't have to dig into the objects every time we want to send raw UDP. """ if data: self.udpClient.send(data) def getCallbacks(self): """ If you'd like to see what callbacks you have registered, this function will pass you back the dict from the OSC.Manager object. """ return dict(self.callbackManager.callbacks) def addCallback(self, method=None, address=None): """ This method will allow you to externally add callbacks into the UDPServer. As a rule of thumb we'd like to keep everything seperate for ease of maintenance. You call this method with the arguments: - method: The method object you want to register as a callback for an OSC address. - address: The OSC address to bind to. (Example: /remix/mynewcallback/) If either of these values isn't set, nothing will get registered. """ if method and address: self.callbackManager.add(method, address) else: # SHOULD RAISE EXCEPTION? return def processIncomingUDP(self): """ This is the juice of our tool. While UDP is billed as an unreliable protocol, as it turns out it's not that bad. In fact, it can be pretty good. There are several limitations to the Ableton Live Python environment. * The Ableton Live Python environment is minimal. The included module list is very short. For instance, we don't have 'select()'. * The Ableton Live Python version is a bit older than what most Python programmers are used to. Its version string says 2.2.1, and the Python webpage shows that the offical 2.2.3 came out May 30, 2003. So we've got 4 years between us and it. Fortunately since I didn't know any Python when I got started on this project the version differences didn't bother me. But I know the lack of modern features has been a pain for a few of our developers. * The Ableton Live Python environment, although it includes the thread module, doesn't function how you'd expect it to. The threads appear to be on a 100ms timer that cannot be altered consistently through Python. I did find an interesting behavior in that when you modify the sys.setcheckinterval value to very large numbers for about 1-5/100ths of a second thread focus goes away entirely and if your running thread is a 'while 1:' loop with no sleep, it gets 4-5 iterations in before the thread management stuff kicks in and puts you down back to 100ms loop. As a goof I tried making a thread that was a 'while 1:' loop with a sys.setcheckinterval(50000) inside it -- first iteration it triggered the behavior, then it stopped. It should also be noted that you can make a blocking TCP socket using the threads interface. But your refresh is going to be about 40ms slower than using a non-blocking UDP socket reader. But hey, you're the boss! So far the best performance for processing incoming packets can be found by attaching a method as a listener to the Song.current_song_time attribute. This attribute updates every 60ms on the dot allowing for 16 passes on the incoming UDP traffic every second. My machine is pretty beefy but I was able to sustain an average of over 1300 /remix/echo callback hits a second and only lost .006% of my UDP traffic over 10 million packets on a machine running Live. One final note -- I make no promises as to the latency of triggers recieved. I haven't tested that at all yet. Since the window is 60ms, don't get your hopes up about MIDI over OSC. """ self.tcpServer.processIncomingUDP() def bind(self): """Bind to the socket and prepare for incoming connections.""" self.tcpServer.bind() def shutdown(self): """If we get shutdown by our parent, close the socket we had open""" self.udpClient.close() self.tcpServer.close() class UDPClient: """ This is a fairly brain-dead UDPClient implementation that is used by the OSCClient to send packets out. You shouldn't need this unless you want to get tricky or make a linewire protocol. """ def __init__(self, dst=None, dstPort=None): """ When the OSCClient instantiates its UDPClient it passes along: - dst: The destination host. If none only send to localhost. - dstPort: The destination port. If none, 9001 by default. """ if dst: self.dst = dst else: # If you'd like to try broadcast, # set this to # I've been unable to get it to work. self.dst = 'localhost' if dstPort: self.dstPort = dstPort else: self.dstPort = 9001 self.udpaddr = (self.dst, self.dstPort) def setDstPort(self, dstPort=None): """ If the port gets reset midstream, close down our UDPSock and reopen to be sure. A little redundant. """ # Manually set the port before init if not dstPort: return self.dstPort = dstPort if self.UDPSock: self.UDPSock.close() self.open() def setDst(self, dst=None): """ If the dst gets reset midstream, we close down our UDPSock and reopen. A little redundant. """ if not dst: return self.dst = dst if self.UDPSock: self.UDPSock.close() self.open() def open(self): """ Open our UDPSock for listening, sets self.UDPSock """ if not self.dst: return if not self.dstPort: return # Open up our socket, we're ready for business! self.udpaddr = (self.dst, self.dstPort) self.UDPSock = socket.socket(socket.AF_INET,socket.SOCK_DGRAM) #Broadcast doesn't work for answering callbacks for some reason. #But, I'll leave this here if you'd like to try. #if self.dst == '': # self.UDPSock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1) def send(self, data): """ If we have data to send, send it, otherwise return. """ # Only send if we have data. if not data == '': #self.conn.send(data) self.UDPSock.sendto(data,self.udpaddr) data = '' def close(self): """ Close our UDPSock """ # Closing time! self.UDPSock.close() class TCPServer: """ RemixNet.UDPServer This class is a barebones UDP server setup with the ability to assign callbacks for incoming data. In the design as is, we use an OSC.CallbackManager when we recieve any data. This class is designed to be used by RemixNet.OSCServer, as it will do all the setup for you and register a few default OSCManager callbacks. """ def __init__(self, oscServer = None, src = None, srcPort = None): """ Sets up the UDPServer component of this package. By default we listen to all interfaces on port 9000 for incoming requests with a 4096 byte buffer. You can modify these settings by using the methods setport() and setHost() """ self.connected = 0 self.listening = 0 self.accepting = 0 self.conn = None if srcPort: self.srcPort = srcPort else: self.srcPort = 9008 if src: self.src = src else: self.src = '127.0.0.1' self.buf = 8192 if oscServer: self.oscServer = oscServer else: pass def acceptConnection(self): try: self.conn, self.addr = self.TCPSock.accept() print 'Connection address:', self.addr if sys.platform == "win32": self.conn.setblocking(0) else: fcntl.fcntl(self.conn, fcntl.F_SETFL, os.O_NONBLOCK) self.rxset.append(self.conn) self.connected = 1 self.listening = 0 self.accepting = 0 self.oscServer.sendOSC('/status/finished_loading', (9010)) except: self.connected = 0 self.listening = 1 self.accepting = 0 pass def processIncomingUDP(self): """ Attempt to process incoming packets in the network buffer. If none are available it will return. If there is data, and a callback manager has been defined we'll send the data to the callback manager. You can specify a callback manager using the UDPServer.setCallbackManager() function and passing it a populated OSC.Manager object. """ try: # You'd think this while 1 loop would get stuck and block the # program. But. As it turns out. It doesn't. //probably gets killed by Live #rxfds, txfds, exfds = select.select(self.rxset, self.txset, self.rxset) #for sock in rxfds: #if sock is self.TCPSock: if self.listening == 1 and self.connected == 0 and self.accepting == 0: self.accepting = 1 thread.start_new_thread(self.acceptConnection, ()) elif self.connected == 1 and self.conn != None: try: rem = 4 length_data = self.conn.recv(rem) length_received = len(length_data) rem = rem - length_received while rem > 0: rxfds, txfds, exfds = select.select(self.rxset, self.txset, self.rxset) data2 = self.conn.recv(rem) length_received = len(data2) rem = rem - length_received length_data.append(data2) packet_length = OSC.readInt(length_data)[0] rem = 4 type_data = self.conn.recv(rem) length_received = len(type_data) rem = rem - length_received while rem > 0: rxfds, txfds, exfds = select.select(self.rxset, self.txset, self.rxset) data2 = self.conn.recv(rem) length_received = len(data2) rem = rem - length_received type_data.append(data2) type = OSC.readInt(type_data)[0] rem = 4 tag_data = self.conn.recv(rem) length_received = len(tag_data) rem = rem - length_received while rem > 0: rxfds, txfds, exfds = select.select(self.rxset, self.txset, self.rxset) data2 = self.conn.recv(rem) length_received = len(data2) rem = rem - length_received tag_data.append(data2) tag = OSC.readInt(tag_data)[0] rem = packet_length packet_data = self.conn.recv(rem) length_received = len(packet_data) rem = rem - length_received while rem > 0: rxfds, txfds, exfds = select.select(self.rxset, self.txset, self.rxset) data2 = self.conn.recv(rem) length_received = len(data2) rem = rem - length_received packet_data.append(data2) if not packet_data: self.oscServer.sendOSCUDP("/NSLOG_REPLACE", "NO PACKET DATA") # No data buffered this round! return else: #print packet_data if packet_data != '\n': # Oh snap, we have data! # If you want to write your own special handlers for dealing # with incoming data, this is the place. self.data contains # the raw data sent to our UDP socket. if self.callbackManager: #self.oscServer.sendOSCUDP("/NSLOG_REPLACE", "self.srcPort") self.callbackManager.handle(packet_data) except socket.error, e3: err = e3.args[0] if err == errno.EAGAIN or err == 10035: return else: # a real error occured print e3 print "Connection closed by remote end" #self.oscServer.sendOSCUDP("/NSLOG_REPLACE", ("CONNETION CLOSED BY REMOTE", str(e3))) self.rxset.remove(self.conn) self.conn.close() self.connected = 0 self.listening = 1 self.conn = None except Exception, e2: pass def setCallbackManager(self, callbackManager): """ You can specify a callbackManager here as derived from OSC.py. We use this function in OSCServer to register the default /remix/ namespace addresses as utility callbacks. """ self.callbackManager = callbackManager def bind(self): """ After initializing you must UDPServer.listen() to bind to the socket and accept whatever packets are in the buffer. Since we're binding a non-blocking socket, your program (and Ableton Live) will still be able to run. """ self.addr = (self.src,self.srcPort) self.TCPSock = socket.socket(socket.AF_INET,socket.SOCK_STREAM) self.rxset = [] self.txset = [] self.connected = 0 self.listening = 0 #self.TCPSock.setblocking(0) port_add = 0 while True: try: self.TCPSock.bind((self.src,self.srcPort+port_add)) self.TCPSock.listen(1) except: port_add += 1 port_add = port_add % 10 else: self.srcPort = self.srcPort + port_add print "listening on port", self.srcPort self.oscServer.sendOSCUDP("/script/port_changed", self.srcPort) self.listening = 1 break def send(self, data): """ If we have data to send, send it, otherwise return. """ length = len(data) type = 2 tag = 0 # Only send if we have data. if not data == '' and self.conn != None: data_to_send = '' + OSC.OSCArgument(length)[1] + OSC.OSCArgument(type)[1] + OSC.OSCArgument(tag)[1] + data #data_to_send.append(data) try: self.conn.send(data_to_send) except socket.error, e: err = e.args[0] if err == errno.EPIPE: pass data = '' def close(self): """ Close our UDPSock """ # Closing time! if self.conn != None: self.conn.close() self.TCPSock.close()