Expert Sleepers MIDI & OSC Scripting Manual v1.1.
Copyright © 2009 Expert Sleepers. All rights reserved. This manual, as well as the software described in it, is furnished under licence and may be used or copied only in accordance with the terms of such licence. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Expert Sleepers. Expert Sleepers assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.
Contents MIDI & OSC Lua scripting 5 Learn by example 5 Share your scripts! 5 Script locations 6 Mac OS X Windows 6 6 Overriding the default script 6 MIDI & OSC Script Functions 6 getParameterID( param ) getParameter( param ) setParameter( param, value ) getParameterMinMax( param ) getParameterUnit( param ) getParameterName( param ) isParameterUsed( param ) getNumParameters() setOthersParameter( id, param, value ) getOthersParameter( id, param ) sendOSC( address, path [, format ] [, values ] )
setGUIBoolValue( id, value ) getGUIBoolValue( id ) setOthersGUIBoolValue( other, id, value ) getOthersGUIBoolValue( other, id ) registerOSCPathForParameter( path, param ) registerOSCPathForParameterNormalized( path, param ) 12 12 12 12 12 12 Pre-defined Global Values 12 Debugging 13 Mac OS X Windows 13 13 Version History 14 Contact 15 Acknowledgements 16 Lua 16 oscpack 16
MIDI & OSC Lua scripting For most Expert Sleepers plug-ins it is possible to extend the plug-in’s MIDI & OSC functionality via user-writeable scripts. Indeed, the plug-in’s standard MIDI functionality is usually implemented using such a script, which you can use as reference for your customisations. Refer to the user manual of the individual plug-ins for information on their particular scripting implementation. The language used for the MIDI scripts is Lua.
Script locations The plug-in looks for MIDI & OSC scripts in standard locations. Scripts must have the filename extension “.lua”. Mac OS X The plug-in looks for scripts in Library/Application Support/Expert Sleepers//Scripts E.g. Library/Application Support/Expert Sleepers/Oomingmak/Scripts Windows The plug-in looks for scripts in C:\Documents and Settings\\Application Data\Expert Sleepers\\Scripts E.g.
getParameter( param ) Returns the value of the plug-in parameter. ‘param’ can either be the parameter name or the parameter ID (as returned from getParameterID()). Using the ID is more efficient. Typically you would obtain the ID in the main script body (which is only executed once) and then use it in a handler function (which can be called many times). E.g. pitch = getParameter( “Pitch” ) pitch = getParameter( paramID_Pitch ) setParameter( param, value ) Sets the value of the plug-in parameter.
The ‘id’ is matched against the OSC Port Offset of the plug-ins. Any plug-in that matches the id will have its parameter set. Note that all the plug-ins must be loaded by the same host application. For controlling instances of the plug-in loaded by other hosts, or running on other computers, use the ‘sendOSC’ command (below). E.g. setOthersParameter( 2, paramID_Pitch, 12.0 ) getOthersParameter( id, param ) As getParameter(), but gets the parameter from another instance of the plug-in.
requestAllCC( function ) Request that the given function be called in response to any MIDI continuous controller (CC) event. E.g. local function handleCC( channel, cc, value ) -- do stuff end requestAllCC( handleCC ) requestAllNRPN( function ) Request that the given function be called in response to any MIDI non-registered parameter number (NRPN) event. E.g.
local function handleNoteOff( channel, noteNumber, velocity ) -- do stuff end requestNoteOff( 60, handleNoteOff ) requestCC( cc, function ) Request that the given function be called in response to the given MIDI continuous controller (CC) event. E.g. local function handleCC( channel, cc, value ) -- do stuff end requestCC( 20, handleCC ) requestNRPN( nrpn, function ) Request that the given function be called in response to the given MIDI non-registered parameter number (NRPN) event. E.g.
requestChannelPressure( function ) Request that the given function be called in response to a MIDI channel pressure (aftertouch) event. E.g. local function handleChannelPressure( channel, value ) -- do stuff end requestChannelPressure( handleChannelPressure ) time() Returns a value in seconds. The value itself is not particularly meaningful, but if you call it twice and subtract the two values you will have the time interval between the two calls. E.g.
setGUIBoolValue( id, value ) Sets a value that can be picked up by GUI objects. ‘id’ is a number between 0 and 7. ‘value’ is interpreted as a boolean value (true or false). See the GUI script method indicator() for a typical usage. getGUIBoolValue( id ) Gets one of the values that can be set with setGUIBoolValue(). ‘id’ is a number between 0 and 7. setOthersGUIBoolValue( other, id, value ) As setGUIBoolValue() but sets the value on other instances of the plug-in - see setOthersParameter() above.
• • • minorVersion dotVersion version The plug-in’s version number is of the form x.y.z (e.g. 2.1.4) where x is the major version number, y is the minor version number, and z is the dot version. The ‘version’ global variable contains a single value combining all three e.g. for version 2.1.4, ‘version’ is 20104.
Version History 1.1.0 27/7/2009 • Added registerOSCPathForParameter() and registerOSCPathForParameterNormalized(). 1.0.0 19/5/2009 • Initial version.
Contact The Expert Sleepers website is here: http://www.expert-sleepers.co.uk/ Or you can email info@expertsleepers.co.uk Or you can use the forum, which is here: http://www.kvraudio.com/forum/viewforum.
Acknowledgements The software described in this manual makes use of the following open source projects. The author is greatly indebted to them for their efforts and generosity. Below are reproduced the various copyright notices and disclaimers that accompany these software projects, in accordance with their terms of use. Lua Copyright (C) 1994-2008 Lua.org, PUC-Rio.
