specific notation.
@menu
-* Input files::
* Titles and headers::
* MIDI output::
-* Displaying LilyPond notation::
-* Skipping corrected music::
+* other midi::
@end menu
-@node Input files
-@section Input files
-
-The main format of input for LilyPond are text files. By convention,
-these files end with @samp{.ly}.
-
-@menu
-* File structure (introduction)::
-* File structure::
-* A single music expression::
-* Multiple scores in a book::
-* Extracting fragments of notation::
-* Including LilyPond files::
-* Text encoding::
-@end menu
-
-
-@node File structure (introduction)
-@subsection File structure (introduction)
-
-A basic example of a lilypond input file is
-
-@example
-\version "2.11.23"
-\score @{
- @{ @} % this is a single music expression;
- % all the music goes in here.
- \header @{ @}
- \layout @{ @}
- \midi @{ @}
-@}
-@end example
-
-@noindent
-There are many variations of this basic pattern, but this
-example serves as a useful starting place.
-
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
-@example
-c'4
-@end example
-
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions; see @ref{File structure}, for
-a list of all such expressions.
-
-
-@node File structure
-@subsection File structure
-
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
-
-@itemize @bullet
-@item
-An output definition, such as @code{\paper}, @code{\midi}, and
-@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
-
-@item
-A direct scheme expression, such as
-@code{#(set-default-paper-size "a7" 'landscape)} or
-@code{#(ly:set-option 'point-and-click #f)}.
-
-@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
-
-@item
-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}.
-
-The @code{\score} must begin with a music expression, and may
-contain only one music expression.
-
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. If there are
-a number of @code{\scores}, one output file will be created for
-each @code{\book} block, in which all corresponding movements are
-concatenated. The only reason to explicitly specify @code{\book} blocks
-in a @code{.ly} file is if you wish multiple output files from a single
-input file. One exception is within lilypond-book documents, where you
-explicitly have to add 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}.
-
-@item
-A compound music expression, such as
-@example
-@{ c'4 d' e'2 @}
-@end example
-
-This will add the piece in a @code{\score} and format it in a
-single book together with all other toplevel @code{\score}s and music
-expressions. In other words, a file containing only the above
-music expression will be translated into
-
-@example
-\book @{
- \score @{
- \new Staff @{
- \new Voice @{
- @{ c'4 d' e'2 @}
- @}
- @}
- @}
- \layout @{ @}
- \header @{ @}
-@}
-@end example
-
-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}.
-
-@item
-A markup text, a verse for example
-@example
-\markup @{
- 2. The first line verse two.
-@}
-@end example
-
-Markup texts are rendered above, between or below the scores or music
-expressions, wherever they appear.
-
-@cindex variables
-@cindex identifiers
-
-@item
-An identifier, such as
-@example
-foo = @{ c4 d e d @}
-@end example
-
-This can be used later on in the file by entering @code{\foo}. The
-name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes.
-
-@end itemize
-
-The following example shows three things that may be entered at
-toplevel
-
-@example
-\layout @{
- % movements are non-justified by default
- ragged-right = ##t
-@}
-
-\header @{
- title = "Do-re-mi"
-@}
-
-@{ c'4 d' e2 @}
-@end example
-
-
-At any point in a file, any of the following lexical instructions can
-be entered:
-
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\sourcefilename}
-@item @code{\sourcefileline}
-
-@end itemize
-
-
-@node A single music expression
-@subsection A single music expression
-
-A @code{\score} must contain a single music expression. However,
-this music expression may be of any size. Recall that music
-expressions may be included inside other expressions to form
-larger expressions. All of these examples are single music
-expressions; note the curly braces @{ @} or angle brackets <<
->> at the beginning and ending of the music.
-
-@example
-@{ c'4 c' c' c' @}
-@end example
-
-@lilypond[ragged-right,verbatim,quote]
-{
- { c'4 c' c' c'}
- { d'4 d' d' d'}
-}
-@end lilypond
-
-@lilypond[ragged-right,verbatim,quote]
-<<
- \new Staff { c'4 c' c' c' }
- \new Staff { d'4 d' d' d' }
->>
-@end lilypond
-
-@example
-@{
- \new GrandStaff <<
- \new StaffGroup <<
- \new Staff @{ \flute @}
- \new Staff @{ \oboe @}
- >>
- \new StaffGroup <<
- \new Staff @{ \violinI @}
- \new Staff @{ \violinII @}
- >>
- >>
-@}
-@end example
-
-
-@node Multiple scores in a book
-@subsection Multiple scores in a book
-
-@funindex \book
-@cindex movements, multiple
-
-A document may contain multiple pieces of music and texts. Examples
-of these are an etude book, or an orchestral part with multiple
-movements. Each movement is entered with a @code{\score} block,
-
-@example
-\score @{
- @var{..music..}
-@}
-@end example
-
-and texts are entered with a @code{\markup} block,
-
-@example
-\markup @{
- @var{..text..}
-@}
-@end example
-
-@funindex \book
-
-All the movements and texts which appear in the same @code{.ly} file
-will normally be typeset in the form of a single output file.
-
-@example
-\score @{
- @var{..}
-@}
-\markup @{
- @var{..}
-@}
-\score @{
- @var{..}
-@}
-@end example
-
-However, if you want multiple output files from the same @code{.ly}
-file, then you can add multiple @code{\book} blocks, where each such
-@code{\book} block will result in a separate output. If you do not
-specify any @code{\book} block in the file, LilyPond will implicitly
-treat the full file as a single @code{\book} block, see @ref{File
-structure}. One important exception is within lilypond-book documents,
-where you explicitly have to add a @code{\book} block, otherwise only
-the first @code{\score} or @code{\markup} will appear in the output.
-
-The header for each piece of music can be put inside the @code{\score}
-block. The @code{piece} name from the header will be printed before
-each movement. The title for the entire book can be put inside the
-@code{\book}, but if it is not present, the @code{\header} which is at
-the top of the file is inserted.
-
-@example
-\header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
-@}
-\score @{
- @dots{}
- \header @{ piece = "Romanze" @}
-@}
-\markup @{
- ..text of second verse..
-@}
-\markup @{
- ..text of third verse..
-@}
-\score @{
- @dots{}
- \header @{ piece = "Menuetto" @}
-@}
-@end example
-
-@node Extracting fragments of notation
-@subsection Extracting fragments of notation
-
-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
-with scissors.
-
-This is done by definining the measures that need to be cut out
-separately. For example, including the following definition
-
-
-@verbatim
-\layout {
- clip-regions
- = #(list
- (cons
- (make-rhythmic-location 5 1 2)
- (make-rhythmic-location 7 3 4)))
-}
-@end verbatim
-
-@noindent
-will extract a fragment starting halfway the fifth measure, ending in
-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.
-
-In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}. The clips are output as EPS files, and are
-converted to PDF and PNG if these formats are switched on as well.
-
-For more information on output formats, see @rprogram{Invoking lilypond}.
-
-@seealso
-
-Examples: @lsr{non-notation,clip-systems.ly}
-
-
-@node Including LilyPond files
-@subsection Including LilyPond files
-
-@funindex \include
-@cindex including files
-
-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 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 @samp{/} rather than the DOS/Windows @samp{\}. For example,
-if @file{stuff.ly} is located one directory higher than the current working
-directory, use
-
-@example
-\include "../stuff.ly"
-@end example
-
-
-@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,
-
-@cindex Cyrillic
-@cindex Hebrew
-@cindex ASCII, non
-
-@li lypondfile[fontload]{utf-8.ly}
-
-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,
-
-@example
-lilypond -dbackend=texstr input/les-nereides.ly
-latex les-nereides.texstr
-@end example
-
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
-
-@example
-lilypond -dbackend=tex input/les-nereides.ly
-@end example
-
-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.
-
-@end ignore
-
-To use a Unicode escape sequence, use
-
-@example
-#(ly:export (ly:wide-char->utf-8 #x2014))
-@end example
-
-
-@seealso
-
-@lsr{text,utf-8.ly}
-
-
-
@node Titles and headers
@section Titles and headers
A particular place of a score can be marked using the @code{\label}
command, either at top-level or inside music. This label can then be
-refered to in a markup, to get the number of the page where the marked
+referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.
@lilypond[verbatim,line-width=11.0\cm]
@end enumerate
The reason why a gauge is needed is that, at the time markups are
-interpreted, the page breaking has not yet occured, so the page numbers
+interpreted, the page breaking has not yet occurred, so the page numbers
are not yet known. To work around this issue, the actual markup
interpretation is delayed to a later time; however, the dimensions of
the markup have to be known before, so a gauge is used to decide these
dimensions. If the book has between 10 and 99 pages, it may be "00",
ie. a two digit number.
-@refcommands
+@predefined
@funindex \label
@code{\label}
@end verbatim
The markups which are used to format the table of contents are defined
-in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
+in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
for formatting the title of the table, and @code{tocItemMarkup}, for
formatting the toc elements, composed of the element title and page
-number. These variables may be changed by the user:
+number. These variables may be changed by the user:
@verbatim
\paper {
\fill-line { \null "Table des matières" \null }
\hspace #1
}
- %% use larfer font size
+ %% use larger font size
tocItemMarkup = \markup \large \fill-line {
\fromproperty #'toc:text \fromproperty #'toc:page
}
}
@end verbatim
-Note how the toc element text and page number are refered to in
+Note how the toc element text and page number are referred to in
the @code{tocItemMarkup} definition.
New commands and markups may also be defined to build more elaborated
table of contents:
-@itemize @bullet
+@itemize
@item first, define a new markup variable in the @code{\paper} block
@item then, define a music function which aims at adding a toc element
using this markup paper variable.
Init files: @file{ly/@/toc@/-init@/.ly}.
-@refcommands
+@predefined
@funindex \table-of-contents
@code{\table-of-contents}
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
-@refbugs
+@knownissues
Many musically interesting effects, such as swing, articulation,
slurring, etc., are not translated to midi.
* Creating MIDI files::
* MIDI block::
* MIDI instrument names::
+* What goes into the MIDI? FIXME::
@end menu
@node Creating MIDI files
The tempo can be specified using the @code{\tempo} command within the
actual music, see @ref{Metronome marks}. An alternative, which does not
result in a metronome mark in the printed score, is shown in the example
-above. In this example the tempo of quarter notes is set to 72 beats per
+above. In this example the tempo of quarter notes is set to 72 beats per
minute.
This kind of tempo
-specification can not take dotted note lengths as an argument. In this
-case, break the dotted notes into smaller units. For example, a tempo
+specification can not take dotted note lengths as an argument. In this
+case, break the dotted notes into smaller units. For example, a tempo
of 90 dotted quarter notes per minute can be specified as 270 eighth
notes per minute
@end example
-@refbugs
+@knownissues
Unterminated (de)crescendos will not render properly in the midi file,
resulting in silent passages of music. The workaround is to explicitly
The MIDI block is analogous to the layout block, but it is somewhat
-simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
+simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
context definitions.
instrument is used.
-@c Yes, this is a cop-out; this info doesn't belong in the Scheme
-@c chapter, but I'm not certain where to stick it.
-@c I think I'll eventually split this chapter into a "paper/layout"
-@c chapter and a "misc issues" chapter. -gp
-@node Displaying LilyPond notation
-@section Displaying LilyPond notation
-
-@funindex \displayLilyMusc
-Displaying a music expression in LilyPond notation can be
-done using the music function @code{\displayLilyMusic}. For example,
+@node What goes into the MIDI? FIXME
+@subsection What goes into the MIDI? FIXME
-@example
-@{
- \displayLilyMusic \transpose c a, @{ c e g a bes @}
-@}
-@end example
-
-will display
+@menu
+* Repeats and MIDI::
+@end menu
-@example
-@{ a, cis e fis g @}
-@end example
+@node Repeats and MIDI
+@subsubsection Repeats and MIDI
+
+@cindex expanding repeats
+@funindex \unfoldRepeats
+
+With a little bit of tweaking, all types of repeats can be present
+in the MIDI output. This is achieved by applying the
+@code{\unfoldRepeats} music function. This function changes all
+repeats to unfold repeats.
+
+@lilypond[quote,verbatim,fragment,line-width=8.0\cm]
+\unfoldRepeats {
+ \repeat tremolo 8 {c'32 e' }
+ \repeat percent 2 { c''8 d'' }
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative {
+ { g' a' a' g' }
+ {f' e' d' c' }
+ }
+}
+\bar "|."
+@end lilypond
-By default, LilyPond will print these messages to the console along
-with all the other messages. To split up these messages and save
-the results of @code{\display@{STUFF@}}, redirect the output to
-a file.
+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
-lilypond file.ly >display.txt
+\score @{
+ @var{..music..}
+ \layout @{ .. @}
+@}
+\score @{
+ \unfoldRepeats @var{..music..}
+ \midi @{ .. @}
+@}
@end example
-@node Skipping corrected music
-@section Skipping corrected music
-
-
-@funindex skipTypesetting
-@funindex showLastLength
-
-When entering or copying music, usually only the music near the end (where
-you
-are adding notes) is interesting to view and correct. To speed up
-this correction process, it is possible to skip typesetting of all but
-the last few measures. This is achieved by putting
+@node other midi
+@section other midi
-@verbatim
-showLastLength = R1*5
-\score { ... }
-@end verbatim
-
-@noindent
-in your source file. This will render only the last 5 measures
-(assuming 4/4 time signature) of every @code{\score} in the input
-file. For longer pieces, rendering only a small part is often an order
-of magnitude quicker than rendering it completely
-
-Skipping parts of a score can be controlled in a more fine-grained
-fashion with the property @code{Score.skipTypesetting}. When it is
-set, no typesetting is performed at all.
-
-This property is also used to control output to the MIDI file. Note that
-it skips all events, including tempo and instrument changes. You have
-been warned.
-
-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
- c8 d
- \set Score.skipTypesetting = ##t
- e e e e e e e e
- \set Score.skipTypesetting = ##f
- c d b bes a g c2 }
-@end lilypond
+Micro tones are also exported to the MIDI file.
-In polyphonic music, @code{Score.skipTypesetting} will affect all
-voices and staves, saving even more time.
projects / lilypond.git / blobdiff