Kunquat Events

h2. Summary

This specification contains information on different Event types that need to be implemented in Kunquat. An Event marks a change in the state of the player at some point in time. These changes include, for example, start/release of a note, note volume change and a tempo change. Some Events control the playback of one note (e.g. pitch slide), some control the playback of the entire song (e.g. tempo change or a jump), and some may control the behaviour of other Events (possibly interactivity events -- see [Kunquat Interactivity Features] for more information).

Creating new Events involves specifying the internal structures of the Events and implementing the intended behaviour in the mixing routines. Global Events usually affect Pattern mixing code and note Events affect mixing code of all Instruments that need to support the Event.

h2. Rationale

As of 2009-02-25 Kunquat features two Event types: Note On and Note Off. This is sufficient for describing the basic structure of a melody. However, since a goal of Kunquat is to provide power for describing musical _performance_ as intended to be heard, the composer must be able to describe the performance in a much more detailed way. This includes specifying ornamentation of melody and specifying dynamics, among others.

h2. Use Cases

h2. Event Types

h3. Global Events

h4. Set Tempo

Set Tempo changes the tempo.

Parameters:

* The new tempo in BPM (beats per minute).

h4. Set Global Volume

Set Global Volume sets a new Global Volume. This affects all active Voices immediately.

Parameters:

* The new Global Volume in dB.

h4. Jump

Jumps to another position in the Song. Events occurring at the same time will be processed only inside the Global Column.

FIXME: How should we handle jump to next Order? (Typically, trackers have separate "Jump to Order" and "Jump to next Pattern at position _x_") Maybe we don't need it!

Parameters:

* The new subsong.
* The new position in the section list.
* The new Pattern position.

h3. Note Events

h4. Note On

Note On specifies the start of a new note.

Parameters:

* Note (without octave definition)
* Note modifier (accidental)
* Octave number
* Instrument number

h4. Note Off

Note Off specifies the start of the release phase of a note. This typically triggers a fade-out of some sort.

Note Off does not require parameters -- it releases the note triggered by the previous Note On in the Column. If there is no such note, Note Off does nothing.

h4. Set Force

Set Force is used to set the Force of a note.

Parameters:

* The value of the force in dB.

h4. Slide force

Slide force slides the force of a note.

At least a logarithmic slide should be provided. A linear slide might also be useful (e.g. when sliding to/from silence, although a silence threshold may be better).

Parameters:

* Target force in dB.
* Duration of the slide in beats (would specifying speed be better in some cases?).

h4. Tremolo

Tremolo oscillates the force of a note.

The oscillation waveform is a sine wave. Other waveforms are probably not important.

Paremeters:

* Speed of the tremolo in cycles per beat.
* Depth of the tremolo in maximum deviation from the mean force (in dB).

h4. Pitch Slide

Pitch Slide slides the pitch of a note.

Parameters:

* Target note.
* Target note modifier.
* Target octave.
* Duration of the slide in beats (would specifying speed be better in some cases?).