@menu
* Input structure::
-* Useful concepts and properties::
* Titles and headers::
* Working with input files::
* Controlling output::
+* MIDI output::
@end menu
@rlearning{Working on input files},
@rlearning{Music expressions explained},
-@rlearning{Score is a single (compound) music expression}.
+@rlearning{Score is a (single) compound musical expression}.
@node Multiple scores in a book
Learning Manual:
@rlearning{How LilyPond input files work}.
-@node Useful concepts and properties
-@section Useful concepts and properties
-
-
-@menu
-* Input modes::
-* Controlling direction and placement::
-* Distances and measurements::
-* Spanners::
-@end menu
-
-@node Input modes
-@subsection Input modes
-
-The way in which the notation contained within an input file is
-interpreted is determined by the current input mode.
-
-@strong{Chord mode}
-
-This is activated with the @code{\chordmode} command, and causes
-input to be interpreted with the syntax of chord notation, see
-@ref{Chord notation}. Chords are rendered as notes on a staff.
-
-Chord mode is also activated with the @code{\chords} command.
-This also creates a new @code{ChordNames} context and
-causes the following input to be interpreted with the syntax of
-chord notation and rendered as chord names in the @code{ChordNames}
-context, see @ref{Printing chord names}.
-
-@strong{Drum mode}
-
-This is activated with the @code{\drummode} command, and causes
-input to be interpreted with the syntax of drum notation, see
-@ref{Basic percussion notation}.
-
-Drum mode is also activated with the @code{\drums} command.
-This also creates a new @code{DrumStaff} context and causes the
-following input to be interpreted with the syntax of drum notation
-and rendered as drum symbols on a drum staff, see @ref{Basic
-percussion notation}.
-
-@strong{Figure mode}
-
-This is activated with the @code{\figuremode} command, and causes
-input to be interpreted with the syntax of figured bass, see
-@ref{Entering figured bass}.
-
-Figure mode is also activated with the @code{\figures} command.
-This also creates a new @code{FiguredBass} context and causes the
-following input to be interpreted with the figured bass syntax
-and rendered as figured bass symbols in the @code{FiguredBass}
-context, see @ref{Introduction to figured bass}.
-
-@strong{Fret and tab modes}
-
-There are no special input modes for entering fret and tab symbols.
-
-To create tab diagrams, enter notes or chords in note mode and
-render them in a @code{TabStaff} context, see
-@ref{Default tablatures}.
-
-To create fret diagrams above a staff, enter them as markup
-above the notes using the @code{\fret-diagram} command, see
-@ref{Fret diagrams}.
-
-@strong{Lyrics mode}
-
-This is activated with the @code{\lyricmode} command, and causes
-input to be interpreted as lyric syllables with optional durations
-and associated lyric modifiers, see @ref{Vocal music}.
-
-Lyric mode is also activated with the @code{\addlyrics} command.
-This also creates a new @code{Lyrics} context and an implicit
-@code{\lyricsto} command which associates the following lyrics
-with the preceding music.
-
-@strong{Markup mode}
-
-This is activated with the @code{\markup} command, and causes
-input to be interpreted with the syntax of markup, see
-@ref{Text markup commands}.
-
-@strong{Note mode}
-
-This is the default mode or it may be activated with the
-@code{\notemode} command. Input is interpreted as pitches,
-durations, markup, etc and typeset as musical notation on a staff.
-
-It is not normally necessary to specify note mode explicitly, but
-it may be useful to do so in certain situations, for example if you
-are in lyric mode, chord mode or any other mode and want to insert
-something that only can be done with note mode syntax.
-
-For example, to indicate dynamic markings for the verses of a
-choral pieces it is necessary to enter note mode to interpret
-the markings:
-
-@lilypond[verbatim,relative=2,quote]
-{ c4 c4 c4 c4 }
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic f 1. } }
- To be sung loudly
-}
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic p 2. } }
- To be sung quietly
-}
-@end lilypond
-
-
-
-@node Controlling direction and placement
-@subsection Controlling direction and placement
-
-TODO: Maybe rename section to "directions".
-
-In typesetting music the direction and placement of many items is
-a matter of choice. For example, the stems of notes can
-be directed up or down; lyrics, dynamics, and other expressive
-marks may be placed above or below the staff; text may be aligned
-left, right or center; etc. Most of these choices may be left to
-be determined automatically by LilyPond, but in some cases it may
-be desirable to force a particular direction or placement.
-
-@strong{Default actions}
-
-By default some directions are always up or always down (e.g.
-dynamics or fermata), while other things can alternate between
-up or down based on the stem direction (like slurs or accents).
-
-@c TODO Add table showing these
-
-@strong{Context layout}
-
-Contexts are positioned in a system from top to bottom in the
-order in which they are encountered. Note, however, that a
-context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.
-
-@c TODO Add example ?
-
-The default order in which contexts are laid out can be changed,
-see @ref{Aligning contexts}
-
-@strong{Articulation direction indicators}
-
-When adding articulations to notes the direction indicator,
-@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
-@code{-} (meaning @qq{use default direction}), can usually be
-omitted, in which case @code{-} is assumed. But a direction
-indicator is @strong{always} required before
-
-@itemize
-@item @code{\tweak} commands
-@item @code{\markup} commands
-@item @code{\tag} commands
-@item string markups, e.g. -"string"
-@item fingering instructions, e.g. @code{-1}
-@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
-@end itemize
-
-@strong{The direction property}
-
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
-
-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
-meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @code{-1}
-respectively. The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}. Alternatively,
-in many cases predefined commands
-exist to specify the direction. These are all of the form
-
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
-
-@noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
-See @rlearning{Within-staff objects}.
-
-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object. In
-this case @code{-1} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
-
-@ignore
-These all have side-axis set to #X
-AmbitusAccidental - direction has no effect
-Arpeggio - works
-StanzaNumber - not tried
-TrillPitchAccidental - not tried
-TrillPitchGroup - not tried
-@end ignore
-
-
-
-@node Distances and measurements
-@subsection Distances and measurements
-
-DISCUSS after working on other sections.
-
-TODO: staff spaces. Maybe move into tweaks?
-
-
-@node Spanners
-@subsection Spanners
-
-
@node Titles and headers
@section Titles and headers
some pieces include a lot more information.
@menu
-* Creating titles::
-* Custom titles::
-* Reference to page numbers::
-* Table of contents::
+* Creating titles::
+* Custom titles::
+* Reference to page numbers::
+* Table of contents::
@end menu
@section Controlling output
@menu
-* Extracting fragments of notation::
-* Skipping corrected music::
+* Extracting fragments of music::
+* Skipping corrected music::
@end menu
-@node Extracting fragments of notation
-@subsection Extracting fragments of notation
+@node Extracting fragments of music
+@subsection Extracting fragments of music
It is possible to quote small fragments of a large score directly from
the output. This can be compared to clipping a piece of a paper score
voices and staves, saving even more time.
+
+@node MIDI output
+@section MIDI output
+
+@cindex Sound
+@cindex MIDI
+
+MIDI (Musical Instrument Digital Interface) is a standard for
+connecting and controlling digital instruments. A MIDI file is a
+series of notes in a number of tracks. It is not an actual
+sound file; you need special software to translate between the
+series of notes and actual sounds.
+
+Pieces of music can be converted to MIDI files, so you can listen to
+what was entered. This is convenient for checking the music; octaves
+that are off or accidentals that were mistyped stand out very much
+when listening to the MIDI output.
+
+@knownissues
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to midi.
+
+The midi output allocates a channel for each staff, and one for global
+settings. Therefore the midi file should not have more than 15 staves
+(or 14 if you do not use drums). Other staves will remain silent.
+
+Not all midi players correctly handle tempo changes in the midi
+output. Players that are known to work include
+@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+
+@menu
+* Creating MIDI files::
+* MIDI block::
+* MIDI instrument names::
+* What goes into the MIDI? FIXME::
+* other midi::
+@end menu
+
+@node Creating MIDI files
+@subsection Creating MIDI files
+
+To create a MIDI from a music piece of music, add a @code{\midi} block
+to a score, for example,
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{
+ \context @{
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 4)
+ @}
+ @}
+@}
+@end example
+
+The tempo can be specified using the @code{\tempo} command within the
+actual music, see @ref{Metronome marks}. An alternative, which does not
+result in a metronome mark in the printed score, is shown in the example
+above. In this example the tempo of quarter notes is set to 72 beats per
+minute.
+This kind of tempo
+specification can not take dotted note lengths as an argument. In this
+case, break the dotted notes into smaller units. For example, a tempo
+of 90 dotted quarter notes per minute can be specified as 270 eighth
+notes per minute
+
+@example
+tempoWholesPerMinute = #(ly:make-moment 270 8)
+@end example
+
+If there is a @code{\midi} command in a @code{\score}, only MIDI will
+be produced. When notation is needed too, a @code{\layout} block must
+be added
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ @}
+ \layout @{ @}
+@}
+@end example
+@cindex layout block
+
+
+
+Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
+crescendi and decrescendi translate into MIDI volume levels. Dynamic
+marks translate to a fixed fraction of the available MIDI volume
+range, crescendi and decrescendi make the volume vary linearly between
+their two extremes. The fractions can be adjusted by
+@code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
+For each type of MIDI instrument, a volume range can be defined. This
+gives a basic equalizer control, which can enhance the quality of
+the MIDI output remarkably. The equalizer can be controlled by
+setting @code{instrumentEqualizer}, or by setting
+
+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@end example
+
+To remove dynamics from the MIDI output, insert the following lines
+in the @code{\midi@{@}} section.
+
+@example
+\midi @{
+ ...
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+@}
+@end example
+
+
+@knownissues
+
+Unterminated (de)crescendos will not render properly in the midi file,
+resulting in silent passages of music. The workaround is to explicitly
+terminate the (de)crescendo. For example,
+
+@example
+@{ a\< b c d\f @}
+@end example
+
+@noindent
+will not work properly but
+
+@example
+@{ a\< b c d\!\f @}
+@end example
+
+@noindent
+will.
+
+
+MIDI output is only created when the @code{\midi} command is within
+a @code{\score} block. If you put it within an explicitly instantiated
+context ( i.e. @code{\new Score} ) the file will fail. To solve this,
+enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
+
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi
+@}
+@end example
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+
+The MIDI block is analogous to the layout block, but it is somewhat
+simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
+context definitions.
+
+
+@cindex context definition
+
+Context definitions follow precisely the same syntax as within the
+\layout block. Translation modules for sound are called performers.
+The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
+
+
+@node MIDI instrument names
+@subsection MIDI instrument names
+
+@cindex instrument names
+@funindex Staff.midiInstrument
+
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property. The instrument name should be chosen from the list in
+@ref{MIDI instruments}.
+
+@example
+\set Staff.midiInstrument = "glockenspiel"
+@var{...notes...}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
+
+@node What goes into the MIDI? FIXME
+@subsection What goes into the MIDI? FIXME
+
+@menu
+* Repeats and MIDI::
+@end menu
+
+@node Repeats and MIDI
+@subsubsection Repeats and MIDI
+
+@cindex expanding repeats
+@funindex \unfoldRepeats
+
+With a little bit of tweaking, all types of repeats can be present
+in the MIDI output. This is achieved by applying the
+@code{\unfoldRepeats} music function. This function changes all
+repeats to unfold repeats.
+
+@lilypond[quote,verbatim,fragment,line-width=8.0\cm]
+\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' }
+ }
+}
+\bar "|."
+@end lilypond
+
+When creating a score file using @code{\unfoldRepeats} for MIDI,
+it is necessary to make two @code{\score} blocks: one for MIDI
+(with unfolded repeats) and one for notation (with volta, tremolo,
+and percent repeats). For example,
+
+@example
+\score @{
+ @var{..music..}
+ \layout @{ .. @}
+@}
+\score @{
+ \unfoldRepeats @var{..music..}
+ \midi @{ .. @}
+@}
+@end example
+
+
+@node other midi
+@subsection other midi
+
+Micro tones are also exported to the MIDI file.
+
+Figured bass has no effect on MIDI.
+
projects / lilypond.git / blobdiff