under heavy development.
@menu
-* Input structure::
-* Useful concepts and properties::
-* Titles and headers::
-* Working with input files::
-* Controlling output::
+* Input structure::
+* Useful concepts and properties::
+* Titles and headers::
+* Working with input files::
+* Controlling output::
+* MIDI output::
@end menu
these files end with @code{.ly}.
@menu
-* Structure of a score::
-* Multiple scores in a book::
-* File structure::
+* Structure of a score::
+* Multiple scores in a book::
+* File structure::
@end menu
@}
@end example
-@warning
-There must be @strong{only one} outer music expression in a
-@code{\score} block, and it @strong{must} be surrounded by
-curly brackets.
-@end warning
+@warning{There must be @strong{only one} outer music expression in
+a @code{\score} block, and it @strong{must} be surrounded by
+curly brackets.}
This single music expression may be of any size, and may contain
other music expressions to any complexity. All of these examples
@end example
Comments are one exception to this general rule. (For others see
-@ref{File structure}.) Both single-line comments and comments
+@ref{File structure}.) Both single-line comments and comments
delimited by @code{%@{ .. %@}} may be placed anywhere within an
input file. They may be placed inside or outside a @code{\score}
block, and inside or outside the single music expression within a
@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
@funindex \book
@cindex movements, multiple
-A document may contain multiple pieces of music and texts. Examples
+A document may contain multiple pieces of music and text. Examples
of these are an etude book, or an orchestral part with multiple
movements. Each movement is entered with a @code{\score} block,
@funindex \book
-All the movements and texts which appear in the same @code{.ly} file
-will normally be typeset in the form of a single output file.
+All the movements and texts which appear in the same @code{.ly} file
+will normally be typeset in the form of a single output file.
@example
\score @{
A @code{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
-@itemize
+@itemize @bullet
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
@menu
-* Input modes::
-* When to add a -::
-* Controlling direction and placement::
-* Distances and measurements::
-* Spanners::
+* Input modes::
+* Direction and placement::
+* Distances and measurements::
+* Spanners::
@end menu
@node Input modes
The way in which the notation contained within an input file is
interpreted is determined by the current input mode.
-@unnumberedsubsubsection 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 \lyricmode or \chordmode or any other mode and want to insert
-something that only can be done with @code(\notemode} 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
-
-@unnumberedsubsubsection 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.
-
-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.
-
-@unnumberedsubsubsection Chord 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
chord notation and rendered as chord names in the @code{ChordNames}
context, see @ref{Printing chord names}.
-@unnumberedsubsubsection Drum mode
+@strong{Drum mode}
This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
and rendered as drum symbols on a drum staff, see @ref{Basic
percussion notation}.
-@unnumberedsubsubsection Figure mode
+@strong{Figure mode}
This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
and rendered as figured bass symbols in the @code{FiguredBass}
context, see @ref{Introduction to figured bass}.
-@unnumberedsubsubsection Fret and tab modes
+@strong{Fret and tab modes}
There are no special input modes for entering fret and tab symbols.
above the notes using the @code{\fret-diagram} command, see
@ref{Fret diagrams}.
+@strong{Lyrics mode}
-@node Direction indicator on articulations
-@subsection Direction indicator on articulations
+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}.
-@c TODO Merge with following section?
+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.
-When adding articulations to notes the direction indicator,
-@code{^}, @code{_} or @code{-}, can usually be omitted, in which
-case @code{-} is assumed. But a direction indicator is
-@strong{always} required before
+@strong{Markup mode}
-@itemize
-@item @code{\tweak} commands
-@item @code{\markup} commands
-@item @code{\tag} commands
-@item text annotation, e.g.-faster, -"with feeling"
-@item fingering instructions, e.g. @code{-1}
-@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
-@end itemize
+This is activated with the @code{\markup} command, and causes
+input to be interpreted with the syntax of markup, see
+@ref{Text markup commands}.
+
+@c silly work-around for texinfo broken-ness
+@c (@strong{Note...} causes a spurious cross-reference in Info)
+@b{Note mode}
-@node Controlling direction and placement
-@subsection Controlling direction and placement
+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.
-TODO: everything
-TODO: Maybe rename section to "directions".
+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 Direction and placement
+@subsection Direction and placement
In typesetting music the direction and placement of many items is
a matter of choice. For example, the stems of notes can
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.
-@unnumberedsubsubsection Default actions
+@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).
-@unnumberedsubsubsection context layout
+@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. For
-example,
+when there is no suitable context available to contain it.
-\contextAbove or whatever it is
+@c TODO Add example ?
-@unnumberedsubsubsection direction indicators
-@verbatim
--
-^ _
-@end verbatim
+The default order in which contexts are laid out can be changed,
+see @ref{Aligning contexts}
-@unnumberedsubsubsection up,down,left,right,center
-Also cover
-#UP
-#DOWN
-#LEFT
-#RIGHT.
+@strong{Articulation direction indicators}
-@unnumberedsubsubsection \fooUp, \fooDown, \fooNeutral
-also mention the typical \fooDown, \fooNeutral predefined commands.
+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
-@unnumberedsubsubsection \override
-Also mention \override Foo #'direction = #'DOWN.
+@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
DISCUSS after working on other sections.
-TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
+TODO: staff spaces. Maybe move into tweaks?
@node Spanners
@subsection Spanners
+Many objects of musical notation extend over several notes or even
+several bars. Examples are crescendi, trills, tuplet brackets, and
+volta repeat brackets. Such objects are called @qq{spanners}, and
+have special properties to control their appearance and behaviour.
+Some of these properties are common to all spanners; others are
+restricted to a sub-set of the spanners.
@node Titles and headers
@section Titles and headers
@section Controlling output
@menu
-* Extracting fragments of notation::
+* 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