X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=a46c14eaee71902342c24871da184d523d87db5f;hb=d182d030b396d66a84efa13d947fbbdfb7240874;hp=363985a0c726f25fe39ded92d14bacae158d1e77;hpb=701c5e3d2e865da2a464b6460a30f14f061089ea;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 363985a0c7..20f2dd6b06 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,20 +1,16 @@ - -@c Note: +@c Note: -*-texinfo-*- @c -@c A menu is needed before every deeper *section nesting of @nodes -@c Run M-x texinfo-all-menus-update -@c to automagically fill in these menus -@c before saving changes - +@c A menu is needed before every deeper *section nesting of @node's; run +@c M-x texinfo-all-menus-update +@c to automagically fill in these menus before saving changes -@ignore - TODO: +@c FIXME: singular vs. plural: Beams/Beam - fix all FIXMEs - Rhythm staff (clef, x-notehead) +@macro refbugs +@strong{BUGS} -@end ignore +@end macro @c .{Reference Manual} @@ -22,128 +18,70 @@ @node Reference Manual @chapter Reference Manual -This document describes GNU LilyPond and its input format. This document -has been revised for LilyPond 1.3.131 +@html + +@end html +This document describes GNU LilyPond and its input format. The last +revision of this document was made for LilyPond 1.4.1. It supposes a +passing familiarity with how LilyPond input works. New users are +encouraged to study the tutorial first. @menu -* Overview:: * Note entry:: -* Music notation:: +* Easier music entry:: +* Staff notation:: * Polyphony:: -* Spanners:: +* Beaming:: +* Accidentals:: +* Expressive marks:: * Ornaments:: * Repeats:: +* Rhythmic music:: * Piano music:: -* Lyrics:: +* Tablatures:: * Chords:: * Writing parts:: -* Custodes:: +* Ancient notation :: * Tuning output:: -* Page layout:: +* Global layout:: * Sound:: -* Music entry:: -* Engravers:: -* Syntactic details:: @end menu -@c . {Overview} -@node Overview -@section Overview - - -The purpose of LilyPond is explained informally by the term `music -typesetter'. This is not a fully correct name: not only does the -program print musical symbols, it also makes esthetic decisions. All -symbols and their placement is @emph{generated} from a high-level -musical description. In other words, LilyPond would be best described -by `music compiler' or `music to notation compiler'. - -Internally, LilyPond is written in a mixture of Scheme and C++. Most of -the algorithms and low-level routines are written in C++, but these low -level components are glued together using Scheme data -structures. LilyPond is linked to GUILE, GNU's Scheme library for -extension. - -When lilypond is run to typeset sheet music, the following happens: - -@itemize @bullet -@item GUILE Initialization: various scheme files are read -@item parsing: first standard .ly initialization files are read, and -then the user @file{.ly} file is read. -@item interpretation: the music in the file is processed "in playing -order", i.e. in the same order as your eyes scan sheet music, and in the -same order that you hear the notes play. - -@item typesetting: -in this step, the results of the interpretation, a typesetting -specification, is solved. - -@item the visible results ("virtual ink") is written to the output file. -@end itemize - -These stages, involve data of a specific type: during parsing, -@strong{Music} objects are created. During the interpretation, -@strong{context} is constructed, and with this context af network of -@strong{graphical objects} (``grobs'') is created. The grobs contain -unknown variables, and the network forms a set of equations. After -solving the equations and filling in these variables, the printed output -(in the form of @strong{molecules}) is written to an output file. - -These threemanship of tasks (parsing, translating, typesetting) and -data-structures (music, context, graphical objects) permeates the entire -design of the program. This manual is ordered in terms of user -tasks. With each concept will be explained to which of the three parts -it belongs. - -LilyPond input can be classified into three types: -@itemize @bullet - @item musical expressions: a musical expression is some combination of -rest, notes, lyrics - @item output definitions: recipes for translating those musical -expressions into performances (MIDI) or graphics (eg. PostScript). - - @item declarations: by declaring and naming musical expressions, you -can enter and edit them in manageable chunks. -@end itemize - - - - +@c FIXME: Note entry vs Music entry at top level menu is confusing. @c . {Note entry} @node Note entry @section Note entry @cindex Note entry +The most basic forms of music are notes. Notes on their own don't +form valid input, but for the sake of brevity we omit @code{\score} +blocks and @code{\paper} declarations. + + @menu -* Notes mode:: -* Pitches:: -* Defining pitch names:: -* Durations:: * Notes:: -* Note head tweaks:: +* Pitches:: +* Chromatic alterations:: * Rests:: -* Skip:: +* Skips:: +* Durations:: +* Ties:: +* Automatic note splitting :: +* Tuplets:: +* Easy Notation note heads :: @end menu -@c . {Notes mode} -@node Notes mode -@subsection Notes mode - -@cindex note mode - -@cindex @code{\notes} -Note mode is introduced by the keyword -@code{\notes}. In Note mode, words can only -contain alphabetic characters. If @code{word} is encountered, -LilyPond first checks for a notename of @code{word}. If no -notename is found, then @code{word} is treated as a string. +@c . {Notes} +@node Notes +@subsection Notes -Since combinations of numbers and dots are used for indicating -durations, it is not possible to enter real numbers in this mode. -@cindex Notes mode +A note is printed by specifying its pitch, and then its duration. +@lilypond[fragment,verbatim] + cis'4 d'8 e'16 c'16 +@end lilypond @c . {Pitches} @node Pitches @@ -161,20 +99,23 @@ The verbose syntax for pitch specification is \pitch @var{scmpitch} @end example -@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}. +@var{scmpitch} is a pitch scheme object. In Note and Chord mode, pitches may be designated by names. The default names are the Dutch note names. The notes are specified by the letters -@code{c} through @code{b}, where @code{c} is an octave below middle C -and the letters span the octave above that C. In Dutch, +@code{a} through @code{g} (where the octave is formed by notes ranging +from @code{c} to @code{b}). The pitch @code{c} is an octave below +middle C and the letters span the octave above that C. + @cindex note names, Dutch -a sharp is formed by adding @code{-is} to the end of a pitch name. A -flat is formed by adding @code{-es}. Double sharps and double flats are -obtained by adding @code{-isis} or @code{-eses}. @code{aes} and -@code{ees} are contracted to @code{as} and @code{es} in Dutch, but both -forms will be accepted. -LilyPond has predefined sets of notenames for various other languages. +In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch +name and a flat is formed by adding @code{-es}. Double sharps and double +flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes} +and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but +both forms are accepted. + +LilyPond has predefined sets of note names for various other languages. To use them, simply include the language specific init file. For example: @code{\include "english.ly"}. The available language files and the names they define are: @@ -188,6 +129,8 @@ norsk.ly c d e f g a b h -iss/-is -ess/-es svenska.ly c d e f g a b h -iss -ess italiano.ly do re mi fa sol la sib si -d -b catalan.ly do re mi fa sol la sib si -d/-s -b +espanol.ly do re mi fa sol la sib si -s -b + @end example @cindex @code{'} @@ -195,54 +138,98 @@ catalan.ly do re mi fa sol la sib si -d/-s -b - The optional octave specification takes the form of a series of single quote (`@code{'}') characters or a series of comma (`@code{,}') characters. Each @code{'} raises the pitch by one octave; each @code{,} lowers the pitch by an octave. @lilypond[fragment,verbatim,center] - c' d' e' f' g' a' b' c'' + c' c'' es' g' as' gisis' ais' @end lilypond -@lilypond[fragment,verbatim,center] - cis' dis' eis' fis' gis' ais' bis' -@end lilypond +@node Chromatic alterations +@subsection Chromatic alterations -@lilypond[fragment,verbatim,center] - ces' des' es' fes' ges' as' bes' +Normally, accidentals are printed automatically, but you may force +accidentals in the following ways: A reminder accidental +@cindex reminder accidental +@cindex @code{?} +can be forced by adding an exclamation mark @code{!} after the pitch. A +cautionary accidental, +@cindex cautionary accidental +@cindex parenthesized accidental +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. + +The automatic production of accidentals can be tuned in many +ways. Refer to @ref{Accidentals} for more information. + +@c . {Rests} +@node Rests +@subsection Rests +@cindex Rests + +A rest is entered like a note, with note name `@code{r}': + +@lilypond[singleline,verbatim] +r1 r2 r4 r8 @end lilypond -@lilypond[fragment,verbatim,center] - cisis' eisis' gisis' aisis' beses' +Whole bar rests centered in the bar are specified using @code{R}, see +@ref{Multi measure rests}. See also @seeinternals{Rest}. + +For polyphonic music, it can be convenient to specify the rest position +directly. You can do that by entering a note, with the keyword +@code{\rest} appended, e.g. Rest collisions will leave these rests alone. + +@lilypond[singleline,verbatim] +a'4\rest d'4\rest @end lilypond -@lilypond[fragment,verbatim,center] - ceses' eses' geses' ases' beses' + +@c . {Skips} +@c FIXME: naming. +@node Skips +@subsection Skips +@cindex Skip +@cindex Invisible rest +@cindex Space note + +An invisible rest, or skip, can be entered like a note with note name +@code{s}, or with @code{\skip @var{duration}}: + +@lilypond[singleline,verbatim] +a2 s4 a4 \skip 1 a4 @end lilypond +The @code{s} syntax is only available in Note mode and Chord mode. +In other situations, you should use the @code{\skip} command, and it is +only available in Note mode and Chord mode. -@c . {Defining pitch names} -@node Defining pitch names -@subsection Defining pitch names +@c FIXME: in lyrics mode, we have " " and _ -@cindex defining pitch names -@cindex pitch names, defining +In Lyrics mode, you can use `@code{" "}' and `@code{_}': +@lilypond[singleline,verbatim] +< + \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di } + \notes\relative c'' { a2 a4 a a2 a4 a } +> +@end lilypond -Note names and chord modifiers can be customised for nationalities. The -syntax is as follows. +The unabbreviated `@code{\skip} @var{duration}' also works outside of +note mode: -@cindex @code{\pitchnames} -@cindex @code{\chordmodifiers} -@example - \pitchnames @var{scheme-alist} - \chordmodifiers @var{scheme-alist} -@end example +@lilypond[singleline,verbatim] +\score { + \context Staff < + { \time 4/8 \skip 2 \time 4/4 } + \notes\relative c'' { a2 a1 } + > +} +@end lilypond -See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for -specific examples how to do this. Some national note names have been -provided, among others: Norwegian, Swedish, German, Italian, Catalan, -French, Dutch and English. +The skip command is merely a empty musical placeholder. It does not +produce any output, not even transparent output. @c . {Durations} @@ -253,19 +240,13 @@ French, Dutch and English. @cindex duration @cindex @code{\duration} -The syntax for an verbose duration specification is -@example - \duration @var{scmduration} -@end example In Note, Chord, and Lyrics mode, durations may be designated by numbers and dots: durations are entered as their reciprocal values. For notes -longer than a whole note, use identifiers. - -@quotation +longer than a whole you must use identifiers. @example -c'\longa c'\breve + c'\breve c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r64 @@ -275,7 +256,7 @@ r1 r2 r4 r8 r16 r32 r64 r64 @lilypond[] \score { \notes \relative c'' { - a\longa a\breve \autoBeamOff + a\breve \autoBeamOff a1 a2 a4 a8 a16 a32 a64 a64 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r64 @@ -283,1156 +264,1918 @@ r1 r2 r4 r8 r16 r32 r64 r64 \paper { \translator { \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - \remove "Time_signature_engraver"; - \consists "Pitch_squash_engraver"; + \remove "Clef_engraver" + \remove "Staff_symbol_engraver" + \remove "Time_signature_engraver" + \consists "Pitch_squash_engraver" } } } @end lilypond -@end quotation -As you can see, the longa is not printed. To get a longa note head, you -have to use a mensural note heads. This is done accomplished by setting -the @code{style} property of the NoteHead grob to @code{mensural}. -If the duration is omitted then it is set equal to the previous duration -entered. At the start of parsing there is no previous duration, so then -a quarter note is assumed. The duration can be followed by a dot -(`@code{.}') to obtain dotted note lengths. +If the duration is omitted then it is set to the previous duration +entered. At the start of parsing a quarter note is assumed. The +duration can be followed by dots (`@code{.}') to obtain dotted note +lengths. @cindex @code{.} @lilypond[fragment,verbatim,center] - a'4. b'4. c'2.. + a'4. b'4.. c'8. @end lilypond @cindex @code{r} @cindex @code{s} -You can alter the length of duration by writing `@code{*}@var{fraction}' -after it. This will not affect the appearance of note heads or rests. +You can alter the length of duration by a fraction @var{N/M} by +appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This +will not affect the appearance of the notes or rests produced. -@c . {Notes} -@node Notes -@subsection Notes +Durations can also be produced through GUILE extension mechanism. +@lilypond[verbatim,fragment] + c\duration #(make-duration 2 1) +@end lilypond -A note specification has the form -@example - @var{pitch}[@var{octavespec}][!][?][@var{duration}] -@end example +@refbugs + +Dot placement for chords is not perfect. In some cases, dots overlap: +@lilypond[] + \context Voice { } +@end lilypond -LilyPond will determine what accidentals to typeset depending on the key -and context, so alteration refer to what note is heard, not to whether -accidentals are printed. A reminder accidental -@cindex reminder accidental -@cindex @code{?} -can be forced by adding an exclamation mark @code{!} after the pitch. -A cautionary accidental, -@cindex cautionary accidental +@node Ties +@subsection Ties -i.e., an accidental within parentheses can be obtained by adding the -question mark `@code{?}' after the pitch. +@cindex Tie +@cindex ties +@cindex @code{~} + +A tie connects two adjacent note heads of the same pitch. The tie in +effect extends the length of a note. A tie is entered with @code{~}. @lilypond[fragment,verbatim,center] - cis' d' e' cis' c'? d' e' c'! + e' ~ e' ~ @end lilypond +When ties are used with chords, all note heads whose pitches match are +connected. Ties are indicated using the tilde symbol `@code{~}'. If +you try to tie together chords which have no common pitches then no +ties will be created. -@node Note head tweaks -@subsection Note head tweaks +If you want less ties created for a chord, you can set +@code{Voice.sparseTies} to true. In this case, a single tie is used +for every tied chord. +@lilypond[fragment,verbatim,center] + \property Voice.sparseTies = ##t + ~ +@end lilypond -[TODO] +In its meaning a tie is just a way of extending a note duration, similar +to the augmentation dot: the following example are two ways of notating +exactly the same concept. +@c +@lilypond[fragment, singleline] +\time 3/4 c'2. c'2 ~ c'4 +@end lilypond +Ties should not be confused with slurs, which indicate articulation, +and phrasing slurs, which indicate musical phrasing. -The note head style can be adjusted with the @code{style} property of -@code{NoteHead}. +See also @seeinternals{Tie}. -@lilypond[fragment,singleline,relative,verbatim] -c'4 -\property Voice.NoteHead \set #'style = #'cross -c'4 -@end lilypond -[discuss more options] +@refbugs -@cindex easy notation -@cindex Hal Leonard +At present, the tie is represented as a separate event, temporally +located in between the notes. Tieing only a subset of the note heads +of a chord is not supported in a simple way. It can be achieved by +moving the tie-engraver into the Thread context and turning on and off +ties per Thread. -A entirely different type of note head is the "easyplay" note head: a -note head that includes a note name. It is used in some publications by -the Hal-Leonard Corporation (a music publishing company). +Switching staffs when a tie is active will not work. -@lilypond[singleline,verbatim] -\score { - \notes { c'2 e'4 f' | g'1 } - \paper { \translator { \EasyNotation } } -} -@end lilypond +@node Automatic note splitting +@subsection Automatic note splitting +@c FIXME: This subsection doesn't belong in @ref{Note entry}. -Note that @code{EasyNotation} overrides a @code{Score} context. You -probably will want to print it with magnification to make it better -readable. +There is a facility for automatically converting long notes to tied +notes. This is done by replacing the @code{Note_heads_engraver} by the +@code{Completion_heads_engraver}. -Limitations: The staff-lines show through the letters. +@lilypond[verbatim,center] +\score{ + \notes\relative c'{ \time 2/4 + c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 + } + \paper{ \translator{ + \ThreadContext + \remove "Note_heads_engraver" + \consists "Completion_heads_engraver" + } } } +@end lilypond +This engraver splits all running notes at the bar line, and inserts +ties. One of its uses is to debug complex scores: if the measures are +not entirely filled, then the ties exactly show how much each measure +is off. -@c . {Rests} -@node Rests -@subsection Rests -@cindex Rests +@refbugs -Rests are entered like notes, with note name `@code{r}'. -There is also a note name -`@code{s}', which produces a space of the specified -duration. +Not all durations (especially those containing tuplets) can be +represented exactly; the engraver will not insert tuplets. +@node Tuplets +@subsection Tuplets -@c . {Skip} -@node Skip -@subsection Skip -@cindex Skip +@cindex tuplets +@cindex triplets +@cindex @code{\times} +Tuplets are made out of a music expression by multiplying all duration +with a fraction. +@cindex @code{\times} @example - \skip @var{duration} @code{;} + \times @var{fraction} @var{musicexpr} @end example -@cindex @code{\skip} -Skips the amount of time specified by @var{duration}. If no other -music is played, a gap will be left for the skipped time with no -notes printed. It works in Note Mode or Lyrics Mode. In Note mode, -this has the same effect as the spacer rest. +The duration of @var{musicexpr} will be multiplied by the fraction. +In print, the fraction's denominator will be printed over the notes, +optionally with a bracket. The most common tuplet is the triplet in +which 3 notes have the length of 2, so the notes are 2/3 of +their written length: +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond +The property @code{tupletSpannerDuration} specifies how long each bracket +should last. With this, you can make lots of tuplets while typing +@code{\times} only once, thus saving typing work. -@c . {Music notation} -@node Music notation -@section Music notation -@cindex Music notation -@menu -* Key:: -* Breath marks:: -* Time signature:: -@end menu +@lilypond[fragment, relative, singleline, verbatim] +\property Voice.tupletSpannerDuration = #(make-moment 1 4) +\times 2/3 { c'8 c c c c c } +@end lilypond -@c . {Key} -@node Key -@subsection Key -@cindex Key +The format of the number is determined by the property +@code{tupletNumberFormatFunction}. The default prints only the +denominator, but if you set it to the Scheme function +@code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den} +instead. -@cindex @code{\key} -@example - @code{\key} @var{pitch} @var{type} @code{;} -@end example -@cindex @code{\minor} -@cindex @code{\major} -@cindex @code{\minor} -@cindex @code{\ionian} -@cindex @code{\locrian} -@cindex @code{\aeolian} -@cindex @code{\mixolydian} -@cindex @code{\lydian} -@cindex @code{\phrygian} -@cindex @code{\dorian} +@cindex @code{tupletNumberFormatFunction} +@cindex tuplet formatting -Change the key signature. @var{type} should be @code{\major} or -@code{\minor} to get @var{pitch}-major or @var{pitch}-minor, -respectively. The second argument is optional; the default is major -keys. The @var{\context} argument can also be given as an integer, -which tells the number of semitones that should be added to the pitch -given in the subsequent @code{\key} commands to get the corresponding -major key, e.g., @code{\minor} is defined as 3. The standard mode names -@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, -@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined. +See also @seeinternals{TupletBracket}. -This command sets @code{Staff.keySignature}. +@refbugs +Nested tuplets are not formatted automatically. In this case, outer +tuplet brackets should be moved automatically. +@node Easy Notation note heads +@subsection Easy Notation note heads -@cindex @code{keySignature} +@cindex easy notation +@cindex Hal Leonard -@c . {Clef} -@subsection Clef changes -@cindex @code{\clef} -@example - \clef @var{clefname} @code{;} -@end example +A entirely different type of note head is the "easyplay" note head: a +note head that includes a note name. It is used in some publications by +Hal-Leonard Inc. music publishers. -Short-cut for +@lilypond[singleline,verbatim,26pt] +\score { + \notes { c'2 e'4 f' | g'1 } + \paper { \translator { \EasyNotation } } +} +@end lilypond -@example - \property Staff.clefGlyph = @var{symbol associated with clefname} - \property Staff.clefPosition = @var{clef Y-position for clefname} - \property Staff.clefOctavation = @var{extra pitch of clefname} -@end example +Note that @code{EasyNotation} overrides a @internalsref{Score} context. You +probably will want to print it with magnification or a large font size to make it more +readable. -Supported clef-names include -@itemize @bullet -@item treble, violin, G, G2: G clef on 2nd line -@item french: G clef on 1st line -@item soprano: C clef on 1st line -@item mezzosoprano: C clef on 2nd line -@item alto: C clef on 3rd line -@item tenor: C clef on 4th line -@item baritone: C clef on 5th line -@item varbaritone: F clef on 3rd line -@item bass, F: F clef on 4th line -@item subbass: F clef on 5th line -@item percussion: percussion clef -@end itemize +@cindex Xdvi +@cindex ghostscript -Supported associated symbols (for Staff.clefGlyph) are: +If you view the result with Xdvi, then staff lines will show through +the letters. Printing the PostScript file obtained with ly2dvi does +produce the correct result. -@itemize @bullet -@item clefs-C: modern style C clef -@item clefs-F: modern style F clef -@item clefs-G: modern style G clef -@item clefs-vaticana_do: Editio Vaticana style do clef -@item clefs-vaticana_fa: Editio Vaticana style fa clef -@item clefs-medicaea_do: Editio Medicaea style do clef -@item clefs-medicaea_fa: Editio Medicaea style fa clef -@item clefs-mensural1_c: modern style mensural C clef -@item clefs-mensural2_c: historic style small mensural C clef -@item clefs-mensural3_c: historic style big mensural C clef -@item clefs-mensural1_f: historic style traditional mensural F clef -@item clefs-mensural2_f: historic style new mensural F clef -@item clefs-mensural_g: historic style mensural G clef -@item clefs-hufnagel_do: historic style hufnagel do clef -@item clefs-hufnagel_fa: historic style hufnagel fa clef -@item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef -@item clefs-percussion: modern style percussion clef -@end itemize -@emph{Modern style} means "as is typeset in current editions". -@emph{Historic style} means "as was typeset or written in contemporary -historic editions". @emph{Editio XXX style} means "as is/was printed in -Editio XXX". +@node Easier music entry +@section Easier music entry +@cindex Music entry +@menu +* Graphical interfaces:: +* Relative octaves:: +* Bar check:: +* Point and click:: +* Skipping corrected music:: +@end menu -@node Breath marks -@subsection Breath marks +When entering music with LilyPond, it is easy to introduce errors. This +section deals with tricks and features that help you enter music, and +find and correct mistakes. -Breath marks are entered using @code{\breathe}: +@node Graphical interfaces +@subsection Graphical interfaces -@lilypond[fragment,relative] -c'4 \breathe d4 -@end lilypond +@cindex GUI +@cindex graphical interface +@cindex sequencer +@cindex RoseGarden +@cindex Denemo +@cindex NoteEdit +@cindex MIDI + +One way to avoid entering notes using the keyboard is to use a +graphical user interface. The following programs are known to have +a lilypond export option: +@itemize @bullet +@item +@uref{http://denemo.sourceforge.net/, Denemo} was once intended as +a LilyPond graphical user interface. It run on Gnome/GTK. +@item +@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html, Noteedit} + is a graphical score editor that runs under KDE/Qt. +@item +@uref{http://rosegarden.sf.net/, RoseGarden} + was the inspiration for naming LilyPond. Nowadays it has been +rewritten from scratch and supports LilyPond export as of version +0.1.6. +@end itemize +Another option is to enter the music using your favorite MIDI +sequencer, and then import it using midi2ly. midi2ly is described in +@ref{Invoking midi2ly}. -@c . {Time signature} -@node Time signature -@subsection Time signature -@cindex Time signature -@cindex meter -@cindex @code{\time} +@c . {Relative} +@node Relative octaves +@subsection Relative octaves +@cindex Relative +@cindex relative octave specification -@example - \time @var{numerator}@code{/}@var{denominator} @code{;} -@end example +Octaves are specified by adding @code{'} and @code{,} to pitch names. +When you copy existing music, it is easy to accidentally put a pitch in +the wrong octave and hard to find such an error. To prevent these +errors, LilyPond features octave entry. -A short-cut for doing +@cindex @code{\relative} @example - \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) + \relative @var{startpitch} @var{musicexpr} @end example -See the documentation of @code{timeSignatureFraction} - +The octave of notes that appear in @var{musicexpr} are calculated as +follows: If no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or less +(This distance is determined without regarding alterations; a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}) -@c . {Partial} -@subsubsection Partial -@cindex Partial -@cindex anacrusis -@cindex upstep -@cindex partial measure -@cindex measure, partial -@cindex shorten measures -@cindex @code{\partial} -@example - \partial @var{duration} @code{;} -@end example +The octave changing marks @code{'} and @code{,} can be added to raise or +lower the pitch by an extra octave. Upon entering relative mode, an +absolute starting pitch must be specified that will act as the +predecessor of the first note of @var{musicexpr}. -Short cut for +Entering music that changes octave frequently is easy in relative mode. +@lilypond[fragment,singleline,verbatim,center] + \relative c'' { + b c d c b c bes a + } +@end lilypond -@example - \property Score.measurePosition = @var{length of duration} -@end example -@cindex @code{|} +And octave changing marks are used for intervals greater than a fourth. +@lilypond[fragment,verbatim,center] + \relative c'' { + c g c f, c' a, e'' } +@end lilypond -See the documentation of @code{measurePosition}. +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord. However, other notes +within the second chord are determined by looking at the immediately +preceding note. +@lilypond[fragment,verbatim,center] + \relative c' { + c + + + } +@end lilypond +@cindex @code{\notes} +The pitch after the @code{\relative} contains a note name. To parse +the pitch as a note name, you have to be in note mode, so there must +be a surrounding @code{\notes} keyword (which is not +shown here). +The relative conversion will not affect @code{\transpose}, +@code{\chords} or @code{\relative} sections in its argument. If you +want to use relative within transposed music, you must place an +additional @code{\relative} inside the @code{\transpose}. -@c . {Polyphony} -@node Polyphony -@section Polyphony -@cindex Polyphony +@c . {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check -[todo : collisiosn, rest-collisinos, voiceX identifiers, how to -which contexts to instantiate.] +@cindex bar check +@cindex @code{barCheckSynchronize} +@cindex @code{|} -@table @code -@cindex @code{\shiftOff} - @item @code{\shiftOff} - Disable horizontal shifting of note heads that collide. - -@cindex @code{\shiftOn} - @item @code{\shiftOn} - Enable note heads that collide with other note heads to be - shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn} -set different shift values. - -@cindex @code{\stemBoth} - @item @code{\stemBoth} - Allow stems, beams, and slurs to point either upwards or - downwards, decided automatically by LilyPond. - -@cindex @code{\stemDown} - @item @code{\stemDown} - Force stems, beams, and slurs to point down. - -@cindex @code{\stemUp} - @item @code{\stemUp} - Force stems, beams and slurs to point up. -@end table - -@c . {Spanners} -@node Spanners -@section Spanners -@cindex Spanners +Whenever a bar check is encountered during interpretation, a warning +message is issued if it doesn't fall at a measure boundary. This can +help you find errors in the input. Depending on the value of +@code{barCheckSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. -@menu -* Beam:: -* Slur :: -* Phrasing slur:: -@end menu +A bar check is entered using the bar symbol, @code{|}: +@example + \time 3/4 c2 e4 | g2. +@end example -@c . {Beam} -@node Beam -@subsection Beams +@cindex skipTypesetting -@cindex beams +Failed bar checks are most often caused by entering incorrect +durations. Incorrect durations often completely garble up the score, +especially if it is polyphonic, so you should start correcting the score +by scanning for failed bar checks and incorrect durations. To speed up +this process, you can use @code{skipTypesetting} (See @ref{Skipping +corrected music})). -@c . {Automatic beams} -@subsubsection Automatic beams +@c . {Point and click} +@node Point and click +@subsection Point and click +@cindex poind and click +Point and click lets you find notes in the input by clicking on them in +the Xdvi window. This makes it very easy to find input that causes some +error in the sheet music. -@cindex automatic beam generation -@cindex autobeam -@cindex @code{Voice.noAutoBeaming} +To use it, you need the following software +@itemize @bullet +@item A dvi viewer that supports src specials. +@itemize @bullet +@item Xdvi, version 22.36 or newer. Available from +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}. + + Note that most @TeX{} distributions ship with xdvik, which is always + a few versions behind the official Xdvi. To find out which xdvi you + are running, try @code{xdvi -version} or @code{xdvi.bin -version}. +@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or +newer. Enablle the menu Settings -> Inverse search. +@end itemize +@item An editor with a client/server interface (or a lightweight GUI editor). +@itemize @bullet +@item Emacs. Emacs is an extensible text-editor. It is available from +@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use +column location. +@item XEmacs. Xemacs is very similar to emacs. +@item NEdit. NEdit runs under Windows, and Unix. + It is available from @uref{http://www.nedit.org}. +@item GVim. GVim is a GUI variant of VIM, the popular VI +clone. It is available from @uref{http://www.vim.org}. +@end itemize +@end itemize -LilyPond will group flagged notes and generate beams autmatically, where -appropriate. -This feature can be disabled by setting the @code{Voice.noAutoBeaming} -property to true, which you may find necessary for the melody that goes -with lyrics, eg. Automatic beaming can easily be overridden for -specific cases by specifying explicit beams. This is discussed in the -next subsubsection. +Xdvi must be configured to find the @TeX{} fonts and music +fonts. Refer to the Xdvi documentation for more information. +To use point-and-click, add one of these lines to the top of your .ly +file. +@example +#(set! point-and-click line-location) +@end example +@cindex line-location +When viewing, Control-Mousebutton 1 will take you to the originating +spot in the @file{.ly} file. Control-Mousebutton 2 will show all +clickable boxes. -@cindex @code{Voice.autoBeamSettings} -@cindex @code{(end * * * *)} -@cindex @code{(begin * * * *)} +If you correct large files with point-and-click, be sure to start +correcting at the end of the file. When you start at the top, and +insert one line, all following locations will be off by a line. -A large number of Voice properties are used to decide how to generate -beams. Their default values appear in @file{scm/auto-beam.scm}. In -general, beams can begin anywhere, but their ending location is -significant. Beams can end on a beat, or at durations specified by the -properties in @code{Voice.autoBeamSettings}. To end beams every quarter -note, for example, you could set the property @code{(end * * * *)} to -@code{(make-moment 1 4)}. To end beams at every three eighth notes you -would set it to @code{(make-moment 1 8)}. The same syntax can be used -to specify beam starting points using @code{(begin * * * *)}, eg: -@quotation +@cindex Emacs +For using point-and-click with emacs, add the following +In your emacs startup file (usually @file{~/.emacs}), @example -\property Voice.autoBeamSettings \override - #'(end * * * *) = #(make-moment 1 4) -\property Voice.autoBeamSettings \override - #'(begin * * * *) = #(make-moment 1 8) +(server-start) @end example -@end quotation -To allow different settings for different time signatures, instead of -the first two asterisks @code{* *} you can specify a time signature; use -@code{(end N M * *)} to restrict the definition to -`@var{N}@code{/}@var{M}' time. For example, to specify beams ending -only for 6/8 time you would use the property @code{(end 6 8 * *)}. +Make sure that the environment variable @var{XEDITOR} is set to +@example +emacsclient --no-wait +%l %f +@end example +@cindex @var{XEDITOR} +If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in +your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f} + +For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or use this +argument with xdvi's @code{-editor} option. +@cindex NEdit +For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or +use this argument with xdvi's @code{-editor} option. + +If can also make your editor jump to the exact location of the note +you clicked. This is only supported on Emacs. Users of version 20 must +apply the patch @file{emacsclient.patch}. Users of version 21 must +apply @file{server.el.patch} (version 21.2 and earlier). At the top +of the @code{ly} file, replace the @code{set!} line with the following +line, +@example +#(set! point-and-click line-column-location) +@end example +@cindex line-colomn-location +and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. + +@refbugs + +When you convert the @TeX{} file to PostScript using @code{dvips}, it +will complain about not finding @code{src:X:Y} files. These complaints +are harmless, and can be ignored. + +@node Skipping corrected music +@subsection Skipping corrected music + +The property @code{Score.skipTypesetting} can be used to switch on and +off typesetting completely during the interpretation phase. When +typesetting is switched off, the music is processed much more quickly. +You can use this to skip over the parts of a score that you have already +checked for errors. + +@lilypond[fragment,singleline,verbatim] +\relative c'' { c8 d +\property Score.skipTypesetting = ##t + e f g a g c, f e d +\property Score.skipTypesetting = ##f +c d b bes a g c2 } +@end lilypond -To allow different endings for notes of different durations, instead of -th last two asterisks you can specify a duration; use @code{(end * * N -M)} to restrict the definition to beams that contain notes of -`@var{N}@code{/}@var{M}' duration. -For example, to specify beam endings for beams that contain 32nd notes, -you would use @code{(end * * 1 32)}. +@node Staff notation +@section Staff notation -@c . {Manual beams} -@cindex Automatic beams -@subsubsection Manual beams -@cindex beams, manual -@cindex @code{]} -@cindex @code{[} +This section deals with music notation that occurs on staff level, +such as keys, clefs and time signatures. -In some cases it may be necessary to override LilyPond's automatic -beaming algorithm. For example, the auto beamer will not beam over -rests or bar lines, so if you want that, specify the begin and end point -manually using @code{[} and @code{]}: +@cindex Staff notation -@quotation -@lilypond[fragment,relative,verbatim] - \context Staff { - r4 [r8 g'' a r8] r8 [g | a] r8 - } -@end lilypond +@menu +* Staff symbol:: +* Key signature:: +* Clef:: +* Time signature:: +* Unmetered music:: +* Bar lines:: +@end menu +@node Staff symbol +@subsection Staff symbol -@cindex @code{stemLeftBeamCount} -If you have specific wishes for the number of beams, you can fully -control the number of beams through the properties -y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. +@cindex adjusting staff symbol +@cindex StaffSymbol, using \property +@cindex staff lines, setting number of -@lilypond[fragment,relative,verbatim] - \context Staff { - [f'8 r16 f g a] - [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] - } -@end lilypond -@end quotation -@cindex @code{stemRightBeamCount} +The lines of the staff symbol are formed by the +@internalsref{StaffSymbol} grob. This grob is created at the moment +that their context is created. You can not change the appearance of +the staff symbol by using @code{\override} or @code{\set}. At the +moment that @code{\property Staff} is interpreted, a Staff context is +made, and the StaffSymbol is created before any @code{\override} is +effective. You can deal with this either overriding properties in a +@code{\translator} definition, or by using @code{\outputproperty}. -@c . {Adjusting beams} -@unnumberedsubsubsec Adjusting beams -@cindex Adjusting beams -FIXME +@refbugs +If you end a staff half way a piece, the staff symbol may not end +exactly on the barline. - -@c . {Slur} -@node Slur -@subsection Slur -@cindex slur +@c . {Key} +@node Key signature +@subsection Key signature +@cindex Key -@menu -* Slur attachments:: -@end menu +@cindex @code{\key} -A slur connects chords and is used to indicate legato. Slurs avoid -crossing stems. A slur is started with @code{(} and stopped with -@code{)}. The starting @code{(} appears to the right of the first note -in the slur. The terminal @code{)} appears to the left of the last note -in the slur. This makes it possible to put a note in slurs from both -sides: +Setting or changing the key signature is done with the @code{\key} +command. +@example + @code{\key} @var{pitch} @var{type} +@end example -@lilypond[fragment,verbatim,center] - f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 -@end lilypond +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} -@c . {Adjusting slurs} -@unnumberedsubsubsec Adjusting slurs +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. +The standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. +This command sets the context property @code{Staff.keySignature}. +Non-standard key signatures can be specified by setting this property +directly. -@node Slur attachments -@subsubsection Slur attachments +The printed signature is a @internalsref{KeySignature} grob, typically +created in @internalsref{Staff} context. -The ending of a slur should whenever possible be attached to a note -head. Only in some instances where beams are involved, LilyPond may -attach a slur to a stem end. In some cases, you may want to override -LilyPond's decision, e.g., to attach the slur to the stem end. This can -be done through @code{Voice.Slur}'s grob-property @code{attachment}: +@cindex @code{keySignature} +@c . {Clef} +@node Clef +@subsection Clef +@cindex @code{\clef} -@quotation -@lilypond[fragment,relative,verbatim] - \property Voice.Slur \set #'direction = #1 - \property Voice.Stem \set #'length = #5.5 - g''8(g)g4 - \property Voice.Slur \set #'attachment = #'(stem . stem) - g8(g)g4 +The clef can be set or changed with the @code{\clef} command: +@lilypond[fragment,verbatim] + \key f\major c''2 \clef alto g'2 @end lilypond -@end quotation -Similarly, slurs can be attached to note heads even when beams are -involved: +Supported clef-names include +@c Moved standard clefs to the top /MB +@table @code +@item treble, violin, G, G2 +G clef on 2nd line +@item alto, C + C clef on 3rd line +@item tenor + C clef on 4th line +@item bass, F + F clef on 4th line +@item french + G clef on 1st line, so-called French violin clef +@item soprano + C clef on 1st line +@item mezzosoprano + C clef on 2nd line +@item baritone + C clef on 5th line +@item varbaritone + F clef on 3rd line +@item subbass + F clef on 5th line +@item percussion + percussion clef +@end table -@quotation -@lilypond[fragment,relative,verbatim] - \property Voice.Slur \set #'direction = #1 - \property Voice.Slur \set #'attachment = #'(head . head) - g''16()g()g()g()d'()d()d()d -@end lilypond -@end quotation +By adding @code{_8} or @code{^8} to the clef name, the clef is +transposed one octave down or up, respectively. Note that you have to +enclose @var{clefname} in quotes if you use underscores or digits in the +name. For example, +@example + \clef "G_8" +@end example -If a slur would strike through a stem or beam, LilyPond will move the -slur away vertically (upward or downward). In some cases, this may -cause ugly slurs that you may want to correct: +The grob for this symbol is @internalsref{Clef}. -@quotation -@lilypond[fragment,relative,verbatim] - \property Voice.Stem \set #'direction = #1 - \property Voice.Slur \set #'direction = #1 - d'32( d'4 )d8.. - \property Voice.Slur \set #'attachment = #'(stem . stem) - d,32( d'4 )d8.. -@end lilypond -@end quotation -LilyPond will increase the curvature of a slur trying to stay free of -note heads and stems. However, if the curvature would increase too much, -the slur will be reverted to its default shape. This decision is based -on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some -cases, you may find ugly slurs beautiful, and tell LilyPond so by -increasing the @code{beautiful} value: +This command is equivalent to setting @code{clefGlyph}, +@code{clefPosition} (which controls the Y position of the clef), +@code{centralCPosition} and @code{clefOctavation}. A clef is created +when any of these properties are changed. -[hoe gedefd?? wat betekent beautiful = X?] -@quotation -@lilypond[verbatim] -\score { - \notes \context PianoStaff < - \time 6/4; - \context Staff=up { s1 * 6/4 } - \context Staff=down < - \clef bass; - \autochange Staff \context Voice - \notes \relative c { - d,8( a' d f a d f d a f d )a - } - > - > - \paper { - linewidth = -1.; - \translator { - \VoiceContext - Slur \override #'beautiful = #5.0 - Slur \override #'direction = #1 - Stem \override #'direction = #-1 - autoBeamSettings \override #'(end * * * *) - = #(make-moment 1 2) - } - \translator { - \PianoStaffContext - VerticalAlignment \override #'threshold = #'(5 . 5) - } - } -} +@c . {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} + +The time signature is set or changed by the @code{\time} +command. +@lilypond[fragment,verbatim] + \time 2/4 c'2 \time 3/4 c'2. @end lilypond -@end quotation -@cindex Adusting slurs +The actual symbol that's printed can be customized with the @code{style} +property. Setting it to @code{#'()} uses fraction style for 4/4 and +2/2 time. +The grob for this symbol is @internalsref{TimeSignature}. There are +many more options for its layout. They are selected through the +@code{style} grob property. See @file{input/test/time.ly} for more +examples. -@c . {Phrasing slur} -@node Phrasing slur -@subsection Phrasing slur -@cindex phrasing slur -@cindex phrasing mark +This command sets the property @code{timeSignatureFraction}, +@code{beatLength} and @code{measureLength}. The property +@code{timeSignatureFraction} determine where bar lines should be +inserted, and how automatic beams should be generated. Changing the +value of @code{timeSignatureFraction} also causes a time signature +symbol to be printed. -A phrasing slur (or phrasing mark) connects chords and is used to -indicate a musical sentence. Phrasing slurs avoid crossing stems. A -phrasing slur is started with @code{\(} and stopped with @code{\)}. The -starting @code{\(} appears to the right of the first note in the -phrasing slur. The terminal @code{\)} appears to the left of the last -note in the phrasing slur. +@c . {Partial} +@subsection Partial +@cindex Partial +@cindex anacrusis +@cindex upbeat +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} -@lilypond[fragment,verbatim,center,relative] - \time 6/4; c''\((d)e f(e)\)d +Partial measures, for example in upbeats, are entered using the +@code{\partial} command: +@lilypond[fragment,verbatim] +\partial 4* 5/16 c'16 c4 f16 a'2. ~ a'8. a'16 | g'1 @end lilypond -[TODO: put together with breath mark.] +The syntax for this command is +@example + \partial @var{duration} +@end example +This is internally translated into +@example + \property Score.measurePosition = -@var{length of duration} +@end example +@cindex @code{|} +The property @code{measurePosition} contains a rational number +indicating how much of the measure has passed at this point. -@c . {Tie} -@menu -* Tie:: -* Tuplets:: -* Text spanner:: -* Ottava:: -* Span requests:: -@end menu +@node Unmetered music +@subsection Unmetered music -@node Tie -@subsubsection Tie +Bar lines and bar numbers are calculated automatically. For unmetered +music (e.g. cadenzas), this is not desirable. The commands +@code{\cadenzaOn} and @code{\cadenzaOff} can be used to switch off the +timing information: -@cindex Tie -@cindex ties -@cindex @code{~} +@lilypond[fragment,relative,singleline,verbatim] +c'2. +\cadenzaOn +c2 +\cadenzaOff +c4 c4 c4 +@end lilypond -A tie connects two adjacent note heads of the same pitch. When used -with chords, it connects all of the note heads whose pitches match. -Ties are indicated using the tilde symbol `@code{~}'. -If you try to tie together chords which have no common pitches, a -warning message will appear and no ties will be created. +The property @code{Score.timing} can be used to switch off this +automatic timing -@lilypond[fragment,verbatim,center] - e' ~ e' ~ -@end lilypond +@c . {Bar lines} +@node Bar lines +@subsection Bar lines +@cindex Bar lines -[sparseTies] +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars +Bar lines are inserted automatically, but if you need a special type +of barline, you can force one using the @code{\bar} command: +@lilypond[fragment,verbatim] c4 \bar "|:" c4 +@end lilypond -@c . {Tuplets} -@node Tuplets -@subsubsection Tuplets -@cindex Tuplets -@cindex Times +The following bar types are available +@lilypond[fragment, relative, singleline, verbatim] +c4 +\bar "|" c +\bar "" c +\bar "|:" c +\bar "||" c +\bar ":|" c +\bar ".|" c +\bar ".|." c +\bar "|." +@end lilypond -Tuplets are made out of a music expression by multiplying their duration -with a fraction. +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}. + +In scores with many staffs, the barlines are automatically placed at +top level, and they are connected between different staffs of a +@internalsref{StaffGroup}: +@lilypond[fragment, verbatim] +< \context StaffGroup < + \context Staff = up { e'4 d' + \bar "||" + f' e' } + \context Staff = down { \clef bass c4 g e g } > +\context Staff = pedal { \clef bass c2 c2 } > +@end lilypond -@cindex @code{\times} -@example - \times @var{fraction} @var{musicexpr} -@end example +The grobs that are created at @internalsref{Staff} level. The name is +@internalsref{BarLine}. -The duration of @var{musicexpr} will be multiplied by the fraction. -In print, the fraction's denominator will be printed over the notes, -optionally with a bracket. The most common tuplet is the triplet in -which 3 notes have the length of 2, so the notes are 2/3 of -their written length: +The command @code{\bar @var{bartype}} is a short cut for +doing @code{\property Score.whichBar = @var{bartype}} +Whenever @code{whichBar} is set to a string, a bar line of that type is +created. @code{whichBar} is usually set automatically: at the start of +a measure it is set to @code{defaultBarType}. The contents of +@code{repeatCommands} is used to override default measure bars. -@lilypond[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end lilypond +@code{whichBar} can also be set directly, using @code{\property} or +@code{\bar }. These settings take precedence over the automatic +@code{whichBar} settings. -[todo: document tupletSpannerDuration] +@cindex Bar_line_engraver +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType -@c . {Text spanner} -@node Text spanner -@subsubsection Text spanner -@cindex Text spanner -@c . {Ottava} -@node Ottava -@subsubsection Ottava -@cindex Ottava -@unnumberedsubsubsec Ottava +@c . {Polyphony} +@node Polyphony +@section Polyphony +@cindex polyphony -[move to trick. Not a supported feature.] +The easiest way to enter such fragments with more than one voice on a +staff is to split chords using the separator @code{\\}. You can use +it for small, short-lived voices (make a chord of voices) or for +single chords: -@lilypond[fragment,relative,verbatim] - a'''' b c a - \property Voice.TextSpanner \set #'type = #'dotted-line - \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) - \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") - \property Staff.centralCPosition = #-13 - a\spanrequest \start "text" b c a \spanrequest \stop "text" +@lilypond[verbatim,fragment] +\context Voice = VA \relative c'' { + c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d > +} @end lilypond +The separator causes @internalsref{Voice} contexts to be instantiated, +bearing the names @code{"1"}, @code{"2"}, etc. +Sometimes, it is necessary to instantiate these contexts by hand: For +Instantiate a separate Voice context for each part, and use +@code{\voiceOne}, up to @code{\voiceFour} to assign a stem directions +and horizontal shift for each part. +@c -@c . {Span requests} -@node Span requests -@subsubsection Span requests -@cindex Span requests - -@cindex @code{\spanrequest} +@lilypond[singleline, verbatim] +\relative c'' +\context Staff < \context Voice = VA { \voiceOne cis2 b } + \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } + \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } > +@end lilypond -@example - \spanrequest @var{startstop} @var{type} -@end example -@cindex @code{\start} -@cindex @code{\stop} +The identifiers @code{\voiceOne} to @code{\voiceFour} set directions +ties, slurs and stems, and set shift directions. + +If you want more than four voices, you can also manually set +horizontal shifts and stem directions, as is shown in the following example: +@lilypond[fragment, verbatim] + \context Staff \notes\relative c''< + \context Voice=one { + \shiftOff \stemUp e4 + } + \context Voice=two { + \shiftOn \stemUp cis + } + \context Voice=three { + \shiftOnn \stemUp ais + } + \context Voice=four { + \shiftOnnn \stemUp fis + } + > +@end lilypond -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that -describes what should be started. Among the supported types are -@code{crescendo}, @code{decrescendo}, @code{beam}, @code{slur}.This is -an internal command. Users should use the shorthands which are defined -in the initialization file @file{spanners.ly}. -You can attach a (general) span request to a note using the following -syntax. +Normally, note heads with a different number of dots are not merged, but +if you set the grob property @code{merge-differently-dotted}, they are: +@lilypond[verbatim,fragment,singleline] +\context Voice < { + g'8 g'8 + \property Staff.NoteCollision \override + #'merge-differently-dotted = ##t + g'8 g'8 + } \\ { [g'8. f16] [g'8. f'16] } + > +@end lilypond -@lilypond[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed}: +@lilypond[fragment, relative=2,verbatim] +\context Voice < { + c8 c4. + \property Staff.NoteCollision + \override #'merge-differently-headed = ##t + c8 c4. } \\ { c2 c2 } > @end lilypond -The slur syntax with parentheses is a shorthand for this. +LilyPond also vertically shifts rests that are opposite of a stem. -@c . {Ornaments} -@node Ornaments -@section Ornaments -@cindex Ornaments -@menu -* Articulation:: -* Text scripts:: -* Grace notes:: -* Bar check:: -@end menu +@lilypond[singleline,fragment,verbatim] +\context Voice < c''4 \\ r4 > +@end lilypond -@c . {Articulation} -@node Articulation -@subsection Articulation -@cindex Articulation +See also @internalsref{NoteCollision} and @internalsref{RestCollision} -@cindex articulations -@cindex scripts -@cindex ornaments +@refbugs -A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. These symbols can be -added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols -are defined in @file{script.ly} and @file{script.scm}. Symbols can be -forced to appear above or below the note by writing -`@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}' -respectively. Here is a chart showing symbols above notes, with the -name of the corresponding symbol appearing underneath. +Resolving collisions is a very intricate subject, and LilyPond only +handles a few situations. When it can not cope, you are advised to use +@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched +rests to override typesetting decisions. -@lilypond[] +@node Beaming +@section Beaming - \score { - < \notes { - \property Score.LyricSyllable \override #'font-family = -#'typewriter - \property Score.LyricSyllable \override #'font-shape = #'upright - c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata - c''-\stopped c''-\staccato c''-\tenuto c''-\upbow - c''-\downbow c''^\lheel c''-\rheel c''^\ltoe - c''-\rtoe c''-\turn c''-\open c''-\flageolet - c''-\reverseturn c''-\trill c''-\prall c''-\mordent - c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall - c''-\thumb c''-\segno c''-\coda - } - \context Lyrics \lyrics { - accent__ marcato__ staccatissimo__ fermata - stopped__ staccato__ tenuto__ upbow - downbow__ lheel__ rheel__ ltoe - rtoe__ turn__ open__ flageolet - reverseturn__ trill__ prall__ mordent - prallprall__ prallmordent__ uprall__ downprall - thumb__ segno__ coda - } - > - \paper { - linewidth = 5.875\in; - indent = 0.0; - } - } +Beams are used to group short notes into chunks that are aligned with +the metrum. They are inserted automatically in most cases. +@lilypond[fragment,verbatim, relative=2] +\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 @end lilypond -@c . {Text scripts} -@node Text scripts -@subsection Text scripts -@cindex Text scripts - -In addition, it is possible to place arbitrary strings of text or markup -text (see @ref{Text markup}) above or below notes by using a string -instead of an identifier: @code{c^"text"}. It is possible to use @TeX{} -commands, but this should be avoided because this makes it impossible -for LilyPond to compute the exact length of the string, which may lead -to collisions. Also, @TeX{} commands won't work with direct postscript -output. Fingerings can be placed by simply using digits. All of these -note ornaments appear in the printed output but have no effect on the -MIDI rendering of the music. - -@c . {Fingerings} -@subsubsection Fingerings -@cindex Fingerings - -To save typing, fingering instructions (digits 0 to 9 are -supported) and single characters shorthands exist for a few -common symbols +If you're not satisfied with the automatic beaming, you can enter the +beams explicitly. If you have beaming patterns that differ from the +defaults, you can also set the patterns for automatic beamer. -@lilypond[] - \score { - \notes \context Voice { - \property Voice.TextScript \set #'font-family = #'typewriter - \property Voice.TextScript \set #'font-shape = #'upright - c''4-._"c-." s4 - c''4--_"c-{}-" s4 - c''4-+_"c-+" s4 - c''4-|_"c-|" s4 - c''4->_"c->" s4 - c''4-^_"c-\\^{ }" s4 - c''4-1_"c-1" s4 - c''4-2_"c-2" s4 - c''4-3_"c-3" s4 - c''4-4_"c-4" s4 - } - \paper { - linewidth = 5.875 \in; - indent = 0.0; - } - } +See also @internalsref{Beam}. -@end lilypond +@c . {Manual beams} +@cindex Automatic beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} +In some cases it may be necessary to override LilyPond's automatic +beaming algorithm. For example, the auto beamer will not beam over +rests or bar lines, If you want that, specify the begin and end point +manually using a @code{[} before the first beamed note and a @code{]} +after the last note: -@cindex @code{\textscript} +@lilypond[fragment,relative,verbatim] + \context Staff { + r4 [r8 g' a r8] r8 [g | a] r8 + } +@end lilypond -@example +@cindex @code{stemLeftBeamCount} - \textscript @var{text} @var{style} -@end example +Normally, beaming patterns within a beam are determined automatically. +When this mechanism fouls up, the properties +@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can +be used to control the beam subdivision on a stem. If you set either +property, its value will be used only once, and then it is erased. -Defines a text to be printed over or under a note. @var{style} is a -string that may be one of @code{roman}, @code{italic}, @code{typewriter}, -@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}. - -You can attach a general textscript request using this syntax: - -@quotation - -@example -c4-\textscript "6" "finger" -c4-\textscript "foo" "normal" -@end example +@lilypond[fragment,relative,verbatim] + \context Staff { + [f8 r16 f g a] + [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] + } +@end lilypond +@cindex @code{stemRightBeamCount} -@end quotation -This is equivalent to @code{c4-6 c4-"foo"}. +The property @code{subdivideBeams} can be set in order to subdivide +all 16th or shorter beams at beat positions. This accomplishes the +same effect as twiddling with @code{stemLeftBeamCount} and +@code{stemRightBeamCount}, but it take less typing. -@cindex @code{\script} -@cindex scripts -@cindex superscript -@cindex subscript @example - \script @var{alias} +[c16 c c c c c c c] +\property Voice.subdivideBeams = ##t +[c16 c c c c c c c] +[c32 c c c c c c c c c c c c c c c] +\property Score.beatLength = #(make-moment 1 8) +[c32 c c c c c c c c c c c c c c c] @end example +@lilypond[] +\score { + \notes \relative c' { + [c16 c c c c c c c] + \property Voice.subdivideBeams = ##t + [c16 c c c c c c c] + [c32 c c c c c c c c c c c c c c c] + \property Score.beatLength = #(make-moment 1 8) + [c32 c c c c c c c c c c c c c c c] + } +} +@end lilypond +@cindex subdivideBeams -Prints a symbol above or below a note. The argument is a string which -points into the script-alias table defined in @file{scm/script.scm}. -Usually the @code{\script} keyword is not used directly. Various -helpful identifier definitions appear in @file{script.ly}. - -For information on how to add scripts, consult @file{scm/script.scm}. +Kneed beams are inserted automatically, when a large gap between two +adjacent beamed notes is detected. This behavior can be tuned through +the grob property @code{auto-knee-gap}. +@cindex beams, kneed +@cindex kneed beams +@cindex auto-knee-gap +@cindex hara kiri +@c TODO -> why this ref? Document? +@cindex @code{neutral-direction} -@c . {Grace notes} -@node Grace notes -@subsection Grace notes +@refbugs +Auto knee beams can not be used together with hara kiri staffs. +[TODO from bugs] +The Automatic beamer does not put @strong{unfinished} beams on the +last notes of a score. +Formatting of ties is a difficult subject. LilyPond often does not +give optimal results. +@menu +* Setting automatic beam behavior :: +@end menu +@ignore +@no de Beam typography +@sub section Beam typography -@cindex Grace music -@cindex @code{\grace} -@cindex ornaments -@cindex grace notes -@cindex @code{graceAlignPosition} +One of the strong points of LilyPond is how beams are formatted. Beams +are quantized, meaning that the left and right endpoints beams start +exactly on staff lines. Without quantization, small wedges of white +space appear between the beam and staff line, and this looks untidy. -@example - \grace @var{musicexpr} -@end example +Beams are also slope-damped: melodies that go up or down should also +have beams that go up or down, but the slope of the beams should be +less than the slope of the notes themselves. -A grace note expression has duration 0; the next real note is -assumed to be the main note. +Some beams should be horizontal. These are so-called concave beams. -You cannot have the grace note after the main note, in terms of -duration, and main notes, but you can typeset the grace notes to the -right of the main note using the property -@code{graceAlignPosition}. -@cindex @code{flagStyle} +[TODO: some pictures.] +@end ignore -When grace music is interpreted, a score-within-a-score is set up: -@var{musicexpr} has its own time bookkeeping, and you could (for -example) have a separate time signature within grace notes. While in -this score-within-a-score, you can create notes, beams, slurs, etc. -Unbeamed eighth notes and shorter by default have a slash through the -stem. This behavior can be controlled with the -@code{flagStyle} property. +@c . {Automatic beams} +@node Setting automatic beam behavior +@subsection Setting automatic beam behavior -@quotation -@lilypond[fragment,verbatim] -\relative c'' { - \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.flagStyle = "" c16 } c4 -} +@cindex @code{autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} +@cindex automatic beams, tuning +@cindex tuning automatic beaming -@end lilypond -@end quotation +In normal time signatures, automatic beams can start on any note but can +only end in a few positions within the measure: beams can end on a beat, +or at durations specified by the properties in +@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/auto-beam.scm}. +The value of @code{autoBeamSettings} is changed using +@code{\override} and unset using @code{\revert}: +@example +\property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur} +\property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) +@end example +Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines +whether the rule applies to begin or end-points. The quantity +@var{P}/@var{Q} refers to the length of the beamed notes (and `@code{* +*}' designates notes of any length), @var{N}/@var{M} refers to a time +signature (wildcards, `@code{* *}' may be entered to designate all time +signatures). + +For example, if you want automatic beams to end on every quarter note, +you can use the following: +@example +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 1 4) +@end example +Since the duration of a quarter note is 1/4 of a whole note, it is +entered as @code{(make-moment 1 4)}. -At present, nesting @code{\grace} notes is not supported. The following -may cause run-time errors: +The same syntax can be used to specify beam starting points. In this +example, automatic beams can only end on a dotted quarter note. @example - @code{\grace @{ \grace c32 c16 @} c4} +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 3 8) +@end example +In 4/4 time signature, this means that automatic beams could end only on +3/8 and on the fourth beat of the measure (after 3/4, that is 2 times +3/8 has passed within the measure). + +You can also restrict rules to specific time signatures. A rule that +should only be applied in @var{N}/@var{M} time signature is formed by +replacing the second asterisks by @var{N} and @var{M}. For example, a +rule for 6/8 time exclusively looks like +@example +\property Voice.autoBeamSettings \override + #'(begin * * 6 8) = ... @end example -Since the meaning of such a construct is unclear, we don't consider -this a loss. Similarly, juxtaposing two @code{\grace} sections is -syntactically valid, but makes no sense and may cause runtime errors. -Ending a staff or score with grace notes may also generate a run-time -error, since there will be no main note to attach the grace notes to. +If you want a rule to apply to certain types of beams, you can use the +first pair of asterisks. Beams are classified according to the shortest +note they contain. For a beam ending rule that only applies to beams +with 32nd notes (and no shorter notes), you would use @code{(end 1 +32 * *)}. -The present implementation is not robust and generally kludgy. We expect -it to change after LilyPond 1.4. Syntax changes might also be -implemented. +@c not true +@c Automatic beams can not be put on the last note in a score. +If a score ends while an automatic beam has not been ended and is still +accepting notes, this last beam will not be typeset at all. + +@cindex automatic beam generation +@cindex autobeam +@cindex @code{Voice.autoBeaming} +@cindex lyrics +For melodies that have lyrics, you may want to switch off +automatic beaming. This is done by setting @code{Voice.autoBeaming} to +@code{#f}. +@refbugs +It is not possible to specify beaming parameters for beams with mixed +durations, that differ from the beaming parameters of all separate +durations, i.e., you'll have to specify manual beams to get: +@lilypond[fragment,singleline,relative] + \property Voice.autoBeamSettings + \override #'(end * * * *) = #(make-moment 3 8) + \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4 +@end lilypond +It is not possible to specify beaming parameters that act differently in +different parts of a measure. This means that it is not possible to use +automatic beaming in irregular meters such as @code{5/8}. +@node Accidentals +@section Accidentals +@cindex Accidentals +This section describes how to change the way that LilyPond automatically +inserts accidentals before the running notes. @menu -* Glissando :: -* Dynamics:: -* Crescendo and Decrescendo:: -* Bar lines:: +* Using the predefined accidental macros:: +* Defining your own accidental typesettings:: @end menu - - -@c . {Glissando} -@node Glissando -@subsubsection Glissando -@cindex Glissando - -@cindex @code{\glissando} - -A glissando line can be requested by attaching a @code{\glissando} to a -note: - -@quotation -@lilypond[fragment,relative,verbatim] - c'' \glissando c' +@node Using the predefined accidental macros +@subsection Using the predefined accidental macros +The constructs for describing the accidental typesetting rules are +quite hairy, so non-experts should stick to the macros defined in +@file{ly/property-init.ly}. +@cindex @file{property-init.ly} + +The macros operate on the ``Current'' context (see @ref{Context properties}). This +means that the macros shuold normally be invoked right after the +creation of the context in which the accidental typesetting described +by the macro is to take effect. I.e. if you want to use +piano-accidentals in a pianostaff then you issue +@code{\pianoAccidentals} first thing after the creation of the piano +staff: +@example +\score @{ + \notes \relative c'' < + \context Staff = sa @{ cis4 d e2 @} + \context GrandStaff < + \pianoAccidentals + \context Staff = sb @{ cis4 d e2 @} + \context Staff = sc @{ es2 c @} + > + \context Staff = sd @{ es2 c @} + > +@} +@end example +@lilypond[singleline] +\score { + \notes \relative c'' < + \context Staff = sa { cis4 d e2 } + \context GrandStaff < + \pianoAccidentals + \context Staff = sb { cis4 d e2 } + \context Staff = sc { es2 c } + > + \context Staff = sd { es2 c } + > + \paper { + \translator { + \StaffContext + minimumVerticalExtent = #'(-4.0 . 4.0) + } + } +} @end lilypond -@end quotation - -Printing of an additional text (such as @emph{gliss.}) must be done -manually. - - - -@c . {Dynamics} -@node Dynamics -@subsubsection Dynamics -@cindex Dynamics - +The macros are: +@table @code +@item \defaultAccidentals + @cindex @code{\defaultAccidentals} + This is the default typesetting behaviour. It should correspond + to 18th century common practice: Accidentals are + remembered to the end of the measure in which they occur and + only on their own octave. + +@item \voiceAccidentals + @cindex @code{\voiceAccidentals} + The normal behaviour is to remember the accidentals on + Staff-level. + This macro, however, typesets accidentals individually for each + voice. + Apart from that the rule is similar to + @code{\defaultAccidentals}. + + Warning: This leads to some weird and often unwanted results + because accidentals from one voice DO NOT get cancelled in other + voices: +@lilypond[singleline,relative,fragment,verbatim] + \context Staff < + \voiceAccidentals + \context Voice=va { \voiceOne es g } + \context Voice=vb { \voiceTwo c, e } + > +@end lilypond + Hence you should only use @code{\voiceAccidentals} + if the voices are to be read solely by + individual musicians. if the staff should be readable also + by one musician/conductor then you should use + @code{\modernVoiceAccidentals} or @code{\modernVoiceCautionaries} + instead. + +@item \modernAccidentals + @cindex @code{\modernAccidentals} + This rule should correspond to the common practice in the 20th + century. + The rule is a bit more complex than @code{\defaultAccidentals}: + You get all the same accidentals, but temporary + accidentals also get cancelled in other octaves. Further more, + in the same octave, they also get cancelled in the following measure: +@lilypond[singleline,fragment,verbatim] + \modernAccidentals + cis' c'' cis'2 | c'' c' +@end lilypond -@cindex @code{\ppp} -@cindex @code{\pp} -@cindex @code{\p} -@cindex @code{\mp} -@cindex @code{\mf} -@cindex @code{\f} -@cindex @code{\ff} -@cindex @code{\fff} -@cindex @code{\ffff} -@cindex @code{\fp} -@cindex @code{\sf} -@cindex @code{\sff} -@cindex @code{\sp} -@cindex @code{\spp} -@cindex @code{\sfz} -@cindex @code{\rfz} - +@item \modernCautionaries + @cindex @code{\modernCautionaries} + This rule is similar to @code{\modernAccidentals}, but the + ``extra'' accidentals (the ones not typeset by + @code{\defaultAccidentals}) are typeset as cautionary accidentals + (i.e. in reduced size): +@lilypond[singleline,fragment,verbatim] + \modernCautionaries + cis' c'' cis'2 | c'' c' +@end lilypond +@item \modernVoiceAccidentals + @cindex @code{\modernVoiceAccidentals} + Multivoice accidentals to be read both by musicians playing one voice + and musicians playing all voices. + + Accidentals are typeset for each voice, but they ARE cancelled + across voices in the same @internalsref{Staff}. + +@item \modernVoiceCautionaries + @cindex @code{\modernVoiceCautionaries} + The same as @code{\modernVoiceAccidentals}, but with the + extra accidentals (the ones not typeset by + @code{\voiceAccidentals}) typeset as cautionaries. + Notice that even though all accidentals typeset by + @code{\defaultAccidentals} ARE typeset by this macro then some + of them are typeset as cautionaries. + +@item \pianoAccidentals + @cindex @code{\pianoAccidentals} + 20th century practice for piano notation. Very similar to + @code{\modernAccidentals} but accidentals also get cancelled + across the staves in the same @internalsref{GrandStaff} or + @internalsref{PianoStaff}. + +@item \pianoCautionaries + @cindex @code{\pianoCautionaries} + As @code{\pianoAccidentals} but with the extra accidentals + typeset as cationaries. + +@item \noResetKey + @cindex @code{\noResetKey} + Same as @code{\defaultAccidentals} but with accidentals lasting + ``forever'' and not only until the next measure: +@lilypond[singleline,fragment,verbatim,relative] + \noResetKey + c1 cis cis c +@end lilypond +@item \forgetAccidentals + @cindex @code{\forgetAccidentals} + This is sort of the opposite of @code{\noResetKey}: Accidentals + are not remembered at all - and hence all accidentals are + typeset relative to the key signature, regardless of what was + before in the music: +@lilypond[singleline,fragment,verbatim,relative] + \forgetAccidentals + \key d\major c4 c cis cis d d dis dis +@end lilypond +@end table +@node Defining your own accidental typesettings +@subsection Defining your own accidental typesettings +This section must be considered gurus-only, and hence it must be +sufficient with a short description of the system and a reference to +the internal documentation. -Dynamic marks are specified by using an identifier after a note: -@code{c4-\ff}. The available dynamic marks are: -@code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, -@code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, -@code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. +The idea of the algorithm is to try several different rules and then +use the rule that gives the highest number of accidentals. +Each rule cosists of +@table @asis +@item Context: + In which context is the rule applied. I.e. if context is + @internalsref{Score} then all staves share accidentals, and if + context is @internalsref{Staff} then all voices in the same + staff share accidentals, but staves don't - like normally. +@item Octavation: + Whether the accidental changes all octaves or only the current + octave. +@item Lazyness: + Over how many barlines the accidental lasts. + If lazyness is @code{-1} then the accidental is forget + immidiately, and if lazyness is @code{#t} then the accidental + lasts forever. +@end table -@c . {Crescendo and Decrescendo} -@node Crescendo and Decrescendo -@subsubsection Crescendo and Decrescendo +As described in the internal documentation of +@reng{Accidental_engraver}, the properties @code{autoAccidentals} and +@code{autoCautionaries} contain lists of rule descriptions. Notice +that the contexts must be listed from in to out - that is +@internalsref{Thread} before @internalsref{Voice}, +@internalsref{Voice} before @internalsref{Staff}, etc. +see the macros in @file{ly/property-init.ly} for examples of how the +properties are set. + +@refbugs + +Currently the simultaneous notes are considered to be entered in +sequential mode. This means that in a chord the accidentals are +typeset as if the notes in the chord happened one at a time - in the +order in which they appear in the input file. + +Of course this is only a problem when you have simultainous notes +which accidentals should depend on each other. +Notice that the problem only occurs when using non-default accidentals +- as the default accidentals only depend on other accidentals on the +same staff and same pitch and hence cannot depend on other +simultainous notes. + +This example shows two examples of the same music giving different +accidentals depending on the order in which the notes occur in the +input file: + +@lilypond[singleline,fragment,verbatim] +\property Staff.autoAccidentals = #'( Staff (any-octave . 0) ) +cis'4 r2 | cis'4 r2 | r | r | +@end lilypond -@cindex Crescendo and Decrescendo -@cindex crescendo -@cindex @code{\cr} -@cindex @code{\rc} -@cindex @code{\decr} -@cindex @code{\rced} -@cindex @code{\<} -@cindex @code{\>} -@cindex @code{\"!} +The only solution is to manually insert the problematic +accidentals using @code{!} and @code{?}. +@node Expressive marks +@section Expressive marks +@c . {Slurs} +@menu +* Slurs :: +* Phrasing slurs:: +* Breath marks:: +* Tempo:: +* Text spanners:: +@end menu -A crescendo mark is started with @code{\cr} and terminated with -@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is -started with @code{\decr} and terminated with @code{\rced}. There are -also shorthands for these marks. A crescendo can be started with -@code{\<} and a decrescendo can be started with @code{\>}. Either one -can be terminated with @code{\!}. Note that @code{\!} must go before -the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go -after the last note. Because these marks are bound to notes, if you -want to get several marks during one note, you must use spacer notes. +@node Slurs +@subsection Slurs +@cindex Slurs +A slur indicates that notes are to be played bound or @emph{legato}. +They are entered using parentheses: @lilypond[fragment,verbatim,center] - c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > + f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 @end lilypond -You can also use a text saying @emph{cresc.} instead of hairpins. Here -is an example how to do it: +See also @seeinternals{Slur}. + +Slurs avoid crossing stems, and are generally attached to note heads. +However, in some situations with beams, slurs may be attached to stem +ends. If you want to override this layout you can do this through the +grob-property @code{attachment} of @internalsref{Slur} in +@internalsref{Voice} context It's value is a pair of symbols, specifying +the attachment type of the left and right end points. @lilypond[fragment,relative,verbatim] - \context Voice { - \property Voice.crescendoText = "cresc." - \property Voice.crescendoSpanner = #'dashed-line - a''2\mf\< a a \!a - } + \slurUp + \property Voice.Stem \set #'length = #5.5 + g'8(g)g4 + \property Voice.Slur \set #'attachment = #'(stem . stem) + g8(g)g4 @end lilypond +If a slur would strike through a stem or beam, the slur will be moved +away upward or downward. If this happens, attaching the slur to the +stems might look better: +@lilypond[fragment,relative,verbatim] + \stemUp \slurUp + d32( d'4 )d8.. + \property Voice.Slur \set #'attachment = #'(stem . stem) + d,32( d'4 )d8.. +@end lilypond -@c . {Bar lines} -@node Bar lines -@subsubsection Bar lines -@cindex Bar lines - -@cindex @code{\bar} -@cindex measure lines -@cindex repeat bars +@ignore +Similarly, the curvature of a slur is adjusted to stay clear of note +heads and stems. When that would increase the curvature too much, the +slur is reverted to its default shape. The threshold for this +decision is in @internalsref{Slur}'s grob-property @code{beautiful}. +It is loosely related to the enclosed area between the slur and the +notes. Usually, the default setting works well, but in some cases you +may prefer a curved slur when LilyPond decides for a vertically moved +one. You can indicate this preference by increasing the +@code{beautiful} value: + +@lilyp ond[verbatim,singleline,relative] + \stemDown \slurUp + c16( a' f' a a f a, )c, + c( a' f' a a f d, )c + \property Voice.Slur \override #'beautiful = #5.0 + c( a' f' a a f d, )c +@end lilypond +@end ignore -@example - \bar @var{bartype}; -@end example +@refbugs -This is a short-cut for doing -@example - \property Score.whichBar = @var{bartype} -@end example +Producing nice slurs is a difficult problem, and LilyPond currently +uses a simple, empiric method to produce slurs. In some cases, the +results of this method are ugly. -You are encouraged to use @code{\repeat} for repetitions. See -@ref{Repeats}, and the documentation of @code{whichBar} in -@ref{(lilypond-internals)LilyPond context properties}. +@ignore +This is reflected by the +@code{beautiful} property, which it is an arbitrary parameter in the +slur formatter. Useful values can only be determined by trial and +error. +@end ignore +@cindex Adjusting slurs -[FIXME] +@node Phrasing slurs +@subsection Phrasing slurs +@cindex phrasing slurs +@cindex phrasing marks -@c . {Bar check} -@node Bar check -@subsection Bar check -@cindex Bar check +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is started using @code{\(} and @code{\)} +respectively. -@cindex bar check -@cindex @code{barCheckNoSynchronize} -@cindex @code{|} +@lilypond[fragment,verbatim,center,relative] + \time 6/4 c' \( d () e f () e \) d +@end lilypond +Typographically, the phrasing slur behaves almost exactly like a normal +slur. See also @seeinternals{PhrasingSlur}. -Whenever a bar check is encountered during interpretation, a warning -message is issued if it doesn't fall at a measure boundary. This can -help you find errors in the input. Depending on the value of -@code{barCheckNoSynchronize}, the beginning of the measure will be -relocated, so this can also be used to shorten measures. -A bar check is entered using the bar symbol, @code{|} +@node Breath marks +@subsection Breath marks +Breath marks are entered using @code{\breathe}. See also +@seeinternals{BreathingSign}. +@lilypond[fragment,relative] +c'4 \breathe d4 +@end lilypond +@c . {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking -@c . {Repeats} -@node Repeats -@section Repeats +Metronome settings can be entered as follows: +@cindex @code{\tempo} +@example + \tempo @var{duration} = @var{perminute} +@end example -@cindex repeats -@cindex @code{\repeat} +For example, @code{\tempo 4 = 76} requests output with 76 quarter notes +per minute. + +@refbugs + +The tempo setting is not printed, but is only used in the MIDI +output. You can trick lily into producing a metronome mark, +though. Details are in @ref{Text markup}. + -In order to specify repeats, use the @code{\repeat} -keyword. Since repeats look and sound differently when played or -printed, there are a few different variants of repeats. -@table @asis -@item unfolded -Repeated music is fully written (played) out. Useful for MIDI -output. +@node Text spanners +@subsection Text spanners +@cindex Text spanners -@item volta -This is the normal notation: Repeats are not written out, but -alternative endings (voltas) are printed, left to right. +Some textual indications, e.g. rallentando or accelerando, often extend +over many measures. This is indicated by following the text with a +dotted line. You can create such texts using text spanners. The syntax +is as follows: +@example +\spanrequest \start "text" +\spanrequest \stop "text" +@end example +LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically +in @internalsref{Voice} context). The string to be printed, as well as the +style is set through grob properties. -@item folded -Alternative endings are written stacked. Which is unfortunately not -practical for anything right now. +An application---or rather, a hack---is to fake octavation indications. +@lilypond[fragment,relative,verbatim] + \relative c' { a''' b c a + \property Voice.TextSpanner \set #'type = #'dotted-line + \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) + \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") + \property Staff.centralCPosition = #-13 + a\spanrequest \start "text" b c a \spanrequest \stop "text" } +@end lilypond -@item tremolo -Make tremolo beams. -@end table +@c . {Ornaments} +@node Ornaments +@section Ornaments +@cindex Ornaments @menu -* Repeat syntax:: -* Manual repeat commands:: -* Tremolo repeats:: -* Tremolo subdivision:: +* Articulations:: +* Text scripts:: +* Grace notes:: +* Glissando :: +* Dynamics:: @end menu -@node Repeat syntax -@subsection Repeat syntax +@c . {Articulation} +@node Articulations +@subsection Articulations +@cindex Articulations -The syntax for repeats is +@cindex articulations +@cindex scripts +@cindex ornaments -@example - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example +A variety of symbols can appear above and below notes to indicate +different characteristics of the performance. They are added to a note +by adding a dash and the the character signifying the +articulation. They are demonstrated here. +@lilypond[singleline] + \score { + \notes \context Voice { + \property Voice.TextScript \set #'font-family = #'typewriter + \property Voice.TextScript \set #'font-shape = #'upright + c''4-._"c-." s4 + c''4--_"c-{}-" s4 + c''4-+_"c-+" s4 + c''4-|_"c-|" s4 + c''4->_"c->" s4 + c''4-^_"c-\\^{ }" s4 + } + } +@end lilypond -If you have alternative endings, you may add +The script is automatically placed, but if you need to force +directions, you can use @code{_} to force them down, or @code{^} to +put them up: +@lilypond[fragment, verbatim] + c''4^^ c''4_^ +@end lilypond + + +Other symbols can be added using the syntax +@var{note}@code{-\}@var{name}. Again, they can be forced up or down +using @code{^} and @code{_}. + +@cindex accent +@cindex marcato +@cindex staccatissimo +@cindex fermata +@cindex stopped +@cindex staccato +@cindex tenuto +@cindex upbow +@cindex downbow +@cindex foot marks +@cindex organ pedal marks +@cindex turn +@cindex open +@cindex flageolet +@cindex reverseturn +@cindex trill +@cindex prall +@cindex mordent +@cindex prallprall +@cindex prallmordent +@cindex prall, up +@cindex prall, down +@cindex mordent +@cindex thumb marking +@cindex segno +@cindex coda + +@lilypond[] + \score { + < + \property Score.LyricText \override #'font-family =#'typewriter + \property Score.LyricText \override #'font-shape = #'upright + \context Staff \notes { + c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata + c''-\stopped c''-\staccato c''-\tenuto c''-\upbow + c''-\downbow c''^\lheel c''-\rheel c''^\ltoe + c''-\rtoe c''-\turn c''-\open c''-\flageolet + c''-\reverseturn c''-\trill c''-\prall c''-\mordent + c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall + c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup + c''-\lineprall c''-\thumb c''-\segno c''-\coda + } + \context Lyrics \lyrics { + accent__ marcato__ staccatissimo__ fermata + stopped__ staccato__ tenuto__ upbow + downbow__ lheel__ rheel__ ltoe + rtoe__ turn__ open__ flageolet + reverseturn__ trill__ prall__ mordent + prallprall__ prallmordent__ uprall__ downprall + upmordent__ downmordent__ pralldown__ prallup__ + lineprall__ thumb__ segno__ coda + } + > + \paper { + linewidth = 5.875\in + indent = 0.0 + } + } +@end lilypond + + +@cindex fingering + +Fingering instructions can also be entered in this shorthand. For +finger changes, use markup texts: +@c +@lilypond[verbatim, singleline, fragment] + c'4-1 c'4-2 c'4-3 c'4-4 + c^#'(finger "2-3") +@end lilypond + + +@cindex @code{\script} +@cindex scripts +@cindex superscript +@cindex subscript + +See also @seeinternals{Script} and @seeinternals{Fingering}. + +@refbugs + +All of these note ornaments appear in the printed output but have no +effect on the MIDI rendering of the music. + +Unfortunately, there is no support for adding fingering instructions or +ornaments to individual note heads. Some hacks exist, though. See +@file{input/test/script-horizontal.ly}. + + +@c . {Text scripts} +@node Text scripts +@subsection Text scripts +@cindex Text scripts + +In addition, it is possible to place arbitrary strings of text or markup +text (see @ref{Text markup}) above or below notes by using a string: +@code{c^"text"}. + +By default, these indications do not influence the note spacing, but +by using the command @code{\fatText}, the widths will be taken into +account. +@c +@lilypond[fragment,singleline,verbatim] \relative c' { +c4^"longtext" \fatText c4_"longlongtext" c4 } +@end lilypond + +It is possible to use @TeX{} commands in the strings, but this should be +avoided because it makes it impossible for LilyPond to compute the +exact length of the string, which may lead to collisions. Also, @TeX{} +commands won't work with direct PostScript output. +@c (see @ref{PostScript output}). + +Text scripts are created in form of @internalsref{TextScript} grobs, in +@internalsref{Voice} context. + +@ref{Text markup} describes how to change the font or access +special symbols in text scripts. + + +@c . {Grace notes} +@node Grace notes +@subsection Grace notes + + + +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes + +Grace notes are ornaments are written out ornaments +@lilypond[relative=2,verbatim,ifragment] + c4 \grace c16 c4 \grace { [c16 d16] } c4 +@end lilypond + +In normal notation, grace notes are supposed to take up no logical +time in a measure. Such an idea is practical for normal notation, but +is not strict enough to put it into a program. The model that LilyPond +uses for grace notes internally is that all timing is done in two +steps: + +Every point in musical time consists of two rational numbers: one +denotes the logical time, one denotes the grace timing. The above +example is shown here with timing tuples. + +@lilypond[] +\score { \notes \relative c''{ + c4^"(0,0)" \grace c16_" "_"(1/4,-1/16)" c4^"(1/4,0)" \grace { + [c16_"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)" + } +\paper { linewidth = 8.\cm } +} +@end lilypond + +The advantage of this approach is that you can use almost any lilypond +construction together with grace notes, for example slurs and clef +changes may appear halfway in between grace notes: + +@lilypond[relative=2,verbatim,fragment] + c4 \grace { [ c16 c, \clef bass c, b(] } )c4 +@end lilypond + +The placement of these grace notes is synchronized between different +staffs, using this grace timing. + +@lilypond[relative=2,verbatim,fragment] +< \context Staff = SA { e4 \grace { c16 d e f } e4 } + \context Staff = SB { c4 \grace { g8 b } c4 } > +@end lilypond + + +Unbeamed eighth notes and shorter by default have a slash through the +stem. This can be controlled with grob property @code{flag-style} of +@internalsref{Stem}. The change in formatting is accomplished by +inserting @code{\startGraceMusic} before handling the grace notes, and +@code{\stopGraceMusic} after finishing the grace notes. You can add to +these definitions to globally change grace note formatting. The +standard definitions are in @file{ly/grace-init.ly}. + + +@lilypond[fragment,verbatim] +\relative c'' \context Voice { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { + \property Voice.Stem \override #'flag-style = #'() + c16 + \property Voice.Stem \revert #'flag-style + } c4 +} +@end lilypond + +If you want to end a note with a grace note, then the standard trick +is to put the grace notes before a phantom ``space note'', e.g. +@lilypond[fragment,verbatim, relative=2] +\context Voice { + < { d1^\trill ( } + { s2 \grace { [c16 d] } } > + )c4 +} +@end lilypond + + +@refbugs + +Grace note synchronization can also lead to surprises. Staff notation, +such as key signatures, barlines, etc. are also synchronized. Take +care when you mix staffs with grace notes and staffs without. + +@lilypond[relative=2,verbatim,fragment] +< \context Staff = SA { e4 \bar "|:" \grace c16 d4 } + \context Staff = SB { c4 \bar "|:" d4 } > +@end lilypond + +Grace sections should only be used within sequential music +expressions. Nesting, juxtaposing, or ending sequential music with a +grace section is not supported, and might produce crashes or other +errors. + +@menu +* Glissando :: +* Dynamics:: +@end menu + + + +@c . {Glissando} +@node Glissando +@subsection Glissando +@cindex Glissando + +@cindex @code{\glissando} + +A glissando line can be requested by attaching a @code{\glissando} to +a note: + +@lilypond[fragment,relative,verbatim] + c'-\glissando c' +@end lilypond + +@refbugs + +Printing of an additional text (such as @emph{gliss.}) must be done +manually. See also @seeinternals{Glissando}. + + + +@c . {Dynamics} +@node Dynamics +@subsection Dynamics +@cindex Dynamics + + + +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} + + +Absolute dynamic marks are specified using an identifier after a +note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. + +@lilypond[verbatim,singleline,fragment,relative] + c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff + c2\sf c\rfz +@end lilypond + +@cindex @code{\cr} +@cindex @code{\rc} +@cindex @code{\decr} +@cindex @code{\rced} +@cindex @code{\<} +@cindex @code{\>} +@cindex @code{\"!} + + +A crescendo mark is started with @code{\cr} and terminated with +@code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is +started with @code{\decr} and terminated with @code{\rced}. There are +also shorthands for these marks. A crescendo can be started with +@code{\<} and a decrescendo can be started with @code{\>}. Either one +can be terminated with @code{\!}. Note that @code{\!} must go before +the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go +after the last note. Because these marks are bound to notes, if you +want several marks during one note, you have to use spacer notes. + +@lilypond[fragment,verbatim,center] + c'' \< \! c'' d'' \decr e'' \rced + < f''1 { s4 s4 \< \! s4 \> \! s4 } > +@end lilypond + +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it: + +@lilypond[fragment,relative=2,verbatim] + c4 \cresc c4 \endcresc c4 +@end lilypond + + +@cindex crescendo +@cindex decrescendo + +You can also supply your own texts: +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.crescendoText = "cresc. poco" + \property Voice.crescendoSpanner = #'dashed-line + a'2\mf\< a a \!a + } +@end lilypond + +@cindex diminuendo + +Dynamics are grobs of @internalsref{DynamicText} and +@internalsref{Hairpin}. Vertical positioning of these symbols is +handled by the @internalsref{DynamicLineSpanner} grob. If you want to +adjust padding or vertical direction of the dynamics, you must set +properties for the @internalsref{DynamicLineSpanner} grob. Predefined +identifiers to set the vertical direction are \dynamicUp and +\dynamicDown. + +@cindex direction, of dynamics +@cindex @code{\dynamicDown} +@cindex @code{\dynamicUp} + +@c . {Repeats} +@node Repeats +@section Repeats + + +@cindex repeats +@cindex @code{\repeat} + +To specify repeats, use the @code{\repeat} keyword. Since repeats +should work differently when played or printed, there are a few +different variants of repeats. + +@table @code +@item unfold +Repeated music is fully written (played) out. Useful for MIDI +output, and entering repetitive music. + +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. + +@item fold +Alternative endings are written stacked. This has limited use but may be +used to typeset two lines of lyrics in songs with repeats, see +@file{input/star-spangled-banner.ly}. + +@item tremolo +Make tremolo beams. + +@item percent +Make beat or measure repeats. These look like percent signs. + +@end table + +@menu +* Repeat syntax:: +* Repeats and MIDI:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivisions:: +* Measure repeats:: +@end menu + +@node Repeat syntax +@subsection Repeat syntax +The syntax for repeats is + +@example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example + +If you have alternative endings, you may add @cindex @code{\alternative} @example \alternative @code{@{} @var{alternative1} @var{alternative2} @var{alternative3} @dots{} @code{@}} @end example - -where each @var{alternative} is a Music expression. +where each @var{alternative} is a music expression. Normal notation repeats are used like this: - -@quotation - @lilypond[fragment,verbatim] c'1 \repeat volta 2 { c'4 d' e' f' } \repeat volta 2 { f' e' d' c' } @end lilypond -@end quotation With alternative endings: - -@quotation - @lilypond[fragment,verbatim] c'1 \repeat volta 2 {c'4 d' e' f'} \alternative { {d'2 d'} {f' f} } @end lilypond -@end quotation -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented at some point in the future.} +Folded repeats look like this: -@quotation @lilypond[fragment,verbatim] c'1 @@ -1440,35 +2183,43 @@ implemented at some point in the future.} \alternative { {d'2 d'} {f' f} } @end lilypond -@end quotation - If you don't give enough alternatives for all of the repeats, then the first alternative is assumed to be repeated often enough to equal the specified number of repeats. -@quotation @lilypond[fragment,verbatim] \context Staff { \relative c' { - \partial 4; - \repeat volta 3 { e | c2 d2 | e2 f2 | } + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } \alternative { { g4 g g } { a | a a a a | b2. } } } } - @end lilypond -@end quotation +@node Repeats and MIDI +@subsection Repeats and MIDI + +@cindex expanding repeats + +For instructions on how to unfoldi repeats for MIDI output, see +the example file @file{input/test/unfold-all-repeats.ly}. -As you can see, LilyPond doesn't remember the timing information, nor -are slurs or ties repeated, so you have to reset timing information -after a repeat, eg using bar-checks, @code{Score.measurePosition} or -@code{\partial}. We hope to fix this after 1.4. -It is possible to nest @code{\repeat}, although it probably is only +@refbugs + +Notice that timing information is not remembered at the start of an +alternative, so you have to reset timing information after a repeat, +e.g. using a bar-check (See @ref{Bar check}), setting +@code{Score.measurePosition} or entering @code{\partial}. Slurs or ties +are also not repeated. + +It is possible to nest @code{\repeat}s, although this probably is only meaningful for unfolded repeats. +Folded repeats offer little more over simultaneous music. + @node Manual repeat commands @subsection Manual repeat commands @@ -1481,7 +2232,7 @@ command can be @table @code @item 'start-repeat Print a |: bar line -@item 'stop-repeat +@item 'end-repeat Print a :| bar line @item (volta . @var{text}) Print a volta bracket saying @var{text}. @@ -1492,19 +2243,21 @@ command can be @lilypond[verbatim, fragment] c''4 \property Score.repeatCommands = #'((volta "93") end-repeat) - c4 c4 + c''4 c''4 \property Score.repeatCommands = #'((volta #f)) - c4 c4 + c''4 c''4 @end lilypond +Repeats brackets are @internalsref{VoltaBracket} grobs. + @node Tremolo repeats @subsection Tremolo repeats @cindex tremolo beams To place tremolo marks between notes, use @code{\repeat} with tremolo style. -@lilypond[verbatim,center] +@lilypond[verbatim,center,singleline] \score { \context Voice \notes\relative c' { \repeat "tremolo" 8 { c16 d16 } @@ -1512,76 +2265,420 @@ style. \repeat "tremolo" 2 { c16 d16 } \repeat "tremolo" 4 c16 } - \paper { - linewidth = 40*\staffspace; - } } @end lilypond -@node Tremolo subdivision -@subsection Tremolo subdivision +Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are +@internalsref{StemTremolo}. The single stem tremolo @emph{must} be +entered without @code{@{} and @code{@}}. + +@refbugs + +Only powers of two and undotted notes are supported repeat counts. + +@node Tremolo subdivisions +@subsection Tremolo subdivisions @cindex tremolo marks @cindex @code{tremoloFlags} Tremolo marks can be printed on a single note by adding `@code{:}[@var{length}]' after the note. The length must be at least 8. A @var{length} value of 8 gives one line across the note stem. If the -length is omitted, then the last value is used, or the value of the -@code{tremoloFlags} property if there was no last value. +length is omitted, then then the last value (stored in +@code{Voice.tremoloFlags}) is used. @lilypond[verbatim,fragment,center] - c'2:8 c':32 + c'2:8 c':32 | c': c': | @end lilypond +@refbugs + + Tremolos in this style do not carry over into the MIDI output. -Using this mechanism pays off when you entering many tremolos, since the -default argument saves a lot of typing. +@node Measure repeats +@subsection Measure repeats +@cindex percent repeats +@cindex measure repeats +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. +Patterns of a one and two measures are replaced by percent-like signs, +patterns that divide the measure length are replaced by slashes. +@lilypond[verbatim,singleline] + \context Voice { \repeat "percent" 4 { c'4 } + \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } +} +@end lilypond -@c . {Piano music} -@node Piano music -@section Piano music -@menu -* Automatic staff changes:: -* Manual staff switches:: -* Pedals:: -* Arpeggio:: -* Follow Thread:: -@end menu +The signs are represented by these grobs: @internalsref{RepeatSlash} and +@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}. +@refbugs -@c . {Automatic staff changes} +You can not nest percent repeats, e.g. by filling in the first measure +with slashes, and repeating that measure with percents. + +@node Rhythmic music +@section Rhythmic music + +Sometimes you might want to show only the rhythm of a melody. This can +be done with the rhythmic staff. All pitches of notes on such a staff +are squashed, and the staff itself looks has a single staff line: + +@lilypond[fragment,relative,verbatim] + \context RhythmicStaff { + \time 4/4 + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | + } +@end lilypond + +@menu +* Percussion staves:: +@end menu + +@node Percussion staves +@subsection Percussion staves +@cindex percussion +@cindex drums +To typeset more than one piece of percussion to be played by the same +musician one typically uses a multiline staff where each staff +position refers to a specific piece of percussion. + +LilyPond is shipped with a bunch of scheme functions which allows you +to do this fairly easily. + +The system is based on the general midi drum-pitches. +In order to use the drum pitches you include +@file{ly/drumpitch-init.ly}. This file defines the pitches from the scheme +variable @code{drum-pitch-names} - which definition can be read in +@file{scm/drums.scm}. You see that each piece of percussion has a full +name and an abbreviated name - and you may freely select whether to +refer to the full name or the abbreviation in your music definition. + +To typeset the music on a staff you apply the scheme function +@code{drums->paper} to the percussion music. This function takes a +list of percussion instrument names, notehead scripts and staff +positions (that is: pitches relative to the C-clef) and uses this to +transform the input music by moving the pitch, changing the notehead +and (optionally) adding a script: +@lilypond[singleline,verbatim] +\include "drumpitch-init.ly" +up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \notes { bassdrum4 snare8 bd r bd sn4 } +\score { + \apply #(drums->paper 'drums) \context Staff < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > +} + +@end lilypond +In the above example the music was transformed using the list @code{'drums}. +Currently the following lists are defined in @file{scm/drums.scm}: +@table @code +@item 'drums +To typeset a typical drum kit on a five line staff. +@lilypond[] +\include "drumpitch-init.ly" +nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl } +mus = \notes { cymc cyms cymr hh hhc hho hhho hhp cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl s16 } +\score { + < + \apply #(drums->paper 'drums) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + minimumVerticalExtent = #'(-4.0 . 5.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +Notice that the scheme supports six different toms. +If you are using fewer toms then you simply select the toms that produce +the desired result - i.e. to get toms on the three middle lines you +use @code{tommh}, @code{tomml} and @code{tomfh}. + +Because the general midi contain no rimshots we use the sidestick for +this purpose instead. +@item 'timbales +To typeset timbales on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { timh ssh timl ssl cb } +mus = \notes { timh ssh timl ssl cb s16 } +\score { + < + \apply #(drums->paper 'timbales) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + + } +} +@end lilypond +@item 'congas +To typeset congas on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl } +mus = \notes { cgh cgho cghm ssh cgl cglo cglm ssl s16 } +\score { + < + \apply #(drums->paper 'congas) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@item 'bongos +To typeset bongos on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl } +mus = \notes { boh boho bohm ssh bol bolo bolm ssl s16 } +\score { + < + \apply #(drums->paper 'bongos) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@item 'percussion +To typeset all kinds of simple percussion on one line staves. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc } +mus = \notes { tri trio trim gui guis guil cb cl tamb cab mar hc s16 } +\score { + < + \apply #(drums->paper 'percussion) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #1 + minimumVerticalExtent = #'(-2.0 . 3.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@end table + +If you don't like any of the predefined lists you can define your own +list at the top of your file: + +@lilypond[singleline, verbatim] +#(define mydrums `( + (bassdrum default #f ,(make-pitch -1 2 0)) + (snare default #f ,(make-pitch 0 1 0)) + (hihat cross #f ,(make-pitch 0 5 0)) + (pedalhihat xcircle "stopped" ,(make-pitch 0 5 0)) + (lowtom diamond #f ,(make-pitch -1 6 0)) +)) +\include "drumpitch-init.ly" +up = \notes { hh8 hh hh hh hhp4 hhp } +down = \notes { bd4 sn bd toml8 toml } +\score { + \apply #(drums->paper 'mydrums) \context Staff < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > +} +@end lilypond + +To use a modified existing list instead of building your own from +scratch you can append your modifications to the start of the existing +list: + +@example +#(define mydrums (append `( + (bassdrum default #f ,(make-pitch -1 2 0)) + (lowtom diamond #f ,(make-pitch -1 6 0)) +) drums )) +@end example + +@c FIXME: Too many levels of headers when using subsubsections. +@c Perhaps junk subsection ``Percussion staves'' +@subsubsection Percussion staves with normal staves +When you include @file{drumpitch-init.ly} then the default pitches +are overridden so that you after the inclusion cannot use the common +dutch pitch names anymore. Hence you might wan't to reinclude +@file{nederlands.ly} after the drum-pattern-definitions: +@lilypond[singleline,verbatim] +\include "drumpitch-init.ly" +up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \notes { bassdrum4 snare8 bd r bd sn4 } +\include "nederlands.ly" +bass = \notes \transpose c, { a4. e8 r e g e } +\score { + < + \apply #(drums->paper 'drums) \context Staff = drums < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > + \context Staff = bass { \clef "F_8" \bass } + > +} +@end lilypond + +@subsubsection Percussion midi output +In order to produce correct midi output you need to produce two score +blocks - one for the paper and one for the midi. +To use the percussion channel you set the property @code{instrument} +to @code{'drums}. Because the drum-pitches themself are similar to the +general midi pitches all you have to do is to insert the voices with +none of the scheme functions to get the correct midi output: + +@example +\score @{ + \apply #(drums->paper 'mydrums) \context Staff < + \clef percussion + \context Voice = up @{ \voiceOne \up @} + \context Voice = down @{ \voiceTwo \down @} + > + \paper@{@} +@} +\score @{ + \context Staff < + \property Staff.instrument = #'drums + \up \down + > + \midi@{@} +@} +@end example + +@refbugs + +This scheme is to be considered a temporary implementation. Even +though the scheme will probably keep on working then the future might +bring some other way of typesetting drums, and probably +there will be made no great efforts in keeping things downwards +compatible. + +@c . {Piano music} +@node Piano music +@section Piano music + +Piano music is an odd type of notation. Piano staves are two normal +staves coupled with a brace. The staves are largely independent, but +sometimes voices can cross between the two staves. The +@internalsref{PianoStaff} is especially built to handle this cross-staffing +behavior. In this section we discuss the @internalsref{PianoStaff} and some +other pianistic peculiarities. + +@menu +* Automatic staff changes:: +* Manual staff switches:: +* Pedals:: +* Arpeggio:: +* Voice follower lines:: +@end menu + + +@c . {Automatic staff changes} @node Automatic staff changes @subsection Automatic staff changes @cindex Automatic staff changes -Voices can be switched from top to bottom staff automatically. The -syntax for this is +Voices can switch automatically between the top and the bottom +staff. The syntax for this is @example - \autochange @var{contexttype} @var{musicexp} -@end example -This will switch notation context of @var{musicexp} between a -@var{contexttype} named @code{up} and @code{down}. Typically, you use -@code{Staff} for @var{contexttype}. The autochanger switches on basis -of pitch (central C is the turning point), and it looks ahead skipping -over rests to switch rests in advance. + \autochange Staff \context Voice @{ @dots{}@var{music}@dots{} @} +@end example +The autochanger switches on basis of pitch (central C is the turning +point), and it looks ahead skipping over rests to switch rests in +advance. Here is a practical example: @lilypond[verbatim,singleline] \score { \notes \context PianoStaff < - \context Staff = "up" { - \autochange Staff \context Voice = VA < \relative c' { g4 a b c d r4 a g } > - } - \context Staff = "down" { - \clef bass; - s1*2 - } > } + \context Staff = "up" { + \autochange Staff \context Voice = VA < \relative c' { + g4 a b c d r4 a g } > } + \context Staff = "down" { + \clef bass + s1*2 +} > } @end lilypond - - +Spacer rests are used to prevent the bottom staff from +terminating too soon. @node Manual staff switches @@ -1590,49 +2687,78 @@ over rests to switch rests in advance. @cindex manual staff switches @cindex staff switch, manual -@cindex @code{\translator} -@example - \translator @var{contexttype} = @var{name} -@end example - -A music expression indicating that the context which is a direct -child of the a context of type @var{contexttype} should be shifted to -a context of type @var{contexttype} and the specified name. - -Usually this is used to switch staffs in Piano music, e.g. - +Voices can be switched between staves manually, using the following command: @example - \translator Staff = top @var{Music} + \translator Staff = @var{staffname} @var{music} @end example - +The string @var{staffname} is the name of the staff. It switches the +current voice from its current staff to the Staff called +@var{staffname}. Typically @var{staffname} is @code{"up"} or +@code{"down"}. @c . {Pedals} @node Pedals @subsection Pedals @cindex Pedals -Piano pedals can be entered using the following span requests of the -types @code{Sustain}, @code{UnaChorda} and @code{Sostenuto}: +Piano pedal instruction can be expressed using +@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda}, +@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}. + +These identifiers are shorthands for spanner commands of the types +@internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}: + @lilypond[fragment,verbatim] -c''4 \spanrequest \start "Sustain" c4 c4 \spanrequest \stop "Sustain" +c''4 \spanrequest \start "Sustain" c''4 +c''4 \spanrequest \stop "Sustain" @end lilypond -For these verbose expressions, standard shorthands have been defined: -@table @code -@item sustainDown -@item sustainUp -@item unaChorda -@item treChorde -@item sostenutoDown -@item sostenutoUp -@end table +The symbols that are printed can be modified by setting +@code{pedal@var{X}Strings}, where @var{X} is one of the pedal types: +Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of +@rgrob{SustainPedal}, for example, for more information. -The symbols that are printed can be modified by setting pedalXStrings, -where one of the pedal types. Refer to the generaetd documentation for -more information. +Pedals can also be indicated by a sequence of brackets, by setting the +@code{pedal-type} property of SustainPedal grobs: + +@lilypond[fragment,verbatim] +\property Staff.SustainPedal \override #'pedal-type = #'bracket +c''4 \sustainDown d''4 e''4 a'4 +\sustainUp \sustainDown + f'4 g'4 a'4 \sustainUp +@end lilypond + +A third style of pedal notation is a mixture of text and brackets, +obtained by setting @code{pedal-type} to @code{mixed}: + +@lilypond[fragment,verbatim] +\property Staff.SustainPedal \override #'pedal-type = #'mixed +c''4 \sustainDown d''4 e''4 c'4 +\sustainUp \sustainDown + f'4 g'4 a'4 \sustainUp +@end lilypond + +The default '*Ped' style for sustain and damper pedals corresponds to +@code{\pedal-type = #'text}. However, @code{mixed} is the default style +for a sostenuto pedal: + +@lilypond[fragment,verbatim] +c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp +@end lilypond + +For fine-tuning of the appearance of a pedal bracket, the properties +@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of +@code{PianoPedalBracket} grobs (see the detailed documentation of +@rgrob{PianoPedalBracket}) can be modified. For example, the bracket +may be extended to the end of the note head. + +@lilypond[fragment,verbatim] +\property Staff.PianoPedalBracket \override + #'shorten-pair = #'(0 . -1.0) +c''4 \sostenutoDown d''4 e''4 c'4 +f'4 g'4 a'4 \sostenutoUp +@end lilypond -Currently, brackets are not supported, only text markings (ie. *Ped -style). @c . {Arpeggio} @@ -1647,319 +2773,216 @@ You can specify an arpeggio sign on a chord by attaching an @code{\arpeggio} to a note of the chord. -@quotation @lilypond[fragment,relative,verbatim] - \context Voice + \context Voice @end lilypond -@end quotation -When an arpeggio crosses staffs in piano music, you attach an arpeggio -to the chords in both staffs, and set -@code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios -in both staffs. +When an arpeggio crosses staves in piano music, you attach an arpeggio +to the chords in both staves, and set +@code{PianoStaff.connectArpeggios}. -@quotation @lilypond[fragment,relative,verbatim] \context PianoStaff < \property PianoStaff.connectArpeggios = ##t - \context Voice = one { } - \context Voice = other { \clef bass; } + \context Voice = one { } + \context Voice = other { \clef bass } > @end lilypond -@end quotation +This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios +are @code{PianoStaff.Arpeggio}. +To add an arrow head to explicitly specify the direction of the +arpeggio, you should set the arpeggio grob property +@code{arpeggio-direction}. -@c . {Follow Thread} -@node Follow Thread -@subsection Follow Thread -@cindex follow thread -@cindex staff switching -@cindex cross staff - -[todo: different name, eg. voice line ? ] - -@cindex @code{followThread} +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.Arpeggio \set #'arpeggio-direction = #1 + + \property Voice.Arpeggio \set #'arpeggio-direction = #-1 + + } +@end lilypond -Whenever a voice switches to another staff a line connecting the notes -can be printed automatically. This is enabled if the property -@code{PianoStaff.followThread} is set to true: +A square bracket on the left indicates that the player should not +arpeggiate the chord. To draw these brackets, set the +@code{molecule-callback} property of @code{Arpeggio} or +@code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use +@code{\arpeggio} statements within the chords as before. -@quotation @lilypond[fragment,relative,verbatim] \context PianoStaff < - \property PianoStaff.followThread = ##t - \context Staff \context Voice { - c'1 - \translator Staff=two - b2 a - } - \context Staff=two {\clef bass; \skip 1*2;} + \property PianoStaff.connectArpeggios = ##t + \property PianoStaff.Arpeggio \override + #'molecule-callback = \arpeggioBracket + \context Voice = one { } + \context Voice = other { \clef bass } > @end lilypond -@end quotation - - -@c . {Lyrics} -@node Lyrics -@section Lyrics - - -@menu -* Lyrics mode:: -* Printing lyrics:: -* Automatic syllable durations:: -* More stanzas:: -@end menu - -@c . {Lyrics mode} -@node Lyrics mode -@subsection Lyrics mode -@cindex Lyrics mode - -@cindex lyric mode -@cindex @code{\lyrics} - -Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has -rules that make it easy to include punctuation and diacritical marks in -words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{} -format or a standard encoding without needing quotes. The precise -definition of this mode is ludicrous, and this will remain so until the -authors of LilyPond acquire a deeper understanding of character -encoding, or someone else steps up to fix this. - -A word in Lyrics mode begins with: an alphabetic character, @code{_}, -@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} -through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, -any 8-bit character with ASCII code over 127, or a two-character -combination of a backslash followed by one of @code{`}, @code{'}, -@code{"}, or @code{^}. - -Subsequent characters of a word can be any character that is not a digit -and not white space. One important consequence of this is that a word -can end with `@code{@}}', which may be confusing. However, LilyPond will -issue a warning. Any @code{_} character which appears in an unquoted -word is converted to a space. This provides a mechanism for introducing -spaces into words without using quotes. Quoted words can also be used -in Lyrics mode to specify words that cannot be written with the above -rules. Here are some examples. Not all of these words are printable by -@TeX{}. -@example -Ah! % a word -2B_||_!2B % not a word because it starts with a digit -``Hello'' % not a word because it starts with ` -_ _ _ _ % 4 words, each one a space -@end example -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. +@refbugs -@cindex lyrics expressions +It is not possible to mix connected arpeggios and unconnected +arpeggios in one PianoStaff at the same time. -Syllables are entered like notes, with pitches replaced by text. For -example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each -with quarter note duration. Note that the hyphen has no special -meaning for lyrics, and does not introduce special symbols. See -section @ref{Lexical modes} for a description of what is interpreted as -lyrics. -Spaces can be introduced into a lyric either by using quotes -(@code{"}) or by using an underscore without quotes: @code{He_could4 -not4}. All unquoted underscores are converted to spaces. Printing -lyrics is discussed in the next section. +@node Voice follower lines +@subsection Voice follower lines -@c . {Printing lyrics} -@node Printing lyrics -@subsection Printing lyrics -@cindex lyrics +@cindex follow voice +@cindex staff switching +@cindex cross staff +@cindex @code{followVoice} -Lyric syllables must be interpreted within a @code{Lyrics} context for -printing them. Here is a full example: +Whenever a voice switches to another staff a line connecting the notes +can be printed automatically. This is enabled if the property +@code{PianoStaff.followVoice} is set to true: -@quotation -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va-4 der Ja- cob Va- der Ja- cob - Slaapt gij nog?2 Slaapt4 gij nog?2 +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.followVoice = ##t + \context Staff \context Voice { + c1 + \translator Staff=two + b2 a } - > -} - + \context Staff=two {\clef bass \skip 1*2 } + > @end lilypond -@end quotation - - +The associated grob is @internalsref{VoiceFollower}. -@cindex extender -@cindex lyric extender -You may want a continuous line after the syllables to show melismata. -To achieve this effect, add a @code{__} lyric as a separate word -after the lyric to be extended. This will create an extender, a line -that extends over the entire duration of the lyric. This line will -run all the way to the start of the next lyric, so you may want to -shorten it by using a blank lyric (using @code{_}). +@node Tablatures +@section Tablatures -@quotation - -@lilypond[verbatim] -\score { - < - \notes \relative c'' { - a4 () b () c () d | c () d () b () a | c () d () b () a - } - \context Lyrics \lyrics { - foo1 __ | bar2. __ _4 | baz1 __ - } - > -} +Tablature notation is used music for plucked string instruments. It +notates pitches not by using note heads, but by indicating on which +string and fret a note must be played. LilyPond offers limited +support for tablature, by abusing the fingering system. -@end lilypond -@end quotation +@menu +* Tablatures basic:: +* Non-guitar tablatures:: +* Tablature in addition to normal staff:: +@end menu -@cindex Lyric hyphen +@node Tablatures basic +@subsection Tablatures basic +@cindex Tablatures basic -If you want to have hyphens centered between syllables (rather than -attached to the end of the first syllable) you can use the special -`@code{-}@code{-}' lyric as a separate word between syllables. This -will result in a hyphen which length varies depending on the space -between syllables, and which will be centered between the syllables. -For example: +Tablature can be typeset with Lilypond by using the +@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As +tablature is a recent feature in Lilypond, most of the guitar special +effects such as hammer, pull, bend are not yet supported. -@quotation +With the @internalsref{TabStaff}, the string number associated to a note +is given though the fingering mechanism, e.g. @code{c4-3} for a C +quarter on the third string. The string 1 is the lowest one, and the +tuning defaults to the standard guitar tuning (with 6 strings). -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va4 -- der Ja -- cob | Va -- der Ja -- cob | - Slaapt gij nog?2 | Slaapt4 gij nog?2 +@lilypond[fragment,verbatim] + \context TabStaff < + \notes { + \property Staff.Stem \override #'direction = #1 + + a,4-2 c'-5 a-4 e'-6 + e-3 c'-5 a-4 e'-6 } - > -} - + > @end lilypond -@end quotation - -@c . {Automatic syllable durations} -@node Automatic syllable durations -@subsection Automatic syllable durations -@cindex Automatic syllable durations +@node Non-guitar tablatures +@subsection Non-guitar tablatures +@cindex Non-guitar tablatures -@cindex automatic lyric durations -@cindex @code{\addlyrics} +There are many ways to customize Lilypond tablatures. -If you have lyrics that are set to a melody, you can import the rhythm -of that melody into the lyrics using @code{\addlyrics}. The syntax for -this is -@example - \addlyrics @var{musicexpr1 musicexpr2} -@end example +First you can change the number of strings, by setting the number of +lines in the @internalsref{TabStaff}. You can change the strings +tuning. A string tuning is given as a Scheme list with one integer +number for each string, the number being the pitch of an open string. -This means that both @var{musicexpr1} and @var{musicexpr2} are -interpreted, but that every non-command atomic music expression -(``every syllable'') in @var{musicexpr2} is interpreted using timing -of @var{musicexpr1}. -@cindex @code{automaticMelismata} +Finally, it is possible to change the Scheme function to format the +tablature note text. The default is @var{fret-number-tablature-format}, +which uses the fret number, but for some instruments that may not use +this notation, just create your own tablature-format function. This +function takes three argument: the string number, the string tuning and +the note pitch. -If the property @code{automaticMelismata} is set in the -context of @var{musicexpr1}, no lyrics will be put on slurred or tied -notes. -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - \property Voice.automaticMelismata = ##t - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics { - do4 re mi fa } -@end lilypond -@end quotation +@node Tablature in addition to normal staff +@subsection Tablature in addition to normal staff +@cindex Tablature in addition to normal staff -You should use a single rhythm melody, and single rhythm lyrics (a -constant duration is the obvious choice). If you do not, you will get -undesired effects when using multiple stanzas: +It is possible to typeset both tablature and a "normal" staff, as +commonly done in many parts. -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics -< { do4 re mi fa } - { do8 re mi fa } > +A common trick for that is to put the notes in a variables, and to hide +the fingering information (which correspond to the string number) for +the standard staff. +@lilypond[verbatim] + part = \notes { + a,4-2 c'-5 a-4 e'-6 + e-3 c'-5 a-4 e'-6 + } + \score{ + \context StaffGroup < + \context Staff < + % Hide fingering number + \property Staff.Fingering \override #'transparent = ##t + + \part + > + \context TabStaff < + \property Staff.Stem \override #'direction = #1 + + \part + > + > + } @end lilypond -@end quotation - -It is valid (but probably not very useful) to use notes instead of -lyrics for @var{musicexpr2}. -@node More stanzas -@subsection More stanzas -@cindex phrasing - -If you have multiple stanzas printed underneath each other, the separate -syllables should be aligned around punctuation. LilyPond can do this if -you explain it which lyric lines belong to which melody. - -To this end, give the Voice context an identity, and set the LyricsVoice -to name starting with that identity. In the following example, the Voice -identity is @code{duet}, and the identities of the LyricsVoices are -@code{duet-1} and @code{duet-2}. +@c . {Chords} +@node Chords +@section Chords +@cindex Chords +LilyPond has support for both entering and printing chords. +@lilypond[verbatim,singleline] +twoWays = \notes \transpose c'' { + \chords { + c1 f:sus4 bes/f + } + + + + } -@lilypond[singleline,verbatim] \score { -\addlyrics - \notes \relative c'' \context Voice = duet { \time 3/4; g2 e4 a2 f4 g2. } - \lyrics \context Lyrics < - \context LyricsVoice = "duet-1" { - \property LyricsVoice . stanza = "Bert" - Hi, my name is bert. } - \context LyricsVoice = "duet-2" { - \property LyricsVoice . stanza = "Ernie" - Ooooo, ch\'e -- ri, je t'aime. } - > -} + < \context ChordNames \twoWays + \context Voice \twoWays > } @end lilypond -You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the -first system) and @code{LyricsVoice.stz} for the following systems. - -@cindex stanza numbering - - -@c . {Chords} -@node Chords -@section Chords -@cindex Chords +This example also shows that the chord printing routines do not try to +be intelligent. If you enter @code{f bes d}, it does not interpret +this as an inversion. -[chords vs. simultaneous music] +As you can see chords really are a set of pitches. They are internally +stored as simultaneous music expressions. This means you can enter +chords by name and print them as notes, enter them as notes and print +them as chord names, or (the most common case) enter them by name, and +print them as name. @menu * Chords mode:: -* Entering named chords:: * Printing named chords:: @end menu @@ -1968,57 +2991,24 @@ first system) and @code{LyricsVoice.stz} for the following systems. @subsection Chords mode @cindex Chords mode -Chord mode is introduced by the keyword -@code{\chords}. It is similar to Note mode, but -words are also looked up in a chord modifier table (containing -@code{maj}, @code{dim}, etc). - -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. Dashes -and carets are used to indicate chord additions and subtractions, -so scripts can not be entered in Chord mode. - -@c . {Entering named chords} -@node Entering named chords -@subsection Entering named chords -@cindex Chords names - -Chord names are a way to generate simultaneous music expressions that -correspond with traditional chord names. It can only be used in -Chord mode (see section @ref{Lexical modes}). - -@example - - @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. -@end example - -@var{tonic} should be the tonic note of the chord, and @var{duration} -is the chord duration in the usual notation. There are two kinds of -modifiers. One type is @emph{chord additions}, which are obtained by -listing intervals separated by dots. An interval is written by its -number with an optional @code{+} or @code{-} to indicate raising or -lowering by half a step. Chord additions has two effects: It adds -the specified interval and all lower odd numbered intervals to the -chord, and it may lower or raise the specified interval. Intervals -must be separated by a dot (@code{.}). - +Chord mode is a mode where you can input sets of pitches using common +names. It is introduced by the keyword @code{\chords}. It is similar +to note mode, but words are also looked up in a chord modifier table +(containing @code{maj}, @code{dim}, etc). Dashes and carets are used +to indicate chord additions and subtractions, so articulation scripts +can not be entered in Chord mode. Throughout these examples, chords have been shifted around the staff using @code{\transpose}. - -@quotation - @lilypond[fragment,verbatim] \transpose c'' { \chords { c1 c:3- c:7 c:8 - c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 + c:9 c:9-.5+.7+ c:3-.5- } } - @end lilypond -@end quotation @cindex @code{aug} @cindex @code{dim} @@ -2033,17 +3023,13 @@ raises the 5th, `@code{dim}' which lowers the 5th, `@code{maj}' which adds a raised 7th, and `@code{sus}' which replaces the 5th with a 4th. -@quotation - @lilypond[fragment,verbatim] \transpose c'' { \chords { c1:m c:min7 c:maj c:aug c:dim c:sus } } - @end lilypond -@end quotation Chord subtractions are used to eliminate notes from a chord. The @@ -2059,11 +3045,10 @@ separated by dots. @end lilypond @cindex @code{/} -Chord inversions can be specified by appending `@code{/}' and -the name of a single note to a chord. This has the effect of -lowering the specified note by an octave so it becomes the lowest -note in the chord. If the specified note is not in the chord, a -warning will be printed. +Chord inversions can be specified by appending `@code{/}' and the name +of a single note to a chord. In a chord inversion, the inverted note is +transposed down until it is the lowest note in the chord. If the note +is not in the chord, a warning will be printed. @lilypond[fragment,verbatim,center] \transpose c''' { @@ -2089,79 +3074,76 @@ so it becomes the lowest note in the chord. @end lilypond -The most interesting application is printing chord names, which is -explained in the next subsection. +The formal syntax for named chords is as follows: +@example + @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. +@end example -You should not combine @code{\relative} with named chords. [FIXME] +@var{tonic} should be the tonic note of the chord, and @var{duration} is +the chord duration in the usual notation. There are two kinds of +modifiers. One type is formed by @emph{chord additions}. Additions are +obtained by listing intervals separated by dots. An interval is written +by its number with an optional @code{+} or @code{-} to indicate raising +or lowering by half a step. Chord additions have two effects: they adds +the specified interval and all lower odd numbered intervals to the +chord, and they may lower or raise the specified interval. -@c . {Printing named chords} -@node Printing named chords -@subsection Printing named chords +@refbugs +Implementation details are gory. For example @code{c:4} not only adds +a fourth, but also removes the third. +@c . {Printing named chords} +@node Printing named chords +@subsection Printing named chords @cindex printing chord names @cindex chord names @cindex chords -@cindex @code{ChordNames} -@cindex @code{ChordNameVoice} -For displaying printed chord names, use the @code{ChordNames} and -@code{ChordNameVoice} contexts. The chords may be entered either using -the notation described above, or directly using simultaneous music. +For displaying printed chord names, use the @internalsref{ChordNames} context. +The chords may be entered either using the notation described above, or +directly using simultaneous music. -@quotation @lilypond[verbatim,singleline] scheme = \notes { \chords {a1 b c} } \score { \notes< - \context ChordNamesVoice \scheme + \context ChordNames \scheme \context Staff \transpose c'' \scheme > } @end lilypond -@end quotation -You can make the chord changes stand out more by setting property +You can make the chord changes stand out by setting @code{ChordNames.chordChanges} to true. This will only display chord -names when there's a change in the chords scheme, but always display the -chord name after a line break: +names when there's a change in the chords scheme and at the start of a +new line. -@c bug -@quotation @lilypond[verbatim] scheme = \chords { - c1:m \break c:m c:m c:m d + c1:m c:m \break c:m c:m d } - \score { \notes < - \context ChordNames \scheme + \context ChordNames { + \property ChordNames.chordChanges = ##t + \scheme } \context Staff \transpose c'' \scheme > - \paper{ - linewidth = 40 * \staffspace; - \translator { - \ChordNamesContext - chordChanges = ##t - } - } +\paper{linewidth= 9.\cm} } @end lilypond -@end quotation - +LilyPond examines chords specified as lists of notes to determine a name +to give the chord. LilyPond will not try to identify chord inversions or +an added bass note, which may result in strange chord names when chords +are entered as a list of pitches: -LilyPond examines chords specified as lists of notes to determine a -name to give the chord. LilyPond will not try to -identify chord inversions or added base, which may result in strange -chord names when chords are entered as a list of pitches: - -@quotation @lilypond[verbatim,center,singleline] scheme = \notes { @@ -2171,158 +3153,67 @@ scheme = \notes { \score { < - \context ChordNamesVoice \scheme + \context ChordNames \scheme \context Staff \scheme > } @end lilypond -@end quotation - -To specify chord inversions, append @code{/}. To specify an -added bass note, append @code{/+ -} -@end lilypond -@end quotation -The chord names that LilyPond should print are fully customizable. The -code to print chord names is written in Scheme. It can be found in -@file{scm/chord-name.scm}. Chord names are based on Banter style -naming, which is unambiguous and has a logical structure. Typical -American style chord names are implemented as a variation on Banter -names, they can be selected by setting property @code{ChordName.style} -to @code{american}: +By default, a chord name system proposed by Harald Banter (See +@ref{Literature}) is used. The system is very regular and predictable. +Typical American style chord names may be selected by setting the +@code{style} property of the @code{ChordNames.ChordName} grob to +@code{'american}. Similarly @code{'jazz} selects Jazz chordnames. -@quotation -@lilypond[verbatim] -\include "english.ly" +Routines that determine the names to be printed are written in Scheme, +and may be customized by the user. The code can be found in +@file{scm/chord-name.scm}. Here's an example showing the differences in +chord name styles: +@c too long? +@c maybe just junk verbatim option? +@lilypond[verbatim,singleline] scheme = \chords { - c % Major triad - cs:m % Minor triad - df:m5- % Diminished triad - c:5^3 % Root-fifth chord - c:4^3 % Suspended fourth triad - c:5+ % Augmented triad - c:2^3 % "2" chord - c:m5-.7- % Diminished seventh - c:7+ % Major seventh - c:7.4^3 % Dominant seventh suspended fourth - c:5+.7 % Augmented dominant seventh - c:m5-.7 % "Half" diminished seventh - c:5-.7 % Dominant seventh flat fifth - c:5-.7+ % Major seventh flat fifth - c:m7+ % Minor-major seventh - c:m7 % Minor seventh - c:7 % Dominant seventh - c:6 % Major sixth - c:m6 % Minor sixth - c:9^7 % Major triad w/added ninth - c:6.9^7 % Six/Nine chord - c:9 % Dominant ninth - c:7+.9 % Major ninth - c:m7.9 % Minor ninth + c1 c:5^3 c:4^3 c:5+ + c:m7+ c:m5-.7 + c:5-.7 c:5+.7 + c:9^7 } \score { \notes < - \context ChordNames \scheme + \context ChordNames = banter \scheme + \context ChordNames = american { + \property ChordNames.ChordName \override + #'style = #'american \scheme } + \context ChordNames = jazz { + \property ChordNames.ChordName \override + #'style = #'jazz \scheme } \context Staff \transpose c'' \scheme > - \paper { - \translator { - \ChordNamesContext - ChordName \override #'word-space = #1 - ChordName \override #'style = #'american - } - } } @end lilypond -@end quotation - -Similarly, Jazz style chord names are implemented as a variation on -American style names: -@quotation -@lilypond[verbatim] -scheme = \chords { - % major chords - c - c:6 % 6 = major triad with added sixth - c:maj % triangle = maj - c:6.9^7 % 6/9 - c:9^7 % add9 - - % minor chords - c:m % m = minor triad - c:m.6 % m6 = minor triad with added sixth - c:m.7+ % m triangle = minor major seventh chord - c:3-.6.9^7 % m6/9 - c:m.7 % m7 - c:3-.9 % m9 - c:3-.9^7 % madd9 - - % dominant chords - c:7 % 7 = dominant - c:7.5+ % +7 = augmented dominant - c:7.5- % 7b5 = hard diminished dominant - c:9 % 7(9) - c:9- % 7(b9) - c:9+ % 7(#9) - c:13^9.11 % 7(13) - c:13-^9.11 % 7(b13) - c:13^11 % 7(9,13) - c:13.9-^11 % 7(b9,13) - c:13.9+^11 % 7(#9,13) - c:13-^11 % 7(9,b13) - c:13-.9-^11 % 7(b9,b13) - c:13-.9+^11 % 7(#9,b13) - - % half diminished chords - c:m5-.7 % slashed o = m7b5 - c:9.3-.5- % o/7(pure 9) - - % diminished chords - c:m5-.7- % o = diminished seventh chord -} -\score { - \notes < - \context ChordNames \scheme - \context Staff \transpose c'' \scheme - > - \paper { - \translator { - \ChordNamesContext - ChordName \override #'word-space = #1 - ChordName \override #'style = #'jazz - } - } -} -@end lilypond -@end quotation @node Writing parts @section Writing parts +Orchestral music involves some special notation, both in the full score, +as in the individual parts. This section explains how to tackle common +problems in orchestral music. + + @c . {Transpose} @menu * Rehearsal marks:: +* Bar numbers:: * Instrument names:: * Transpose:: -* Sound output for transposing instruments:: * Multi measure rests:: * Automatic part combining:: +* Hara kiri staves:: +* Sound output for transposing instruments:: @end menu @c . {Rehearsal marks} @@ -2331,1887 +3222,1341 @@ scheme = \chords { @cindex Rehearsal marks @cindex mark @cindex @code{\mark} -@cindex @code{Mark_engraver} - -@example - \mark @var{unsigned}; - \mark @var{string}; - \mark ; -@end example - -With this command, you can print a rehearsal mark above the system. You -can provide a number, a string or a markup text as argument. If there is -no argument, the property @code{rehearsalMark} is used and automatically -incremented. +To print a rehearsal mark, use the @code{\mark} command. @lilypond[fragment,verbatim] \relative c'' { - c1 \mark "A2"; - c1 \mark ; - c1 \mark ; - c1 \mark "12"; - c1 \mark #'(music "scripts-segno") ; + c1 \mark "A" + c1 \mark \default + c1 \mark \default + c1 \mark "12" + c1 \mark \default c1 } @end lilypond -@node Instrument names -@subsection Instrument names - -You can specify an instrument name for a staff by setting -@code{Staff.instrument} and @code{Staff.instr}. This will print a string -before the start of the staff. For the first start, @code{instrument} is -used, for the next ones @code{instr} is used. - -@lilypond[verbatim,singleline] -\score { \notes { - \property Staff.instrument = "instr " { c''4 } } - \paper { - \translator { \StaffContext - \consists "Instrument_name_engraver"; } } } -@end lilypond - -This requires that you add the @code{Instrument_name_engraver} to the -staff context. - - -@node Transpose -@subsection Transpose -@cindex Transpose -@cindex transposition of pitches -@cindex @code{\transpose} - -A music expression can be transposed with @code{\transpose}. The syntax -is -@example - \transpose @var{pitch} @var{musicexpr} -@end example - -This means that middle C in @var{musicexpr} is transposed to -@var{pitch}. - -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose cis'} or @code{\transpose des'} will transpose up half -a tone. The first version will print sharps and the second version -will print flats. - -@quotation -@lilypond[fragment,verbatim] -\context Staff { - \clef "F"; - { \key e \major; c d e f } - \clef "G"; - \transpose des'' { \key e \major; c d e f } - \transpose cis'' { \key e \major; c d e f } -} - -@end lilypond -@end quotation - -If you want to use both @code{\transpose} and @code{\relative}, then -you must use @code{\transpose} first. @code{\relative} will have no -effect music that appears inside a @code{\transpose}. - -@node Sound output for transposing instruments -@subsection Sound output transposing instruments - -When you want to play a score containing transposed and untransposed -instruments, you have to instruct LilyPond the pitch offset (in -semitones) for the transposed instruments. This is done using -@code{transposing}. - -@cindex @code{transposing} - -@example - \property Staff.instrument = #"Cl. in B-flat" - \property Staff.transposing = #-2 -@end example - - -@c . {Multi measure rests} -@node Multi measure rests -@subsection Multi measure rests -@cindex Multi measure rests - -@cindex @code{R} - -Multi measure rests are entered using `@code{R}'. It is specifically -meant for entering parts: the rest can expand to fill a score with -rests, or it can be printed as a single multimeasure rest This expansion -is controlled by the property @code{Score.skipBars}. If this is set to true, -Lily will not expand empty measures, and the appropriate number is added -automatically. - -@lilypond[fragment,verbatim] - \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 -@end lilypond - -Currently, there is no way to condense multiple rests into a single -multimeasure rest. - -@cindex condensing rests - -@node Automatic part combining -@subsection Automatic part combining -@cindex automatic part combining -@cindex part combiner - -You will already have seen that LilyPond can combine several Threads -into one Voice, and put several Voices onto one Staff. The automatic -part combiner takes this a step further. Two parts of music can be -combined together in an intelligent way, ie, when the two parts are -identical for a period of time, only one can be showed. In places where -the two parts differ, stem directions can be set automatically. That is -why the part combiner is of great use for the typesetting of Hymns and -orchestral scores. - - -@subsubsection Part combine syntax - -The syntax for part combining is - -@example - \partcombine @var{context} @var{musicexpr1} @var{musicexpr2} -@end example - -where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be -combined into one context @var{context}. The names of the music -expressions must start with the prefixes @code{one} and @code{two}. - -@subsubsection Part combine usage - -@cindex @code{Thread_devnull_engraver} -@cindex @code{Voice_engraver} -@cindex @code{A2_engraver} - -The most useful function of the part combiner to combining threads into -one voice, as common for wind parts in orchestral scores: - -@lilypond[verbatim,singleline,fragment] - \context Staff < - \context Voice=one \partcombine Voice - \context Thread=one \notes\relative c'' { - g a b r - } - \context Thread=two \notes\relative c'' { - g r2 f4 - } - > -@end lilypond - -If you have developed a bit of a feel for LilyPond's functioning, you -will notice that what you see above is quite unusual. The first -@code{g} appears only once, although it was specified twice (once in -each Thread). That is the work of the -@code{Thread_devnull_engraver}@footnote{On unix systems, the file -@file{/dev/null} is special device: anything written to it is -discarded.}, that works closely together with the part combiner. When -the part combiner notices that two threads are identical, it tells the -@code{Thread_devnull_engraver} to discard everything in the second -thread. - -Similarly, the markings @emph{@`{a}2}, @emph{Solo} and @emph{Solo II}, -are created by the @code{A2_engraver}. The @code{A2_engraver} also acts -upon instructions of the part combiner. Another thing that the -@code{A2_engraver} does, is forcing of stem, slur and tie directions, -always when both threads are not identical; up for the musicexpr called -@code{one}, down for the musicexpr called @code{two}. - -There is actually a third engraver involved in part combining; the -@code{Voice_devnull_engraver}. This one takes care of removing -redundant spanners such as beams, slurs, ties, crescendi, etc. - -If you just want the splitting of Threads and setting of directions, and -not the textual markings, you may set the property @var{soloADue} to false: - -@lilypond[verbatim,singleline] - \context Staff < - \context Voice=one \partcombine Voice - \context Thread=one \notes\relative c'' { - b4 a c g - } - \context Thread=two \notes\relative c'' { - d,2 a4 g' - } - > - \paper{ - \translator { - \VoiceContext - soloADue = ##f - } - } -@end lilypond - -There are a number of other properties that you can use to tweak the -behavior of part combining, refer to the automatically generated -documentation of the involved engravers and the examples in the tutorial. - - -@c . {Custodes} -@node Custodes -@section Custodes -@cindex Custos -@cindex Custodes - -A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a -staff context symbol that appears at the end of a staff line. It -anticipates the pitch of the first note(s) of the following line and -thus helps the player or singer to manage line breaks during -performance, thus enhancing readability of a score. - -@quotation -@lilypond[verbatim] -\score { - \notes { c'1 d' e' d' \break c' d' e' d' } - \paper { - \translator { - \StaffContext - \consists Custos_engraver; - Custos \override #'style = #'mensural; - } - } -} -@end lilypond -@end quotation - -Custodes were frequently used in music notation until the 16th century. -There were different appearences for different notation styles. -Nowadays, they have survived only in special forms of musical notation -such as via the editio vaticana dating back to the beginning of the 20th -century. - -For typesetting custodes, just put a @code{Custos_engraver} into the -@code{StaffContext} when declaring the @code{\paper} block. In this -block, you can also globally control the appearance of the custos symbol -by setting the custos @code{style} property. Currently supported styles -are @code{vaticana}, @code{medicaea}, @code{hufnagel} and -@code{mensural}. - -@quotation -\paper @{ - \translator @{ - \StaffContext - \consists Custos_engraver; - Custos \override #'style = #'mensural; - @} -@} -@end quotation - -The property can also be set locally, for example in a @code{\notes} -block: - -@quotation -\notes @{ - \property Staff.Custos \override #'style = #'vaticana - c'1 d' e' d' \break c' d' e' d' -@} -@end quotation - -@c . {Tuning output} -@node Tuning output -@section Tuning output - -LilyPond tries to take as much formatting as possible out of your -hands. Nevertheless, there are situations where it needs some help, or -where you want to override its decisions. - -Here we discuss how you can do that. - -Notational output is specified in so called grobs (graphic -objects). Each grob carries with it a set of properties (grob -properties) specific to that grob. For example, a stem grob has grob -properties that specify its direction, length and thickness. - -The most common way of tuning the output is to alter the values of these -properties. There are two ways of doing that: first, you can -specifically select a set of grobs at one point, and set properties as -you wish, or secondly, you can (temporarily) modify the definition of a -grob, thereby affecting an entire group of grobs. - -@menu -* Tuning groups of grobs :: -* Tuning per grob :: -* What to tune?:: -* Text markup:: -@end menu - -@node Tuning groups of grobs -@subsection Tuning groups of grobs - -@cindex grob description - -A grob definition is an association list, that is stored in a context -property. By assigning to that property (using plain @code{\property}), -you can change the resulting grobs. -@lilypond[verbatim, fragment] -c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4 -@end lilypond -The @code{\property} statement effectively empties the definition of the -Stem object. One of the effects is that property specifying how it -should be printed is erased, with the effect of rendering it invisible. - -@cindex \override -@cindex \revert -@cindex \set - - -This mechanism is fairly crude, since you can only set, but not modify, -the definition of a grob. For this reason, there is a more advanced -mechanism: you can add a property on top of an existing definition, or -remove a property: @code{\override} adds a settings, @code{\revert} -removes that setting. -@lilypond[verbatim] -c'4 \property Voice.Stem \override #'thickness = #4.0 -c'4 \property Voice.Stem \revert #'thickness -c'4 -@end lilypond - -For the digirati, the grob description is an Scheme association -list. Since it is singly linked, we can treat it as a stack, and -@code{\override} and @code{\revert} are just push and pop -operations. This pushing and popping is also used in the -@code{autoBeamSettings} property. - -If you revert a setting which was not set in the first place, then it -has no effect. However, if the setting was set as a system default, it -may remove the default value, and this may give surprising results, -including crashes. In other words, if you use @code{\override} and -@code{\revert}, be sure to balance the overrides and reverts. - -If balancing them is too much work, use the following shorthand: -@code{\set} performs a revert followed by an override: -@example -\property Voice.Stem \set #'thickness = #2.0 -@end example - -Formally the syntax for these constructions is -@example -\property @var{context}.@var{grobname} \override @var{symbol} = @var{value} -\property @var{context}.@var{grobname} \set @var{symbol} = @var{value} -\property @var{context}.@var{grobname} \revert @var{symbol} -@end example -Here @var{symbol} is a Scheme expression of symbol type, @var{context} -and @var{grobname} are strings and @var{value} is a Scheme expression. - -LilyPond will hang or crash if @var{value} contains cyclic references. - - - -@node Tuning per grob -@subsection Tuning per grob - -@cindex \outputproperty - -A second way of tuning grobs is the more arcane @code{\outputproperty} -feature. -Syntax is as follows -@example -\outputproperty @var{predicate} @var{symbol} = @var{value} -@end example -Here @code{predicate} is a Scheme functoin taking a grob a argument -argument, and returning a boolean. This statement is processed by the -@code{Output_property_engraver}. It instructs the engraver to feed all -grobs that it sees to @var{predicate}. Whenever the predicate returns -true, the grob property @var{symbol} will be set to @var{value}. - -You will need to combine this statement with @code{\context} to select -the appropriate context to apply this to. - -If possible, avoid this feature: the semantics are not very clean, and -the syntax and semantics are up for rewrite. - -Here are some random examples: - -@lilypond[fragment,verbatim,singleline] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'note-head-interface) - #'extra-offset = #'(0.5 . 0.75) - } -@end lilypond - -@cindex @code{extra-offset} - -This selects all note heads occurring at current staff level, and sets -the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting -them up and right. - -Move the text "m.d.", but not the fingering instruction "2". -@lilypond[verbatim,singleline] -#(define (make-text-checker text) - (lambda (grob) (equal? text (ly-get-elt-property grob 'text)))) - -\score { - \notes\relative c''' { - \property Voice.Stem \set #'direction = #1 - \outputproperty #(make-text-checker "m.d.") - #'extra-offset = #'(-3.5 . -4.5) - a^2^"m.d." - } -} -@end lilypond - - - - -@node What to tune? -@subsection What to tune? - -This all tells you how to tune grobs, but what variables are there? The -question is not answered in this manual (although you may encounter -some examples.). - -Grob properties are tied directly to the implementation of LilyPond, and -they are thus a moving target. Refer to the automatically generated -documentation of the internals (available from the website). - -You need the following information - -@itemize @bullet -@item -which grob to modify -@item -which property to modify -@item -which context the grob comes from. -@end itemize - -Included with the automatically generated documentation is a master list -of grobs. Each one can be clicked, taking you to a overview of the -available properties. - -There is also a master list of contexts. Clicking each takes you to an -overview of the context, listing which grob types are created there. - - - -@node Text markup -@subsection Text markup -@cindex text markup -@cindex markup text - -LilyPond has an internal mechanism to typeset texts. You can -form text markup expressions by composing scheme expressions -in the following way. - -@lilypond[verbatim] -\score { \notes \relative c' { - b-#"text" - c-#'(bold "text") - d-#'(lines "one" (bold "text")) - e-#'(music (named "noteheads-2" "flags-u3")) -} -\paper { linewidth = 10.\cm; } } +As you can see, the mark is incremented automatically if you use +@code{\mark \default}. The value to use is stored in the property +@code{rehearsalMark} is used and automatically incremented. The grob +is @internalsref{RehearsalMark} in @internalsref{Score} context. See +@code{input/test/boxed-molecule.ly} if you need boxes around the +marks. + +The @code{\mark} command can also be used to put signs like coda, +segno and fermatas on a barline. The trick is to use the text markup +mechanism to access the fermata symbol. +@lilypond[fragment,verbatim,relative=1] + c1 \mark #'(music "scripts-ufermata") + c1 @end lilypond -Normally, the Scheme markup text is stored in the @code{text} property -of a grob. Formally, it is defined as follows: - -@example -text: string | (head? text+) -head: markup | (markup+) -markup-item: property | abbrev | @var{fontstyle} -property: (@var{key} . @var{value}) -abbrev: @code{rows lines roman music bold italic named super sub text} -@end example - -The markup is broken down and converted into a list of grob properties, -which are prepended to the grop's property list. The -@var{key}-@var{value} pair is a grob property. - -The following abbreviations are currently -defined: - -@table @code -@item rows -horizontal mode: set all text on one line (default) -@item lines - vertical mode: set every text on new line -@item roman - select roman font -@item music - select feta font -@item bold - select bold series -@item italic - select italic shape -@item named - lookup by character name -@item text - plain text lookup (by character value) -@item super - superscript -@item sub - subscript -@end table - -@var{fontstyle} may be any of @code{finger volta timesig mmrest mark -script large Large dynamic} - - -@c . {Page layout} -@node Page layout -@section Page layout -@cindex Page layout - -@menu -* Paper block:: -* Paper variables:: -* Font Size:: -* Paper size:: -* Line break:: -* Page break:: -@end menu - -@c . {Paper block} -@node Paper block -@subsection Paper block -@cindex Paper block - -The most important output definition is the @code{\paper} block, for -music notation. The syntax is - -@example - @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} -@end example - -where each of the items is one of - -@itemize @bullet - @item An assignment. The assignment must be terminated by a - semicolon. - - @item A context definition. See Section @ref{Notation Contexts} for - more information on context definitions. - - @item \stylesheet declaration. Its syntax is - @example - \stylesheet @var{alist} - @end example - - See @file{font.scm} for details of @var{alist}. -@end itemize - -@c . {Paper variables} -@node Paper variables -@subsection Paper variables -@cindex Paper variables - -The paper block has some variables you may want to use or change: - -@table @code -@cindex @code{indent} - @item @code{indent} - The indentation of the first line of music. -@cindex @code{staffspace} - - @item @code{staffspace} - The distance between two staff lines, calculated from the center - of the lines. You should use either this or @code{stafflinethickness} - as a unit for distances you modify. - -@cindex @code{linewidth} - @item @code{linewidth} - Sets the width of the lines. - -If set to a negative value, a single - unjustified line is produced. - -@cindex @code{textheight} - - @item @code{textheight} - Sets the total height of the music on each page. Only used by - ly2dvi. -@cindex @code{interscoreline} - - @item @code{interscoreline} - Sets the spacing between the score lines. Defaults to 16 pt. -@cindex @code{interscorelinefill} - - @item @code{interscorelinefill} - If set to a positive number, the distance between the score - lines will stretch in order to fill the full page. In that - case @code{interscoreline} specifies the minimum spacing. - Defaults to 0. -@cindex @code{stafflinethickness} - - @item @code{stafflinethickness} - Determines the thickness of staff lines, and also acts as a scaling - parameter for other line thicknesses. -@end table - - - -@c . {Font size} -@node Font Size -@subsection Font size -@cindex font size - -The Feta font provides musical symbols at six different sizes. These -fonts are 11 point, 13 point, 16 point, 20 point, -23 point, and 26 point. The point size of a font is the -height of the five lines in a staff when displayed in the font. - -Definitions for these sizes are the files @file{paperSZ.ly}, where -@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of -these files, the identifiers @code{paperEleven}, @code{paperThirteen}, -@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and -@code{paperTwentysix} are defined respectively. The default -@code{\paper} block is also set. - -The font definitions are generated using a Scheme function. For more -details, see the file @file{font.scm}. - - - -@c . {Paper size} -@node Paper size -@subsection Paper size -@cindex Paper size - -@cindex paper size -@cindex page size -@cindex @code{papersize} - -To change the paper size, you must first set the -@code{papersize} variable at top level. Set it to -the strings @code{a4}, @code{letter}, or @code{legal}. After this -specification, you must set the font as described above. If you want -the default font, then use the 20 point font. The new paper size will -not take effect if the font is not loaded and selected afterwards. - -@example - papersize = "a4" - \include "paper16.ly" - - \score @{ - ... - \paper @{ \paperSixteen @} - @} -@end example - -The file "paper16.ly" will now include a file named @file{a4.ly}, which -will set the paper variables @code{hsize} and @code{vsize} (used by -@code{ly2dvi}) - - - - - - - -@c . {Line break} -@node Line break -@subsection Line break - -@cindex line breaks -@cindex breaking lines - -Line breaks are normally computed automatically. They are chosen such -that the resulting spacing has low variation, and looks neither cramped -nor loose. - -Occasionally you might want to override the automatic breaks; you can do -this by specifying @code{\break}. This will force a line break at this -point. Do remember that line breaks can only occur at places where there -are barlines. If you want to have a line break where there is no -barline, you can force a barline by entering @code{\bar "";}. - -Similarly, @code{\noBreak} forbids a line break at a certain point. - -@cindex @code{\penalty} - -The @code{\break} and @code{\noBreak} commands are defined in terms of -the penalty command: -@example - \penalty @var{int} @code{;} -@end example - -This imposes encourages or discourages LilyPond to make a line break -at this point. - -@strong{Warning} do not use @code{\penalty} directly. It is rather -kludgy, and slated for rewriting. - -@c . {Page break} -@node Page break -@subsection Page break - -@cindex page breaks -@cindex breaking pages - - -Page breaks are normally computed by @TeX{}, so they are not under direct -control. However, you can insert a commands into the @file{.tex} output to -instruct @TeX{} where to break pages. For more details, see the -example file @file{input/test/between-systems.ly} - -[or -> Tricks? ] - - - - - - -@c . {Sound} -@node Sound -@section Sound -@cindex Sound - -LilyPond allows MIDI output, with the purpose of proof-hearing the music -you enter. The performance lacks lots of interesting effects, such as -swing, articulation, slurring, tieing, etc. - -Also note that it is not possible to use the percussion channel -(generally channel 10 of a MIDI file). - -@menu -* MIDI block:: -* MIDI instrument names:: -* Tempo:: -@end menu - -@c . {MIDI block} -@node MIDI block -@subsection MIDI block -@cindex MIDI block - - -The MIDI block is analogous to the paper block, but it is somewhat -simpler. The @code{\midi} block can contain: -@cindex MIDI block - -@itemize @bullet - @item a @code{\tempo} definition - @item context definitions -@end itemize - -Assignments in the @code{\midi} block are not allowed. - - - -@cindex context definition - -Context definitions follow precisely the same syntax as within the -\paper block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/performer.ly}. - -[Volume control] -[Instrument Equaliser] - -FIXME: would it be useful to refer to files like scm/midi.scm, -or to give examples of how to tweak MIDI output volume? - +The problem is that marks that occur at a line break are typeset only +at the beginning of the next line, opposite to what you want for the +fermata. This can be corrected by the following property setting +@example +\property Score.RehearsalMark \override + #'visibility-lambda = #begin-of-line-invisible +@end example -@c . {MIDI instrument names} -@node MIDI instrument names -@subsection MIDI instrument names -@cindex instrument names -@cindex @code{Staff.midiInstrument} -@cindex @code{Staff.instrument} +@cindex fermatas +@cindex coda +@cindex segno +@cindex barlines, putting symbols on -The MIDI instrument name is set by the @code{Staff.midiInstrument} -property or, if that property is not set, the @code{Staff.instrument} -property. The instrument name should be chosen from the following list. -If the selected string does not exactly match, then LilyPond uses the -default piano. -[FIXME: to appendix ] +@node Bar numbers +@subsection Bar numbers -@example -"acoustic grand" "contrabass" "lead 7 (fifths)" -"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" -"electric grand" "pizzicato strings" "pad 1 (new age)" -"honky-tonk" "orchestral strings" "pad 2 (warm)" -"electric piano 1" "timpani" "pad 3 (polysynth)" -"electric piano 2" "string ensemble 1" "pad 4 (choir)" -"harpsichord" "string ensemble 2" "pad 5 (bowed)" -"clav" "synthstrings 1" "pad 6 (metallic)" -"celesta" "synthstrings 2" "pad 7 (halo)" -"glockenspiel" "choir aahs" "pad 8 (sweep)" -"music box" "voice oohs" "fx 1 (rain)" -"vibraphone" "synth voice" "fx 2 (soundtrack)" -"marimba" "orchestra hit" "fx 3 (crystal)" -"xylophone" "trumpet" "fx 4 (atmosphere)" -"tubular bells" "trombone" "fx 5 (brightness)" -"dulcimer" "tuba" "fx 6 (goblins)" -"drawbar organ" "muted trumpet" "fx 7 (echoes)" -"percussive organ" "french horn" "fx 8 (sci-fi)" -"rock organ" "brass section" "sitar" -"church organ" "synthbrass 1" "banjo" -"reed organ" "synthbrass 2" "shamisen" -"accordion" "soprano sax" "koto" -"harmonica" "alto sax" "kalimba" -"concertina" "tenor sax" "bagpipe" -"acoustic guitar (nylon)" "baritone sax" "fiddle" -"acoustic guitar (steel)" "oboe" "shanai" -"electric guitar (jazz)" "english horn" "tinkle bell" -"electric guitar (clean)" "bassoon" "agogo" -"electric guitar (muted)" "clarinet" "steel drums" -"overdriven guitar" "piccolo" "woodblock" -"distorted guitar" "flute" "taiko drum" -"guitar harmonics" "recorder" "melodic tom" -"acoustic bass" "pan flute" "synth drum" -"electric bass (finger)" "blown bottle" "reverse cymbal" -"electric bass (pick)" "skakuhachi" "guitar fret noise" -"fretless bass" "whistle" "breath noise" -"slap bass 1" "ocarina" "seashore" -"slap bass 2" "lead 1 (square)" "bird tweet" -"synth bass 1" "lead 2 (sawtooth)" "telephone ring" -"synth bass 2" "lead 3 (calliope)" "helicopter" -"violin" "lead 4 (chiff)" "applause" -"viola" "lead 5 (charang)" "gunshot" -"cello" "lead 6 (voice)" -@end example +@cindex bar numbers +@cindex measure numbers +@cindex currentBarNumber +Bar numbers are printed by default at the start of the line. The +number itself is a property that can be set by modifying the +@code{currentBarNumber} property, i.e. +@example + \property Score.currentBarNumber = #217 +@end example +If you want boxed bar numbers, see the example file +@code{input/test/boxed-molecule.ly}. +See also @seeinternals{BarNumber}. +@refbugs -@c . {Tempo} -@node Tempo -@subsection Tempo -@cindex Tempo -@cindex beats per minute -@cindex metronome marking +Printing bar numbers at regular intervals is not implemented. +Barnumbers can collide with the StaffGroup, if there is one at the +top. To solve this, You have to twiddle with the +@internalsref{padding} property of @internalsref{BarNumber} if your +score starts with a @internalsref{StaffGroup}. -@cindex @code{\tempo} -@example - \tempo @var{duration} = @var{perminute} @code{;} -@end example +@node Instrument names +@subsection Instrument names -Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests -output with 76 quarter notes per minute. +In scores, the instrument name is printed before the staff. This can +be done by setting @code{Staff.instrument} and +@code{Staff.instr}. This will print a string before the start of the +staff. For the first start, @code{instrument} is used, for the next +ones @code{instr} is used. +@lilypond[verbatim,singleline] + \property Staff.instrument = "ploink " { c''4 } +@end lilypond +You can also use markup texts to construct more complicated instrument +names: +@lilypond[verbatim,singleline] +#(define text-flat + '((font-relative-size . -2 ) (music "accidentals--1"))) -@c . {Music entry} -@node Music entry -@section Music entry -@cindex Music entry -@menu -* Relative:: -* Point and click:: -@end menu +\score { \notes { + \property Staff.instrument = #`((kern . 0.5) (lines + "2 Clarinetti" (columns " (B" ,text-flat ")"))) + c'' 4 } +} +@end lilypond +@refbugs -@c . {Relative} -@node Relative -@subsection Relative -@cindex Relative -@cindex relative octave specification +When you put a name on a grand staff or piano staff the width of the +brace is not taken into account. You must add extra spaces to the end of +the name to avoid a collision. -Octaves are specified by adding @code{'} and @code{,} to pitch names. -When you copy existing music, it is easy to accidentally put a pitch in -the wrong octave and hard to find such an error. To prevent these -errors, LilyPond features octave entry. +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} -@cindex @code{\relative} +A music expression can be transposed with @code{\transpose}. The syntax +is @example - \relative @var{startpitch} @var{musicexpr} + \transpose @var{pitch} @var{musicexpr} @end example -The octave of notes that appear in @var{musicexpr} are calculated as -follows: If no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or less. - The octave changing marks @code{'} and @code{,} can then -be added to raise or lower the pitch by an extra octave. Upon entering -relative mode, an absolute starting pitch must be specified that will -act as the predecessor of the first note of @var{musicexpr}. - -This distance is determined without regarding accidentals: a -@code{fisis} following a @code{ceses} will be put above the -@code{ceses}. +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. -Entering scales is straightforward in relative mode. +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose cis'} or @code{\transpose des'} will transpose up half +a tone. The first version will print sharps and the second version +will print flats. -@lilypond[fragment,verbatim,center] - \relative c'' { - g a b c d e f g g, g - } +@lilypond[singleline, verbatim] +mus =\notes { \key d \major cis d fis g } +\score { \notes \context Staff { + \clef "F" \mus + \clef "G" + \transpose g'' \mus + \transpose f'' \mus +}} @end lilypond -And octave changing marks are used for intervals greater than a fourth. +If you want to use both @code{\transpose} and @code{\relative}, then +you must use @code{\transpose} first. @code{\relative} will have no +effect music that appears inside a @code{\transpose}. -@lilypond[fragment,verbatim,center] - \relative c'' { - c g c f, c' a, e'' } -@end lilypond +@c . {Multi measure rests} +@node Multi measure rests +@subsection Multi measure rests +@cindex Multi measure rests -If the preceding item is a chord, the first note of the chord is used -to determine the first note of the next chord. But other notes -within the second chord are determined by looking at the immediately -preceding note. +@cindex @code{R} -@lilypond[fragment,verbatim,center] - \relative c' { - c - - - } -@end lilypond -@cindex @code{\notes} +Multi measure rests are entered using `@code{R}'. It is specifically +meant for full bar rests and for entering parts: the rest can expand to +fill a score with +rests, or it can be printed as a single multimeasure rest This expansion +is controlled by the property @code{Score.skipBars}. If this is set to true, +Lily will not expand empty measures, and the appropriate number is added +automatically. -The pitch after the @code{\relative} contains a notename. To parse -the pitch as a notename, you have to be in note mode, so there must -be a surrounding @code{\notes} keyword (which is not -shown here). +@lilypond[fragment,verbatim] + \time 3/4 r2. | R2. | R2.*2 + \property Score.skipBars = ##t R2.*17 R2.*4 +@end lilypond -The relative conversion will not affect @code{\transpose} or -@code{\relative} sections in its argument. If you want to use -relative within transposed music, you must place an additional -@code{\relative} inside the @code{\transpose}. +Notice that the @code{R2.} is printed as a whole rest, centered in the +measure. +@cindex whole rests for a full measure -@c . {Point and click} -@node Point and click -@subsection Point and click +The grob for this object is @internalsref{MultiMeasureRest}. -[todo] +@refbugs -@c . {Engravers} -@node Engravers -@section Engravers -@cindex engravers -@menu -* Notation Contexts:: -* Creating contexts:: -* Default contexts:: -* Context properties:: -* Changing context definitions:: -* Defining new contexts:: -@end menu +Currently, there is no way to automatically condense multiple rests +into a single multimeasure rest. Multi measure rests do not take part +in rest collisions. + +@cindex condensing rests -@c . {Music expressions} +@node Automatic part combining +@subsection Automatic part combining +@cindex automatic part combining +@cindex part combiner +Automatic part combining is used to merge two parts of music onto a +staff in an intelligent way. It is aimed primarily at typesetting +orchestral scores. When the two parts are identical for a period of +time, only one is shown. In places where the two parts differ, they +are typeset as separate voices, and stem directions are set +automatically. Also, solo and @emph{a due} parts can be identified +and marked. -@c . {Notation Contexts} -@node Notation Contexts -@subsection Notation Contexts +The syntax for part combining is -@cindex notation contexts +@example + \partcombine @var{context} @var{musicexpr1} @var{musicexpr2} +@end example +where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be +combined into one context of type @var{context}. The music expressions +must be interpreted by contexts whose names should start with @code{one} +and @code{two}. -Notation contexts are objects that only exist during a run of LilyPond. -During the interpretation phase of LilyPond (when lily prints -"interpreting music"), music a @code{\score} block is interpreted in -time order, i.e. in much the same order that humans read, play, and -write music. +The most useful function of the part combiner is to combine parts into +one voice, as common for wind parts in orchestral scores: -During this reading, the notation context is holds the state -for the current point within the music. It contains information like +@lilypond[verbatim,singleline,fragment] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + g a () b r + } + \context Thread=two \relative c'' { + g r4 r f + } + > +@end lilypond -@itemize @bullet - @item What notes are playing at this point? - @item What symbols will be printed at this point? - @item What is the current key signature, time signature, point within - the measure, etc.? -@end itemize +Notice that the first @code{g} appears only once, although it was +specified twice (once in each part). Stem, slur and tie directions are +set automatically, depending whether there is a solo or unisono. The +first part (with context called @code{one}) always gets up stems, and +`solo', while the second (called @code{two}) always gets down stems and +`Solo II'. -Contexts are grouped hierarchically: A @code{Voice} context is -contained in a @code{Staff} context (because a staff can contain -multiple voices at any point), a @code{Staff} context is contained in -a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because -these can all contain multiple staffs). +If you just want the merging parts, and not the textual markings, you +may set the property @var{soloADue} to false. +@lilypond[verbatim,singleline,fragment] + \context Staff < + \property Staff.soloADue = ##f + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + b4 a c g + } + \context Thread=two \relative c'' { + d,2 a4 g' + } + > +@end lilypond -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called performance contexts. +There are a number of other properties that you can use to tweak the +behavior of part combining, refer to the automatically generated +documentation of @reng{Thread_devnull_engraver} and +@reng{Voice_devnull_engraver}. Look at the documentation of the +responsible engravers, @code{Thread_devnull_engraver}, +@code{Voice_devnull_engraver} and @code{A2_engraver}. +@refbugs -@node Creating contexts -@subsection Creating contexts +In @code{soloADue} mode, when the two voices play the same notes on and +off, the part combiner may typeset @code{a2} more than once in a +measure. -@cindex @code{\context} -@cindex context selection +@lilypond[fragment,singleline] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + c b c b c a c a + } + \context Thread=two \relative c'' { + b b b b f a f a + } + > +@end lilypond -Contexts for a music expression can be selected manually, using the -following music expression. +@cindex @code{Thread_devnull_engraver} +@cindex @code{Voice_engraver} +@cindex @code{A2_engraver} -@example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example +@node Hara kiri staves +@subsection Hara kiri staves -This instructs lilypond to interpret @var{musicexpr} within the context - of type @var{contexttype} and with name @var{contextname}. If this -context does not exist, it will be created. +In orchestral scores, staff lines that only have rests are usually removed. +This saves some space. LilyPond also supports this through the hara +kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of +the Japanese Samourai warriors.} staff. This staff commits suicide when +it finds itself to be empty after the line-breaking process. It will +not disappear when it contains normal rests, you must use multi measure +rests. -@quotation +The hara kiri staff is specialized version of the @internalsref{Staff} +context. It is available as the context identifier +@code{\HaraKiriStaffContext}. Observe how the second staff in this +example disappears in the second line. -@lilypond[verbatim,singleline] -\score { - \notes \relative c'' { - c4 f +@lilypond[verbatim] +\score { + \notes \relative c' < + \context Staff = SA { e4 f g a \break c1 } + \context Staff = SB { c4 d e f \break R1 } + > + \paper { + linewidth = 6.\cm + \translator { \HaraKiriStaffContext } } } - @end lilypond -@end quotation -In this example, the @code{c} and @code{d} are printed on the -default staff. For the @code{e}, a context Staff called -@code{another} is specified; since that does not exist, a new -context is created. Within @code{another}, a (default) Voice context -is created for the @code{e4}. When all music referring to a -context is finished, the context is ended as well. So after the -third quarter, @code{another} is removed. +@node Sound output for transposing instruments +@subsection Sound output for transposing instruments +When you want to make a MIDI file from a score containing transposed +and untransposed instruments, you have to instruct LilyPond the pitch +offset (in semitones) for the transposed instruments. This is done +using the @code{transposing} property. It does not affect printed +output. -@node Default contexts -@subsection Default contexts +@cindex @code{transposing} -Most music expressions don't need @code{\context}: they inherit the -notation context from their parent. Each note is a music expression, and -as you can see in the following example, only the sequential music -enclosing the three notes has an explicit context. +@example + \property Staff.instrument = #"Cl. in B-flat" + \property Staff.transposing = #-2 +@end example -@lilypond[verbatim,singleline] -\score { \notes \context Voice = goUp { c'4 d' e' } } -@end lilypond -There are some quirks that you must keep in mind when dealing with -defaults: -Every top-level music is interpreted by the Score context, in other -words, you may think of @code{\score} working like -@example - \score @{ - \context Score @var{music} - @} -@end example +@c . {Custodes} +@node Ancient notation +@section Ancient notation -Sequential music follows the contexts of its "children". Take this example -@lilypond[verbatim, singleline] -\score { \context Score \notes { c'4 ( d' )e' } } -@end lilypond +@menu +* Ancient note heads:: +* Custodes:: +* Ancient clefs :: +* Figured bass:: +@end menu -The sequential music is interpreted by the Score context initially -(notice that the @code{\context} specification is redundant), but when a -note is encountered, contexts are setup to accept that note. In this -case, a Thread, Voice and Staff are created. The rest of the sequential -music is also interpreted with the same Thread, Voice and Staff context, -putting the notes on the same staff, in the same voice. -This is a convenient mechanism, but do not expect opening chords to work -without @code{\context}. For every note, a separate staff is -instantiated. +@node Ancient note heads +@subsection Ancient note heads -@lilypond[verbatim, singleline] -\score { \notes } + To get a longa note head, you have to use mensural note heads. This +is accomplished by setting the @code{style} property of the +NoteHead grob to @code{mensural}. There is also a note head style +@code{baroque} which gives mensural note heads for @code{\longa} and +@code{\breve} but standard note heads for shorter notes. + +@lilypond[fragment,singleline,verbatim] + \property Voice.NoteHead \set #'style = #'mensural + \property Voice.NoteHead \set #'font-family = #'ancient + a'\longa @end lilypond -Of course, if the chord is preceded by a normal note in sequential -music, the chord will be interpreted by the Thread of the preceding -note: -@lilypond[verbatim,singleline] -\score { \notes { c'4 } } +@node Custodes +@subsection Custodes + +@cindex Custos +@cindex Custodes + +A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a +staff context symbol that appears at the end of a staff line. It +anticipates the pitch of the first note(s) of the following line and +thus helps the player or singer to manage line breaks during +performance, thus enhancing readability of a score. + +@lilypond[verbatim] +\score { + \notes { c'1 \break + \property Staff.Custos \set #'style = #'mensural + d' } + \paper { + \translator { + \StaffContext + \consists Custos_engraver + } + } +} @end lilypond +Custodes were frequently used in music notation until the 17th century. +There were different appearances for different notation styles. +Nowadays, they have survived only in special forms of musical notation +such as via the @emph{editio vaticana} dating back to the beginning of +the 20th century. +For typesetting custodes, just put a @code{Custos_engraver} into the +@internalsref{Staff} context when declaring the @code{\paper} block. In this +block, you can also globally control the appearance of the custos symbol +by setting the custos @code{style} property. Currently supported styles +are @code{vaticana}, @code{medicaea}, @code{hufnagel} and +@code{mensural}. -@node Context properties -@subsection Context properties +@example +\paper @{ + \translator @{ + \StaffContext + \consists Custos_engraver + Custos \override #'style = #'mensural + @} +@} +@end example -Notation contexts can be modified from within the @file{.ly} file. The -following music expression does that job: +The property can also be set locally, for example in a @code{\notes} +block: -@cindex @code{\property} @example - \property @var{contextname}.@var{propname} = @var{value} +\notes @{ + \property Staff.Custos \override #'style = #'vaticana + c'1 d' e' d' \break c' d' e' d' +@} @end example -Sets the @var{propname} property of the context @var{contextname} to the -specified Scheme expression @var{value}. All @var{propname} and -@var{contextname} are strings, which are typically unquoted. +@node Ancient clefs +@subsection Ancient clefs -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@code{Voice} context can be set in the @code{Score} context (for -example) and thus take effect in all @code{Voice} contexts. +LilyPond supports a variety of clefs, many of them ancient. These can +be selected from the @code{ancient} font family, by setting +@code{Staff.clefGlyph}) to one of the following values +@table @code +@item clefs-C + modern style C clef +@item clefs-F + modern style F clef +@item clefs-G + modern style G clef +@item clefs-vaticana_do + Editio Vaticana style do clef +@item clefs-vaticana_fa + Editio Vaticana style fa clef +@item clefs-medicaea_do + Editio Medicaea style do clef +@item clefs-medicaea_fa + Editio Medicaea style fa clef +@item clefs-mensural1_c + modern style mensural C clef +@item clefs-mensural2_c + historic style small mensural C clef +@item clefs-mensural3_c + historic style big mensural C clef +@item clefs-mensural1_f + historic style traditional mensural F clef +@item clefs-mensural2_f + historic style new mensural F clef +@item clefs-mensural_g + historic style mensural G clef +@item clefs-hufnagel_do + historic style hufnagel do clef +@item clefs-hufnagel_fa + historic style hufnagel fa clef +@item clefs-hufnagel_do_fa + historic style hufnagel combined do/fa clef +@item clefs-percussion + modern style percussion clef +@end table +@emph{Modern style} means ``as is typeset in current editions.'' +@emph{Historic style} means ``as was typeset or written in contemporary +historic editions''. @emph{Editio XXX style} means ``as is/was printed in +Editio XXX.'' +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel clefs -@c . {Context definitions} -@node Changing context definitions -@subsection Changing context definitions -@cindex context definition -@cindex translator definition +@node Figured bass +@subsection Figured bass + +@cindex Basso continuo + +LilyPond has limited support for figured bass: + +@lilypond[verbatim,fragment] +< + \context FiguredBass + \figures { + <_! 3+ 5- >4 + < [4 6] 8 > + } + \context Voice { c4 g8 } +> +@end lilypond -The most common way to define a context is by extending an existing -context. You can change an existing context from the paper block, by -first initializing a translator with an existing context identifier: +The support for figured bass consists of two parts: there is an input +mode, introduced by @code{\figures}, where you can enter bass figures +as numbers, and there is a context called @internalsref{FiguredBass} +that takes care of making @internalsref{BassFigure} grobs. + +In figures input mode, a group of bass figures is delimited by +@code{<} and @code{>}. The duration is entered after the @code{>}. @example -\paper @{ - \translator @{ - @var{context-identifier} - @} @} + <4 6> @end example -Then you can add engravers, remove engravers and set context -properties. The syntax for these operations are respectively +@lilypond[fragment] +\context FiguredBass +\figures { <4 6> } +@end lilypond + +Accidentals are added to the numbers if you alterate them by +appending @code{-}, @code{!} and @code{+}. + @example - \remove @var{engravername} - \consists @var{engravername} - @var{propname} = @var{value} + <4- 6+ 7!> @end example +@lilypond[fragment] + \context FiguredBass +\figures { <4- 6+ 7!> } +@end lilypond -Here @var{engravername} is a string, the name of an engraver in the -system. @var{propname} is a string and @var{value} is a Scheme -expression. +Spaces or dashes may be inserted by using @code{_}. Brackets are +introduced with @code{[} and @code{]}. -@lilypond[verbatim,singleline] -\score { \notes { - c'4 c'4 } - \paper { - \translator { \StaffContext - \consists Instrument_name_engraver; - instrument = #"foo" - \remove Clef_engraver; - } } } +@example + < [4 6] 8 [_ 12]> +@end example +@lilypond[fragment] + \context FiguredBass +\figures { < [4 6] 8 [_ 12]> } @end lilypond -@cindex engraver +Although the support for figured bass may superficially resemble chord +support, it works much simpler: in figured bass simply stores the +numbers, and then prints the numbers you entered. There is no +conversion to pitches, and no realizations of the bass are played in +the MIDI file. -These type of property assignments happen before interpretation starts, -so a @code{\property} expression will override any predefined settings. -Engravers are the actual C++ modules that do the work in the -interpretation phase. +@c . {Tuning output} +@node Tuning output +@section Tuning output +LilyPond tries to take as much formatting as possible out of your +hands. Nevertheless, there are situations where it needs some help, or +where you want to override its decisions. In this section we discuss +ways to do just that. -There are some pre-defined identifiers to simplify editing translators, -they are defined in @file{ly/engraver.ly}. These pre-defined -identifiers are: +Formatting is internally done by manipulating so called grobs (graphic +objects). Each grob carries with it a set of properties (grob +properties) specific to that object. For example, a stem grob has +properties that specify its direction, length and thickness. -@table @code -@cindex @code{StaffContext} - @item @code{StaffContext} - Default Staff context. -@cindex @code{RhythmicStaffContext} +The most direct way of tuning the output is by altering the values of +these properties. There are two ways of doing that: first, you can +temporarily change the definition of a certain type of grob, thus +affecting a whole set of objects. Second, you can select one specific +object, and set a grob property in that object. - @item @code{RhythmicStaffContext} - Default RhythmicStaff context. -@cindex @code{VoiceContext} +@menu +* Tuning groups of grobs :: +* Tuning per grob :: +* Font selection:: +* Text markup:: +@end menu - @item @code{VoiceContext} - Default Voice context. -@cindex @code{ScoreContext} +@node Tuning groups of grobs +@subsection Tuning groups of grobs - @item @code{ScoreContext} - Default Score context. +@cindex grob description -@cindex @code{HaraKiriStaffContext} - @item @code{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Japanese Samourai warriors.} -@end table -@node Defining new contexts -@subsection Defining new contexts +A grob definition is a Scheme association list, that is stored in a +context property. By assigning to that property (using plain +@code{\property}), you can change the resulting grobs. -If you want to build a context from scratch, you must also supply the -following extra information: -@itemize @bullet - @item A name, specified by @code{\name @var{contextname};}. +@lilypond[verbatim, fragment] +c'4 \property Voice.Stem = #'() +@end lilypond - @item A cooperation engraver. This is specified by @code{\type -@var{typename};}. -@end itemize +The @code{\property} assignment effectively empties the definition of +the Stem object. One of the effects is that the recipe of how it should be +printed is erased, with the effect of rendering it invisible. The above +assignment is available as a standard identifier, for the case that you +find this useful: +@example + \property Voice.Stem = \turnOff +@end example -A context definition has this syntax: +@cindex \override +@cindex \revert +@cindex \set -@example +This mechanism is fairly crude, since you can only set, but not modify, +the definition of a grob. For this reason, there is a more advanced +mechanism. - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} -@end example +The definition of a grob is actually a list of default grob +properties. For example, the definition of the Stem grob (available in +@file{scm/grob-description.scm}), defines the following values for +@internalsref{Stem} -@var{translatorinit} can be an identifier or @example - + (thickness . 0.8) + (beamed-lengths . (0.0 2.5 2.0 1.5)) + (Y-extent-callback . ,Stem::height) + @var{...} @end example -where @var{typename} is one of -The cooperation engraver groups other engravers, and specifies how they -should cooperate. Choices are: +You can add a property on top of the existing definition, or remove a +property, thus overriding the system defaults: +@lilypond[verbatim] +c'4 \property Voice.Stem \override #'thickness = #4.0 +c'4 \property Voice.Stem \revert #'thickness +c'4 +@end lilypond +You should balance @code{\override} and @code{\revert}. If that's too +much work, you can use the @code{\set} shorthand. It performs a revert +followed by an override. The following example gives exactly the same +result as the previous one. +@lilypond[verbatim] +c'4 \property Voice.Stem \set #'thickness = #4.0 +c'4 \property Voice.Stem \set #'thickness = #0.8 +c'4 +@end lilypond +If you use @code{\set}, you must explicitly restore the default. -@table @code -@cindex @code{Engraver_group_engraver} - @item @code{Engraver_group_engraver} - The standard cooperation engraver. -@cindex @code{Score_engraver} +Formally the syntax for these constructions is +@example +\property @var{context}.@var{grobname} \override @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \set @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \revert @var{symbol} +@end example +Here @var{symbol} is a Scheme expression of symbol type, @var{context} +and @var{grobname} are strings and @var{value} is a Scheme expression. - @item @code{Score_engraver} - This is cooperation module that should be in the top level context, -and only the toplevel context. -@cindex @code{Grace_engraver_group} +If you revert a setting which was not set in the first place, then it +has no effect. However, if the setting was set as a system default, it +may remove the default value, and this may give surprising results, +including crashes. In other words, @code{\override} and @code{\revert}, +must be carefully balanced. - @item @code{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded - `miniscore'. -@end table +These are examples of correct nesting of @code{\override}, @code{\set}, +@code{\revert}. -@var{translatormodifierlist} is a list of items where each item is -one of +A clumsy but correct form: +@example + \override \revert \override \revert \override \revert +@end example -@itemize @bullet - @item @code{\consists} @var{engravername} @code{;} - Add @var{engravername} to the list of modules in this context. - The order of engravers added with @code{\consists} is - significant. - - @item @code{\consistsend} @var{engravername} @code{;} - Analogous to @code{\consists}, but makes sure that - @var{engravername} is always added to the end of the list of - engravers. - - Some engraver types need to be at the end of the list; this - insures they are put there, and stay there, if a user adds or - removes engravers. This command is usually not needed for - end-users. - - @item @code{\accepts} @var{contextname} @code{;} - Add @var{contextname} to the list of context this context can - contain. The first listed context is the context to create by - default. - - @item @code{\denies}. The opposite of @code{\accepts}. Added for -completeness, but is never used in practice. - - - @item @code{\remove} @var{engravername} @code{;} - Remove a previously added (with @code{\consists}) engraver. - - @item @code{\name} @var{contextname} @code{;} - This sets name of the context, e.g. @code{Staff}, @code{Voice}. If - the name is not specified, the translator won't do anything. +Shorter version of the same: +@example + \override \set \set \revert +@end example - @item @var{propname} @code{=} @var{value} @code{;} - A property assignment. -@end itemize +A short form, using only @code{\set}. This requires you to know the +default value: +@example + \set \set \set \set @var{to default value} +@end example -In the @code{\paper} block, it is also possible to define translator -identifiers. Like other block identifiers, the identifier can only -be used as the very first item of a translator. In order to define -such an identifier outside of @code{\score}, you must do +If there is no default (i.e. by default, the grob property is unset), +then you can use +@example + \set \set \set \revert +@end example -@quotation +For the digirati, the grob description is an Scheme association +list. Since a Scheme list is a singly linked list, we can treat it as a +stack, and @code{\override} and @code{\revert} are just push and pop +operations. This pushing and popping is also used for overriding +automatic beaming settings. -@example -\paper @{ - foo = \translator @{ @dots{} @} -@} -\score @{ - \notes @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} -@end example +@refbugs -@end quotation +LilyPond will hang or crash if @var{value} contains cyclic references. +The backend is not very strict in type-checking grob properties. If you +@code{\revert} properties that are expected to be set by default, +LilyPond may crash. -@cindex paper types, engravers, and pre-defined translators - +@node Tuning per grob +@subsection Tuning per grob - Properties can be preset within the @code{\translator} block -corresponding to the appropriate context. In this case, the syntax -is +@cindex \outputproperty +A second way of tuning grobs is the more arcane @code{\outputproperty} +feature. The syntax is as follows: @example - @var{propname} @code{=} @var{value} +\outputproperty @var{predicate} @var{symbol} = @var{value} @end example +Here @code{predicate} is a Scheme function taking a grob argument, and +returning a boolean. This statement is processed by the +@code{Output_property_engraver}. It instructs the engraver to feed all +grobs that it sees to @var{predicate}. Whenever the predicate returns +true, the grob property @var{symbol} will be set to @var{value}. -The property settings are used during the interpretation phase. They -are read by the LilyPond modules where interpretation contexts are -built of. These modules are called @emph{translators}. Translators for -notation are called @emph{engravers}, and translators for sound are -called @emph{performers}. - +You will need to combine this statement with @code{\context} to select +the appropriate context to apply this to. +Here are some random examples. -@c . {Syntactic details} -@node Syntactic details -@section Syntactic details -@cindex Syntactic details -@menu -* Top level:: -* Identifiers:: -* Music expressions:: -* Manipulating music expressions:: -* Assignments:: -* Lexical details:: -* Lexical modes:: -* Ambiguities:: -@end menu +In the following example, all note heads occurring at current staff +level, are shifted up and right by setting their @code{extra-offset} +property. -@c . {Top level} -@node Top level -@subsection Top level -@cindex Top level +@lilypond[fragment,verbatim,singleline] +\relative c'' { c4 + \context Staff \outputproperty + #(make-type-checker 'note-head-interface) + #'extra-offset = #'(0.5 . 0.75) + } +@end lilypond -This section describes what you may enter at top level. +@cindex @code{extra-offset} +In this example, the predicate checks the @code{text} grob property, to +shift only the `m.d.' text, but not the fingering instruction "2". +@lilypond[verbatim,singleline] +#(define (make-text-checker text) + (lambda (grob) (equal? text (ly-get-grob-property grob 'text)))) -@c . {Score} -@subsubsection Score -@cindex Score +\score { + \notes\relative c''' { + \property Voice.Stem \set #'direction = #1 + \outputproperty #(make-text-checker "m.d.") + #'extra-offset = #'(-3.5 . -4.5) + a^2^"m.d." + } +} +@end lilypond -@cindex score definition +@refbugs -The output is generated combining a music expression with an output -definition. A score block has the following syntax: +If possible, avoid this feature: the semantics are not very clean, and +the syntax and semantics are up for rewrite. -@example - \score @{ @var{musicexpr} @var{outputdefs} @} -@end example -@var{outputdefs} are zero or more output definitions. If no output -definition is supplied, the default @code{\paper} block will be added. +@node Font selection +@subsection Font selection -@c . {Default output} -@subsubsection Default output +The most common thing to change about the appearance of fonts is +their size. The font size of a @internalsref{Voice}, +@internalsref{Staff} or @internalsref{Thread} context, can be easily +changed by setting the @code{fontSize} property for that context: +@lilypond[fragment,relative=1] + c4 c4 \property Voice.fontSize = #-1 + f4 g4 +@end lilypond + This command will not change the size of variable symbols, such as +beams or slurs. You can use this command to get smaller symbol for +cue notes, but that involves some more subtleties. An elaborate +example of those is in @file{input/test/cue-notes.ly}. -Default values for the @code{\paper} and @code{\midi} block are set by -entering such a block at top-level. +@cindex cue notes +@cindex font size +@cindex size -@c . {Header} -@subsubsection Header -@cindex Header -@cindex @code{\header} +The font used for printing a grob can be selected by setting +@code{font-name}, e.g. +@example + \property Staff.TimeSignature + \set #'font-name = #"cmr17" +@end example +You may use any font which is available to @TeX{}, such as foreign +fonts or fonts that do not belong to the Computer Modern font family. +Font selection for the standard fonts, @TeX{}'s Computer Modern fonts, +can also be adjusted with a more fine-grained mechanism. By setting +the grob properties described below, you can select a different font. +All three mechanisms work for every grob that supports +@code{font-interface}. -The syntax is +@table @code +@item font-family + A symbol indicating the general class of the typeface. Supported are +@code{roman} (Computer Modern), @code{braces} (for piano staff +braces), @code{music} (the standard music font), @code{ancient} (the +ancient notation font) @code{dynamic} (font for dynamic signs) and +@code{typewriter}. + +@item font-shape + A symbol indicating the shape of the font, there are typically several + font shapes available for each font family. Choices are @code{italic}, + @code{caps} and @code{upright} + +@item font-series +A symbol indicating the series of the font. There are typically several +font series for each font family and shape. Choices are @code{medium} +and @code{bold}. + +@item font-relative-size + A number indicating the size relative the standard size. For example, + with 20pt staff height, relative size -1 corresponds to 16pt staff + height, and relative size +1 corresponds to 23 pt staff height. + +@item font-design-size +A number indicating the design size of the font. + +This is a feature of the Computer Modern Font: each point size has a +slightly different design. Smaller design sizes are relatively wider, +which enhances readability. +@end table +For any of these properties, the value @code{*} (i.e. the @emph{symbol}, +@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used +to override default setting, which are always present. For example: @example - \header @{ @var{key1} = @var{val1}; -@cindex @code{ly2dvi} - @var{key2} = @var{val2}; @dots{} @} + \property Lyrics . LyricText \override #'font-series = #'bold + \property Lyrics . LyricText \override #'font-family = #'typewriter + \property Lyrics . LyricText \override #'font-shape = #'* @end example +@cindex @code{font-style} -A header describes the file's contents. It can also appear in a -@code{\score} block. Tools like @code{ly2dvi} can use this -information for generating titles. Key values that are used by -@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, -metre, arranger, piece and tagline. +There are also pre-cooked font selection qualifiers. These are +selected through the grob property @code{font-style}. For example, +the style @code{finger} selects family @code{number} and relative size +@code{-3}. Styles available include @code{volta}, @code{finger}, +@code{tuplet}, @code{timesig}, @code{mmrest}, @code{script}, +@code{large}, @code{Large} and @code{dynamic}. The style sheets and +tables for selecting fonts are located in @file{scm/font.scm}. Refer +to this file for more information. -It is customary to put the @code{\header} at the top of the file. +@cindex magnification -@subsubsection Default output +The size of the font may be scaled with the grob property +@code{font-magnification}. For example, @code{2.0} blows up all +letters by a factor 2 in both directions. -A @code{\midi} or @code{\paper} block at top-level sets the default +@refbugs -paper block for all scores that lack an explicit paper block. +Relative size is not linked to any real size. -@c . {Identifiers} -@node Identifiers -@subsection Identifiers -@cindex Identifiers +There is no style sheet provided for other fonts besides the @TeX{} +family, and the style sheet can not be modified easiyl. -All of the information in a LilyPond input file, is represented as a -Scheme value. In addition to normal Scheme data types (such as pair, -number, boolean, etc.), LilyPond has a number of specialized data types, - -@itemize @bullet -@item Input -@item c++-function -@item Music -@item Identifier -@item Translator_def -@item Duration -@item Pitch -@item Score -@item Music_output_def -@item Moment (rational number) -@end itemize +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} -LilyPond also includes some transient object types. Objects of these -types are built during a LilyPond run, and do not `exist' per se within -your input file. These objects are created as a result of your input -file, so you can include commands in the input to manipulate them, -during a lilypond run. -@itemize @bullet -@item Grob: short for Graphical object. See @ref{Grobs}. -@item Molecule: device-independent page output object, -including dimensions. Produced by some Grob functions -See @ref{Molecules} -@item Translator: object that produces audio objects or Grobs. This is -not yet user accessible. -@item Font_metric: object representing a font. (See @ref{Font metrics}) +@node Text markup +@subsection Text markup +@cindex text markup +@cindex markup text -@end itemize +LilyPond has an internal mechanism to typeset texts. You can +form text markup expressions by composing scheme expressions +in the following way. +@lilypond[verbatim, singleline] + \relative c' { + \fatText + a^#"upright" + b_#'(bold "bold") + c^#'(italic "italic") + d_#'((bold italic) "ff") + e^#'(dynamic "ff") + f_#'(lines "one" (bold "two")) + g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3")) + } +@end lilypond -@node Music expressions -@subsection Music expressions +Normally, the Scheme markup text is stored in the @code{text} property +of a grob. Formally, it is defined as follows: -@cindex music expressions +@example +text: string | (head? text+) +head: markup | (markup+) +markup-item: property | abbrev +property: (@var{key} . @var{value}) +abbrev: @code{columns lines roman music bold italic named super sub} + @code{overstrike text finger volta timesig mmrest mark script} + @code{large Large dynamic} +@end example -Music in LilyPond is entered as a music expression. Notes, rests, lyric -syllables are music expressions, and you can combine music expressions -to form new ones, for example by enclosing a list of expressions in -@code{\sequential @{ @}} or @code{< >}. In this example, a compound -expression is formed out of the quarter note @code{c} and a quarter note -@code{d}: +The markup is broken down and converted into a list of grob properties, +which are prepended to the property list. The @var{key}-@var{value} +pair is a grob property. A list of properties available is included in +the generated documentation for @rint{Text_interface}. -@example -\sequential @{ c4 d4 @} -@end example +The following abbreviations are defined: +@table @code +@item columns + horizontal mode: set all text on one line (default) +@item lines + vertical mode: set every text on a new line +@item roman + select roman font +@item music + selects the Feta font (the standard font for music notation glyphs), +and uses named lookup -@cindex Sequential music -@cindex @code{\sequential} -@cindex sequential music -@cindex @code{<} -@cindex @code{>} -@cindex Simultaneous music -@cindex @code{\simultaneous} +@item bold + select bold series +@item italic + select italic shape +@item named + lookup by character name +@item text + plain text lookup (by character value) +@item super + superscript +@item sub + subscript +@item overstrike + the next text or character overstrikes this one +@item finger + select fingering number fontstyle +@item volta + select volta number fontstyle +@item timesig + select time signature number fontstyle +@item mmrest + select multi measure rest number fontstyle +@item mark + select mark number fontstyle +@item script + select scriptsize roman fontstyle +@item large + select large roman fontstyle +@item Large + select Large roman fontstyle +@item dynamic + select dynamics fontstyle +@end table -The two basic compound music expressions are simultaneous and -sequential music. -@example - \sequential @code{@{} @var{musicexprlist} @code{@}} - \simultaneous @code{@{} @var{musicexprlist} @code{@}} -@end example -For both, there is a shorthand: -@example - @code{@{} @var{musicexprlist} @code{@}} -@end example -for sequential and -@example - @code{<} @var{musicexprlist} @code{>} -@end example -for simultaneous music. -Other compound music expressions include -@example - \repeat @var{expr} - \transpose @var{pitch} @var{expr} - \apply @var{func} @var{expr} - \context @var{type} = @var{id} @var{expr} - \times @var{fraction} @var{expr} -@end example +@cindex metronome mark -In principle, the way in which you nest sequential and simultaneous to -produce music is not relevant. In the following example, three chords -are expressed in two different ways: +One practical application of complicated markup is to fake a metronome +marking: -@lilypond[fragment,verbatim,center] - \notes \context Voice { - - < { a b c' } { c' d' e' } > - } -@end lilypond +@lilypond[verbatim] +#(define note '(columns + (music "noteheads-2" ((kern . -0.1) "flags-stem")))) +#(define eight-note `(columns ,note ((kern . -0.1) + (music ((raise . 3.5) "flags-u3"))))) +#(define dotted-eight-note + `(columns ,eight-note (music "dots-dot"))) -However, in some cases, LilyPond will also try to choose contexts, and -use the structure of the music expression to do so. This can have -undesired effects: for example, LilyPond will create a separate staff -for each note if you start a @code{\score} with a chord: -@lilypond[verbatim,center,singleline] - \score { - \notes +\score { + \notes\relative c'' { + a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64") } -@end lilypond - The solution is to explicitly instantiate the context you desire. -In this case this is typically a Voice context -@lilypond[verbatim,center,singleline] - \score { - \notes\context Voice + \paper { + linewidth = -1. + \translator{ + \ScoreContext + TextScript \override #'font-shape = #'upright + } } +} @end lilypond -If you use @code{\context Staff} you will get separate stems for each -note head, leading to collisions, so don't use that. +@refbugs +The syntax and semantics of markup texts are not clean, and both +syntax and semantics are slated for a rewrite. -@c . {Manipulating music expressions} -@node Manipulating music expressions -@subsection Manipulating music expressions +LilyPond does not do kerning, and there generally spaces texts +slightly too wide. -The @code{\apply} mechanism gives you access to the internal -representation of music. You can write Scheme-functions that operate -directly on it. The syntax is -@example - \apply #@var{func} @var{music} -@end example -This means that @var{func} is applied to @var{music}. The function -@var{func} should return a music expression. -This example replaces the text string of a script. It also shows a dump -of the music it processes, which is useful if you want to know more -about how music is stored. -@lilypond[verbatim] -#(define (testfunc x) - (if (equal? (ly-get-mus-property x 'text) "foo") - (ly-set-mus-property x 'text "bar")) - ;; recurse - (ly-set-mus-property x 'elements - (map testfunc (ly-get-mus-property x 'elements))) - (display x) - x -) -\score { \notes - \apply #testfunc { c4_"foo" } -} -@end lilypond - -For more information on what is possible, see the @ref{Tricks} and the -automatically generated documentation. - -As always: directly accessing internal representations is dangerous: the -implementation is subject to changes, so you should not use this if -possible. - - -@c . {Assignments} -@node Assignments -@subsection Assignments -@cindex Assignments - -Identifiers allow objects to be assigned to names during the parse -stage. To assign an identifier, you use @var{name}@code{=}@var{value} -and to refer to an identifier, you preceed its name with a backslash: -`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of -the input-types listed above. Identifier assignments can appear at top -level in the LilyPond file, but also in @code{\paper} blocks. - -Semicolons are forbidden after top level assignments, but mandatory in -other places. The rules about semicolons and assignments are very -confusing, but when LilyPond input evolves more towards Scheme, we hope -that this problem will grow smaller. - -An identifier can be created with any string for its name, but you will -only be able to refer to identifiers whose names begin with a letter, -being entirely alphabetical. It is impossible to refer to an identifier -whose name is the same as the name of a keyword. - -The right hand side of an identifier assignment is parsed completely -before the assignment is done, so it is allowed to redefine an -identifier in terms of its old value, e.g. -@example -foo = \foo * 2.0 -@end example +@node Global layout +@section Global layout -When an identifier is referenced, the information it points to is -copied. For this reason, an identifier reference must always be the -first item in a block. -@example -\paper @{ - foo = 1.0 - \paperIdent % wrong and invalid -@} +The global layout determined by three factors: the page layout, the +iline breaks and the spacing. These all influence each other: The +choice of spacing determines how densely each system of music is set, +whree line breaks breaks are chosen, and thus ultimately how many +pages a piece of music takes. In this section we will explain how the +lilypond spacing engine works, and how you can tune its results. -\paper @{ - \paperIdent % correct - foo = 1.0 @} -@end example +Globally spoken, this procedure happens in three steps: first, +flexible distances (``springs'') are chosen, based on durations. All +possible line breaking combination are tried, and the one with the +best results---a layout that has uniform density and requires as +little stretching or cramping as possible---is chosen. When the score +is processed by @TeX{}, page are filled with systems, and page breaks +are chosen whenever the page gets full. -@c . {Lexical details} -@node Lexical details -@subsection Lexical details -@cindex Lexical details @menu +* Vertical spacing:: +* Horizontal spacing:: +* Font Size:: +* Line breaking:: +* Page layout:: @end menu -@c . {Comments} -@subsubsection Comments -@cindex Comments - -@cindex @code{%} +@node Vertical spacing +@subsection Vertical spacing -A one line comment is introduced by a @code{%} character. -Block comments are started by @code{%@{} and ended by @code{%@}}. -They cannot be nested. +@cindex vertical spacing +@cindex distance between staffs +@cindex staff distance +@cindex between staves, distance -@c . {Direct Scheme} -@subsubsection Direct Scheme -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code +The height of each system is determined automatically by lilypond, to +keep systems from bumping into each other, some minimum distances are +set. By changing these, you can put staffs closer together, and thus +put more systems onto one page. - -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. In some places Scheme expressions also form valid syntax: -whereever it is allowed, +Normally staves are stacked vertically. To make +staves maintain a distance, their vertical size is padded. This is +done with the property @code{minimumVerticalExtent}. It takes a pair +of numbers, so if you want to make it smaller from its, then you could +set @example - #@var{scheme} + \property Staff.minimumVerticalExtent = #'(-4 . 4) @end example -evaluates the specified Scheme code. If this is used at toplevel, then -the result is discarded. Example: +This sets the vertical size of the current staff to 4 staff-space on +either side of the center staff line. The argument of +@code{minimumVerticalExtent} is interpreted as an interval, where the +center line is the 0, so the first number is generally negative. you +could also make the staff larger at the bottom by setting it to +@code{(-6 . 4)}. The default value is @code{(-6 . 6)}. + +Vertical aligment of staves is handled by the +@internalsref{VerticalAlignment} grob, which lives at +@internalsref{Score} level. + +The piano staffs are handled a little differently: to make cross-staff +beaming work correctly, it necessary that the distance between staves +is fixed. This is also done with a @internalsref{VerticalAlignment} +grob, created in @internalsref{PianoStaff}, but a forced distance is +set. This is done with the grob property #'forced-distance. If you +want to override this, use a @code{\translator} block as follows: @example - \property Staff.TestObject \override #'foobar = #(+ 1 2) + \translator @{ + \PianoStaffContext + VerticalAlignment \override #'forced-distance = #9 + @} @end example +This would bring the staffs together at a distance of 9 staff spaces, +and again this is measured from the center line of each staff. -@code{\override} expects two Scheme expressions, so there are two Scheme -expressions. The first one is a symbol (@code{foobar}), the second one -an integer (namely, 3). - -Scheme is a full-blown programming language, and a full discussion is -outside the scope of this document. Interested readers are referred to -the website @uref{http://www.schemers.org/} for more information on -Scheme. -@c . {Keywords} -@subsubsection Keywords -@cindex Keywords +@node Horizontal spacing +@subsection Horizontal Spacing +The spacing engine translates differences in durations into +stretchable distances (``springs'') of differing lengths. Longer +durations get more space, shorter durations get less. The basis for +assigning spaces to durations, is that the shortest durations get a +fixed amount of space, and the longer durations get more: doubling a +duration adds a fixed amount of space to the note. -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. - -@example -apply arpeggio autochange spanrequest commandspanrequest -simultaneous sequential accepts alternative bar breathe -char chordmodifiers chords clef cm consists consistsend -context denies duration dynamicscript elementdescriptions -font grace header in lyrics key mark pitch -time times midi mm name pitchnames notes outputproperty -override set revert partial paper penalty property pt -relative remove repeat addlyrics partcombine score -script stylesheet skip textscript tempo translator -transpose type -@end example +For example, the following piece contains lots of half, quarter and +8th notes, the eighth note is followed by 1 note head width. The The +quarter note is followed by 2 NHW, the half by 3 NHW, etc. +@lilypond[fragment, verbatim, relative=1] + c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4 +@end lilypond -@c . {Integers} -@subsubsection Integers +These two amounts of space are @code{shortest-duration-space} +@code{spacing-increment}, grob properties of +@internalsref{SpacingSpanner}. Normally @code{spacing-increment} is +set to 1.2, which is the width of a note head, and +@code{shortest-duration-space} is set to 2.0, meaning that the +shortest note gets 2 noteheads of space. For normal notes, this space +is always counted from the left edge of the symbol, so the short notes +in a score is generally followed by one note head width of space. + +If one would follow the above procedure exactly, then adding a single +32th note to a score that uses 8th and 16th notes, would widen up the +entire score a lot. The shortest note is no longer a 16th, but a 64th, +thus adding 2 noteheads of space to every note. To prevent this, the +shortest duration for spacing is not the shortest note in the score, +but the most commonly found shortest note. Notes that are even +shorter this are followed by a space that is proportonial to their +duration relative to the common shortest note. So if we were to add +only a few 16th notes to the example above, they would be followed by +half a NHW: + +@lilypond[fragment, verbatim, relative=1] + c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4 +@end lilypond -@cindex integers -@cindex @code{+} -@cindex @code{-} -@cindex @code{*} -@cindex @code{/} +The most common shortest duration is determined as follows: in every +measure, the shortest duration is determined. The most common short +duration, is taken as the basis for the spacing, with the stipulation +that this shortest duration should always be equal to or shorter than +1/8th note. The shortest duration is printed when you run lilypond +with @code{--verbose}. These durations may also be customized. If you +set the @code{common-shortest-duration} in +@internalsref{SpacingSpanner}, then this sets the base duration for +spacing. The maximum duration for this base (normally 1/8th), is set +through @code{base-shortest-duration}. + +@cindex @code{common-shortest-duration} +@cindex @code{base-shortest-duration} +@cindex @code{stem-spacing-correction} +@cindex @code{spacing} + +In the introduction it was explained that stem directions influence +spacing. This is controlled with @code{stem-spacing-correction} in +@internalsref{NoteSpacing}. The @code{StaffSpacing} grob contains the +same property for controlling the stem/barline spacing. In the +following example shows these corrections, once with default settings, +and once with exaggerated corrections. + +@lilypond + \score { \notes { + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + \property Staff.NoteSpacing \override #'stem-spacing-correction + = #1.5 + \property Staff.StaffSpacing \override #'stem-spacing-correction + = #1.5 + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + } + \paper { linewidth = -1. } } +@end lilypond -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. -@c . {Reals} -@subsubsection Reals -@cindex real numbers +@refbugs +Spacing is determined on a score wide basis. If you have a score that +changes its character (measured in durations) half way during the +score, the part containing the longer durations will be spaced too +widely. +Generating optically pleasing spacing is black magic. LilyPond tries +to deal with a number of frequent cases. Here is an example that is +not handled correctly, due to the combination of chord collisions and +kneed stems. +@lilypond +\score { + \context PianoStaff \notes \transpose c''' < + \context Staff = up { s1 } + \context Staff = down { [c8 c \translator Staff=up c +\translator Staff=down c c c] } + > + \paper { linewidth = -1 } +} +@end lilypond -Formed from an optional minus sign and a sequence of digits followed -by a @emph{required} decimal point and an optional exponent such as -@code{-1.2e3}. Reals can be built up using the usual operations: -`@code{+}', `@code{-}', `@code{*}', and -`@code{/}', with parentheses for grouping. -@cindex @code{\mm}, -@cindex @code{\in} -@cindex @code{\cm} -@cindex @code{\pt} -@cindex dimensions +@c . {Font size} +@node Font Size +@subsection Font size +@cindex font size, setting +@cindex staff size, setting +@cindex @code{paper} file -A real constant can be followed by one of the dimension keywords: -@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, -points, inches and centimeters, respectively. This converts the number -to a real that is the internal representation of dimensions. +The Feta font provides musical symbols at seven different sizes. +These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23 +point, and 26 point. The point size of a font is the height of the +five lines in a staff when displayed in the font. +Definitions for these sizes are the files @file{paperSZ.ly}, where +@code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any +of these files, the identifiers @code{paperEleven}, +@code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen}, +@code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix} +are defined respectively. The default @code{\paper} block is also +set. These files should be imported at toplevel, i.e. +@example + \include "paper26.ly" + \score @{ ... @} +@end example -@c . {Strings} -@subsubsection Strings -@cindex string -@cindex concatenate +The font definitions are generated using a Scheme function. For more +details, see the file @file{scm/font.scm}. -Begins and ends with the @code{"} character. To include a @code{"} -character in a string write @code{\"}. Various other backslash -sequences have special interpretations as in the C language. A string -that contains no spaces can be written without the quotes. See -@ref{Lexical modes} for details on unquoted strings; their -interpretation varies depending on the situation. Strings can be -concatenated with the @code{+} operator. -The tokenizer accepts the following commands. They have no grammatical -function, hence they can appear anywhere in the input. +@c . {Line break} +@node Line breaking +@subsection Line breaking +@cindex line breaks +@cindex breaking lines -@c . {Main input} -@subsubsection Main input -@cindex Main input +Line breaks are normally computed automatically. They are chosen such +that it looks neither cramped nor loose, and that consecutive lines have +similar density. -@cindex @code{\maininput} +Occasionally you might want to override the automatic breaks; you can +do this by specifying @code{\break}. This will force a line break at +this point. Line breaks can only occur at places where there are bar +lines. If you want to have a line break where there is no bar line, +you can force an invisible bar line by entering @code{\bar +""}. Similarly, @code{\noBreak} forbids a line break at a certain +point. -The @code{\maininput} command is used in init files to signal that the -user file must be read. This command cannot be used in a user file. -@c . {File inclusion} -@subsubsection Main input -@cindex Main input +@cindex regular line breaks +@cindex four bar music. -@subsubsection File inclusion -@cindex @code{\include} +If you want linebreaks at regular intervals, you can use the following: @example - \include @var{filename} -@end example +< \repeat 7 unfold @{ s1 * 4 \break @} + @emph{real music} +> +@end example +This makes the following 28 measures (assuming 4/4 time) be broken every +4 measures. -Include @var{filename}. The argument @var{filename} may be a quoted string (an -unquoted string will not work here!) or a string identifier. The full -filename including the @file{.ly} extension must be given, +@node Page layout +@subsection Page layout -@subsubsection Version information -@cindex @code{\version} -@example - \version @var{string} ; -@end example +@cindex page breaks +@cindex breaking pages -Specify the version of LilyPond that a file was written for. The -argument is a version string in quotes, for example @code{"1.2.0"}. -This is used to detect invalid input, and to aid -@code{convert-ly} a tool that automatically upgrades input files. See -See @ref{convert-ly} for more information on @code{convert-ly}. +@cindex @code{indent} +@cindex @code{linewidth} -@cindex convert-ly +The most basic settings influencing the spacing are @code{linewidth} +and @code{indent}, both set in the @code{\paper} block. They control +the indentation of the first line of music, and the lengths of the +lines. If @code{linewidth} set to a negative value, a single +unjustified line is produced. A similar effect for scores that are +longer than one line, can be produced by setting @code{raggedright} to +true in the @code{\paper} block. + +@cindex page layout + +The page layout process happens outside lilypond. Ly2dvi sets page +layout instructions. Ly2dvi responds to the following variables in the +@code{\paper} block. The variable @code{textheight} sets the total +height of the music on each page. The spacing between systems is +controlled with @code{interscoreline}, its default is 16pt. +The distance between the score lines will stretch in order to fill the +full page @code{interscorelinefill} is set to a positive number. In +that case @code{interscoreline} specifies the minimum spacing. +@cindex @code{textheight} +@cindex @code{interscoreline} +@cindex @code{interscorelinefill} -@c . {Pitch names} -@subsubsection Defining pitch names -@cindex Lexical modes -@cindex definining pitch names -@cindex pitch names, definining -@cindex note names -@cindex chord modifier names +If the variable @code{lastpagefill} is defined (that is, it gets any +value assigned in the @code{\paper} block), systems are evenly +distributed vertically on the last page. This might produce ugly +results in case there are not enough systems on the last page. Note +that @command{lilypond-book} ignores @code{lastpagefill}. See +@ref{Insert music snippets into your texts using lilypond-book} for +more information. -A @code{\paper} block at top level sets the default paper block. A -@code{\midi} block at top level works similarly. +@cindex @code{lastpagefill} -@c . {Assignments} -@subsubsection Assignments -@cindex assignments -@cindex @code{#} +Page breaks are normally computed by @TeX{}, so they are not under +direct control of LilyPond. However, you can insert a commands into +the @file{.tex} output to instruct @TeX{} where to break pages. You +can insert a @code{\newpage} from within lilypond. This is done by +setting the @code{between-systems-strings} on the +@internalsref{NonMusicalPaperColumn} where the system is broken. -Identifier assignments may appear at top level. @ref{Assignments} +@cindex paper size +@cindex page size +@cindex @code{papersize} +To change the paper size, you must first set the +@code{papersize} paper variable variable. Set it to +the strings @code{a4}, @code{letter}, or @code{legal}. After this +specification, you must set the font as described above. If you want +the default font, then use the 20 point font. +@example + \paper@{ papersize = "a4" @} + \include "paper16.ly" +@end example -@c . {Direct scheme} -@subsubsection Direct scheme -@cindex Direct scheme +The file @code{paper16.ly} will now include a file named @file{a4.ly}, which +will set the paper variables @code{hsize} and @code{vsize} (used by +Lilypond and @code{ly2dvi}) -Scheme statements maybe issued to produce interesting side-effects. -@c . {Lexical modes} -@node Lexical modes -@subsection Lexical modes -@cindex Lexical modes -@cindex input mode -@cindex mode, input -@cindex @code{\notes} -@cindex @code{\chords} -@cindex @code{\lyrics} - -To simplify entering notes, lyrics, and chords, LilyPond has three -special input modes on top of the default mode: note, lyrics and chords -mode. These input modes change the way that normal, unquoted words are -interpreted: for example, the word @code{cis} may be interpreted as a -C-sharp, as a lyric syllable `cis' or as a C-sharp major triad -respectively. -A mode switch is entered as a compound music expressions -@example -@code{\notes} @var{musicexpr} -@code{\chords} @var{musicexpr} -@code{\lyrics} @var{musicexpr}. -@end example +@c . {Sound} +@node Sound +@section Sound +@cindex Sound -In each of these cases, these expressions do not add anything to the -meaning of their arguments. They are just a way to indicate that the -arguments should be parsed in indicated mode. The modes are treated in -more detail in the sections @ref{Note entry}, @ref{Lyrics} and -@ref{Chords}. +LilyPond can produce MIDI output. The performance lacks lots of +interesting effects, such as swing, articulation, slurring, etc., but it +is good enough for proof-hearing the music you have entered. Ties, +dynamics and tempo changes are interpreted. -You may nest different input modes. +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 the volume vary +linearly between their two extremities. The fractions be adjusted by +overriding the @code{absolute-volume-alist} defined in +@file{scm/midi.scm}. -@c . {Ambiguities} -@node Ambiguities -@subsection Ambiguities -@cindex ambiguities -@cindex grammar +For each type of musical instrument (that MIDI supports), a volume range +can be defined. This gives you basic equalizer control, which can +enhance the quality of the MIDI output remarkably. You can add +instruments and ranges or change the default settings by overriding the +@code{instrument-equalizer-alist} defined in @file{scm/midi.scm}. +Both loudness controls are combined to produce the final MIDI volume. -The grammar contains a number of ambiguities. We hope to resolve them at -some time. -@itemize @bullet - @item The assignment - @example -foo = bar -@end example +@menu +* MIDI block:: +* MIDI instrument names:: +@end menu + +@c . {MIDI block} +@node MIDI block +@subsection MIDI block +@cindex MIDI block - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. - @item The assignment +The MIDI block is analogous to the paper block, but it is somewhat +simpler. The @code{\midi} block can contain: +@cindex MIDI block - @example -foo = -6 -@end example +@itemize @bullet + @item a @code{\tempo} definition + @item context definitions +@end itemize - can be interpreted as making an integer identifier - containing -6, or a Request identifier containing the - fingering `6' (with neutral direction). +Assignments in the @code{\midi} block are not allowed. - @item If you do a nested repeat like - @quotation -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example +@cindex context definition - @end quotation +Context definitions follow precisely the same syntax as within the +\paper block. Translation modules for sound are called performers. +The contexts for MIDI output are defined in @file{ly/performer-init.ly}. - then it is ambiguous to which @code{\repeat} the - @code{\alternative} belongs. This is the classic if-then-else - dilemma. It may be solved by using braces. - @item (an as yet unidentified ambiguity :-) -@end itemize +@node MIDI instrument names +@subsection MIDI instrument names +@cindex instrument names +@cindex @code{Staff.midiInstrument} +@cindex @code{Staff.instrument} +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property or, if that property is not set, the @code{Staff.instrument} +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. +@refbugs +If the selected string does not exactly match, then LilyPond uses the +default (Grand Piano). It is not possible to select an instrument by +number. -@c .{Local emacs vars} -@c Local variables: -@c mode: texinfo -@c minor-mode: font-lock -@c minor-mode: outline -@c outline-layout: (-1 : 0) -@c outline-use-mode-specific-leader: "@c \." -@c outline-primary-bullet: "{" -@c outline-stylish-prefixes: nil -@c outline-override-protect: t -@c End: