3.5 Creating MIDI output

LilyPond can produce files that conform to the MIDI (Musical Instrument Digital Interface) standard and so allow for the checking of the music output aurally (with the help of an application or device that understands MIDI). Listening to MIDI output may also help in spotting errors such as notes that have been entered incorrectly or are missing accidentals and so on.

MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but require additional software to produce sound from them.

3.5.1 Supported notation for MIDI

The following musical notation can be used with LilyPond’s default capabilities to produce MIDI output;

• Breath marks
• Chords entered as chord names
• Crescendi, decrescendi over multiple notes. The volume is altered linearly between the two extremes
• Dynamic markings from ppppp to fffff, including mp, mf and sf
• Microtones but not microtonal chords. A MIDI player that supports pitch bending will also be required.
• Lyrics
• Pitches
• Rhythms entered as note durations, including tuplets
• ‘Simple’ articulations; staccato, staccatissimo, accent, marcato and portato
• Tempo changes using the \tempo function
• Ties
• Tremolos that are not entered with a ‘:[number]’ value

Panning, balance, expression, reverb and chorus effects can also be controlled by setting context properties, see Context properties for MIDI effects.

When combined with the ‘articulate’ script the following, additional musical notation can be output to MIDI;

• Appoggiaturas. These are made to take half the value of the note following (without taking dots into account). For example;

  \appoggiatura c8 d2.

  The c will take the value of a crotchet.

• Ornaments (i.e., mordents, trills and turns et al.)
• Rallentando, accelerando, ritardando and a tempo
• Slurs, including phrasing slurs
• Tenuto

See Enhancing MIDI output.

3.5.2 Unsupported notation for MIDI

The following items of musical notation cannot be output to MIDI;

• Articulations other than staccato, staccatissimo, accent, marcato and portato
• Crescendi and decrescendi over a single note
• Fermata
• Figured bass
• Glissandi
• Falls and doits
• Microtonal chords
• Rhythms entered as annotations, e.g., swing
• Tempo changes without \tempo (e.g., entered as annotations)
• Tremolos that are entered with a ‘:[number]’ value

3.5.3 The MIDI block

To create a MIDI output file from a LilyPond input file, insert a \midi block, which can be empty, within the \score block;

\score {
  … music …
  \layout { }
  \midi { }
}

The default output file extension (.midi) can be changed by using the -dmidi-extension option with the lilypond command:

lilypond -dmidi-extension=mid MyFile.ly

Alternatively, add the following Scheme expression before the start of either the \book, \bookpart or \score blocks. See File structure.

#(ly:set-option 'midi-extension "mid")

See also

Notation Reference: File structure, Creating output file metadata.

Installed Files: ‘scm/midi.scm’.

Known issues and warnings

