X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finput.itely;h=392fbb3ea00f7094959440fdf70b8cefaefbffdb;hb=72c8c9aef2cff0a61953a52adaf83d6dd74f8b18;hp=3cd37ae70cb201042dd962411b1a4547326a0f8b;hpb=e0fd1e06146950d87a9657d2e6ee33599b3b2d44;p=lilypond.git diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely index 3cd37ae70c..392fbb3ea0 100644 --- a/Documentation/user/input.itely +++ b/Documentation/user/input.itely @@ -7,23 +7,20 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.38" +@c \version "2.11.61" -@node Input syntax -@chapter Input syntax +@node General input and output +@chapter General input and output -This section deals with general LilyPond input syntax issues, +This section deals with general LilyPond input and output issues, rather than specific notation. -FIXME: don't complain about anything in this chapter. It's still -under heavy development. - @menu -* Input structure:: -* Useful concepts and properties:: -* Titles and headers:: -* Working with input files:: -* Controlling output:: +* Input structure:: +* Titles and headers:: +* Working with input files:: +* Controlling output:: +* MIDI output:: @end menu @@ -34,9 +31,9 @@ The main format of input for LilyPond are text files. By convention, these files end with @code{.ly}. @menu -* Structure of a score:: -* Multiple scores in a book:: -* File structure:: +* Structure of a score:: +* Multiple scores in a book:: +* File structure:: @end menu @@ -108,7 +105,7 @@ Learning Manual: @rlearning{Working on input files}, @rlearning{Music expressions explained}, -@rlearning{Score is a single (compound) music expression}. +@rlearning{Score is a (single) compound musical expression}. @node Multiple scores in a book @@ -224,7 +221,7 @@ A @code{\score} block. This score will be collected with other toplevel scores, and combined as a single @code{\book}. This behavior can be changed by setting the variable @code{toplevel-score-handler} at toplevel. The default handler is -defined in the init file @file{scm/@/lily@/.scm}. +defined in the init file @file{../scm/@/lily@/.scm}. @item A @code{\book} block logically combines multiple movements @@ -239,7 +236,7 @@ a @code{\book} block if you want more than a single @code{\score} or @code{\markup} in the same example. This behavior can be changed by setting the variable @code{toplevel-book-handler} at toplevel. The default handler is defined in the init file -@file{scm/@/lily@/.scm}. +@file{../scm/@/lily@/.scm}. @item A compound music expression, such as @@ -268,7 +265,7 @@ music expression will be translated into This behavior can be changed by setting the variable @code{toplevel-music-handler} at toplevel. The default handler is -defined in the init file @file{scm/@/lily@/.scm}. +defined in the init file @file{../scm/@/lily@/.scm}. @item A markup text, a verse for example @@ -290,7 +287,7 @@ foo = @{ c4 d e d @} @end example This can be used later on in the file by entering @code{\foo}. The -name of an variable should have alphabetic characters only; no +name of a variable should have alphabetic characters only; no numbers, underscores or dashes. @end itemize @@ -333,220 +330,6 @@ A multi-line comment delimited by @code{%@{ .. %@}}. Learning Manual: @rlearning{How LilyPond input files work}. -@node Useful concepts and properties -@section Useful concepts and properties - - -@menu -* Input modes:: -* Controlling direction and placement:: -* Distances and measurements:: -* Spanners:: -@end menu - -@node Input modes -@subsection Input modes - -The way in which the notation contained within an input file is -interpreted is determined by the current input mode. - -@strong{Chord mode} - -This is activated with the @code{\chordmode} command, and causes -input to be interpreted with the syntax of chord notation, see -@ref{Chord notation}. Chords are rendered as notes on a staff. - -Chord mode is also activated with the @code{\chords} command. -This also creates a new @code{ChordNames} context and -causes the following input to be interpreted with the syntax of -chord notation and rendered as chord names in the @code{ChordNames} -context, see @ref{Printing chord names}. - -@strong{Drum mode} - -This is activated with the @code{\drummode} command, and causes -input to be interpreted with the syntax of drum notation, see -@ref{Basic percussion notation}. - -Drum mode is also activated with the @code{\drums} command. -This also creates a new @code{DrumStaff} context and causes the -following input to be interpreted with the syntax of drum notation -and rendered as drum symbols on a drum staff, see @ref{Basic -percussion notation}. - -@strong{Figure mode} - -This is activated with the @code{\figuremode} command, and causes -input to be interpreted with the syntax of figured bass, see -@ref{Entering figured bass}. - -Figure mode is also activated with the @code{\figures} command. -This also creates a new @code{FiguredBass} context and causes the -following input to be interpreted with the figured bass syntax -and rendered as figured bass symbols in the @code{FiguredBass} -context, see @ref{Introduction to figured bass}. - -@strong{Fret and tab modes} - -There are no special input modes for entering fret and tab symbols. - -To create tab diagrams, enter notes or chords in note mode and -render them in a @code{TabStaff} context, see -@ref{Default tablatures}. - -To create fret diagrams above a staff, enter them as markup -above the notes using the @code{\fret-diagram} command, see -@ref{Fret diagrams}. - -@strong{Lyrics mode} - -This is activated with the @code{\lyricmode} command, and causes -input to be interpreted as lyric syllables with optional durations -and associated lyric modifiers, see @ref{Vocal music}. - -Lyric mode is also activated with the @code{\addlyrics} command. -This also creates a new @code{Lyrics} context and an implicit -@code{\lyricsto} command which associates the following lyrics -with the preceding music. - -@strong{Markup mode} - -This is activated with the @code{\markup} command, and causes -input to be interpreted with the syntax of markup, see -@ref{Text markup commands}. - -@c silly work-around for texinfo broken-ness -@c (@strong{Note...} causes a spurious cross-reference in Info) -@b{Note mode} - -This is the default mode or it may be activated with the -@code{\notemode} command. Input is interpreted as pitches, -durations, markup, etc and typeset as musical notation on a staff. - -It is not normally necessary to specify note mode explicitly, but -it may be useful to do so in certain situations, for example if you -are in lyric mode, chord mode or any other mode and want to insert -something that only can be done with note mode syntax. - -For example, to indicate dynamic markings for the verses of a -choral pieces it is necessary to enter note mode to interpret -the markings: - -@lilypond[verbatim,relative=2,quote] -{ c4 c4 c4 c4 } -\addlyrics { - \notemode{\set stanza = \markup{ \dynamic f 1. } } - To be sung loudly -} -\addlyrics { - \notemode{\set stanza = \markup{ \dynamic p 2. } } - To be sung quietly -} -@end lilypond - - - -@node Controlling direction and placement -@subsection Controlling direction and placement - -TODO: Maybe rename section to "directions". - -In typesetting music the direction and placement of many items is -a matter of choice. For example, the stems of notes can -be directed up or down; lyrics, dynamics, and other expressive -marks may be placed above or below the staff; text may be aligned -left, right or center; etc. Most of these choices may be left to -be determined automatically by LilyPond, but in some cases it may -be desirable to force a particular direction or placement. - -@strong{Default actions} - -By default some directions are always up or always down (e.g. -dynamics or fermata), while other things can alternate between -up or down based on the stem direction (like slurs or accents). - -@c TODO Add table showing these - -@strong{Context layout} - -Contexts are positioned in a system from top to bottom in the -order in which they are encountered. Note, however, that a -context will be created implicitly if a command is encountered -when there is no suitable context available to contain it. - -@c TODO Add example ? - -The default order in which contexts are laid out can be changed, -see @ref{Aligning contexts} - -@strong{Articulation direction indicators} - -When adding articulations to notes the direction indicator, -@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or -@code{-} (meaning @qq{use default direction}), can usually be -omitted, in which case @code{-} is assumed. But a direction -indicator is @strong{always} required before - -@itemize -@item @code{\tweak} commands -@item @code{\markup} commands -@item @code{\tag} commands -@item string markups, e.g. -"string" -@item fingering instructions, e.g. @code{-1} -@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--} -@end itemize - -@strong{The direction property} - -The position or direction of many layout objects is controlled -by the @code{direction} property. - -The value of the @code{direction} property may be -set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1}, -meaning @qq{down} or @qq{below}. The symbols @code{UP} and -@code{DOWN} may be used instead of @code{1} and @code{-1} -respectively. The default direction may be specified by setting -@code{direction} to @code{0} or @code{CENTER}. Alternatively, -in many cases predefined commands -exist to specify the direction. These are all of the form - -@noindent -@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral} - -@noindent -where @code{xxxNeutral} means @qq{use the default direction}. -See @rlearning{Within-staff objects}. - -In a few cases, arpeggio being the only common example, the value -of the @code{direction} property specifies whether the object -is to be placed to the right or left of the parent object. In -this case @code{-1} or @code{LEFT} means @qq{to the left} and -@code{1} or @code{RIGHT} means @qq{to the right}. @code{0} -or @code{CENTER} means @qq{use the default} direction, as before. - -@ignore -These all have side-axis set to #X -AmbitusAccidental - direction has no effect -Arpeggio - works -StanzaNumber - not tried -TrillPitchAccidental - not tried -TrillPitchGroup - not tried -@end ignore - - - -@node Distances and measurements -@subsection Distances and measurements - -DISCUSS after working on other sections. - -TODO: staff spaces. Maybe move into tweaks? - - -@node Spanners -@subsection Spanners - - @node Titles and headers @section Titles and headers @@ -554,10 +337,10 @@ Almost all printed music includes a title and the composer's name; some pieces include a lot more information. @menu -* Creating titles:: -* Custom titles:: -* Reference to page numbers:: -* Table of contents:: +* Creating titles:: +* Custom titles:: +* Reference to page numbers:: +* Table of contents:: @end menu @@ -590,32 +373,32 @@ Subsubtitle, centered below the subtitle. @funindex poet @item poet -Name of the poet, flush-left below the subtitle. +Name of the poet, flush-left below the subsubtitle. + +@funindex instrument +@item instrument +Name of the instrument, centered below the subsubtitle. Also +centered at the top of pages (other than the first page). @funindex composer @item composer -Name of the composer, flush-right below the subtitle. +Name of the composer, flush-right below the subsubtitle. @funindex meter @item meter Meter string, flush-left below the poet. -@funindex opus -@item opus -Name of the opus, flush-right below the composer. - @funindex arranger @item arranger -Name of the arranger, flush-right below the opus. - -@funindex instrument -@item instrument -Name of the instrument, centered below the arranger. Also -centered at the top of pages (other than the first page). +Name of the arranger, flush-right below the composer. @funindex piece @item piece -Name of the piece, flush-left below the instrument. +Name of the piece, flush-left below the meter. + +@funindex opus +@item opus +Name of the opus, flush-right below the arranger. @cindex page breaks, forcing @funindex breakbefore @@ -645,13 +428,13 @@ may use any @ref{Formatting text}, commands in the header. \book { \header { dedication = "dedicated to me" - title = \markup \center-align { "Title first line" "Title second line, + title = \markup \center-column { "Title first line" "Title second line, longer" } subtitle = "the subtitle," subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version)) poet = "Poet" - composer = \markup \center-align { "composer" \small "(1847-1973)" } + composer = \markup \center-column { "composer" \small "(1847-1973)" } texttranslator = "Text Translator" meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" } @@ -715,14 +498,14 @@ Note that the music expression must come before the @code{\header}. } @end lilypond -@funindex printallheaders +@funindex print-all-headers @noindent You may change this behavior (and print all the headers when defining @code{\header} inside @code{\score}) by using @example \paper@{ - printallheaders=##t + print-all-headers = ##t @} @end example @@ -751,7 +534,7 @@ Headers may be completely removed by setting them to false. A more advanced option is to change the definitions of the following variables in the @code{\paper} block. The init file -@file{ly/titling-init.ly} lists the default layout. +@file{../ly/titling-init.ly} lists the default layout. @table @code @funindex bookTitleMarkup @@ -840,7 +623,7 @@ The @code{\page-ref} markup command takes three arguments: @item the label, a scheme symbol, eg. @code{#'firstScore}; @item a markup that will be used as a gauge to estimate the dimensions of the markup; -@item a markup that will be used in place of the page number if the label +@item a markup that will be used in place of the page number if the label is not known; @end enumerate @@ -871,11 +654,11 @@ top-level, or inside a music expression. \pageBreak \tocItem \markup "First score" -\score { +\score { { c' % ... \tocItem \markup "Some particular point in the first score" - d' % ... + d' % ... } } @@ -930,7 +713,7 @@ in the table of contents of an opera: } } -tocAct = +tocAct = #(define-music-function (parser location text) (markup?) (add-toc-item! 'tocActMarkup text)) @end verbatim @@ -945,7 +728,7 @@ tocAct = } } -tocAct = +tocAct = #(define-music-function (parser location text) (markup?) (add-toc-item! 'tocActMarkup text)) @@ -963,7 +746,7 @@ tocAct = @seealso -Init files: @file{ly/@/toc@/-init@/.ly}. +Init files: @file{../ly/@/toc@/-init@/.ly}. @predefined @@ -990,166 +773,437 @@ Init files: @file{ly/@/toc@/-init@/.ly}. @funindex \include @cindex including files -A large project may be split up into separate files. To refer to another -file, use +A large project may be split up into separate files. To refer to +another file, use @example \include "otherfile.ly" @end example -The line @code{\include "file.ly"} is equivalent to pasting the contents -of file.ly into the current file at the place where you have the -\include. For example, for a large project you might write separate files -for each instrument part and create a @q{full score} file which brings -together the individual instrument files. - -The initialization of LilyPond is done in a number of files that are -included by default when you start the program, normally transparent to the -user. Run @code{lilypond --verbose} to see a list of paths and files that Lily -finds. - -Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where -VERSION is in the form @q{2.6.1}) are on the path and available to -@code{\include}. Files in the -current working directory are available to \include, but a file of the same -name in LilyPond's installation takes precedence. Files are -available to \include from directories in the search path specified as an -option when invoking @code{lilypond --include=DIR} which adds DIR to the -search path. - -The @code{\include} statement can use full path information, but with the UNIX -convention @code{/} rather than the DOS/Windows @code{\}. For example, -if @file{stuff.ly} is located one directory higher than the current working -directory, use +The line @code{\include "otherfile.ly"} is equivalent to pasting the +contents of @file{otherfile.ly} into the current file at the place +where the @code{\include} appears. For example, in a large +project you might write separate files for each instrument part +and create a @qq{full score} file which brings together the +individual instrument files. Normally the included file will +define a number of variables which then become available +for use in the full score file. Tagged sections can be +marked in included files to assist in making them usable in +different places in a score, see @ref{Different editions from +one source}. + +Files in the current working directory may be referenced by +specifying just the file name after the @code{\include} command. +Files in other locations may be included by giving either a full +path reference or a relative path reference (but use the UNIX +forward slash, /, rather than the DOS/Windows back slash, \, as the +directory separator.) For example, if @file{stuff.ly} is located +one directory higher than the current working directory, use @example \include "../stuff.ly" @end example +@noindent +or if the included orchestral parts files are all located in a +subdirectory called @file{parts} within the current directory, use + +@example +\include "parts/VI.ly" +\include "parts/VII.ly" +... etc +@end example + +Files which are to be included can also contain @code{\include} +statements of their own. These second-level +@code{\include} statements are not interpreted until they have +been brought into the main file, so the file names they specify +must all be relative to the directory containing the main file, +not the directory containing the included file. + +Files can also be included from a directory in a search path +specified as an option when invoking LilyPond from the command +line. The included files are then specified using just their +file name. For example, to compile @file{main.ly} which includes +files located in a subdirectory called @file{parts} by this method, +cd to the directory containing @file{main.ly} and enter + +@example +lilypond --include=parts main.ly +@end example + +and in main.ly write + +@example +\include "VI.ly" +\include "VII.ly" +... etc +@end example + +Files which are to be included in many scores may be placed in +the LilyPond directory @file{../ly}. (The location of this +directory is installation-dependent - see @rlearning{Other sources +of information}). These files can then be included simply by +naming them on an @code{\include} statement. This is how the +language-dependent files like @file{english.ly} are included. + +LilyPond includes a number of files by default when you start +the program. These includes are not apparent to the user, but the +files may be identified by running @code{lilypond --verbose} from +the command line. This will display a list of paths and files that +LilyPond uses, along with much other information. Alternatively, +the more important of these files are discussed in @rlearning{Other +sources of information}. These files may be edited, but changes to +them will be lost on installing a new version of LilyPond. + +Some simple examples of using @code{\include} are shown in +@rlearning{Scores and parts}. + +@seealso +Learning Manual: +@rlearning{Other sources of information}, +@rlearning{Scores and parts}. + +@knownissues + +If an included file is given a name which is the same as one in +LilyPond's installation files, LilyPond's file from the +installation files takes precedence. + + @node Different editions from one source @subsection Different editions from one source -@funindex \tag -@cindex tag +Several mechanisms are available to facilitate the generation +of different versions of a score from the same music source. +Variables are perhaps most useful for combining lengthy sections +of music and/or annotation in various ways, while tags are more +useful for selecting one from several alternative shorter sections +of music. Whichever method is used, separating the notation from +the structure of the score will make it easier to change the +structure while leaving the notation untouched. -The @code{\tag} command marks music expressions with a name. These -tagged expressions can be filtered out later. With this mechanism it -is possible to make different versions of the same music source. +@menu +* Using variables:: +* Using tags:: +@end menu -In the following example, we see two versions of a piece of music, one -for the full score, and one with cue notes for the instrumental part +@node Using variables +@unnumberedsubsubsec Using variables -@example -c1 +@cindex variables, use of + +If sections of the music are defined in variables they can be +reused in different parts of the score, see @rlearning{Organizing +pieces with variables}. For example, an @notation{a cappella} +vocal score frequently includes a piano reduction of the parts +for rehearsal purposes which is identical to the vocal music, so +the music need be entered only once. Music from two variables +may be combined on one staff, see @ref{Automatic part combining}. +Here is an example: + +@lilypond[verbatim,quote] +sopranoMusic = \relative c'' { a4 b c b8( a)} +altoMusic = \relative g' { e4 e e f } +tenorMusic = \relative c' { c4 b e d8( c) } +bassMusic = \relative c' { a4 gis a d, } +allLyrics = \lyricmode {King of glo -- ry } << - \tag #'part << - R1 \\ - @{ - \set fontSize = #-1 - c4_"cue" f2 g4 @} + \new Staff = "Soprano" \sopranoMusic + \new Lyrics \allLyrics + \new Staff = "Alto" \altoMusic + \new Lyrics \allLyrics + \new Staff = "Tenor" { + \clef "treble_8" + \tenorMusic + } + \new Lyrics \allLyrics + \new Staff = "Bass" { + \clef "bass" + \bassMusic + } + \new Lyrics \allLyrics + \new PianoStaff << + \new Staff = "RH" { + \set Staff.printPartCombineTexts = ##f + \partcombine + \sopranoMusic + \altoMusic + } + \new Staff = "LH" { + \set Staff.printPartCombineTexts = ##f + \clef "bass" + \partcombine + \tenorMusic + \bassMusic + } >> - \tag #'score R1 >> -c1 -@end example +@end lilypond + +Separate scores showing just the vocal parts or just the piano +part can be produced by changing just the structural statements, +leaving the musical notation unchanged. + +For lengthy scores, the variable definitions may be placed in +separate files which are then included, see @ref{Including +LilyPond files}. + +@node Using tags +@unnumberedsubsubsec Using tags + +@funindex \tag +@funindex \keepWithTag +@funindex \removeWithTag +@cindex tag +@cindex keep tagged music +@cindex remove tagged music + +The @code{\tag #'@var{partA}} command marks a music expression +with the name @var{partA}. +Expressions tagged in this way can be selected or filtered out by +name later, using either @code{\keepWithTag #'@var{name}} or +@code{\removeWithTag #'@var{name}}. The result of applying these filters +to tagged music is as follows: +@multitable @columnfractions .5 .5 +@headitem Filter + @tab Result +@item +Tagged music preceded by @code{\keepWithTag #'@var{name}} + @tab Untagged music and music tagged with @var{name} is included; + music tagged with any other tag name is excluded. +@item +Tagged music preceded by @code{\removeWithTag #'@var{name}} +@tab Untagged music and music tagged with any tag name other than + @var{name} is included; music tagged with @var{name} is + excluded. +@item +Tagged music not preceded by either @code{\keepWithTag} or +@code{\removeWithTag} +@tab All tagged and untagged music is included. +@end multitable + +The arguments of the @code{\tag}, @code{\keepWithTag} and +@code{\removeWithTag} commands should be a symbol +(such as @code{#'score} or @code{#'part}), followed +by a music expression. + +In the following example, we see two versions of a piece of music, +one showing trills with the usual notation, and one with trills +explicitly expanded: + +@lilypond[verbatim,quote] +music = \relative g' { + g8. c32 d + \tag #'trills {d8.\trill } + \tag #'expand {\repeat unfold 3 {e32 d} } + c32 d + } + +\score { + \keepWithTag #'trills \music +} +\score { + \keepWithTag #'expand \music +} +@end lilypond + +@noindent +Alternatively, it is sometimes easier to exclude sections of music: + +@lilypond[verbatim,quote] +music = \relative g' { + g8. c32 d + \tag #'trills {d8.\trill } + \tag #'expand {\repeat unfold 3 {e32 d} } + c32 d + } + +\score { + \removeWithTag #'expand + \music +} +\score { + \removeWithTag #'trills + \music +} +@end lilypond + +Tagged filtering can be applied to articulations, texts, etc. by +prepending -The same can be applied to articulations, texts, etc.: they are -made by prepending @example --\tag #@var{your-tag} +-\tag #'@var{your-tag} @end example -to an articulation, for example, + +to an articulation. For example, this would define a note with a +conditional fingering indication and a note with a conditional +annotation: + @example -c1-\tag #'part ^4 +c1-\tag #'finger ^4 +c1-\tag #'warn ^"Watch!" @end example -This defines a note with a conditional fingering indication. +Multiple tags may be placed on expressions with multiple +@code{\tag} entries: -@cindex keepWithTag -@cindex removeWithTag -By applying the @code{\keepWithTag} and @code{\removeWithTag} -commands, tagged expressions can be filtered. For example, -@example +@lilypond[quote,verbatim] +music = \relative c'' { + \tag #'a \tag #'both { a a a a } + \tag #'b \tag #'both { b b b b } +} << - @var{the music} - \keepWithTag #'score @var{the music} - \keepWithTag #'part @var{the music} +\keepWithTag #'a \music +\keepWithTag #'b \music +\keepWithTag #'both \music >> -@end example -would yield +@end lilypond -@c FIXME: broken -@c @lilypondfile[ragged-right,quote]{tag-filter.ly} +Multiple @code{\removeWithTag} filters may be applied to a single +music expression to remove several differently named tagged sections: -The arguments of the @code{\tag} command should be a symbol -(such as @code{#'score} or @code{#'part}), followed by a -music expression. It is possible to put multiple tags on -a piece of music with multiple @code{\tag} entries, +@lilypond[verbatim,quote] +music = \relative c'' { +\tag #'A { a a a a } +\tag #'B { b b b b } +\tag #'C { c c c c } +\tag #'D { d d d d } +} +{ +\removeWithTag #'B +\removeWithTag #'C +\music +} +@end lilypond -@example - \tag #'original-part \tag #'transposed-part @dots{} -@end example +Two or more @code{\keepWithTag} filters applied to a single music +expression will cause @emph{all} tagged sections to be removed, as +the first filter will remove all tagged sections except the one +named, and the second filter will remove even that tagged section. + +@seealso + +Learning Manual: +@rlearning{Organizing pieces with variables}. + +Notation Reference: +@ref{Automatic part combining}, +@ref{Including LilyPond files}. +@ignore +@c This warning is more general than this placement implies. +@c Rests are not merged whether or not they come from tagged sections. +@c Should be deleted? -td @knownissues -Multiple rests are not merged if you create the score with both tagged -sections. +Multiple rests are not merged if you create a score with more +than one tagged section at the same place. +@end ignore @node Text encoding @subsection Text encoding -LilyPond uses the Pango library to format multi-lingual texts, and -does not perform any input-encoding conversions. This means that any -text, be it title, lyric text, or musical instruction containing -non-ASCII characters, must be utf-8. The easiest way to enter such text is -by using a Unicode-aware editor and saving the file with utf-8 encoding. Most -popular modern editors have utf-8 support, for example, vim, Emacs, -jEdit, and GEdit do. - -@c Currently not working -@ignore -Depending on the fonts installed, the following fragment shows Hebrew -and Cyrillic lyrics, +LilyPond uses the character repertoire defined by the Unicode +consortium and ISO/IEC 10646. This defines a unique name and +code point for the character sets used in virtually all modern +languages and many others too. Unicode can be implemented using +several different encodings. LilyPond uses the UTF-8 encoding +(UTF stands for Unicode Transformation Format) which represents +all common Latin characters in one byte, and represents other +characters using a variable length format of up to four bytes. + +The actual appearance of the characters is determined by the +glyphs defined in the particular fonts available - a font defines +the mapping of a subset of the Unicode code points to glyphs. +LilyPond uses the Pango library to layout and render multi-lingual +texts. + +Lilypond does not perform any input-encoding conversions. This +means that any text, be it title, lyric text, or musical +instruction containing non-ASCII characters, must be encoded in +UTF-8. The easiest way to enter such text is by using a +Unicode-aware editor and saving the file with UTF-8 encoding. Most +popular modern editors have UTF-8 support, for example, vim, Emacs, +jEdit, and GEdit do. All MS Windows systems later than NT use +Unicode as their native character encoding, so even Notepad can +edit and save a file in UTF-8 format. A more functional +alternative for Windows is BabelPad. + +If a LilyPond input file containing a non-ASCII character is not +saved in UTF-8 format the error message -@cindex Cyrillic -@cindex Hebrew -@cindex ASCII, non +@example +FT_Get_Glyph_Name () error: invalid argument +@end example -@li lypondfile[fontload]{utf-8.ly} +will be generated. -The @TeX{} backend does not handle encoding specially at all. Strings -in the input are put in the output as-is. Extents of text items in the -@TeX{} backend, are determined by reading a file created via the -@file{texstr} backend, +Here is an example showing Cyrillic, Hebrew and Portuguese +text: -@example -lilypond -dbackend=texstr input/les-nereides.ly -latex les-nereides.texstr -@end example +@lilypond[quote] +%c No verbatim here as the code does not display correctly in PDF +% Cyrillic +bulgarian = \lyricmode { + Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон. +} -The last command produces @file{les-nereides.textmetrics}, which is -read when you execute +% Hebrew +hebrew = \lyricmode { + זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן. +} -@example -lilypond -dbackend=tex input/les-nereides.ly -@end example +% Portuguese +portuguese = \lyricmode { + à vo -- cê uma can -- ção legal +} -Both @file{les-nereides.texstr} and @file{les-nereides.tex} need -suitable LaTeX wrappers to load appropriate La@TeX{} packages for -interpreting non-ASCII strings. +\relative { + c2 d e f g f e +} +\addlyrics { \bulgarian } +\addlyrics { \hebrew } +\addlyrics { \portuguese } +@end lilypond -@end ignore +To enter a single character for which the Unicode escape sequence +is known but which is not available in the editor being used, use +@code{\char ##xhhhh} within a @code{\markup} block, where +@code{hhhh} is the hexadecimal code for the character required. +For example, @code{\char ##x03BE} enters the Unicode U+03BE +character, which has the Unicode name @qq{Greek Small Letter Xi}. +Any Unicode hexadecimal code may be substituted, and if all special +characters are entered in this format it is not necessary to save +the input file in UTF-8 format. Of course, a font containing all +such encoded characters must be installed and available to LilyPond. + +The following example shows UTF-8 coded characters being used in +four places -- in a rehearsal mark, as articulation text, in lyrics +and as stand-alone text below the score: + +@lilypond[quote,verbatim] +\score { + \relative c'' { + c1 \mark \markup { \char ##x03EE } + c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } } + } + \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } } +} +\markup { "Copyright 2008" \char ##x00A9 } +@end lilypond -To use a Unicode escape sequence, use +To enter the copyright sign in the copyright notice use: @example -#(ly:export (ly:wide-char->utf-8 #x2014)) +\header @{ + copyright = \markup @{ \char ##x00A9 "2008" @} +@} @end example - @node Displaying LilyPond notation @subsection Displaying LilyPond notation @@ -1174,6 +1228,8 @@ with all the other messages. To split up these messages and save the results of @code{\display@{STUFF@}}, redirect the output to a file. +@c TODO What happens under Windows? + @example lilypond file.ly >display.txt @end example @@ -1184,12 +1240,12 @@ lilypond file.ly >display.txt @section Controlling output @menu -* Extracting fragments of notation:: +* Extracting fragments of music:: * Skipping corrected music:: @end menu -@node Extracting fragments of notation -@subsection Extracting fragments of notation +@node Extracting fragments of music +@subsection Extracting fragments of music It is possible to quote small fragments of a large score directly from the output. This can be compared to clipping a piece of a paper score @@ -1206,7 +1262,7 @@ separately. For example, including the following definition (cons (make-rhythmic-location 5 1 2) (make-rhythmic-location 7 3 4))) -} +} @end verbatim @noindent @@ -1215,7 +1271,7 @@ the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7. More clip regions can be defined by adding more pairs of -rhythmic-locations to the list. +rhythmic-locations to the list. In order to use this feature, LilyPond must be invoked with @code{-dclip-systems}. The clips are output as EPS files, and are @@ -1268,3 +1324,592 @@ In polyphonic music, @code{Score.skipTypesetting} will affect all voices and staves, saving even more time. + +@node MIDI output +@section MIDI output + +@cindex Sound +@cindex MIDI + +MIDI (Musical Instrument Digital Interface) is a standard for +connecting and controlling digital instruments. A MIDI file is a +series of notes in a number of tracks. It is not an actual +sound file; you need special software to translate between the +series of notes and actual sounds. + +Pieces of music can be converted to MIDI files, so you can listen to +what was entered. This is convenient for checking the music; octaves +that are off or accidentals that were mistyped stand out very much +when listening to the MIDI output. + +@c TODO Check this +The midi output allocates a channel for each staff, and one for global +settings. Therefore the midi file should not have more than 15 staves +(or 14 if you do not use drums). Other staves will remain silent. + +@menu +* Creating MIDI files:: +* MIDI block:: +* What goes into the MIDI output?:: +* Repeats in MIDI:: +* Controlling MIDI dynamics:: +* Percussion in MIDI:: +@end menu + +@node Creating MIDI files +@subsection Creating MIDI files + +To create a MIDI output file from a LilyPond input file, add a +@code{\midi} block to a score, for example, + +@example +\score @{ + @var{...music...} + \midi @{ @} +@} +@end example + +If there is a @code{\midi} block in a @code{\score} with no +@code{\layout} block, only MIDI output will be produced. When +notation is needed too, a @code{\layout} block must be also be +present. + +@example +\score @{ + @var{...music...} + \midi @{ @} + \layout @{ @} +@} +@end example + +Pitches, rhythms, ties, dynamics, and tempo changes are interpreted +and translated correctly to the MIDI output. Dynamic marks, +crescendi and decrescendi translate into MIDI volume levels. +Dynamic marks translate to a fixed fraction of the available MIDI +volume range. Crescendi and decrescendi make the volume vary +linearly between their two extremes. The effect of dynamic markings +on the MIDI output can be removed completely, see @ref{MIDI block}. + +The initial tempo and later tempo changes can be specified +with the @code{\tempo} command within the music notation. These +are reflected in tempo changes in the MIDI output. This command +will normally result in the metronome mark being printed, but this +can be suppressed, see @ref{Metronome marks}. An alternative way +of specifying the inital or overall MIDI tempo is described below, +see @ref{MIDI block}. + +@unnumberedsubsubsec Instrument names + +@cindex instrument names +@funindex Staff.midiInstrument + +The MIDI instrument to be used is specified by setting the +@code{Staff.midiInstrument} property to the instrument name. +The name should be chosen from the list in @ref{MIDI instruments}. + +@example +\new Staff @{ + \set Staff.midiInstrument = "glockenspiel" + @var{...notes...} +@} +@end example + +@example +\new Staff \with @{midiInstrument = "cello"@} @{ + @var{...notes...} +@} +@end example + +If the selected instrument does not exactly match an instrument from +the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"}) +instrument is used. + + +@snippets + +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{changing-midi-output-to-one-channel-per-voice.ly} + +@knownissues + +@c In 2.11 the following no longer seems to be a problem -td +@ignore +Unterminated (de)crescendos will not render properly in the midi file, +resulting in silent passages of music. The workaround is to explicitly +terminate the (de)crescendo. For example, + +@example +@{ a\< b c d\f @} +@end example + +@noindent +will not work properly but + +@example +@{ a\< b c d\!\f @} +@end example + +@noindent +will. +@end ignore + +Changes in the MIDI volume take place only on starting a note, so +crescendi and decrescendi cannot affect the volume of a +single note. + +Not all midi players correctly handle tempo changes in the midi +output. Players that are known to work include MS Windows Media +Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}. + +@node MIDI block +@subsection MIDI block +@cindex MIDI block + +A @code{\midi} block must appear within a score block if MIDI output +is required. It is analogous to the layout block, but somewhat +simpler. Often, the @code{\midi} block is left empty, but it +can contain context rearrangements, new context definitions or code +to set the values of properties. For example, the following will +set the initial tempo exported to a MIDI file without causing a tempo +indication to be printed: + +@example +\score @{ + @var{...music...} + \midi @{ + \context @{ + \Score + tempoWholesPerMinute = #(ly:make-moment 72 4) + @} + @} +@} +@end example + +In this example the tempo is set to 72 quarter note +beats per minute. This kind of tempo specification cannot take +a dotted note length as an argument. If one is required, break +the dotted note into smaller units. For example, a tempo of 90 +dotted quarter notes per minute can be specified as 270 eighth +notes per minute: + +@example +tempoWholesPerMinute = #(ly:make-moment 270 8) +@end example + +@cindex MIDI context definitions + +Context definitions follow precisely the same syntax as those +within a @code{\layout} block. Translation modules for sound are +called performers. The contexts for MIDI output are defined in +@file{../ly/@/performer@/-init@/.ly}, +see @rlearning{Other sources of information}. +For example, to remove the effect of dynamics +from the MIDI output, insert the following lines in the +@code{\midi@{ @}} block. + +@example +\midi @{ + ... + \context @{ + \Voice + \remove "Dynamic_performer" + @} +@} +@end example + +MIDI output is created only when a @code{\midi} block is included +within a score block defined with a @code{\score} command. If it +is placed within an explicitly instantiated score context (i.e. +within a @code{\new Score} block) the file will fail. To solve +this, enclose the @code{\new Score} and the @code{\midi} commands +in a @code{\score} block. + +@example +\score @{ + \new Score @{ @dots{}notes@dots{} @} + \midi @{ @} +@} +@end example + +@node What goes into the MIDI output? +@subsection What goes into the MIDI output? + +@c TODO Check grace notes - timing is suspect? + +@unnumberedsubsubsec Supported in MIDI + +@cindex Pitches in MIDI +@cindex MIDI, Pitches +@cindex Quarter tones in MIDI +@cindex MIDI, quarter tones +@cindex Microtones in MIDI +@cindex MIDI, microtones +@cindex Chord names in MIDI +@cindex MIDI, chord names +@cindex Rhythms in MIDI +@cindex MIDI, Rhythms +@c TODO etc + +The following items of notation are reflected in the MIDI output: + +@itemize +@item Pitches +@item Quarter tones (See @ref{Accidentals}. Rendering needs a +player that supports pitch bend.) +@item Chords entered as chord names +@item Rhythms entered as note durations, including tuplets +@item Tremolos entered without @q{@code{:}[@var{number}]} +@item Ties +@item Dynamic marks +@item Crescendi, decrescendi over multiple notes +@item Tempo changes entered with a tempo marking +@item Lyrics +@end itemize + +@unnumberedsubsubsec Unsupported in MIDI + +@c TODO index as above + +The following items of notation have no effect on the MIDI output: + +@itemize +@item Rhythms entered as annotations, e.g. swing +@item Tempo changes entered as annotations with no tempo marking +@item Staccato and other articulations and ornamentations +@item Slurs and Phrasing slurs +@item Crescendi, decrescendi over a single note +@item Tremolos entered with @q{@code{:}[@var{number}]} +@item Figured bass +@end itemize + + +@node Repeats in MIDI +@subsection Repeats in MIDI + +@cindex repeats in MIDI +@funindex \unfoldRepeats + +With a few minor additions, all types of repeats can be represented +in the MIDI output. This is achieved by applying the +@code{\unfoldRepeats} music function. This function changes all +repeats to unfold repeats. + +@lilypond[quote,verbatim] +\unfoldRepeats { + \repeat tremolo 8 {c'32 e' } + \repeat percent 2 { c''8 d'' } + \repeat volta 2 {c'4 d' e' f'} + \alternative { + { g' a' a' g' } + {f' e' d' c' } + } +} +\bar "|." +@end lilypond + +When creating a score file using @code{\unfoldRepeats} for MIDI, +it is necessary to make two @code{\score} blocks: one for MIDI +(with unfolded repeats) and one for notation (with volta, tremolo, +and percent repeats). For example, + +@example +\score @{ + @var{..music..} + \layout @{ .. @} +@} +\score @{ + \unfoldRepeats @var{..music..} + \midi @{ .. @} +@} +@end example + +@node Controlling MIDI dynamics +@subsection Controlling MIDI dynamics + +MIDI dynamics are implemented by the Dynamic_performer which lives +by default in the Voice context. It is possible to control the +overall MIDI volume, the relative volume of dynamic markings and +the relative volume of different instruments. + +@unnumberedsubsubsec Dynamic marks + +Dynamic marks are translated to a fixed fraction of the available +MIDI volume range. The default fractions range from 0.25 for +@notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic +marks and the associated fractions can be seen in +@file{../scm/midi.scm}, see @rlearning{Other sources of information}. +This set of fractions may be changed or extended by providing a +function which takes a dynamic mark as its argument and returns the +required fraction, and setting +@code{Score.dynamicAbsoluteVolumeFunction} to this function. + +For example, if a @notation{rinforzando} dynamic marking, +@code{\rfz}, is required, this will not by default +have any effect on the MIDI volume, as this dynamic marking is not +included in the default set. Similarly, if a new dynamic marking +has been defined with @code{make-dynamic-script} that too will not +be included in the default set. The following example shows how the +MIDI volume for such dynamic markings might be added. The Scheme +function sets the fraction to 0.9 if a dynamic mark of rfz is +found, or calls the default function otherwise. + +@lilypond[verbatim,quote] +#(define (myDynamics dynamic) + (if (equal? dynamic "rfz") + 0.9 + (default-dynamic-absolute-volume dynamic))) + +\score { + \new Staff { + \set Staff.midiInstrument = "cello" + \set Score.dynamicAbsoluteVolumeFunction = #myDynamics + \new Voice { + \relative c'' { + a\pp b c-\rfz + } + } + } + \layout {} + \midi {} +} +@end lilypond + +Alternatively, if the whole table of fractions needs to be +redefined, it would be better to use the +@notation{default-dynamic-absolute-volume} procedure in +@file{../scm/midi.scm} and the associated table as a model. +The final example in this section shows how this might be done. + +@unnumberedsubsubsec Overall MIDI volume + +The minimum and maximum overall volume of MIDI dynamic markings is +controlled by setting the properties @code{midiMinimumVolume} and +@code{midiMaximumVolume} at the @code{Score} level. These +properties have an effect only on dynamic marks, so if they +are to apply from the start of the score a dynamic mark must be +placed there. The fraction corresponding to each dynamic mark is +modified with this formula + +@example +midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction +@end example + +In the following example the dynamic range of the overall MIDI +volume is limited to the range 0.2 - 0.5. + +@lilypond[verbatim,quote] +\score { + << + \new Staff { + \key g \major + \time 2/2 + \set Staff.midiInstrument = #"flute" + \new Voice \relative c''' { + r2 g\mp g fis ~ + fis4 g8 fis e2 ~ + e4 d8 cis d2 + } + } + \new Staff { + \key g \major + \set Staff.midiInstrument = #"clarinet" + \new Voice \relative c'' { + b1\p a2. b8 a + g2. fis8 e + fis2 r + } + } + >> + \layout { } + \midi { + \context { + \Score + tempoWholesPerMinute = #(ly:make-moment 72 2) + midiMinimumVolume = #0.2 + midiMaximumVolume = #0.5 + } + } +} +@end lilypond + +@unnumberedsubsubsec Equalizing different instruments (i) + +If the minimum and maximum MIDI volume properties are set in +the @code{Staff} context the relative volumes of the MIDI +instruments can be controlled. This gives a basic instrument +equalizer, which can enhance the quality of the MIDI output +remarkably. + +In this example the volume of the clarinet is reduced relative +to the volume of the flute. There must be a dynamic +mark on the first note of each instrument for this to work +correctly. + +@lilypond[verbatim,quote] +\score { + << + \new Staff { + \key g \major + \time 2/2 + \set Staff.midiInstrument = #"flute" + \set Staff.midiMinimumVolume = #0.7 + \set Staff.midiMaximumVolume = #0.9 + \new Voice \relative c''' { + r2 g\mp g fis ~ + fis4 g8 fis e2 ~ + e4 d8 cis d2 + } + } + \new Staff { + \key g \major + \set Staff.midiInstrument = #"clarinet" + \set Staff.midiMinimumVolume = #0.3 + \set Staff.midiMaximumVolume = #0.6 + \new Voice \relative c'' { + b1\p a2. b8 a + g2. fis8 e + fis2 r + } + } + >> + \layout { } + \midi { + \context { + \Score + tempoWholesPerMinute = #(ly:make-moment 72 2) + } + } +} +@end lilypond + +@unnumberedsubsubsec Equalizing different instruments (ii) + +If the MIDI minimum and maximum volume properties are not set +LilyPond will, by default, apply a small degree of equalization +to a few instruments. The instruments and the equalization +applied are shown in the table @notation{instrument-equalizer-alist} +in @file{../scm/midi.scm}. + +This basic default equalizer can be replaced by setting +@code{instrumentEqualizer} in the @code{Score} context to a new +Scheme procedure which accepts a MIDI instrument name as its only +argument and returns a pair of fractions giving the minimum and +maximum volumes to be applied to that instrument. This replacement +is done in the same way as shown for resetting the +@code{dynamicAbsoluteVolumeFunction} at the start of this section. +The default equalizer, @notation{default-instrument-equalizer}, in +@file{../scm/midi.scm} shows how such a procedure might be written. + +The following example sets the relative flute and clarinet volumes +to the same values as the previous example. + +@lilypond[verbatim,quote] +#(define my-instrument-equalizer-alist '()) + +#(set! my-instrument-equalizer-alist + (append + '( + ("flute" . (0.7 . 0.9)) + ("clarinet" . (0.3 . 0.6))) + my-instrument-equalizer-alist)) + +#(define (my-instrument-equalizer s) + (let ((entry (assoc s my-instrument-equalizer-alist))) + (if entry + (cdr entry)))) + +\score { + << + \new Staff { + \key g \major + \time 2/2 + \set Score.instrumentEqualizer = #my-instrument-equalizer + \set Staff.midiInstrument = #"flute" + \new Voice \relative c''' { + r2 g\mp g fis ~ + fis4 g8 fis e2 ~ + e4 d8 cis d2 + } + } + \new Staff { + \key g \major + \set Staff.midiInstrument = #"clarinet" + \new Voice \relative c'' { + b1\p a2. b8 a + g2. fis8 e + fis2 r + } + } + >> + \layout { } + \midi { + \context { + \Score + tempoWholesPerMinute = #(ly:make-moment 72 2) + } + } +} +@end lilypond + +@ignore +@c Delete when satisfied this is adequately covered elsewhere -td + +@n ode Microtones in MIDI +@s ubsection Microtones in MIDI + +@cindex microtones in MIDI + +Microtones consisting of half sharps and half flats are exported +to the MIDI file and render correctly in MIDI players which support +pitch bending. See @ref{Note names in other languages}. Here is +an example showing all the half sharps and half flats. It can be +copied out and compiled to test microtones in your MIDI player. + +@lilypond[verbatim,quote] +\score { + \relative c' { + c cih cis cisih + d dih ees eeh + e eih f fih + fis fisih g gih + gis gisih a aih + bes beh b bih + } + \layout {} + \midi {} +} +@end lilypond +@end ignore + + +@node Percussion in MIDI +@subsection Percussion in MIDI + +Percussion instruments are generally notated in a @code{DrumStaff} +context and when notated in this way they are outputted correctly +to MIDI channel@tie{}10, but some pitched percussion instruments, +like the xylophone, marimba, vibraphone, timpani, etc., are +treated like @qq{normal} instruments and music for these instruments +should be entered in a normal @code{Staff} context, not a +@code{DrumStaff} context, to obtain the correct MIDI output. + +Some non-pitched percussion sounds included in the general MIDI +standard, like melodic tom, taiko drum, synth drum, etc., cannot +be reached via MIDI channel@tie{}10, so the notation for such +instruments should also be entered in a normal @code{Staff} +context, using suitable normal pitches. + +Many percussion instruments are not included in the general MIDI +standard, e.g. castanets. The easiest, although unsatisfactory, +method of producing some MIDI output when writing for such +instruments is to substitute the nearest sound from the standard +set. + +@c TODO Expand with examples, and any other issues + +@knownissues + +Because the general MIDI standard does not contain rim shots, the +sidestick is used for this purpose instead. + +