The Kyma Language for Sound Design, Version 4.5

Scripting
MIDI Scripts
There are two different kinds of scripts in Kyma: Event Value-generating scripts (found in the MIDIVoice
and the MIDIMapper Sounds), and Sound-constructing scripts (Scripts and FileInterpreters).
MIDIVoice and MIDIMapper scripts provide an algorithmic way to generate events indistinguishable
from events coming from a MIDI file or a MIDI device. You can use these scripts to generate control signals
or note events algorithmically. MIDI scripts are intended to replace the older scripting Sounds in
applications that model an “instrument” playing from a “score”.
MIDIVoice and MIDIMapper scripts do not run in real time. When you compile a MIDI script, the script
is executed first and the generated events are saved. Then the remainder of the Sound is compiled and
loaded along with the events saved from the script. When you start the Sound, the generated events will
be started at the appointed time.
The Script and FileInterpreter Sounds construct new Sounds that are combinations of Mixers and
TimeOffsets. Scripting Sounds do not generate events. Instead, they assist you in the process of building
Sounds the way you would build them in the graphic Sound editor. When there is a describable pattern
to the Sound parameters and the way the Sounds are put together, you can use a scripting Sound to construct
complex Sound structures automatically. For example, say you wanted to construct a reverberation
algorithm out of six ReverbSection Sounds, each with a slightly different DecayTime and Delay. Using a
scripting Sound, you could use a loop to construct a Mixer of ReverbSection Sounds, each with its own
DecayTime and Delay. That way, you could save time by writing a single loop instead of setting all
twelve parameters by hand.
When you compile a scripting Sound, it first constructs the equivalent combination of Mixers and
TimeOffsets; then it compiles, loads and starts that automatically-constructed Sound.
The MIDIVoice and MIDIMapper modules give you three choices for the source of MIDI events: the live
MIDI input stream (originating from external controllers, or from a sequencer or other software running
in parallel with Kyma), a MIDI file stored on disk, or a script (which generates events algorithmically and
then emits them). To the Kyma Sound, events coming from a script are indistinguishable from events
coming from a MIDI file.
There are two main ways of working with the MIDI scripts:
1. Creating low-level notes and controller events at specific times
2. Creating and manipulating high level EventCollections: combinations of Note and Rest objects
Creating Notes and Controller Events
The syntax for a basic note event is:
self keyDownAt: aTime duration: aDur frequency: aFreq velocity: aVel.
Where aTime is a time specified with units (for example, 1 s or 2 beats), aDur is a duration specified
with units, aFreq is a frequency specified with units (for example, 440 hz, 60 nn, or 4c), and aVel is a
velocity value between 0 and 1. The duration:, frequency:, and velocity: tags are optional, the
default values are 10 ms, 0 nn, and 1, respectively.
For example, to send a note event for a middle C lasting for one second, you would use:
self keyDownAt: 0 s duration: 1 s frequency: 4 c.
Note events cause the following to happen:
♦ At the given time, !KeyDown is set to -1.
♦ After 5 ms, !KeyDown is set to 1, !KeyNumber is set to the pitch equivalent of the frequency, and
!KeyVelocity is set to the velocity value.
♦ After the given duration has passed, !KeyDown is set to 0.