MSL Sustain/Long Press and Multiclick Documentation Request

Albert

Hi everyone,

I've been exploring the new MSL scripting language and really enjoying the cleaner syntax with braces and more C-like structure. However, I'm trying to convert some of my MOS scripts that use sustain/long press and multiclick functionality, and I can't find any documentation on how to implement these features in MSL.
In MOS, I'm using:

!sustain 500
!multiclick 250

Label sustain
  if sustainCount = 1
    Reset
  endif
end

Label click
  if clickCount = 2
    Undo
  endif
end

This gives me long press behavior (hold for 500ms to reset) and double-click detection (two presses within 250ms to undo).

My questions:

Is sustain/long press functionality implemented in MSL yet? If so, what's the syntax?
How do we handle multiclick in MSL? Is there an equivalent to the !multiclick declaration and clickCount variable?

Are there MSL equivalents for:

Label sustain and Label endSustain
sustainCount variable
Label click and Label endClick
clickCount variable

If these features aren't implemented yet, is there a timeline for when they might be available? Should I stick with MOS for scripts that need this functionality for now?

I've searched through the forum and documentation but haven't found any examples of MSL scripts using these features. Any examples or pointers to documentation would be greatly appreciated!
Thanks for any help!

jeff

This is a lot to digest, but here is the script I use for sustain and multi-click testing and use as a reference. I'll break it down later.

#name Repeat and Sustain Me
#repeat
#sustain

print "Starting"

function OnRepeat(repeatCount repeatDelta repeatElapsed) {
  print ("Repeat " repeatCount repeatDelta repeatElapsed)
}

function OnTimeout(repeatCount repeatElapsed) {
  print ("Timeout " repeatCount repeatElapsed)
}

function OnRelease (sustainCount sustainElapsed) {
  print ("Going up after" sustainCount sustainElapsed)
}

function OnSustain(sustainCount sustainElapsed) {
  print( "sustain" sustainCount sustainElapsed)
}

jeff

To get what MOS did with !sustain you now use #sustain. Like !sustain, #sustain can be followed by a millisecond number which is how long you want to wait between notifications.

When the trigger is held longer than this number, the function named OnSustain is called, this is equivalent to the old "Label sustain".

If you keep holding the trigger down, OnSustain may be called multiple times, and each time the value of the sustainCount argument will be 1 larger.

When you finally release the trigger the OnRelease function is called. Defining that is optional if you're not interested in release behavior.

jeff

To get what MOS called !multiclick you now use #repeat. In the example this is combined with #sustain, but you can use it by itself if you don't need sustain notifications.

What #repeat scripts do is keep the script in a sort of suspension after it runs once, so that if another trigger comes in, it resumes the previous script and calls the OnRepeat function rather than the main body of the script. This is equivalent to what MOS called "Label click". OnRepeat receives three arguments: the number of repeats that have been received so far, the number of milliseconds between the current click and the last one, and the total number of milliseconds from the current click to the first one.

The script will suspend waiting for repeat notifications until it times out, the length of this timeout defaults to 1 second but can be adjusted with....I'm forgetting that, need to check some notes. If you do not push the trigger another time before this timeout ends, the function OnTimeout is called and the script completely ends.

alexs1

jeff

Hey, Jeff,

Can you help me out with the #repeat function?

`#name Track Record/Overdub/Mute
#repeat

if mode == "reset"
Record

else if mode == "record"
Record

else if mode == "Play"
Overdub

else if mode == "overdub"
Overdub

function OnRepeat(1 1000 1000)
Mute

function OnTimeout()`

Here's my grasshopper attempt to use it in a script. The idea is that tapping once (before 1 second) will execute the Record/Overdub functions, and double tapping (twice within one second, while mode == :play) Mutes the track (without going into overdub while mode == :play).

Albert

Ah, thanks! that really helps!

jeff

A digression on function arguments...

Functions with special meaning to the system like OnSustain, OnRepeat are passed positional arguments. You can reference the arguments using positional references like $1 and $2, or you can give them names and reference them by name like sustainCount and sustainElapased. I chose to use those names to make it clearer what they are, but you can use any name you want. These forms are equivalent:

function OnRepeat(repeatCount repeatDelta repeatElapsed) {
  print ("Repeat " repeatCount repeatDelta repeatElapsed)
}

function OnRepeat(x y z) {
  print ("Repeat " x y z)
}

fuction OnRepeat {
   print ("Repeat " $1 $2 $3)
}

Typically, the most interesting argument is passed first, so if that's the only one you need you don't have to declare the others:

function OnRepeat(count) {
  print ("I've been clicked" count "times")
}

The built-in function print assembles a string by combining the values of all of its arguments, putting a space between them, and sending the result to the script console. So to use a script with print calls in them you will want to have the console window open. This is useful when debugging scripts.

benT

Is there a way to check how many/which arguments are provided, and let the function only use those?

jeff

This would be what most languages call the "function signature". MSL doesn't have "include files" for system functions that you can look at, so it's a documentation issue. One of the larger side-projects happening in the background is a revamp of how the documentation is made available on the web, so in the near future I would imagine a System Function Reference that describes all that with words.

Beyond that, it would be handy if the script editor had some built in way to pop-up help text showing you the function arguments after you type in a name, but that's a longer term goal. We'll start by just having adequate documentation.

