Tip: Creating UserActions

Developing Our Action

Step 1
So first we need the spec. Again, this action is going to allow for precise adjustment of Looper’s Speed parameter. What are the steps needed to make this happen?

A. We need a way of specifying which Looper device we want to operate on.
B. We need a way of finding the parameter within Looper that we want to operate on.
C. We need to know the range of the parameter we want to control.
D. We need to figure out how we’ll specify the value we want to set the parameter to. The value range shown in Live is -36.0 to 36.0.

Step 2
Next we need a name for our action. LOOPERSPD x (where x is the speed to set) should work.

Step 3
Next we need to define the basic action in ClyphXUserActions.py. ClyphXUserActions.py covers how to do this, so I’ll just post the code snippets. First we need to edit the dictionary to include our action:
self._action_dict = {#<--DO NOTE REMOVE THIS
'EX_ACTION_1' : 'example_action_one',
'EX_ACTION_2' : 'example_action_two',
'LOOPERSPD' : 'set_looper_speed'
}#<--DO NOTE REMOVE THIS
This defines that our action name will call the function named set_looper_speed. Now we need to define that function. We’ll just create a skeleton (function that doesn’t really do anything) to start with.
def set_looper_speed(self, track, args):
    self._parent.log_message('set_looper_speed called for track=' + str(track) + ' with args=' + args)
This will simply write to Live’s log file when the action is triggered from an X-Trigger. You’ll want to test this out to make sure that it works. To do that, load a new set in Live, create an X-Clip named LOOPERSPD 36.0, trigger it and then look in Live’s log file. Also, save the set. From here on out, every time we change our function, we’ll need to reload the set to test our changes.

Step 4
Now let’s tackle the A part of the spec. ClyphX does part of the work for us by passing the track that the action should apply to. When accessing our action from an X-Trigger, we can use all the common options for specifying the track to operate on. For example, 4/LOOPERSPD 36.0 or “My Track”/LOOPERSPD 36.0. Next, we need to find the Looper device on the track. For this, we’ll assume that Looper is not inside a rack and that we want to operate on the first Looper found on the track. Let’s modify our function to do that:
def set_looper_speed(self, track, args):
    self._parent.log_message('set_looper_speed called for track=' + str(track) + ' with args=' + args)
    looper = None
    for device in track.devices:
      if device.class_name == 'Looper':
        looper = device
        break
    self._parent.log_message('set_looper_speed, looper=' + str(looper))
As a side note, if we planned on creating several actions that applied to Looper, we would break out this Looper locating section into its own function so we could reuse it.

Step 5
Now let’s tackle the B part of the spec. Assuming we don’t know where the Speed parameter is within Looper’s parameter list, we’d have to find it. We actually might as well tackle the C part of the spec at this point too. Let’s modify our function to do that:
def set_looper_speed(self, track, args):
    self._parent.log_message('set_looper_speed called for track=' + str(track) + ' with args=' + args)
    looper = None
    for device in track.devices:
      if device.class_name == 'Looper':
        looper = device
        break
    self._parent.log_message('set_looper_speed, looper=' + str(looper))
    if looper:
      for index in range(len(looper.parameters)):
        param = looper.parameters[index]
        self._parent.log_message(str(index) + ': ' + str(param.name) + ' range=' + str(param.min) + '-' + str(param.max))
We actually got lucky here because the range of the Speed parameter in the API is exactly the same as the range shown in Looper itself. This isn’t always the case. Anyhow, now we’ve got the range (-36.0 – 36.0) and the index of the parameter (5).

Step 6
The D part of the spec is simple since the range in the API is the same as the range shown in Looper, so it’s obvious how we’ll specify the value. Now, we could do some error checking to assert that the value (argument) passed to our function is in the correct range, but it isn’t necessary because we have to use a try/except anyway. We need/want to use a try/except because the argument will be a string (text) and we need to convert it to a float (number). So the function will simply silently fail if an incorrect value or string is passed. This methodology is used a lot in ClyphX, so there are plenty examples. Anyhow, let’s get rid of all the logging and finish up the function:
def set_looper_speed(self, track, args):
    looper = None
    for device in track.devices:
      if device.class_name == 'Looper':
        looper = device
        break
    if looper:
      try: looper.parameters[5].value = float(args.strip())
      except: pass

Step 7
Test the action with a variety of correct (like LOOPERSPD -14.5) and incorrect (like LOOPERSPD 37.8 or LOOPERSPD breakit) arguments to confirm that it works as expected.

You're welcome. I was hoping this would help you achieve what you were looking for it, but also hope that I presented it in a way that will be useful for other people/purposes too.

Hey Stray,

This post is verg useful to me, pretty much the only thing out there that explains this stuff, along with the UserAction file, so thanks for taking the time.
I wanted to edit this function and actually make it a bit easier.
All I want to do is select the looper device (or any other device), so I looked at the LOM documents to find out how to select a device, which is in the song class.
This is what I came up with:


def selbus_one(self, track, args):
self._parent.log_message('selbus_one called for track=' + str(track) + ' with args=' + args)
looper = None
for device in track.devices:
if device.class_name =='Looper':
looper = device
break
if looper:
try: looper.select_device
except: pass

It probably shows that I have no idea what I'm doing, but I keep trying!
Any insight on this? Do I need to mention the song class somewhere?
In the future I want to be able to select my device racks on 3 different busses so i can easily see which FX I'm tweaking, so this would be the first step on understanding how that works.

I've looked at the Dev Set but it doesn't look like something I can use in this situation.
I just want to view a device, like MIDI learning the name of a track so that it switches to that track.
Also in the manual it says that the Dev Track can only be used from an X-Clip but I want to map it to a button through the preferences file.

Ooops...yeah, I meant DEV SEL. Sorry about that.

Not possible AFAIK.