There are fifteen MIDI channels available and one additional channel (#10) for drums. Staves are assigned to channels in sequence, so a score that contains more than fifteen staves will result in the extra staves sharing (but not overwriting) the same MIDI channel. This may be a problem if the sharing staves have conflicting, channel-based, MIDI properties – such as different MIDI instruments – set.

Using a midi block with polymetric notation may cause unexpected barcheck warnings. In this case move the Timing_translator from the Score context to the Staff context within the midiblock.

\midi {
  \context {
    \Score
    \remove "Timing_translator"
  }
  \context {
     \Staff
     \consists "Timing_translator"
  }
}

3.5.4 Controlling MIDI dynamics

It is possible to control the overall MIDI volume, the relative volume of dynamic markings and the relative volume of different instruments.

Dynamic marks translate automatically into volume levels in the available MIDI volume range whereas crescendi and decrescendi vary the volume linearly between their two extremes. It is possible to control the relative volume of dynamic markings, and the overall volume levels of different instruments.

Dynamic marks in MIDI

Only the dynamic markings from ppppp to fffff, including mp, mf and sf have values assigned to them. This value is then applied to the value of the overall MIDI volume range to obtain the final volume included in the MIDI output for that particular dynamic marking. The default fractions range from 0.25 for ppppp to 0.95 for fffff. The complete set of dynamic marks and their associated fractions can be found in ‘scm/midi.scm’.

Selected Snippets

Creating custom dynamics in MIDI output

The following example shows how to create a dynamic marking, not included in the default list, and assign it a specific value so that it can be used to affect MIDI output.

The dynamic mark \rfz is assigned a value of 0.9.

#(define (myDynamics dynamic) (if (equal? dynamic "rfz") 0.9 (default-dynamic-absolute-volume dynamic))) \score { \new Staff { \set Staff.midiInstrument = #"cello" \set Score.dynamicAbsoluteVolumeFunction = #myDynamics \new Voice { \relative { a'4\pp b c-\rfz } } } \layout {} \midi {} }

Installed Files: ‘ly/script-init.ly’ ‘scm/midi.scm’.

Snippets: (snippets)MIDI section ‘MIDI’ in Snippets.

Internals Reference: (internals)Dynamic_performer section ‘Dynamic_performer’ in Internals Reference.

Setting MIDI volume

The minimum and maximum overall volume of MIDI dynamic markings is controlled by setting the properties midiMinimumVolume and midiMaximumVolume at the Score level. These properties have an effect only at the start of a voice and on dynamic marks. The fraction corresponding to each dynamic mark is modified with this formula

midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction

In the following example the dynamic range of the overall MIDI volume is limited to the range 0.2 - 0.5.

\score {
  <<
    \new Staff {
      \set Staff.midiInstrument = "flute"
      … music …
    }
    \new Staff {
      \set Staff.midiInstrument = "clarinet"
      … music …
    }
  >>
  \midi {
    \context {
      \Score
      midiMinimumVolume = #0.2
      midiMaximumVolume = #0.5
    }
  }
}

Simple MIDI instrument equalization can be achieved by setting midiMinimumVolume and midiMaximumVolume properties within the Staff context.

\score {
  \new Staff {
    \set Staff.midiInstrument = "flute"
    \set Staff.midiMinimumVolume = #0.7
    \set Staff.midiMaximumVolume = #0.9
    … music …
  }
  \midi { }
}

For scores with multiple staves and multiple MIDI instruments, the relative volumes of each instrument can be set individually;

\score {
  <<
    \new Staff {
      \set Staff.midiInstrument = "flute"
      \set Staff.midiMinimumVolume = #0.7
      \set Staff.midiMaximumVolume = #0.9
      … music …
    }
    \new Staff {
      \set Staff.midiInstrument = "clarinet"
      \set Staff.midiMinimumVolume = #0.3
      \set Staff.midiMaximumVolume = #0.6
      … music …
    }
  >>
  \midi { }
}

In this example the volume of the clarinet is reduced relative to the volume of the flute.

If these volumes properties are not set then LilyPond still applies a ‘small degree’ of equalization to certain instruments. See ‘scm/midi.scm’.

Installed Files: ‘scm/midi.scm’.

See also

Notation Reference: Score layout.

Internals Reference: (internals)Dynamic_performer section ‘Dynamic_performer’ in Internals Reference.

Selected Snippets

Replacing default MIDI instrument equalization

The default MIDI instrument equalizer can be replaced by setting the instrumentEqualizer property in the Score context to a user-defined Scheme procedure that uses a MIDI instrument name as its argument along with a pair of fractions indicating the minimum and maximum volumes respectively to be applied to that specific instrument.

The following example sets the minimum and maximum volumes for flute and clarinet respectively.

#(define my-instrument-equalizer-alist '()) #(set! my-instrument-equalizer-alist (append '( ("flute" . (0.7 . 0.9)) ("clarinet" . (0.3 . 0.6))) my-instrument-equalizer-alist)) #(define (my-instrument-equalizer s) (let ((entry (assoc s my-instrument-equalizer-alist))) (if entry (cdr entry)))) \score { << \new Staff { \key g \major \time 2/2 \set Score.instrumentEqualizer = #my-instrument-equalizer \set Staff.midiInstrument = "flute" \new Voice \relative { r2 g''\mp g fis~ 4 g8 fis e2~ 4 d8 cis d2 } } \new Staff { \key g \major \set Staff.midiInstrument = "clarinet" \new Voice \relative { b'1\p a2. b8 a g2. fis8 e fis2 r } } >> \layout { } \midi { } }

Known issues and warnings

Changes in the MIDI volume take place only on starting a note, so crescendi and decrescendi cannot affect the volume of a single note.

Setting MIDI block properties

The \midi block can contain context rearrangements, new context definitions or code that sets the values of certain properties.

\score {
  … music …
  \midi {
    \tempo 4 = 72
  }
}

Here the tempo is set to 72 quarter-note beats per minute. The tempo mark in the \midi block will not appear in the printed score. Although any other \tempo indications specified within the \score block will also be reflected in the MIDI output.

In a \midi block the \tempo command is setting properties during the interpretation of the music and in the context of output definitions; so it is interpreted as if it were a context modification.

Context definitions follow the same syntax as those in a \layout block;

\score {
  … music …
  \midi {
    \context {
      \Voice
      \remove "Dynamic_performer"
    }
  }
}

This example removes the effect of dynamics from the MIDI output. Note: LilyPond’s translation modules used for sound are called ‘performers’.

See also

Learning Manual: (learning)Other sources of information section ‘Other sources of information’ in Learning Manual.

Notation Reference: Expressive marks, Score layout.

Installed Files: ‘ly/performer-init.ly’.

Snippets: (snippets)MIDI section ‘MIDI’ in Snippets.

Internals Reference: (internals)Dynamic_performer section ‘Dynamic_performer’ in Internals Reference.

Known issues and warnings

Some MIDI players do not always correctly handle tempo changes in the midi output.

Changes to the midiInstrument, as well as some MIDI options, at the beginning of a staff may appear twice in the MIDI output.

3.5.5 Using MIDI instruments

MIDI instruments are set using the midiInstrument property within a Staff context.

\score {
  \new Staff {
    \set Staff.midiInstrument = "glockenspiel"
    … music …
  }
  \midi { }
}

or

\score {
  \new Staff \with {midiInstrument = "cello"} {
    … music …
  }
  \midi { }
}

If the instrument name does not match any of the instruments listed in the ‘MIDI instruments’ section, the acoustic grand instrument will be used instead. See MIDI instruments.

See also

Learning Manual: (learning)Other sources of information section ‘Other sources of information’ in Learning Manual.

Notation Reference: MIDI instruments, Score layout.

Installed Files: ‘scm/midi.scm’.

Known issues and warnings

Percussion instruments that are notated in a DrumStaff context will be output, correctly, to MIDI channel 10 but some pitched, percussion instruments like the xylophone, marimba, vibraphone or timpani, are treated as “normal” instruments so the music for these should be entered in a Staff (not DrumStaff) context to obtain correct MIDI output. A full list of channel 10 drum-kits entries can be found in ‘scm/midi.scm’. See (learning)Other sources of information section ‘Other sources of information’ in Learning Manual.

3.5.6 Using repeats with MIDI

Repeats can be represented in the MIDI output by applying the \unfoldRepeats command.

\score {
  \unfoldRepeats {
    \repeat tremolo 8 { c'32 e' }
    \repeat percent 2 { c''8 d'' }
    \repeat volta 2 { c'4 d' e' f' }
    \alternative {
      { g' a' a' g' }
      { f' e' d' c' }
    }
  }
  \midi { }
}

In order to restrict the effect of \unfoldRepeats to the MIDI output only, while also generating printable scores, it is necessary to make two \score blocks; one for MIDI (with unfolded repeats) and one for the notation (with volta, tremolo, and percent repeats);

\score {
  … music …
  \layout { }
}
\score {
  \unfoldRepeats {
    … music …
  }
  \midi { }
}

When using multiple voices, each of the voices must contain completely unfolded repeats for correct MIDI output.

See also

Notation Reference: Repeats.

3.5.7 MIDI channel mapping

When generating a MIDI file from a score, LilyPond will automatically assign every note in the score to a MIDI channel, the one on which it should be played when it is sent to a MIDI device. A MIDI channel has a number of controls available to select, for example, the instrument to be used to play the notes on that channel, or to request the MIDI device to apply various effects to the sound produced on the channel. At all times, every control on a MIDI channel can have only a single value assigned to it (which can be modified, however, for example, to switch to another instrument in the middle of a score).

The MIDI standard supports only 16 channels per MIDI device. This limit on the number of channels also limits the number of different instruments which can be played at the same time.

LilyPond creates separate MIDI tracks for each staff, (or discrete instrument or voice, depending on the value of Score.midiChannelMapping), and also for each lyrics context. There is no limit to the number of tracks.

To work around the limited number of MIDI channels, LilyPond supports a number of different modes for MIDI channel allocation, selected using the Score.midiChannelMapping context property. In each case, if more MIDI channels than the limit are required, the allocated channel numbers wrap around back to 0, possibly causing the incorrect assignment of instruments to some notes. This context property can be set to one of the following values:

'staff

Allocate a separate MIDI channel to each staff in the score (this is the default). All notes in all voices contained within each staff will share the MIDI channel of their enclosing staff, and all are encoded in the same MIDI track.

The limit of 16 channels is applied to the total number of staff and lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.

'instrument

Allocate a separate MIDI channel to each distinct MIDI instrument specified in the score. This means that all the notes played with the same MIDI instrument will share the same MIDI channel (and track), even if the notes come from different voices or staves.

In this case the lyrics contexts do not count towards the MIDI channel limit of 16 (as they will not be assigned to a MIDI instrument), so this setting may allow a better allocation of MIDI channels when the number of staves and lyrics contexts in a score exceeds 16.

'voice

Allocate a separate MIDI channel to each voice in the score that has a unique name among the voices in its enclosing staff. Voices in different staves are always assigned separate MIDI channels, but any two voices contained within the same staff will share the same MIDI channel if they have the same name. Because midiInstrument and the several MIDI controls for effects are properties of the staff context, they cannot be set separately for each voice. The first voice will be played with the instrument and effects specified for the staff, and voices with a different name from the first will be assigned the default instrument and effects.

Note: different instruments and/or effects can be assigned to several voices on the same staff by moving the Staff_performer from the Staff to the Voice context, and leaving midiChannelMapping to default to 'staff or set to 'instrument; see the snippet below.

For example, the default MIDI channel mapping of a score can be changed to the 'instrument setting as shown:

\score {
  ...music...
  \midi {
    \context {
      \Score
      midiChannelMapping = #'instrument
    }
  }
}

Selected Snippets

Changing MIDI output to one channel per voice

When outputting MIDI, the default behavior is for each staff to represent one MIDI channel, with all the voices on a staff amalgamated. This minimizes the risk of running out of MIDI channels, since there are only 16 available per track.

However, by moving the Staff_performer to the Voice context, each voice on a staff can have its own MIDI channel, as is demonstrated by the following example: despite being on the same staff, two MIDI channels are created, each with a different midiInstrument.

\score { \new Staff << \new Voice \relative c''' { \set midiInstrument = #"flute" \voiceOne \key g \major \time 2/2 r2 g-"Flute" ~ g fis ~ fis4 g8 fis e2 ~ e4 d8 cis d2 } \new Voice \relative c'' { \set midiInstrument = #"clarinet" \voiceTwo b1-"Clarinet" a2. b8 a g2. fis8 e fis2 r } >> \layout { } \midi { \context { \Staff \remove "Staff_performer" } \context { \Voice \consists "Staff_performer" } \tempo 2 = 72 } }

3.5.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.

3.5.9 Enhancing MIDI output

The default MIDI output is basic but can be improved by setting MIDI instruments and various \midi block properties.

Additional scripts allow to fine-tune the way dynamics, articulations and rhythm are rendered in MIDI: the ‘articulate’ script and the ‘swing’ script.

The ‘articulate’ script

To use the ‘articulate’ script add the appropriate \include command at the top of the input file;

\include "articulate.ly"

The script creates MIDI output into appropriately ‘time-scaled’ notes to match many articulation and tempo indications. Engraved output however, will also be altered to literally match the MIDI output.

\score {
  \articulate <<
    … music …
  >>
  \midi { }
}

The \articulate command enables abbreviatures (such as trills and turns) to be processed. A full list of supported items can be found in the script itself. See ‘ly/articulate.ly’.

See also

Learning Manual: (learning)Other sources of information section ‘Other sources of information’ in Learning Manual.

Notation Reference: Score layout.

Installed Files: ‘ly/articulate.ly’.

The ‘swing’ script

The ‘swing’ script provides additional functions allowing for regular durations to be played with an inequal rhythm. The most obvious example is ‘swing’ intepretation commonly found in jazz music where binary eighth notes should be played in a ternary fashion; however additional interpretations are also supported.

This script has to be \include-d at the beginning of the input file:

\include "swing.ly"

Three commands are provided:

• \tripletFeel creates a triplet-feel swing. It takes two arguments: the durations that should be affected by it (typically 8 for eighth notes), and then the music expression to which it should be applied.
• \applySwing takes an additional argument prior to the music expression: a ‘weight list’ of n number ratios expressing the way regular notes should be played: for example, #'(2 1) indicates that every other note should be played twice as long as the following note (in fact, \tripletFeel duration {music} is actually a shortcut for \applySwing duration #'(2 1) {music}). Smoother swung eighths may be obtained with a weight list of #'(3 2), or other values depending on taste.

  That list may include more than two values, which allows for longer and more sophisticated groove patterns; for example, a samba feel for sixteenth notes may be obtained as follows:

  \score { \applySwing 16 #'(3 2 2 3) { … music … } \midi { } }

• \applySwingWithOffset adds yet another argument between the ‘weight list’ and the music expression: an offset length (entered as a ly:make-moment expression). This command should be used when the music expression has to start off-beat, with a partial swing cycle.

Additional help and information is included in the script file: see ‘ly/swing.ly’.

See also

Learning Manual: (learning)Other sources of information section ‘Other sources of information’ in Learning Manual.

Notation Reference: Rhythms.

Installed Files: ‘ly/swing.ly’.

Known issues and warnings

• \repeat constructs in music (even \repeat unfold) are not taken into consideration when determining note timing. This will lead to problems unless the durations of all repeated parts are integer multiples of the swing cycle duration.
• These functions are oblivious to time signatures and measures. That is why offsets need to be supplied by using \applySwingWithOffset if music starts off-beat.
• Grace notes are ignored and simply left unaffected; so are tuplets.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Más nyelvek: català, deutsch, español, français, italiano, 日本語.
Az automatikus nyelvválasztásról.