[Linuxsampler-devel] some progress on instrument scripts

[Christian S. <sch...@li...>]

Hi there!

Some progress on the real-time instrument script front:

	http://download.linuxsampler.org/pix/screenshots/gigedit_script_3b.jpg

The first instruments scripts are finally running with the gig format sampler 
engine. In the screenshot you see an example script with gigedit's new script 
editor which fires new notes (with different samples than the main notes were) 
if the player exceeds a certain channel aftertouch limit.

Current state:

	- The script language: if you worked with Kontakt before, then you 
	  should be familiar with this script language right away. If not, you 
	  can have a look at the source directory src/scriptvm/examples for some 
	  basic core language script examples. The language is really easy.

	- Scripting feature is currently only working with the gig format yet. I 
	  added a LinuxSampler specific extension to the original Gig file format 
	  for storing instrument scripts to .gig files by using gigedit. 
	  Obviously if you store scripts to gig files, they will not load with 
	  the original GigaStudio 4 software of course.

	- Adding scripting to the SFZ engine is easy. Involves probably only 
	  adding 10 lines of code or so. It probably just requires a new opcode 
	  for referencing script files. Since I am no expert regarding the SFZ 
	  format, I wait for others to come up with comments how to extend the 
	  SFZ file format with a new opcode. Or maybe some company already 
	  introduced a scripting opcode, no idea.

	- gigedit does not yet transfer scripts to the sampler in live-mode. That 
	  is, each time you alter a script with gigedit, you have to force the 
	  sampler to reload the instrument with the new version of the script.

	- gigedit's script editor is yet very very primitive. It has some basic 
	  keyword syntax highlighting, but that's pretty much it. My plan was to 
	  hook the editor up with the sampler's internal script parser, so that 
	  i.e. parser warnings, parser errors, keywords, variables, built-in 
	  variables and built-in functions are always marked up in the editor 
	  correctly (similar like today's C++ IDEs are hooked up with clang).
	  Updating this with the sampler parser could be done in real-time while 
	  typing, because it parses instrument scripts in few milliseconds.

	- Scripts are handled with the gig format now similar to samples. That is 
	  scripts are stored in file global space, and you can then reference 
	  individual scripts from gig instruments. You do that by right clicking 
	  on an instrument in gigedit's instrument tree tab, then select "Edit 
	  script slots..." and drag a script from the new script tree tab to the
	  script slots window of the instrument. Note that even though you can 
	  already create more than one script slot per instrument, LinuxSampler 
	  will currently only execute the 1st script slot of each instrument yet. 
	  If you create more than one slot, the sampler will show you a warning 
	  on the console when you load the scripted instrument.

	- Script suspension: the ScriptVM engine suspends your script from 
	  execution if you call the buit-in "wait()" function. This function 
	  takes one argument which defines the sleep time in microseconds. 
	  However the latter is not yet implemented in the sampler. The script 
	  will simply be resumed in the next audio cycle for now.

	  Then scripts should be suspended automatically by the sampler if they 
	  executed too long and would thus threaten the sampler's real-time
	  requirements. I haven't implemented that either yet. The question is 
	  how should that decision be made exactly? Counting ScriptVM 
	  instructions? Comparing real time stamps? Having said that, be careful 
	  when you write while loops in your scripts. If you write an endless 
	  loop in you script without wait() call, the sampler will currently 
	  hang forever.

	- String type variables in scripts: all string type operations are *NOT* 
	  real-time safe ATM! Use string variables and operations like string 
	  concatenation, cast from int to string and message() function calls 
	  just for debugging purposes of your script. Otherwise you might get 
	  dropouts. You can use the preprocessor feature to switch your scripts 
	  from debug to normal mode. So if you pack your string variables and 
	  operations into appropriate preprocessor statements, you can 
	  enable/disable all of them at any time by changing just one line.

	  I wonder how Kontakt addresses strings. Whether they are real-time 
	  safe? Not sure if its worth it to address this issue at all.

	- Built-in script functions and variables: The plan is to implement all 
	  functions and variables regarding MIDI processing which you might 
	  already know from the mentioned sampler. I am personally not interested 
	  in  implementing the ui_* set of functions right now.

	  I made some of the functions not as strict as in Kontakt. That is, many 
	  functions will accept a variable amount of arguments. For example
	  you can also use the play_note() function with only two arguments. For 
	  the remaining arguments, the sampler will simply used default values 
	  (if it makes sense, depends on the function of course).

	  Additionally I started to add the first gig format specific variables 
	  and functions, which you can also find in the screenshot. They are 
	  required to deal with the special features of the gig format by script.

	- ls_instr_script: This is a new command line tool. I basically used it 
	  for  debugging the parser. You can pipe in instrument scripts (or copy 
	  paste it), it will parse them, show you any parser errors, warnings in 
	  ... now hold your breath ... *in* *color* ... wooow ;-).

	  And if you are running the tool in "core" language mode, you can even 
	  execute the scripts from the command line. You might use this probably 
	  sometimes until i.e. gigedit script editor is hooked up with the 
	  samplers script parser one day. Or maybe not ;-) Thats up to you.

If it it's not yet clear to you already: this is *bloody* *bleeding* *edge* 
yet. Backup your files, expect crashes, grab you life vest, etc.

David, sorry that I decided for another route. But Andreas had already some 
basic KSP Bison parser hanging around on his disk, so it was too tempting to 
pickup his Bison approach for this scripting feature. ;-)

Questions, comments?

CU
Christian