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 the
78 following music expression.
81 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
85 This means that @var{musicexpr} should be interpreted within a context
86 of type @var{contexttype} (with name @var{contextname} if specified).
87 If no such context exists, it will be created.
89 @lilypond[verbatim,singleline]
91 \notes \relative c'' {
92 c4 <d4 \context Staff = "another" e4> f
98 In this example, the @code{c} and @code{d} are printed on the default
99 staff. For the @code{e}, a context @code{Staff} called @code{another}
100 is specified; since that does not exist, a new context is created.
101 Within @code{another}, a (default) Voice context is created for the
102 @code{e4}. A context is ended when when all music referring it has
103 finished, so after the third quarter, @code{another} is removed.
106 @node Default contexts
107 @subsection Default contexts
109 Every top level music is interpreted by the @code{Score} context; in
110 other words, you may think of @code{\score} working like
114 \context Score @var{music}
118 Music expressions inherit their context from the enclosing music
119 expression. Hence, it is not necessary to explicitly specify
120 @code{\context} for most expressions. In
121 the following example, only the sequential expression has an explicit
122 context. The notes contained therein inherit the @code{goUp} context
123 from the enclosing music expression.
125 @lilypond[verbatim,singleline]
126 \notes \context Voice = goUp { c'4 d' e' }
130 Second, contexts are created automatically to be able to interpret the
131 music expressions. Consider the following example.
133 @lilypond[verbatim, singleline]
134 \score { \notes { c'4-( d' e'-) } }
138 The sequential music is interpreted by the Score context initially,
139 but when a note is encountered, contexts are setup to accept that
140 note. In this case, a Thread, Voice, and Staff context are created.
141 The rest of the sequential music is also interpreted with the same
142 Thread, Voice, and Staff context, putting the notes on the same staff,
145 @node Context properties
146 @subsection Context properties
148 Contexts have properties. These properties are set from the @file{.ly}
149 file using the following expression:
150 @cindex @code{\property}
151 @cindex context properties
152 @cindex properties, context
155 \property @var{contextname}.@var{propname} = @var{value}
159 Sets the @var{propname} property of the context @var{contextname} to
160 the specified Scheme expression @var{value}. Both @var{propname} and
161 @var{contextname} are strings, which can often be written unquoted.
164 Properties that are set in one context are inherited by all of the
165 contained contexts. This means that a property valid for the
166 @internalsref{Voice} context can be set in the @internalsref{Score} context
167 (for example) and thus take effect in all @internalsref{Voice} contexts.
169 @cindex @code{Current}
170 If you do not wish to specify the name of the context in the
171 @code{\property}-expression itself, you can refer to the abstract context
172 name, @code{Current}. The @code{Current} context is the latest
173 used context. This will typically mean the @internalsref{Thread}
174 context, but you can force another context with the
175 @code{\property}-command. Hence the expressions
178 \property @var{contextname}.@var{propname} = @var{value}
185 \context @var{contextname}
186 \property Current.@var{propname} = @var{value}
190 do the same thing. The main use for this is in predefined variables.
191 This construction allows the specification of a property-setting
192 without restriction to a specific context.
194 Properties can be unset using the following statement.
196 \property @var{contextname}.@var{propname} \unset
199 @cindex properties, unsetting
200 @cindex @code{\unset}
203 This removes the definition of @var{propname} in @var{contextname}. If
204 @var{propname} was not defined in @var{contextname} (but was inherited
205 from a higher context), then this has no effect.
209 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
210 the inverse of @code{\property \set}.
213 @node Context evaluation
214 @subsection Context evaluation
216 Contexts can be modified during interpretation with Scheme code. The
219 \applycontext @var{function}
222 @var{function} should be a Scheme function taking a single argument,
223 being the context to apply it to. The following code will print the
224 current bar number on the standard output during the compile.
229 (format #t "\nWe were called in barnumber ~a.\n"
230 (ly:get-context-property x 'currentBarNumber)))
235 @node Defining contexts
236 @subsection Defining contexts
238 @cindex context definition
239 @cindex translator definition
241 The most common way to create a new context definition is by extending
242 an existing one. An existing context from the paper block is copied
243 by referencing a context identifier:
248 @var{context-identifier}
254 Every predefined context has a standard identifier. For example, the
255 @code{Staff} context can be referred to as @code{\StaffContext}.
257 The context can then be modified by setting or changing properties,
262 Stem \set #'thickness = #2.0
263 defaultBarType = #"||"
266 These assignments happen before interpretation starts, so a @code{\property}
267 command will override any predefined settings.
273 It is not possible to collect multiple property assignments in a
274 variable, and apply to one @code{\translator} definition by
275 referencing that variable.
277 @node Engravers and performers
278 @subsection Engravers and performers
281 Each context is composed of a number of building blocks, or plug-ins
282 called engravers. An engraver is a specialized C++ class that is
283 compiled into the executable. Typically, an engraver is responsible
284 for one function: the @code{Slur_engraver} creates only @code{Slur}
285 objects, and the @code{Skip_event_swallow_translator} only swallows
286 (silently gobbles) @code{SkipEvent}s.
293 An existing context definition can be changed by adding or removing an
294 engraver. The syntax for these operations is
296 \consists @var{engravername}
297 \remove @var{engravername}
304 Here @var{engravername} is a string, the name of an engraver in the
305 system. In the following example, the @code{Clef_engraver} is removed
306 from the Staff context. The result is a staff without a clef, where
307 the central C is at its default position, the center line.
309 @lilypond[verbatim,singleline]
317 \remove Clef_engraver
323 A list of all engravers is in the internal documentation,
324 see @internalsref{All engravers}.
326 @node Defining new contexts
327 @subsection Defining new contexts
330 It is also possible to define new contexts from scratch. To do this,
331 you must define give the new context a name. In the following
332 example, a very simple Staff context is created: one that will put
333 note heads on a staff symbol.
337 \type "Engraver_group_engraver"
340 \consists "Staff_symbol_engraver"
341 \consists "Note_head_engraver"
342 \consistsend "Axis_group_engraver"
347 The argument of @code{\type} is the name for a special engraver that
348 handles cooperation between simple engravers such as
349 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
350 should always be @code{Engraver_group_engraver} (unless you are
351 defining a Score context from scratch, in which case
352 @code{Score_engraver} must be used).
354 The complete list of context modifiers is as follows:
356 @item @code{\alias} @var{alternate-name}:
357 This specifies a different name. In the above example,
358 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
360 @item @code{\consistsend} @var{engravername}:
361 Analogous to @code{\consists}, but makes sure that
362 @var{engravername} is always added to the end of the list of
365 Engravers that group context objects into axis groups or alignments
366 need to be at the end of the list. @code{\consistsend} insures that
367 engravers stay at the end even if a user adds or removes engravers.
369 @item @code{\accepts} @var{contextname}:
370 This context can contains @var{contextname} contexts. The first
371 @code{\accepts} is created as a default context when events (eg. notes
372 or rests) are encountered.
374 @item @code{\denies}:
375 The opposite of @code{\accepts}.
377 @item @code{\name} @var{contextname}:
378 This sets the type name of the context, e.g. @code{Staff},
379 @code{Voice}. If the name is not specified, the translator will not
384 @node Scheme integration
385 @section Scheme integration
389 @cindex Scheme, in-line code
390 @cindex accessing Scheme
391 @cindex evaluating Scheme
394 LilyPond internally uses GUILE, a Scheme-interpreter, to represent
395 data throughout the whole program, and glue together different program
396 modules. For advanced usage, it is sometimes necessary to access and
397 program the Scheme interpreter.
399 Scheme is a full-blown programming language, from the LISP
400 family. and a full discussion is outside the scope of this document.
401 Interested readers are referred to the website
402 @uref{http://www.schemers.org/} for more information on Scheme.
404 The GUILE library for extension is documented at
405 @uref{http://www.gnu.org/software/guile}.
407 When it is installed, the following link should take you to its manual
408 @ref{(guile.info)guile}
413 * Input variables and Scheme::
419 @subsection Inline Scheme
421 Scheme expressions can be entered in the input file by entering a
422 hash-sign (@code{#}). The expression following the hash-sign is
423 evaluated as Scheme. For example, the boolean value @var{true} is
424 @code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
425 and can be used in property assignments:
427 \property Staff.autoBeaming = ##f
431 @node Input variables and Scheme
432 @subsection Input variables and Scheme
435 The input format supports the notion of variable: in the following
436 example, a music expression is assigned to a variable with the name
439 traLaLa = \notes @{ c'4 d'4 @}
444 There is also a form of scoping: in the following example, the
445 @code{\paper} block also contains a @code{traLaLa} variable, which is
446 independent of the outer @code{\traLaLa}.
448 traLaLa = \notes @{ c'4 d'4 @}
449 \paper @{ traLaLa = 1.0 @}
452 In effect, each input file is a scope, and all @code{\header},
453 @code{\midi} and @code{\paper} blocks are scopes nested inside that
456 Both variables and scoping are implemented in the GUILE module system.
457 An anonymous Scheme module is attached to each scope. An assignment of
460 traLaLa = \notes @{ c'4 d'4 @}
464 is internally converted to a Scheme definition
466 (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
469 This means that input variables and Scheme variables may be freely
470 mixed. In the following example, a music fragment is stored in the
471 variable @code{traLaLa}, and duplicated using Scheme. The result is
472 imported in a @code{\score} by means of a second variable
475 traLaLa = \notes @{ c'4 d'4 @}
477 #(define newLa (map ly:music-deep-copy
478 (list traLaLa traLaLa)))
480 (make-sequential-music newLa))
485 In the above example, music expressions can be `exported' from the
486 input to the Scheme interpreter. The opposite is also possible. By
487 wrapping a Scheme value in the function @code{ly:export}, a Scheme
488 value is interpreted as if it were entered in LilyPond syntax: instead
489 of defining @code{\twice}, the example above could also have been
493 \score @{ #(ly:export (make-sequential-music newLa)) @}
500 @node Scheme datatypes
501 @subsection Scheme datatypes
503 Scheme is used to glue together different program modules. To aid this
504 glue function, many lilypond specific object types can be passed as
507 The following list are all lilypond specific types, that
508 can exist during parsing:
515 In C++ terms, an @code{Event} is a subtype of @code{Music}. However,
516 both have different functions in the syntax.
517 @item Music_output_def
524 During a run, transient objects are also created and destroyed.
527 @item Grob: short for `Graphical object'.
528 @item Scheme_hash_table
531 @item Molecule: Device-independent page output object,
532 including dimensions.
538 @item Translator: An object that produces audio objects or Grobs.
539 It may be accessed with @code{\applyoutput}.
541 @item Font_metric: An object representing a font.
544 Many functions are defined to manipulate these data structures. They
545 are all listed and documented in the internals manual, see
546 @internalsref{All scheme functions}.
550 @subsection Assignments
553 Variables allow objects to be assigned to names during the parse
554 stage. To assign a variable, use
556 @var{name}@code{=}@var{value}
558 To refer to a variable, precede its name with a backslash:
559 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
560 the input-types listed above. Variable assignments can appear at top
561 level in the LilyPond file, but also in @code{\paper} blocks.
563 A variable can be created with any string for its name, but for
564 accessing it in the LilyPond syntax, its name must consist of
565 alphabetic characters only, and may not be a keyword of the syntax.
566 There are no restrictions for naming and accessing variables in the
569 The right hand side of a variable assignment is parsed completely
570 before the assignment is done, so variables may be redefined in terms
571 of its old value, e.g.
577 When a variable is referenced in LilyPond syntax, the information it
578 points to is copied. For this reason, an variable reference must
579 always be the first item in a block.
584 \paperIdent % wrong and invalid
590 \paperIdent % correct
597 @node Music storage format
598 @section Music storage format
600 Music in LilyPond is entered as music expressions. This section
601 discusses different types of music expressions, and explains
602 information is stored internally. This internal storage is accessible
603 through the Scheme interpreter, so music expressions may be
604 manipulated using Scheme functions.
607 * Music expressions::
608 * Internal music representation::
609 * Manipulating music expressions::
612 @node Music expressions
613 @subsection Music expressions
614 @cindex music expressions
616 Notes, rests, lyric syllables are music expressions. Small music
617 expressions may be combined to form larger ones, for example by
618 enclosing a list of expressions in @code{\sequential @{ @}} or @code{<
619 >}. In the following example, a compound expression is formed out of
620 the quarter note @code{c} and a quarter note @code{d}:
623 \sequential @{ c4 d4 @}
626 @cindex Sequential music
627 @cindex @code{\sequential}
628 @cindex sequential music
631 @cindex Simultaneous music
632 @cindex @code{\simultaneous}
634 The two basic compound music expressions are simultaneous and
638 \sequential @code{@{} @var{musicexprlist} @code{@}}
639 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
642 For both, there is a shorthand:
645 @code{@{} @var{musicexprlist} @code{@}}
652 @code{<} @var{musicexprlist} @code{>}
656 for simultaneous music.
657 In principle, the way in which you nest sequential and simultaneous to
658 produce music is not relevant. In the following example, three chords
659 are expressed in two different ways:
661 @lilypond[fragment,verbatim,center,quote]
662 \notes \context Voice {
663 <a c'> <b d'> <c' e'>
664 < { a b c' } { c' d' e' } >
667 However, using @code{<} and @code{>} for entering chords leads to
668 various peculiarities. For this reason, a special syntax
669 for chords was introduced in version 1.7: @code{<< >>}.
675 Other compound music expressions include
678 \transpose @var{from} @var{to} @var{expr}
679 \apply @var{func} @var{expr}
680 \context @var{type} = @var{id} @var{expr}
681 \times @var{fraction} @var{expr}
684 @node Internal music representation
685 @subsection Internal music representation
692 When a music expression is parsed, it is converted into a set of
693 Scheme music objects. The defining property of a music object is that
694 it takes up time. Time is a rational number that measures the length
695 of a piece of music, in whole notes.
697 A music object has three kinds of types
700 Music name: each music expression has a name, for example, a note
701 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
702 a @internalsref{SimultaneousMusic}. A list of all expressions
703 available is in the internals manual, under @internalsref{Music
707 Each music name has several `types' or interface. For example, a
708 note is an @code{event}, but it is also a @code{note-event}, a
709 @code{rhythmic-event} and a @code{melodic-event}.
711 All classes of music are listed in the internals manual, under
712 @internalsref{Music classes}.
714 Each music object is represented by a C++ object. For technical
715 reasons, different music objects may be represented by different C++
716 object types. For example, a note is @code{Event} object, while
717 @code{\grace} creates a @code{Grace_music} object.
719 We expect that distinctions between different C++ types will disappear
723 The actual information of a music expression is stored in properties.
724 For example, a @internalsref{NoteEvent} has @code{pitch} and
725 @code{duration} properties that store the pitch and duration of that
726 note. A list of all properties available is in the internals manual,
727 under @internalsref{Music properties}.
729 A compound music expresssion is a music object that contains other
730 music objects in its properties. A list of objects can be stored in
731 the @code{elements} property of a music object, or a single `child'
732 music object is stored in the @code{element} object. For example,
733 @internalsref{SequentialMusic} has its children in @code{elements},
734 and @internalsref{GraceMusic} has its single argument in
735 @code{element}. The body of a repeat is in @code{element} property of
736 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
738 @node Manipulating music expressions
739 @subsection Manipulating music expressions
741 Music objects and their properties can be accessed and manipulated
742 directly, through the @code{\apply} mechanism. Scheme functions can
743 read and write properties using the functions
744 @code{ly:get-music-property} and @code{ly:set-music-property!}.
746 The syntax for @code{\apply}
748 \apply #@var{func} @var{music}
752 This means that the scheme function @var{func} is called with
753 @var{music} as its argument. The return value of @var{func} is the
754 result of the entire expresssion.
756 An example is a function that reverses the order of elements in
759 #(define (rev-music-1 m)
760 (ly:set-music-property! 'elements (reverse
761 (ly:get-music-property mus 'elements)))
763 \apply #rev-music-1 @{ c4 d4 @}
766 The use of such a function is very limited. The effect of this
767 function is void, when it is applied to an argument which is does not
768 have multiple children, for example
771 \apply #rev-music-1 \grace @{ c4 d4 @}
775 does not do anything: @code{\grace} is stored as
776 @internalsref{GraceMusic}, which has no @code{elements}, only a single
777 @code{element}. Every generally applicable function for @code{\apply}
778 must --like music expressions themselves-- be recursive.
780 The following example is such a recursive function: it first extracts
781 the @code{elements} of an expression, reverses them and puts them
782 back. Then it recurses, both on @code{elements} and @code{element}
785 #(define (reverse-music music)
786 (let* ((elements (ly:get-mus-property music 'elements))
787 (child (ly:get-mus-property music 'element))
788 (reversed (reverse elements)))
791 (ly:set-mus-property! music 'elements reversed)
794 (if (ly:music? child) (reverse-music child))
795 (map reverse-music reversed)
800 A slightly more elaborate example is in
801 @inputfileref{input/test,reverse-music.ly}.
803 Some of the input syntax is also implemented as recursive music
804 functions. For example, the syntax for polyphony
810 is actually implemented as a recursive function that replaces the
811 above by the internal equivalent of
813 < \context Voice = "1" @{ \voiceOne a @}
814 \context Voice = "2" @{ \voiceTwo a @} >
817 Other applications of @code{\apply} are writing out repeats
818 automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
819 saving keystrokes (@inputfileref{input/test,music-box.ly}) and
821 LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
825 @file{scm/music-functions.scm}, @file{scm/music-types.scm},
826 @inputfileref{input/test,add-staccato.ly},
827 @inputfileref{input/test,duration-check.ly}.
828 @inputfileref{input/test,unfold-all-repeats.ly},
829 @inputfileref{input/test,music-box.ly}.
831 @node Lexical details
832 @section Lexical details
843 Begins and ends with the @code{"} character. To include a @code{"}
844 character in a string write @code{\"}. Various other backslash
845 sequences have special interpretations as in the C language. A string
846 that contains no spaces can be written without the quotes. Strings can
847 be concatenated with the @code{+} operator.
852 @section Output details
854 LilyPond's default output format is @TeX{}. Using the option @option{-f}
855 (or @option{--format}) other output formats can be selected also, but
856 currently none of them work reliably.
858 At the beginning of the output file, various global parameters are defined.
859 It also contains a large @code{\special} call to define PostScript routines
860 to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
861 driver must be able to understand such embedded PostScript, or the output
862 will be rendered incompletely.
864 Then the file @file{lilyponddefs.tex} is loaded to define the macros used
865 in the code which follows. @file{lilyponddefs.tex} includes various other
866 files, partially depending on the global parameters.
868 Now the music is output system by system (a `system' consists of all
869 staves belonging together). From @TeX{}'s point of view, a system is an
870 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
871 vertically on the baseline of the text. Between systems,
872 @code{\interscoreline} is inserted vertically to have stretchable space.
873 The horizontal dimension of the @code{\hbox} is given by the
874 @code{linewidth} parameter from LilyPond's @code{\paper} block.
877 After the last system LilyPond emits a stronger variant of
878 @code{\interscoreline} only if the macro
879 @code{\lilypondpaperlastpagefill} is not defined (flushing the systems
880 to the top of the page). You can avoid that by setting the variable
881 @code{lastpagefill} in LilyPond's @code{\paper} block.
883 It is possible to fine-tune the vertical offset further by defining the
884 macro @code{\lilypondscoreshift}. Example:
887 \def\lilypondscoreshift@{0.25\baselineskip@}
891 @code{\baselineskip} is the distance from one text line to the next.
893 The code produced by LilyPond should be run through La@TeX{}, not
896 Here an example how to embed a small LilyPond file @code{foo.ly} into
897 running La@TeX{} text without using the @code{lilypond-book} script
898 (@pxref{lilypond-book manual}).
901 \documentclass@{article@}
903 \def\lilypondpaperlastpagefill@{@}
905 \def\lilypondscoreshift@{0.25\baselineskip@}
908 This is running text which includes an example music file
914 The file @file{foo.tex} has been simply produced with
920 It is important to set the @code{indent} parameter to zero in the
921 @code{\paper} block of @file{foo.ly}.
923 The call to @code{\lineskip} assures that there is enough vertical space
924 between the LilyPond box and the surrounding text lines.