version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.51"
@node Input syntax
@chapter Input syntax
This section deals with general LilyPond input syntax issues,
rather than specific notation.
-FIXME: don't complain about anything in this chapter. It's still
-under heavy development.
-
@menu
* Input structure::
* Titles and headers::
@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,
+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
@example
-lilypond -dbackend=texstr input/les-nereides.ly
-latex les-nereides.texstr
+FT_Get_Glyph_Name () error: invalid argument
@end example
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
+will be generated.
-@example
-lilypond -dbackend=tex input/les-nereides.ly
-@end example
+Here is an example showing Cyrillic, Hebrew and Portuguese
+text:
-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.
+@lilypond[verbatim,quote]
+% Cyrillic
+bulgarian = \lyricmode {
+ Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
+}
-@end ignore
+% Hebrew
+hebrew = \lyricmode {
+ זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
+}
+
+% Portuguese
+portuguese = \lyricmode {
+ à vo -- cê uma can -- ção legal
+}
-To use a Unicode escape sequence, use
+\relative {
+ c2 d e f g f e
+}
+\addlyrics { \bulgarian }
+\addlyrics { \hebrew }
+\addlyrics { \portuguese }
+@end lilypond
+
+To enter a single character for which the Unicode escape sequence
+is known but which is not available in the editor being used, enter
@example
-#(ly:export (ly:wide-char->utf-8 #x2014))
+#(ly:export (ly:wide-char->utf-8 #x03BE))
@end example
+where in this example @code{x03BE} is the hexadecimal code for 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.
+
+@knownissues
+
+The @code{ly:export} format may be used in text within @code{\mark} or
+@code{\markup} commands but not in lyrics.
@node Displaying LilyPond notation
@subsection Displaying LilyPond notation
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
(cons
(make-rhythmic-location 5 1 2)
(make-rhythmic-location 7 3 4)))
-}
+}
@end verbatim
@noindent
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
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
-@knownissues
-
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to midi.
-
+@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.
-Not all midi players correctly handle tempo changes in the midi
-output. Players that are known to work include
-@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
-
@menu
-* Creating MIDI files::
-* MIDI block::
-* MIDI instrument names::
-* What goes into the MIDI? FIXME::
-* other midi::
+* Creating MIDI files::
+* MIDI block::
+* MIDI instrument names::
+* Repeats in MIDI::
+* What else goes into the MIDI output?::
@end menu
@node Creating MIDI files
@subsection Creating MIDI files
-To create a MIDI from a music piece of music, add a @code{\midi} block
+To 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 @{
- \context @{
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 4)
- @}
- @}
+ \midi @{ @}
@}
@end example
-The tempo can be specified using the @code{\tempo} command within the
-actual music, see @ref{Metronome marks}. An alternative, which does not
-result in a metronome mark in the printed score, is shown in the example
-above. In this example the tempo of quarter notes is set to 72 beats per
-minute.
-This kind of tempo
-specification can not take dotted note lengths as an argument. In this
-case, break the dotted notes into smaller units. For example, a tempo
-of 90 dotted quarter notes per minute can be specified as 270 eighth
-notes per minute
-
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
-
-If there is a @code{\midi} command in a @code{\score}, only MIDI will
-be produced. When notation is needed too, a @code{\layout} block must
-be added
+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 @{
\layout @{ @}
@}
@end example
-@cindex layout block
+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}.
+@ignore
+@c TODO Investigate dynamicAbsoluteVolumeFunction and the two
+@c midi..Volume properties, then document properly.
-Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels. Dynamic
-marks translate to a fixed fraction of the available MIDI volume
-range, crescendi and decrescendi make the volume vary linearly between
-their two extremes. The fractions can be adjusted by
+The fractions can be adjusted by setting
@code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
For each type of MIDI instrument, a volume range can be defined. This
gives a basic equalizer control, which can enhance the quality of
\set Staff.midiMaximumVolume = #0.8
@end example
-To remove dynamics from the MIDI output, insert the following lines
-in the @code{\midi@{@}} section.
-
-@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
-@}
-@end example
-
+@end ignore
@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,
@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}.
-MIDI output is only created when the @code{\midi} command is within
-a @code{\score} block. If you put it within an explicitly instantiated
-context ( i.e. @code{\new Score} ) the file will fail. To solve this,
-enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
+
+@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 @{
- \new Score @{ @dots{}notes@dots{} @}
- \midi
+ @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:
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+@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.
-The MIDI block is analogous to the layout block, but it is somewhat
-simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
-context definitions.
+@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.
-@cindex context definition
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi @{ @}
+@}
+@end example
-Context definitions follow precisely the same syntax as within the
-\layout block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
+@snippets
+@c TODO Check header and text appear in this example
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
@node MIDI instrument names
@subsection MIDI instrument names
instrument is used.
-@node What goes into the MIDI? FIXME
-@subsection What goes into the MIDI? FIXME
-
-@menu
-* Repeats and MIDI::
-@end menu
+@node Repeats in MIDI
+@subsection Repeats in MIDI
-@node Repeats and MIDI
-@subsubsection Repeats and MIDI
-
-@cindex expanding repeats
+@cindex repeats in MIDI
@funindex \unfoldRepeats
-With a little bit of tweaking, all types of repeats can be present
+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,fragment,line-width=8.0\cm]
+@lilypond[quote,verbatim]
\unfoldRepeats {
\repeat tremolo 8 {c'32 e' }
\repeat percent 2 { c''8 d'' }
@end example
-@node other midi
-@subsection other midi
+@node What else goes into the MIDI output?
+@subsection What else goes into the MIDI output?
+
+@c TODO Check grace notes - timing is suspect?
+
+@unnumberedsubsubsec Microtones
+
+@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
+
+@knownissues
+
+@c TODO List things that have no effect
+@c TODO Check these
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to midi. Also, figured bass,
+chords, and lyrics have no effect on MIDI.
-Micro tones are also exported to the MIDI file.
-Figured bass has no effect on MIDI.
projects / lilypond.git / blobdiff