Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@c \version "2.19.2"
@node General input and output
@chapter General input and output
@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
-@funindex \pushToTag
-@funindex \appendToTag
@cindex tag
@cindex keep tagged music
@cindex remove tagged music
-@cindex splice into tagged music
The @code{\tag #'@var{partA}} command marks a music expression
with the name @var{partA}.
Tagged music preceded by @code{\keepWithTag #'@var{name}} or
@code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
@tab Untagged music and music tagged with any of the given tag
- names is included;
+ names is included;
music tagged with any other tag name is excluded.
@item
Tagged music preceded by @code{\removeWithTag #'@var{name}} or
@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.
+@code{\removeWithTag} commands should be a symbol or list of
+symbols (such as @code{#'score} or @code{#'(violinI violinII}),
+followed by a music expression. If @emph{and only if} the symbols
+are valid LilyPond identifiers (alphabetic characters only, no
+numbers, underscores, or dashes) which cannot be confused with notes,
+the @code{#'} may be omitted and, as a shorthand, a list of symbols
+can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can
+be written @code{\tag violinI.violinII}. The same applies to
+@code{\keepWithTag} and @code{\removeWithTag}.
In the following example, we see two versions of a piece of music,
one showing trills with the usual notation, and one with trills
command with a list of multiple tags: this will only remove tagged
sections not given in @emph{any} of the tags.
+@cindex tag groups
+@funindex \tagGroup
+While @code{\keepWithTag} is convenient when dealing with
+@emph{one} set of alternatives, the removal of music tagged with
+@emph{unrelated} tags is problematic when using tags for more than
+one purpose. For that reason, @q{tag groups} of related tags can
+be declared:
+
+@example
+\tagGroup #'(violinI violinII viola cello)
+@end example
+
+declares the respective tags as belonging to one tag group.
+
+@example
+\keepWithTag #'violinI @dots{}
+@end example
+
+will then only be concerned with tags from @code{violinI}'s tag
+group: any element of the included music that is tagged with one
+or more of tags from this set but @emph{not} with @code{violinI}
+will get removed.
+
+To any @code{\keepWithTag} command, only tags from the tag groups
+of the tags given in the command are visible.
+
+Tags cannot be members of more than one tag group.
+
+@funindex \pushToTag
+@funindex \appendToTag
+@cindex splice into tagged music
+
Sometimes you want to splice some music at a particular place in an
existing music expression. You can use @code{\pushToTag} and
@code{\appendToTag} for adding material at the front or end of the
@end lilypond
Both commands get a tag, the material to splice in at every occurence of
-the tag, and the tagged expression. The commands make sure to
-copy everything that they change so that the original @code{\test}
-retains its meaning.
+the tag, and the tagged expression.
@seealso
Learning Manual:
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2014" \char ##x00A9 }
+\markup { "Copyright 2008--2015" \char ##x00A9 }
@end lilypond
@cindex copyright sign
* Replacing the notation font::
@end menu
+@funindex clip-regions
+@cindex Fragments, music
+@cindex Music fragments
+
@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
-with scissors.
-
-This is done by defining the measures that need to be cut out
-separately. For example, including the following definition
-
+It is possible to output one or more fragments of a score by defining
+the explicit location of the music to be extracted within the
+@code{\layout} block of the the input file using the @code{clip-regions}
+function, and then running LilyPond with the @option{-dclip-systems}
+option;
-@verbatim
-\layout {
+@example
+\layout @{
clip-regions
= #(list
(cons
(make-rhythmic-location 5 1 2)
(make-rhythmic-location 7 3 4)))
-}
-@end verbatim
+@}
+@end example
@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.
+This example will extract a single fragment of the input file
+@emph{starting} after a half-note duration in fifth measure
+(@code{5 1 2}) and @emph{ending} after three, quarter notes in the
+seventh measure (@code{7 3 4}).
+
+Additional fragments can be extracted by adding more pairs of
+@code{make-rhythmic-location} entries to the @code{clip-regions} list in
+the @code{\layout} block.
+
+By default, each music fragment will be output as a separate @code{EPS}
+file, but other formats such as @code{PDF} or @code{PNG} can also be
+created if required. The extracted music is output as if had been
+literally @q{cut} from the original printed score so if a fragment runs
+over one or more lines, a separate ouput file for each line will be
+generated.
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+@seealso
+Notation Reference:
+@ref{The layout block}.
+
+Application Usage
+@rprogram{Command-line usage}.
-In order to use this feature, LilyPond must be invoked with
-@option{-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}.
@node Skipping corrected music
@subsection Skipping corrected music
@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.
+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.
+that are off or accidentals that were mistyped stand out very much when
+listening to the MIDI output.
Standard MIDI output is somewhat crude; optionally, an enhanced and
more realistic MIDI output is available by means of
specified within the music notation will be reflected in the MIDI
output.
-Usually it is enough to leave the @code{\midi} block empty, but it
-can contain context rearrangements, new context definitions or code
-to set the values of properties. Here the tempo is set to 72
-quarter-note beats per minute, but @emph{only} for the MIDI's
-audio playback.
+Usually it is enough to leave the @code{\midi} block empty, but it can
+contain context rearrangements, new context definitions or code to set
+the values of properties. Here the tempo is set to 72 quarter-note
+beats per minute, but @emph{only} for the MIDI's audio playback.
@example
\score @{
@end example
Note that @code{\tempo} is actually a command for setting properties
-during the interpretation of the music and in the context of output definitions, like a @code{\midi} block, is reinterpreted as if it
-were a context modification.
+during the interpretation of the music and in the context of output
+definitions, like a @code{\midi} block, is reinterpreted as if it were a
+context modification.
@cindex MIDI context definitions
removes the effect of dynamics from the MIDI output. Translation
modules for sound are called @q{performers}.
-
@snippets
-
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{changing-midi-output-to-one-channel-per-voice.ly}
-@knownissues
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/performer-init.ly}.
+
+Snippets:
+@rlsr{MIDI}.
-Some operating systems require a @emph{specific} file extension for
-MIDI files. If a different extension is preferred insert the following
-line at the top-level of the input file, before the start of any
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+@knownissues
+Some operating systems require a @emph{specific} file extension for MIDI
+files. If a different extension is preferred insert the following line
+at the top-level of the input file, before the start of any
@code{\book}, @code{\bookpart} or @code{\score} blocks;
@example
Some MIDI players may not always correctly handle tempo changes in the
midi output.
-@seealso
-Installed Files:
-@file{../ly/performer-init.ly}.
-
-Learning Manual:
-@rlearning{Other sources of information}.
+Changes to @code{midiInstrument} (and other MIDI options) at the
+beginning of a staff may appear twice in the MIDI output.
@node MIDI Instruments
@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}.
+@code{Staff.midiInstrument} property to the instrument name. The name
+should be chosen from the list in @ref{MIDI instruments}.
@example
\new Staff @{
the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
instrument is used.
+@seealso
+Notation Reference:
+@ref{MIDI instruments}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
@node What goes into the MIDI output?
@subsection What goes into the MIDI output?
@item Rallentando, accelerando, ritard, and a tempo
@end itemize
+@seealso
+Notation Reference:
+@ref{Accidentals},
+@ref{Breath marks},
+@ref{Expressive marks}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
@node Unsupported in MIDI
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
-The following items of notation have no effect on the MIDI output,
-even if you use @ref{The Articulate script}:
+The following items of notation have no effect on the MIDI output, even
+if you use @ref{The Articulate script}:
@itemize
@item Rhythms entered as annotations, e.g. swing
@item Glissandi, falls and doits
@end itemize
+@seealso
+Installed Files:
+@file{ly/articulate.ly}.
+
@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.
+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 {
output will only occur correctly if @emph{each} voice contains fully
notated repeat indications.
-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,
+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):
@example
\score @{
@}
@end example
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
+
@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.
+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.
@menu
* Dynamic marks::
@node Dynamic marks
@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
+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}.
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.
+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 @code{rfz} is found, or calls the default function
+otherwise.
@lilypond[verbatim,quote]
#(define (myDynamics dynamic)
}
@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.
+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.
+@seealso
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
+
+Installed Files:
+@file{scm/midi.scm}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
+
@node Overall MIDI volume
@unnumberedsubsubsec Overall MIDI volume
\set Staff.midiInstrument = #"flute"
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
+
@node Equalizing different instruments (i)
@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.
+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.
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
@lilypond[verbatim,quote]
\score {
\set Staff.midiMaximumVolume = #0.9
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
@node Equalizing different instruments (ii)
@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}.
+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.
+@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 Staff.midiInstrument = #"flute"
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
}
@end lilypond
+@seealso
+Installed Files:
+@file{scm/midi.scm}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
@ignore
@c Delete when satisfied this is adequately covered elsewhere -td
@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.
+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.
+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.
+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
+@seealso
+Notation Reference:
+@ref{Percussion},
+@ref{Score layout}.
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+@knownissues
Because the general MIDI standard does not contain rim shots, the
sidestick is used for this purpose instead.
+
+
@node The Articulate script
@subsection The Articulate script
A more realistic MIDI output is possible when using the Articulate
script. It tries to take articulations (slurs, staccato, etc) into
account, by replacing notes with sequential music of suitably
-time-scaled note plus skip. It also tries to unfold trills turns
-etc., and take rallentando and accelerando into account.
+time-scaled note plus skip. It also tries to unfold trills turns etc.,
+and take rallentando and accelerando into account.
-To use the Articulate script, you have to include it at the top of
-your input file,
+To use the Articulate script, you have to include it at the top of your
+input file,
@example
\include "articulate.ly"
@example
\unfoldRepeats \articulate <<
- all the rest of the score@dots{}
+ all the rest of the score@dots{}
>>
@end example
example shown above as it enables performing abbreviatures such as
@notation{trills}.
-@knownissues
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+Internals Reference:
+@rinternals{UnfoldedRepeatedMusic}.
+
+@knownissues
Articulate shortens chords and some music (esp. organ music) could
sound worse.
projects / lilypond.git / blobdiff