Scripting Language

Why use scripts?

In Usine, you can resolve almost any problem using modules. But sometimes it can lead to complicated or very repetitive patches, which can be very time consuming to change or update.

For example:

  1. Dealing with arrays (especially when their size is variable)
  2. Dealing with MIDI data
  3. Doing data loops with repetitive iterations and logical conditions
  4. Doing complex maths
  5. Etc…

This is where the scripting language comes in useful.

Limitations

Scripts can process audio, but the CPU usage is very high. However for most data, MIDI and text use they will be perfect.

If you want to manipulate audio, you should consider using the C++ SDKto build your own modules.

Open a scripting window

A script is a text document you can edit in any basic text editor (wordpad, etc…).

Unlike word processor programs, a text editor saves text without any formatting or other data in the file, just like in the “plain text” format word processors can save to.

In Usine patch window, drag and drop an “empty script” module (located in the “scripts” folder).

Double click on the module, the scripting window opens:

There you have a file menu to save or load your scripts, an edit menu for copying, pasting and so on, and a script menu to compile your script when it’s ready for testing or using.

Below you have two tabs:

  • Script to process: there you write your script or copy and paste from a text document.
  • Help: a list of the most important types, functions and procedures you can use.

You also have a basic skeleton of the script structure:

  • title
  • Parameters declaration
  • Initialisation procedure (surrounded by the keywords “begin” and “end”;)
  • Global variables
  • Main script procedure (surrounded by the keywords “begin” and “end.”).

Compilation

When you have finished writing your script just click OK to compile it and create your module.

Basic concepts

Basically by when you write and compile a script, you build a module of your own, with its own inlets and outlets, and its own way to process data.

So before creating a script you just have to plan which inlets you need, which outlets, and how the data is processed inside.

It’s also important to figure what kind of inlet-outlet you need (will it be a fader, a switch, a MIDI input, or anything), and its properties: scale, minimum-maximum value, number of decimals (precision), default value, etc…

Some precision about the “type” of an inlet-outlet: actually if you choose your input to be a fader, you can still plug a switch or anything to it, but choosing the type of an inlet-outlet defines two things:

  • What the input will expect: if your inlet is a button for instance, it will expect

values either 0 or 1, if it’s a MIDI inlet, it’ll expect MIDI (but you can still plug something else if you want to obtain weird results), etc…

  • The kind of “interface design” module Usine will create when you drag a wire from

this inlet-outlet. If your inlet is a MIDI note fader for instance, when you drag a wire from it Usine will create a MIDI note fader.

For example, I could create a simple A+B script to add only integers between 1 and 10, (it’s totally useless, since the A+B module already exists in Usine): for this I would need to create an inlet labeled “A”, with a precision of 0 decimals (integer), a min value of 0, a max of 10, a linear range, and this inlet would be a fader. Same for the “B” inlet. I would need also an outlet let’s call it “sum”, precision 0 decimals.

Then inside the script, I would need to access the values of my inlets, store them into variables, compute the sum, and send the sum to the outlet.