As far as "only use those"...you only need to declare the ones you want to use in the function definition, but they have to be in order so it isn't as flexible as it could be. I'm looking at a few options here, like automatically having function arguments referenced by name without needing to declare them, so instead of this:

function OnRepeat(repeatCount) {
   print repeatCount
}

You could just write:

function OnRepeat {
  print repeatCount
}

You still have to know that within the body of a function named OnRepeat that the symbol named repeatCount will have a value, which is where the documentation is still necessary.

benT

I was thinking more like a workaround for not having lists or arrays - let’s say I want to make a custom shuffle function, like the one you already have. Is there a way to call a function with different number of arguments each time, ie write

customShuffle(1,2,3,4,1,1,1,2)

Or
customShuffle(1,2,3,1,1,2)

And let the function work out how many arguments were provided and how to use those (test if argument/variable exists/is set), or iterate over all of the provided arguments.

Use case here could be different number of arguments for 3/4 or 4/4 time signature for instance, or having flexibility for different songs and setups without making new functions every time…

jeff

Ah, varargs. Functions can be called with any number of arguments, even if they don't declare them in their definition. You can reference them with positional references $1, $2, etc.

There are two things missing to make this useful. There isn't a way to know how many arguments were passed. You can sort of do that by testing to see if the value of $42 is greater than zero provided that you only pass non-zero numbers. If you reference an argument that was not passed it is technically "null" which compares to zero if you use it in an equality expression.

Next, there isn't a way to iterate over the arguments using a variable. Example: say there are four arguments passed $1 $2 $3 and $4. In most languages you could do something like this:

   for i = 1 ; i <= numberOfArguments ; i++ {
        print("Argument" i " is " $i )
  }

You would have to do this which is awkward:

  if $1 > 0 {...first arg was passed...}
  if $2 > 0 {...second arg was passed...}

Certainly room for improvement there.

benT

Yes, varargs! 🙂

I tried the approach, which works - but I get unresolved reference error if I do not use all of the arguments. This is of course not so surprising, but would it cause any trouble or can I dismiss it as a warning?

#name varg

function vargtest {
if $1 > 0 {print ("one") }
if $2 > 0 {print ("two") }
}

varg(1)
one
Line 4 column 6: $: Unresolved reference
varg(1,2)
one
two

jeff

First when comparing the mode variable to mode names, capitalization is significant. So all of those quoted strings need to have an initial capital letter, "Reset", "Record", etc.

For the double tap Mute, yeah, there is an interesting problem here.

The main body of the script (all the if..else if... code) will always run the first time you press the button. The OnRepeat function will only run on press 2, 3, etc. but the main part always runs. For scripts like this that swap between modes, those will always happen first before OnRepeat, in this case going from Play to Overdub, before the Mute happens.

There are ways to defer the moving from Play to Overdub, but that would mean that the Overdub would always happen after the timeout (default 1 second) rather than immediately which is probably not what you want. There is a tradeoff here, you can either make the script responsive to single taps, or you have to delay it for a 1/2 second or so to see if any other taps come in during that time.

Ignoring that problem for awhile, you can get the tap-2-Mute behavior like this:

function OnRepeat {
  if repeatCount == 1 Mute
}

That gets you the double tap Mute, but you will see see all the single tap behavior happen first. I played around with deferring the Play->Overdub and it was harder than it should be because there are several states that have to be considered. I'll post that when I get it working, but I first wanted to make sure it was understood that you can't have "single tap but only if not double tap" behavior without deferring everything until after the double tap timeout.

jeff

This raises an interesting feature idea. It might be nice to have an option to always defer running the script until after the double-tap timeout expires, so you can write the script with less contorted logic testing to see where you are and what time it is. Something like this:

#name WaitForDouble
#repeat 500 defer

if repeatCount == 1 {
    // do the double tap stuff
}
else if repeatCount == 0 {
  // do the single tap stuff
}

The extra "defer" means always wait for 1/2 second before deciding what to do. You can accomplish the same thing with a more complicated combination of OnRepeat and OnTimeout, this just makes it easier if you're okay with the action lag.

jeff

It's actually pretty easy to do this deferred multi-click script, so I don't know if I'll add anything new. Here it is...

#name RepTest
#repeat 500

function OnTimeout {
  print(repeatCount + 1 "clicks")
}

The key here is that the main script body doesn't do anything, everything is in the OnTimeout function. The <code>#repeat 500</code> means that it will timeout in 500 milliseconds, then you can use repeatCount to decide what to do. Note that repeatCount is the number of repeats AFTER the first one, so a repeatCount of 0 means the button was pressed once, repeatCount of 1 means two presses, etc.

alexs1

@jeff

Awesome, thanks for the snippets! Knowing the ClickCount translation to repeatCount makes some things easier.

I decided to keep recording on a separate trigger for now. Deferring seems like it could come in handy one day, though, glad it's not too complicated.

alexs1

@jeff

`#name Track Select + Double-Click Mute
#repeat 500

function OnRepeat {
if repeatCount == 1
if mode == "Play"
Mute
}

else if repeatCount == 0 {
SelectTrack
}

function OnTimeout()`

This is the new script I'm testing—first tap selects Track assigned in binding, second tap mutes/unmutes while mode == "Play". Am I on the right track (ha)? In the script log, I see an unresolved symbol error for "repeatCount" and it doesn't seem to work for either first or second press.