Scripting - bare bones minimum docs

OK - I know some people are keen to experiment with scripting — unfortunately the documentation is not even close to being ready for any serious learning. However, I have put an introductory document online along with the current system functions that are available. The language itself is still changing (which is why documentation is also in flux) although I’m getting closer to a point where I’m starting to be happy with it.

In case you’re wondering, GPScript is proprietary. After looking at numerous existing scripting languages (Lua, Python, Chaiscript and other such things), I decided that (a) I didn’t want a language that used C-style syntax so (b) I hated them all and (c) more seriously, I wanted a language that “knew” about Gig Performer.

So for example, in GPScript, you can declare an integer variable as follows:
var tranposeAmount : integer
and a statement such as
tranposeAmount = 2

but if you have a MidiIn Block in Gig Performer called A800 (e.g. a Roland MIDI controller) you can write
var A800 : MidiInBlock

You can then write code like this:

On NoteEvent (m : NoteMessage) from A800
   SendNow(A800, Tranpose(m, tranposeAmount))

which will transpose all incoming notes by 2 semitones.

Please understand that this stuff is seriously in flux. While scripting is most certainly working, I am reserving all rights to tweak the syntax and to change (add/remove) system functions at will based on how we see things moving forward. Although it might, do not expect that any script you write today will work in a month :slight_smile:

Edit: June 2022 - GP 4.5 documentation is available

View introduction document

View system function list

Thanks David for this short GPScript tutorial and the documentation!! That’s really awesome… seeing endless possibilities for my next gigs.

I already know how I’ll spend the day tomorrow… :wink:

OK, but per the caveats (and the NDA!), you should not use anything in Gig Performer 2 for “real” gigs — lots of ways for it to crash right now, specially once you start playing with scripting.

Sorry for the spoiler but we’re serious about this. Last thing we need is for users to use beta software in a live situation, have it crash, and consequently give the software a bad name.

Don’t worry. I didn’t mean playing gigs with GP2 but rather going deeply into GPScript and checking out some things that might be helpful for a potential live setup in the future. The best thing to test if a concept or function works (for me) is to prepare some real world usecases that I could use later when everything will be stable and public.

David, I saw your documentation in the forum.

Will it be possible to observe the global metronome
and switch varations at specific bars?

This way switching variations could be automated and you can concentrate on
playing the correct notes without taking care of switching the correct varaition at the correct time.

In earlier times I did that with Ableton and sendung progam changes to GigPerformer.

Yes, we will be adding another callback to GPScript specifically for this. It will look something like this:

on beat(currentBeat…)
// do something on the beat

Not exactly sure what the TYPE will look like at this point but probably something that lets us get at the bar beat and possibly the subbeat

Adding Scripting to GP2 is the game changer for me. Quick question - if using SendNow or other midi events, does it add any additional latency or delay, particularly if there are a number of SendNow events happening for a note event?

Of course it does. To quote Robert Heinlein, TANSTAAFL

David is right of course, but I would be VERY surprised if you could actually be able to tell that there is additional processing going on.
If something took 1ms to complete and now it may take 2ms you are absolutely not be able to tell the difference, but there will be 1ms latency added :slight_smile:

GPScript is going to be as efficient as possible, integrated into GP completely and not some kind of “glued on” functionality. This alone will most likely make it as efficient as it can get.

As long as the food is good I don’t mind paying.

It’s not going to be cheap but it will be very inexpensive.

Works great so far.

David, could you maybe post some little code examples to see a bit more about the syntax (for/while loops/conditions)?

  var note : NoteMessage

  note = MakeNoteEventEx(61, 80, 1)
  SendNow(A800, note)

  note = MakeNoteEventEx(61, 0, 1)   
  SendLater(A800, note, 2000)

Is it possible to access single values/elements of objects like NoteMessage? Something like note.velocity = 0?
Is there (already) an array implementation where we could save incoming note events or create a map with different chord types to trigger?

And do you maybe consider to give a possibility to separate multiple scripts into blocks instead of having one global large script? It would be cool if we could create MIDI processing blocks with input and output that would do single jobs like “Transpose an octave down” or “Convert melody to triads” and that could be inserted between MIDI In blocks and instruments. Would highly improve the reusability of certain scripts :slight_smile:

But already now it’s really powerful.

if expression

(The ‘else’ clause is optional and note that you don’t need parentheses around the expression)

while expression do
for assignment ; expression ; assignment do


var i : integer;
for i = 0; i < 20; i = i + 1 do

Please look at the system function list ( that I mentioned originally. You will find functions such as





   m : NoteMessage

m = WithNoteNumber(m, 42)  // Change the note number to 42

Again, all this stuff is subject to change as we see how you guys use it

Yes, there are arrays but they’re still limited to a few types

You can currently write things like

   a : integer[3]  // An array with 3 values in it
   a[0] = 42; // Etc

There is also a notion of a dynamic array for passing arrays of different sizes to functions, e.g.

function foo (x : integer array)
   Print ( Size(x) ) // Print the current size of this array in the script logger window

I think I have implemented arrays for integers, doubles and widgets so far :slight_smile:

Also, arrays have a maximum size of 128 for now.

And do you maybe consider to give a possibility to separate multiple scripts into blocks instead of having one global large script

Not instead of but the plan is to have something I call a “splugin” (Nebojsa will come up with a better name) which will be a plugin containing a script that will run when MIDI data arrives. It will have all sorts of interesting features :slight_smile:

Sounds good!

Thanks for the coding hints. That’s what I was looking for :slight_smile:

Yeah, I’m sorry this stuff is dribbling out so slowly — while the basic scripting system has been around for some months, I’ve been very distracted with other stuff (currently completely overhauling the OSC system) so GPScript has been sort of sidelined. We know how important GPScript will be to some users.

Much appreciated under the hood functions are yet another reason why I’m so in love with your program David!!!


Trying to figure out how to learn gp script. When I click on the link (View introduction document) It takes me to a page that says its no longer available. Has this changed to a different location?
Im just trying to get as much information as I can to begin to learn how to use gp script…

Thanks in advance for any assistance.