[ << General input and output ]	[Top][Contents][Index]	[ Spacing issues >> ]
[ < MIDI channel mapping ]	[ Up : Creating MIDI output ]	[ Enhancing MIDI output > ]

---

3.6.8 Context properties for MIDI effects

The following context properties can be used to apply various MIDI effects to notes played on the MIDI channel associated with the current staff, MIDI instrument or voice (depending on the value of the Score.midiChannelMapping context property and the context in which the Staff_performer is located; see MIDI channel mapping).

Changing these context properties will affect all notes played on the channel after the change, however some of the effects may even apply also to notes which are already playing (depending on the implementation of the MIDI output device).

The following context properties are supported:

Staff.midiPanPosition

The pan position controls how the sound on a MIDI channel is distributed between left and right stereo outputs. The context property accepts a number between -1.0 (#LEFT) and 1.0 (#RIGHT); the value -1.0 will put all sound power to the left stereo output (keeping the right output silent), the value 0.0 (#CENTER) will distribute the sound evenly between the left and right stereo outputs, and the value 1.0 will move all sound to the right stereo output. Values between -1.0 and 1.0 can be used to obtain mixed distributions between left and right stereo outputs.

Staff.midiBalance

The stereo balance of a MIDI channel. Similarly to the pan position, this context property accepts a number between -1.0 (#LEFT) and 1.0 (#RIGHT). It varies the relative volume sent to the two stereo speakers without affecting the distribution of the stereo signals.

Staff.midiExpression

Expression level (as a fraction of the maximum available level) to apply to a MIDI channel. A MIDI device combines the MIDI channel’s expression level with a voice’s current dynamic level (controlled using constructs such as \p or \ff) to obtain the total volume of each note within the voice. The expression control could be used, for example, to implement crescendo or decrescendo effects over single sustained notes (not supported automatically by LilyPond).

The expression level ranges from 0.0 (no expression, meaning zero volume) to 1.0 (full expression).

Staff.midiReverbLevel

Reverb level (as a fraction of the maximum available level) to apply to a MIDI channel. This property accepts numbers between 0.0 (no reverb) and 1.0 (full effect).

Staff.midiChorusLevel

Chorus level (as a fraction of the maximum available level) to apply to a MIDI channel. This property accepts numbers between 0.0 (no chorus effect) and 1.0 (full effect).

Known issues and warnings

As MIDI files do not contain any actual audio data, changes in these context properties translate only to requests for changing MIDI channel controls in the outputted MIDI files. Whether a particular MIDI device (such as a software MIDI player) can actually handle any of these requests in a MIDI file is entirely up to the implementation of the device: a device may choose to ignore some or all of these requests. Also, how a MIDI device will interpret different values for these controls (generally, the MIDI standard fixes the behavior only at the endpoints of the value range available for each control), and whether a change in the value of a control will affect notes already playing on that MIDI channel or not, is also specific to the MIDI device implementation.

When generating MIDI files, LilyPond will simply transform the fractional values within each range linearly into values in a corresponding (7-bit, or 14-bit for MIDI channel controls which support fine resolution) integer range (0-127 or 0-32767, respectively), rounding fractional values towards the nearest integer away from zero. The converted integer values are stored as-is in the generated MIDI file. Please consult the documentation of your MIDI device for information about how the device interprets these values.