4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
10 @node Technical manual
11 @chapter Technical manual
14 When LilyPond is run, it reads an input file which is parsed. During
15 parsing, Music objects are created. This music is interpreted, which
16 is done by contexts, that produce graphical objects. This section
17 discusses details of these three concepts, and how they are glued
18 together with the embedded Scheme interpreter.
21 * Interpretation context::
22 * Scheme integration::
23 * Music storage format::
29 @node Interpretation context
30 @section Interpretation context
35 * Context properties::
36 * Context evaluation::
38 * Engravers and performers::
39 * Defining new contexts::
43 Interpretation contexts are objects that only exist during program
44 run. During the interpretation phase (when @code{interpreting music}
45 is printed on the standard output), the music expression in a
46 @code{\score} block is interpreted in time order, the same order in
47 which we hear and play the music. During this phase, the interpretation
48 context holds the state for the current point within the music, for
51 @item What notes are playing at this point?
53 @item What symbols will be printed at this point?
55 @item What is the current key signature, time signature, point within
59 Contexts are grouped hierarchically: A @internalsref{Voice} context is
60 contained in a @internalsref{Staff} context (because a staff can contain
61 multiple voices at any point), a @internalsref{Staff} context is contained in
62 @internalsref{Score}, @internalsref{StaffGroup}, or
63 @internalsref{ChoirStaff} context.
65 Contexts associated with sheet music output are called @emph{notation
66 contexts}, those for sound output are called @emph{performance
67 contexts}. The default definitions of the standard notation and
68 performance contexts can be found in @file{ly/engraver-init.ly} and
69 @file{ly/performer-init.ly}, respectively.
72 @node Creating contexts
73 @subsection Creating contexts
74 @cindex @code{\context}
75 @cindex context selection
77 Contexts for a music expression can be selected manually, using one of
78 the following music expressions:
81 \new @var{contexttype} @var{musicexpr}
82 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
86 This means that @var{musicexpr} should be interpreted within a context
87 of type @var{contexttype} (with name @var{contextname} if specified).
88 If no such context exists, it will be created:
90 @lilypond[verbatim,singleline]
92 \notes \relative c'' {
93 c4 <<d4 \context Staff = "another" e4>> f
99 In this example, the @code{c} and @code{d} are printed on the default
100 staff. For the @code{e}, a context @code{Staff} called @code{another}
101 is specified; since that does not exist, a new context is created.
102 Within @code{another}, a (default) Voice context is created for the
103 @code{e4}. A context is ended when when all music referring it has
104 finished, so after the third quarter, @code{another} is removed.
106 The @code{\new} construction creates a context with a
107 generated, unique @var{contextname}. An expression with
108 @code{\new} always leads to a new context. This is convenient
109 for creating multiple staffs, multiple lyric lines, etc.
111 When using automatic staff changes, automatic phrasing, etc., the
112 context names have special meanings, so @code{\new} cannot be
116 @node Default contexts
117 @subsection Default contexts
119 Every top level music is interpreted by the @code{Score} context; in
120 other words, you may think of @code{\score} working like
124 \context Score @var{music}
128 Music expressions inherit their context from the enclosing music
129 expression. Hence, it is not necessary to explicitly specify
130 @code{\context} for most expressions. In
131 the following example, only the sequential expression has an explicit
132 context. The notes contained therein inherit the @code{goUp} context
133 from the enclosing music expression.
135 @lilypond[verbatim,singleline]
136 \notes \context Voice = goUp { c'4 d' e' }
140 Second, contexts are created automatically to be able to interpret the
141 music expressions. Consider the following example:
143 @lilypond[verbatim, singleline]
144 \score { \notes { c'4-( d' e'-) } }
148 The sequential music is interpreted by the Score context initially,
149 but when a note is encountered, contexts are setup to accept that
150 note. In this case, a @code{Thread}, @code{Voice}, and @code{Staff}
151 context are created. The rest of the sequential music is also
152 interpreted with the same @code{Thread}, @code{Voice}, and
153 @code{Staff} context, putting the notes on the same staff, in the same
156 @node Context properties
157 @subsection Context properties
159 Contexts have properties. These properties are set from the @file{.ly}
160 file using the following expression:
161 @cindex @code{\property}
162 @cindex context properties
163 @cindex properties, context
166 \property @var{contextname}.@var{propname} = @var{value}
170 Sets the @var{propname} property of the context @var{contextname} to
171 the specified Scheme expression @var{value}. Both @var{propname} and
172 @var{contextname} are strings, which can often be written unquoted.
175 Properties that are set in one context are inherited by all of the
176 contained contexts. This means that a property valid for the
177 @internalsref{Voice} context can be set in the @internalsref{Score} context
178 (for example) and thus take effect in all @internalsref{Voice} contexts.
180 @cindex @code{Current}
181 If you do not wish to specify the name of the context in the
182 @code{\property}-expression itself, you can refer to the abstract context
183 name, @code{Current}. The @code{Current} context is the latest
184 used context. This will typically mean the @internalsref{Thread} context,
185 but you can force another context with the
186 @code{\property}-command. Hence the expressions
189 \property @var{contextname}.@var{propname} = @var{value}
196 \context @var{contextname}
197 \property Current.@var{propname} = @var{value}
201 do the same thing. The main use for this is in predefined variables.
202 This construction allows the specification of a property-setting
203 without restriction to a specific context.
205 Properties can be unset using the following statement.
207 \property @var{contextname}.@var{propname} \unset
210 @cindex properties, unsetting
211 @cindex @code{\unset}
214 This removes the definition of @var{propname} in @var{contextname}. If
215 @var{propname} was not defined in @var{contextname} (but was inherited
216 from a higher context), then this has no effect.
220 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
221 the inverse of @code{\property \set}.
224 @node Context evaluation
225 @subsection Context evaluation
227 Contexts can be modified during interpretation with Scheme code. The
230 \applycontext @var{function}
233 @var{function} should be a Scheme function taking a single argument,
234 being the context to apply it to. The following code will print the
235 current bar number on the standard output during the compile:
240 (format #t "\nWe were called in barnumber ~a.\n"
241 (ly:get-context-property x 'currentBarNumber)))
246 @node Defining contexts
247 @subsection Defining contexts
249 @cindex context definition
250 @cindex translator definition
252 The most common way to create a new context definition is by extending
253 an existing one. An existing context from the paper block is copied
254 by referencing a context identifier:
259 @var{context-identifier}
265 Every predefined context has a standard identifier. For example, the
266 @code{Staff} context can be referred to as @code{\StaffContext}.
268 The context can then be modified by setting or changing properties,
273 Stem \set #'thickness = #2.0
274 defaultBarType = #"||"
277 These assignments happen before interpretation starts, so a @code{\property}
278 command will override any predefined settings.
284 It is not possible to collect multiple property assignments in a
285 variable, and apply to one @code{\translator} definition by
286 referencing that variable.
288 @node Engravers and performers
289 @subsection Engravers and performers
292 Each context is composed of a number of building blocks, or plug-ins
293 called engravers. An engraver is a specialized C++ class that is
294 compiled into the executable. Typically, an engraver is responsible
295 for one function: the @code{Slur_engraver} creates only @code{Slur}
296 objects, and the @code{Skip_event_swallow_translator} only swallows
297 (silently gobbles) @code{SkipEvent}s.
304 An existing context definition can be changed by adding or removing an
305 engraver. The syntax for these operations is
307 \consists @var{engravername}
308 \remove @var{engravername}
315 Here @var{engravername} is a string, the name of an engraver in the
316 system. In the following example, the @code{Clef_engraver} is removed
317 from the Staff context. The result is a staff without a clef, where
318 the central C is at its default position, the center line:
320 @lilypond[verbatim,singleline]
328 \remove Clef_engraver
334 A list of all engravers is in the internal documentation,
335 see @internalsref{All engravers}.
337 @node Defining new contexts
338 @subsection Defining new contexts
341 It is also possible to define new contexts from scratch. To do this,
342 you must define give the new context a name. In the following
343 example, a very simple Staff context is created: one that will put
344 note heads on a staff symbol.
348 \type "Engraver_group_engraver"
351 \consists "Staff_symbol_engraver"
352 \consists "Note_head_engraver"
353 \consistsend "Axis_group_engraver"
358 The argument of @code{\type} is the name for a special engraver that
359 handles cooperation between simple engravers such as
360 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
361 should always be @code{Engraver_group_engraver} (unless you are
362 defining a Score context from scratch, in which case
363 @code{Score_engraver} must be used).
365 The complete list of context modifiers is the following:
367 @item @code{\alias} @var{alternate-name}:
368 This specifies a different name. In the above example,
369 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s.
371 @item @code{\consistsend} @var{engravername}:
372 Analogous to @code{\consists}, but makes sure that
373 @var{engravername} is always added to the end of the list of
376 Engravers that group context objects into axis groups or alignments
377 need to be at the end of the list. @code{\consistsend} insures that
378 engravers stay at the end even if a user adds or removes engravers.
380 @item @code{\accepts} @var{contextname}:
381 This context can contains @var{contextname} contexts. The first
382 @code{\accepts} is created as a default context when events (e.g. notes
383 or rests) are encountered.
385 @item @code{\denies}:
386 The opposite of @code{\accepts}.
388 @item @code{\name} @var{contextname}:
389 This sets the type name of the context, e.g. @code{Staff},
390 @code{Voice}. If the name is not specified, the translator will not
395 @node Scheme integration
396 @section Scheme integration
400 @cindex Scheme, in-line code
401 @cindex accessing Scheme
402 @cindex evaluating Scheme
405 LilyPond internally uses GUILE, a Scheme-interpreter, to represent
406 data throughout the whole program, and glue together different program
407 modules. For advanced usage, it is sometimes necessary to access and
408 program the Scheme interpreter.
410 Scheme is a full-blown programming language, from the LISP
411 family. and a full discussion is outside the scope of this document.
412 Interested readers are referred to the website
413 @uref{http://www.schemers.org/} for more information on Scheme.
415 The GUILE library for extension is documented at
416 @uref{http://www.gnu.org/software/guile}.
418 When it is installed, the following link should take you to its manual
419 @ref{(guile.info)guile}
424 * Input variables and Scheme::
430 @subsection Inline Scheme
432 Scheme expressions can be entered in the input file by entering a
433 hash-sign (@code{#}). The expression following the hash-sign is
434 evaluated as Scheme. For example, the boolean value @var{true} is
435 @code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
436 and can be used in property assignments:
438 \property Staff.autoBeaming = ##f
442 @node Input variables and Scheme
443 @subsection Input variables and Scheme
446 The input format supports the notion of variable: in the following
447 example, a music expression is assigned to a variable with the name
450 traLaLa = \notes @{ c'4 d'4 @}
455 There is also a form of scoping: in the following example, the
456 @code{\paper} block also contains a @code{traLaLa} variable, which is
457 independent of the outer @code{\traLaLa}.
459 traLaLa = \notes @{ c'4 d'4 @}
460 \paper @{ traLaLa = 1.0 @}
463 In effect, each input file is a scope, and all @code{\header},
464 @code{\midi} and @code{\paper} blocks are scopes nested inside that
467 Both variables and scoping are implemented in the GUILE module system.
468 An anonymous Scheme module is attached to each scope. An assignment of
471 traLaLa = \notes @{ c'4 d'4 @}
475 is internally converted to a Scheme definition
477 (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
480 This means that input variables and Scheme variables may be freely
481 mixed. In the following example, a music fragment is stored in the
482 variable @code{traLaLa}, and duplicated using Scheme. The result is
483 imported in a @code{\score} by means of a second variable
486 traLaLa = \notes @{ c'4 d'4 @}
488 #(define newLa (map ly:music-deep-copy
489 (list traLaLa traLaLa)))
491 (make-sequential-music newLa))
496 In the above example, music expressions can be `exported' from the
497 input to the Scheme interpreter. The opposite is also possible. By
498 wrapping a Scheme value in the function @code{ly:export}, a Scheme
499 value is interpreted as if it were entered in LilyPond syntax: instead
500 of defining @code{\twice}, the example above could also have been
504 \score @{ #(ly:export (make-sequential-music newLa)) @}
511 @node Scheme datatypes
512 @subsection Scheme datatypes
514 Scheme is used to glue together different program modules. To aid this
515 glue function, many LilyPond specific object types can be passed as
518 The following list are all LilyPond specific types, that
519 can exist during parsing:
526 In C++ terms, an @code{Event} is a subtype of @code{Music}. However,
527 both have different functions in the syntax.
528 @item Music_output_def
535 During a run, transient objects are also created and destroyed.
538 @item Grob: short for `Graphical object'.
539 @item Scheme_hash_table
542 @item Molecule: Device-independent page output object,
543 including dimensions.
549 @item Translator: An object that produces audio objects or Grobs.
550 It may be accessed with @code{\applyoutput}.
552 @item Font_metric: An object representing a font.
555 Many functions are defined to manipulate these data structures. They
556 are all listed and documented in the internals manual, see
557 @internalsref{All scheme functions}.
561 @subsection Assignments
564 Variables allow objects to be assigned to names during the parse
565 stage. To assign a variable, use
567 @var{name}@code{=}@var{value}
569 To refer to a variable, precede its name with a backslash:
570 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
571 the input-types listed above. Variable assignments can appear at top
572 level in the LilyPond file, but also in @code{\paper} blocks.
574 A variable can be created with any string for its name, but for
575 accessing it in the LilyPond syntax, its name must consist of
576 alphabetic characters only, and may not be a keyword of the syntax.
577 There are no restrictions for naming and accessing variables in the
580 The right hand side of a variable assignment is parsed completely
581 before the assignment is done, so variables may be redefined in terms
582 of its old value, e.g.
588 When a variable is referenced in LilyPond syntax, the information it
589 points to is copied. For this reason, an variable reference must
590 always be the first item in a block.
595 \paperIdent % wrong and invalid
601 \paperIdent % correct
608 @node Music storage format
609 @section Music storage format
611 Music in LilyPond is entered as music expressions. This section
612 discusses different types of music expressions, and explains how
613 information is stored internally. This internal storage is accessible
614 through the Scheme interpreter, so music expressions may be
615 manipulated using Scheme functions.
618 * Music expressions::
619 * Internal music representation::
620 * Manipulating music expressions::
623 @node Music expressions
624 @subsection Music expressions
625 @cindex music expressions
627 Notes, rests, lyric syllables are music expressions. Small music
628 expressions may be combined to form larger ones, for example, by
629 enclosing a list of expressions in @code{\sequential @{ @}} or @code{<<
630 >>}. In the following example, a compound expression is formed out of
631 the quarter note @code{c} and a quarter note @code{d}:
634 \sequential @{ c4 d4 @}
637 @cindex Sequential music
638 @cindex @code{\sequential}
639 @cindex sequential music
642 @cindex Simultaneous music
643 @cindex @code{\simultaneous}
645 The two basic compound music expressions are simultaneous and
649 \sequential @code{@{} @var{musicexprlist} @code{@}}
650 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
653 For both, there is a shorthand:
656 @code{@{} @var{musicexprlist} @code{@}}
663 @code{<<} @var{musicexprlist} @code{>>}
667 for simultaneous music.
668 In principle, the way in which you nest sequential and simultaneous to
669 produce music is not relevant. In the following example, three chords
670 are expressed in two different ways:
672 @lilypond[fragment,verbatim,center,quote]
673 \notes \context Voice {
674 <<a c'>> <<b d'>> <<c' e'>>
675 << { a b c' } { c' d' e' } >>
678 However, using @code{<<} and @code{>>} for entering chords leads to
679 various peculiarities. For this reason, a special syntax
680 for chords was introduced in version 1.7: @code{< >}.
686 Other compound music expressions include:
689 \transpose @var{from} @var{to} @var{expr}
690 \apply @var{func} @var{expr}
691 \context @var{type} = @var{id} @var{expr}
692 \times @var{fraction} @var{expr}
695 @node Internal music representation
696 @subsection Internal music representation
703 When a music expression is parsed, it is converted into a set of
704 Scheme music objects. The defining property of a music object is that
705 it takes up time. Time is a rational number that measures the length
706 of a piece of music, in whole notes.
708 A music object has three kinds of types:
711 music name: Each music expression has a name, for example, a note
712 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
713 a @internalsref{SimultaneousMusic}. A list of all expressions
714 available is in the internals manual, under @internalsref{Music
718 `type' or interface: Each music name has several `types' or interface,
719 for example, a note is an @code{event}, but it is also a @code{note-event},
720 a @code{rhythmic-event} and a @code{melodic-event}.
722 All classes of music are listed in the internals manual, under
723 @internalsref{Music classes}.
725 C++ object: Each music object is represented by a C++ object. For technical
726 reasons, different music objects may be represented by different C++
727 object types. For example, a note is @code{Event} object, while
728 @code{\grace} creates a @code{Grace_music} object.
730 We expect that distinctions between different C++ types will disappear
734 The actual information of a music expression is stored in properties.
735 For example, a @internalsref{NoteEvent} has @code{pitch} and
736 @code{duration} properties that store the pitch and duration of that
737 note. A list of all properties available is in the internals manual,
738 under @internalsref{Music properties}.
740 A compound music expression is a music object that contains other
741 music objects in its properties. A list of objects can be stored in
742 the @code{elements} property of a music object, or a single `child'
743 music object in the @code{element} object. For example,
744 @internalsref{SequentialMusic} has its children in @code{elements},
745 and @internalsref{GraceMusic} has its single argument in
746 @code{element}. The body of a repeat is in @code{element} property of
747 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
749 @node Manipulating music expressions
750 @subsection Manipulating music expressions
752 Music objects and their properties can be accessed and manipulated
753 directly, through the @code{\apply} mechanism.
754 The syntax for @code{\apply} is
756 \apply #@var{func} @var{music}
760 This means that the scheme function @var{func} is called with
761 @var{music} as its argument. The return value of @var{func} is the
762 result of the entire expression. @var{func} may read and write music
763 properties using the functions @code{ly:get-mus-property} and
764 @code{ly:set-mus-property!}.
766 An example is a function that reverses the order of elements in
768 @lilypond[verbatim,singleline]
769 #(define (rev-music-1 m)
770 (ly:set-mus-property! m 'elements (reverse
771 (ly:get-mus-property m 'elements)))
773 \score { \notes \apply #rev-music-1 { c4 d4 } }
776 The use of such a function is very limited. The effect of this
777 function is void when applied to an argument which is does not have
778 multiple children. The following function application has no effect:
781 \apply #rev-music-1 \grace @{ c4 d4 @}
785 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
786 @code{elements}, only a single @code{element}. Every generally
787 applicable function for @code{\apply} must -- like music expressions
788 themselves -- be recursive.
790 The following example is such a recursive function: It first extracts
791 the @code{elements} of an expression, reverses them and puts them
792 back. Then it recurses, both on @code{elements} and @code{element}
795 #(define (reverse-music music)
796 (let* ((elements (ly:get-mus-property music 'elements))
797 (child (ly:get-mus-property music 'element))
798 (reversed (reverse elements)))
801 (ly:set-mus-property! music 'elements reversed)
804 (if (ly:music? child) (reverse-music child))
805 (map reverse-music reversed)
810 A slightly more elaborate example is in
811 @inputfileref{input/test,reverse-music.ly}.
813 Some of the input syntax is also implemented as recursive music
814 functions. For example, the syntax for polyphony
820 is actually implemented as a recursive function that replaces the
821 above by the internal equivalent of
823 << \context Voice = "1" @{ \voiceOne a @}
824 \context Voice = "2" @{ \voiceTwo b @} >>
827 Other applications of @code{\apply} are writing out repeats
828 automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
829 saving keystrokes (@inputfileref{input/test,music-box.ly}) and
831 LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
835 @file{scm/music-functions.scm}, @file{scm/music-types.scm},
836 @inputfileref{input/test,add-staccato.ly},
837 @inputfileref{input/test,unfold-all-repeats.ly}, and
838 @inputfileref{input/test,music-box.ly}.
840 @node Lexical details
841 @section Lexical details
847 Begins and ends with the @code{"} character. To include a @code{"}
848 character in a string write @code{\"}. Various other backslash
849 sequences have special interpretations as in the C language. A string
850 that contains no spaces can be written without the quotes. Strings can
851 be concatenated with the @code{+} operator.
855 @section Output details
857 LilyPond's default output format is @TeX{}. Using the option @option{-f}
858 (or @option{--format}) other output formats can be selected also, but
859 currently none of them work reliably.
861 At the beginning of the output file, various global parameters are defined.
862 It also contains a large @code{\special} call to define PostScript routines
863 to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
864 driver must be able to understand such embedded PostScript, or the output
865 will be rendered incompletely.
867 Then the file @file{lilyponddefs.tex} is loaded to define the macros used
868 in the code which follows. @file{lilyponddefs.tex} includes various other
869 files, partially depending on the global parameters.
871 Now the music is output system by system (a `system' consists of all
872 staves belonging together). From @TeX{}'s point of view, a system is an
873 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
874 vertically on the baseline of the text. Between systems,
875 @code{\interscoreline} is inserted vertically to have stretchable space.
876 The horizontal dimension of the @code{\hbox} is given by the
877 @code{linewidth} parameter from LilyPond's @code{\paper} block.
880 After the last system LilyPond emits a stronger variant of
881 @code{\interscoreline} only if the macro
882 @code{\lilypondpaperlastpagefill} is not defined (flushing the systems
883 to the top of the page). You can avoid that by setting the variable
884 @code{lastpagefill} in LilyPond's @code{\paper} block.
886 It is possible to fine-tune the vertical offset further by defining the
887 macro @code{\lilypondscoreshift}:
890 \def\lilypondscoreshift@{0.25\baselineskip@}
894 where @code{\baselineskip} is the distance from one text line to the next.
896 The code produced by LilyPond should be run through La@TeX{}, not
899 Here an example how to embed a small LilyPond file @code{foo.ly} into
900 running La@TeX{} text without using the @code{lilypond-book} script
901 (@pxref{lilypond-book manual}):
904 \documentclass@{article@}
906 \def\lilypondpaperlastpagefill@{@}
908 \def\lilypondscoreshift@{0.25\baselineskip@}
911 This is running text which includes an example music file
917 The file @file{foo.tex} has been simply produced with
923 It is important to set the @code{indent} parameter to zero in the
924 @code{\paper} block of @file{foo.ly}.
926 The call to @code{\lineskip} assures that there is enough vertical space
927 between the LilyPond box and the surrounding text lines.