1 \input texinfo @c -*-texinfo-*-
3 @setfilename orchestrallily.info
4 @settitle The OrchestralLily package for Lilypond
8 @documentencoding UTF-8
23 @c *******************************************************
24 @c ** COPYRIGHT INFORMATION **
25 @c *******************************************************
28 This is the documentation of the OrchestralLily package for Lilypond, the GNU music
29 typesetting application.
31 Copyright @copyright{} 2008 @uref{http://reinhold.kainhofer.com,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
35 @c *******************************************************
37 @c *******************************************************
41 @subtitle A Lilypond package for orchestral scores.
42 @author @uref{http://reinhold.kainhofer.com,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
44 @c The following two commands start the copyright page.
46 @vskip 0pt plus 1filll
48 @setcontentsaftertitlepage
51 @c Output the table of contents at the beginning.
56 @c *******************************************************
58 @c *******************************************************
62 @top The OrchestralLily Package
65 @item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
66 @item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
67 @item @b{Date}: June 2008
68 @item @b{Download}: @uref{http://wiki.kainhofer.com/_media/lilypond/orchestrallily.ly,orchestrallily.ly, (Version 0.03@comma{} 2008-06-24)}, licensed under the GPL v3.0
69 @item @b{Development version}:
71 @item Web-Frontend: @uref{http://repo.or.cz/w/orchestrallily.git}
72 @item read-only git URL: git://repo.or.cz/orchestrallily.git (use git clone URL)
74 @item @b{Documentation}: @uref{index.html,HTML (one page per section)}, @uref{orchestrallily-bigpage.html,HTML (Single page)}, @uref{orchestrallily.pdf,PDF}
77 @comment @end ifnottex
80 @comment * About OrchestralLily and Download::
84 * Structure of a score::
85 * What OrchestralLily does::
88 * Settings defined by OrchestralLily::
89 * Available functions::
90 * Extending OrchestralLily::
91 * Frequently asked questions::
93 * Known limitations and missing features::
95 * OrchestralLily index::
99 @c *******************************************************
101 @c *******************************************************
103 @comment @node About OrchestralLily and Download
104 @comment @chapter About OrchestralLily and Download
107 @comment @comment @comment @item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
108 @comment @item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
109 @comment @item @b{Date}: February 2008
110 @comment @item @b{Download}: @uref{http://wiki.kainhofer.com/_media/lilypond/orchestrallily.ly,orchestrallily.ly, (Version 0.02@comma{} 2008-03-06)}, licensed under the GPL v3.0
111 @comment @end itemize
117 Orchestral scores might have a quite complicated structure, which is cumbersome to construct manually, in particular since each movement will have the same structure. The OrchestralLily package for @uref{http://www.lilypond.org/,Lilypond} aids you by adding some more magic to lilypond's already existing magic: You only define the structure of the whole piece once, you define the music that each instrument plays in each movement, and lilypond will do the rest. In particular, OrchestralLily will
119 @item generate appropriate staves and staff groups
120 @item collate them in the proper (defined) order
121 @item add correct instrument names (if defined by the user)
122 @item add movement titles (if defined)
123 @item add a header "Movement name tacet" in an instrumental score for each movement where the instrument rests
124 @item add correct clefs, keys, time sigatures, transpositions and other settings to each staff (if defined by the user)
127 This way, generating full scores, scores for individual instruments and for instrument groups are really simple and no additional manual work!
130 As you can imagine, if you have lots of parts and lots of instruments, the number of similar staves/scores simply multiply (e.g. for 12 parts with 23 instruments, you'll have 12*23=276 individual staves, not counting any staff groups!). If you also want to include cue notes into the instrumental scores, you'll define a separate staff or score for the full score, where you call killCues. Thus the number will automatically double!
132 As they all look really similar, why not automate their creation instead of manually writing them? That is exactly where OrchestralLily comes in.
136 @chapter A simple example
138 Assume you have a piece called "Dada" with soprano solo (including lyrics) and violoncello. You might want to create a score for soprano only, one for cello one, one including both, a cello score including soprano (but in smaller size), etc.
140 We will call the soprano staff @code{SSolo} and the cello staff @code{Vc}. First, we need to define the music and lyrics for each, as well as the score structure. These will go into one file, say @code{dada-defs.ly}:
142 @verbatiminclude dada-defs.ly
145 For each scores (full score, instrumental score, etc.), we write one additional file to generate the score.
148 Notice that all variables have a similar structure: First comes "Dada", then the instrument name ("SSolo" or "Vc"), and finally an indicator ("Settings", "Clef", "Music", "Lyrics", ...). For some of the variables, the instrument or the piece name is left out (This is only important for works with multiple pieces / movements, where you want one variable used in multiple pieces). Also notice that in the full score we have also added a "Percussion" instrument, but haven't defined any music for it (because e.g. it will only play in the second movement, which we haven't written yet). OrchestralLily will then simply ignore this instrument in the "Dada" part of the work.
150 Finally, the call @code{\orchestralScoreStructure} defines a FullScore and an InvertedScore with SSolo and Vc as children. This call tells OrchestralLily how the structure of your score looks like.
152 The above definitions are all that is needed by OrchestralLily to generate all various kinds of scores!
154 @lilypond[quote,verbatim,staffsize=14,line-width=8.0\cm]
156 \include "dada-defs.ly"
159 \createScore #"Dada" #'("SSolo")
162 \createScore #"Dada" #'("Vc")
164 % the percussion score, no notes defined -> Tacet
165 \createScore #"Dada" #'("Percussion")
168 \createScore #"Dada" #'("FullScore")
171 The actual score creation is done with a call to @code{\createScore}, with the part name ("Dada" in our case) as the first argument and a list of instrument / staff group identifiers as second argument.
175 Now, suppose we want to generate a score for Vc, including the soprano staff in smaller size. This is also really simple in OrchestralLily:
177 @lilypond[quote,verbatim]
179 \include "dada-defs.ly"
181 \header { instrument = \VcInstrumentName }
183 % For the SSolo staff, use a smaller staff size!
184 DadaSSoloSettings = {
187 \override Staff.StaffSymbol #'staff-space = #(magstep -4)
190 \createScore #"Dada" #'("InvertedScore")
194 In full scores, the violoncello and contrabass staff is typically shown with a bracket (StaffGroup) of their own, and the solo staves are shown without any bracket. To achieve this, all you have to do is to define the correct score structure (including a VcB staff group, consisting only of the Vc staff):
196 @lilypond[quote,verbatim]
198 \include "dada-defs.ly"
200 \orchestralScoreStructure #'(
201 ("VcB" StaffGroup ("Vc"))
202 ("FullScore" ParallelMusic ("Percussion" "SSolo" "VcB"))
205 \createScore #"Dada" #'("FullScore")
209 Although it was not explicitly shown in this simple example, OrchestralLily of course supports also nested staff groups.
211 @node Extended example
212 @chapter Extended example: Multiple pieces
214 The whole power of OrchestralLily, however, becomes unleashed only for pieces with multiple movements/sub-parts. Let us now add a second song "Didi", with only Timpani and Soprano Solo, as well as a third song "Dodo" with all instruments playing. For this, we have to add the corresponding music to the definitions file @b{dadafull-defs.ly}, which becomes:
217 @verbatiminclude dadafull-defs.ly
220 After these definitions, we can easily generate individual instrumental scores, as well as a full score:
221 @lilypond[quote,verbatim]
223 \include "dadafull-defs.ly"
225 \header { instrument = \TimInstrumentName }
227 \createScore #"Dada" #'("Tim")
228 \createScore #"Didi" #'("Tim")
229 \createScore #"Dodo" #'("Tim")
232 @lilypond[quote,verbatim]
234 \include "dadafull-defs.ly"
236 \header { instrument = \SSoloInstrumentName }
238 \createScore #"Dada" #'("SSolo")
239 \createScore #"Didi" #'("SSolo")
240 \createScore #"Dodo" #'("SSolo")
243 @lilypond[quote,verbatim]
245 \include "dadafull-defs.ly"
247 \header { instrument = \VcInstrumentName }
249 \createScore #"Dada" #'("Vc")
250 \createScore #"Didi" #'("Vc")
251 \createScore #"Dodo" #'("Vc")
254 @lilypond[quote,verbatim]
256 \include "dadafull-defs.ly"
258 \createScore #"Dada" #'("FullScore")
259 \createScore #"Didi" #'("FullScore")
260 \createScore #"Dodo" #'("FullScore")
265 @node Structure of a score
266 @chapter Structure of a score, naming staff groups
269 @image{score_structure,,,A typical score hierarchy}
271 A full score typically consists of several levels of staves and staff groupings, which can also be understood as a hierarchy of staves. We will assign each level in this hierarchy an identifier (written in red in the example). For example, the score on the left has the tree:
273 @item "FullScore" (parallel staves/groups)
275 @item "Woodwinds" (staff group)
277 @item "Fl" (staff with two voices)
278 @item "Ob" (staff with two voices)
280 @item "Strings" (staff group)
282 @item "Violins" (grand staff)
284 @item "VI" (simple staff)
285 @item "VII" (simple staff)
287 @item "Va" (simple staff)
289 @item "Vocal" (parallel staves/groups)
291 @item "Solo" (parallel staves)
293 @item "SSolo" (simple staff)
294 @item "TSolo" (simple staff)
296 @item "Choir" (choir staff)
298 @item "S" (simple staff)
299 @item "A" (simple staff)
300 @item "T" (simple staff)
301 @item "B" (simple staff)
304 @item "VcB" (staff group)
306 @item "Vc" (simple staff)
310 So, the "FullScore" consists of parallel music of the following staves/groups: "Woodwinds", "Strings", "Vocal" and "VcB".
311 Similarly, "Choir" is a ChoirStaff and consists of the individual staves "S", "A", "T" and "B". To be able to generate such a score automatically, lilypond needs to know the structure of the tree. For this, it suffices to know the type and all children of each group, e.g. which staves/groups are direct children of "FullScore", which of "Vocal", etc. No information about the individual staves is needed yet.
314 * Hierarchies in OrchestralLily::
315 * Different staff types::
316 * Different voice types::
317 * Why giving each level a name::
320 @node Hierarchies in OrchestralLily
321 @section How to define this hierarchy in OrchestralLily
323 This structure can be easily defined in OrchestralLily by calling @code{\orchestral-score-structure} with a simple list describing the hierarchy:
325 \orchestral-score-structure #'(
326 ("FullScore" "SimultaneousMusic" ("Woodwinds" "Strings" "Vocal" "VcB"))
327 ("Woodwinds" "StaffGroup" ("Fl" "Ob"))
328 ("Fl" "PartCombinedStaff" ("FlI" "FlII"))
329 ("Ob" "PartCombinedStaff" ("ObI" "ObII"))
330 ("Strings" "StaffGroup" ("Violins" "Va"))
331 ("Violins" "GrandStaff" ("VI" "VII"))
332 ("Vocal" "SimultaneousMusic" ("Solo" "Choir"))
333 ("Solo" "SimultaneousMusic" ("SSolo" "TSolo"))
334 ("Choir" "ChoirStaff" ("S" "A" "T" "B"))
335 ("VcB" "StaffGroup" ("Vc"))
337 ("Percussion" "RhythmicStaff" ())
340 Please note the apostrophe before the list! There are no apostrophes needed in front of the staff group types (because the whole is list is already quoted!).
342 Each entry of the list describes one grouping of staves or voices and has three possible forms:
344 ; Staff group of given type
345 ("StaffID" "StaffGroupType" ("List" "of" "child" "identifiers"))
346 ; Staves connected without a bracket
347 ("StaffID" "SimultaneousMusic"|"ParallelMusic" ("List" "children" ))
348 ; One staff with multiple voices
349 ("StaffID" "ParallelVoicesStaff" ("List" "of" "voices"))
350 ; Staff with two part-combined voices
351 ("StaffID" "PartCombinedStaff" ("Two" "voices"))@c
352 ; Non-default staff type
353 ("StaffID" "StaffType" ())
354 ("StaffID" "StaffType" ("ChildVoiceName"))
356 The first entry creates a staff group of type @code{StaffGroupType} (e.g. @code{StaffGroup}, @code{GrandStaff}, @code{PianoStaff}, @code{ChoirStaff}), the second one (i.e. giving either "SimultaneousMusic" or "ParallelMusic" as staff type) creates parallel staves connected by a simple line, but no bracket. In lilypond syntax, this is equivalent to @code{<< Staff1 Staff2 >>}.
357 The third and fourth forms are not really staff groups, but staves containing multiple voices. The third one with #f as staff type generates a staff with multiple voices (@code{\voiceOne}, @code{\voiceTwo}, etc.), possibly with lyrics, while the fourth one with #t (for combined=##t) as staff type staff with two part-combined voices (e.g. Flute 1 and Flute 2 combined in one staff for Flute). Internally, @code{\partcombine} is used for this (with all its limitations!).
359 If an identifier from the list of child identifiers is not defined in that hierarchy list, it is assumed to be a simple staff.
361 @node Different staff types
362 @section Different staff types
364 Lilypond supports more types than just ordinary staves: DrumStaff, FiguredBass, etc.
365 In OrchestralLily, the type of a staff (e.g. DrumStaff, RhythmicStaff, etc.) can
366 also be defined directly in the score structure by an entry like
368 ; Non-default staff type
369 ("StaffID" "StaffType" ())
370 ("StaffID" "StaffType" ("ChildVoiceName"))
373 If "ChildVoiceName" is given, it is used as voice name (in particular, the music
374 is extracted from [Piece]ChildVoiceNameMusic), otherwise, the ID of the staff
375 is also taken for the Voice (the music is extracted from [Piece]StaffIDMusic).
377 @node Different voice types
378 @section Different voice types
380 Some staves and some music definitions need different contexts than Voice, which
381 is used by default. For example, music defined with @code{\\drummode} needs to
382 be inside a @code{DrumVoice}, @code{\figuremode} inside @code{FiguredBass}, etc.
384 To set the type of context used for a voice in Orchestrallily, simply call
385 @code{\orchestralVoiceTypes} with an association list defining the voice type
386 for each voice ID. For example:
388 \orchestralVoiceTypes #'(
390 ("Iix" "FiguredBass")
396 @node Why giving each level a name
397 @section The advantage of giving each level a name
399 One of the advantages of assigning each group a name is that you can now tell OrchestralLily to generate e.g. a vocal score (containing only the "Vocal" staff group). Whether you want to generate an individual instrumental score, a full score, or a score for a group of instruments, is then no difference to OrchestralLily: You simply tell OrchestralLily to generate the score for a given identifier, and you will end up with the correct PDF. If you tell OrchestralLily to build the "FullScore" score, you'll get a score with the group named "FullScore" (which happens to be the full score), if you tell it to build "Fl", you'll get a score with just one staff, namely the one for the flutes. Similarly, to generate a pure choral score, simply tell OrchestralLily to build the score for the "Choir" group.
402 @node What OrchestralLily does
403 @chapter What OrchestralLily does
406 * How a score is generated::
407 * How a staff is generated::
408 * How a staff group is generated::
411 Say you have the following structure
414 ("V" "GrandStaff" ("VI" "VII"))
415 ("Strings" "StaffGroup" ("V" "Va"))
416 ("FullScore" "ParallelMusic" ("Strings" "SSolo"))
419 in you score structure definition. This means you have two violins, one viola and a soprano solo.
422 @node How a score is generated
423 @section How a score is generated
427 \createScore #"PieceA" #"FullScore"
429 in your lilypond file, OrchestralLily will generate a score for you that is similar to the following hand-written score:
436 \header @{ piece = \PieceA[FullScore]PieceName @}
439 If there exists e.g. a variable @code{\PieceAStringsStaff}, it is used, otherwise the staff (group) will be generated by OrchestralLily as described below.
441 If none of the sub-staves (and their sub-staves, etc.) contains any music, OrchestralLily will instead create a title to indicate no music is to be played:
443 \markup \piece-title \PieceA[FullScore]PieceNameTacet
445 Here, piece-title is the function used by OrchestralLily to format piece headings. It simply returns the proper markup definition for the given string.
448 @node How a staff group is generated
449 @section How a staff group is generated
451 If there is no definition for @code{\PieceAStringsStaff}, it is generated (as a StaffGroup as defined in the score structure) by OrchestralLily and is equivalent to the following manual definition:
453 \context StaffGroup = "\PieceAStringsSt" \with @{
454 instrumentName = \PieceAStringsInstrumentName
455 shortInstrumentName = \PieceAStringsShortInstrumentName
463 Again, if any of the @code{PieceAVStaff} or @code{PieceAVaStaff} variable is defined, it is inserted, otherwise the corresponding staff or staff group is created automatically (unless there is no music definition for it, in which case it is simply ignored). If any of the instrument name variables is not defined, the corresponding assignment is left out (without any error or warning message!).
465 If the definition of the Strings group in the score structure were a @code{ParallelMusic} or @code{SimultaneousMusic}, the generated code would be equivalent to
472 without the possibility to have an instrument name attached.
475 @node How a staff is generated
476 @section How a staff is generated
478 If the staff for e.g. "SSolo" is not manually defined, OrchestralLily generates it in a form equivalent to
480 \context Staff = "PieceASSoloSt" \with @{
481 instrumentName = \PieceASSoloInstrumentName
482 shortInstrumentName = \PieceASSoloShortInstrumentName
484 \context Voice = "PieceASSoloVoice" <<
486 \PieceA[SSolo]Settings
491 \context Lyrics = "PieceASSoloLyrics" \lyricsto "PieceASSoloVoice" \PieceASSoloLyrics
495 If no lyrics are defined (i.e. the variable @code{\PieceASSoloLyrics} is not defined), the @code{\dynamicUp} as well as the lyrics context is left out. Similarly, if any of the variables shown above is not defined, it is simply left out without any warning or error. If no music is defined (e.g. the variable @code{\PieceASSoloMusic} is not defined), no staff will be generated and it will simply be left out in the parent group.
498 @node Suffixes in use
499 @chapter Suffixes in use
501 @multitable @columnfractions .25 .20 .20 .10 .25
502 @headitem @tab in Score @tab in Staff group @tab in Staff
503 @headitem Suffix @tab @tab @tab StaffType @tab Parallel
504 @item @code{...PieceName} @tab Title for the piece @tab - @tab - @tab -
505 @item @code{...PieceNameTacet} @tab Piece title if no music is found @tab - @tab - @tab -
506 @item @code{...Staff} @tab Used as staff/group @tab - @tab - @tab -
507 @headitem The following variables are only used if ...Staff is not defined (i.e. the staff is created by OrchestralLily):
508 @item @code{...Music} @tab - @tab - @tab - @tab used as music for the staff
509 @item @code{...Lyrics} @tab - @tab - @tab - @tab Lyrics assigned to music
510 @item @code{...Settings} @tab - @tab - @tab - @tab music expression at beginning of staff
511 @item @code{...Clef} @tab - @tab - @tab - @tab music expression at beginning of staff
512 @item @code{...Key} @tab - @tab - @tab - @tab music expression at beginning of staff
513 @item @code{...TimeSignature} @tab - @tab - @tab - @tab music expression at beginning of staff
514 @item @code{...TransposeTo} @tab - @tab - @tab - @tab pitch, definition position of middle c' for the piece
515 @item @code{...InstrumentName} @tab - @tab assigned as instr. name @tab - @tab assigned as instr. name
516 @item @code{...ShortInstrumentName} @tab - @tab assigned as instr. name @tab - @tab assigned as instr. name
517 @item @code{...MidiInstrument} @tab - @tab assigned as MIDI instr. @tab - @tab assigned as MIDI instr.
520 The order in which these variables are looked up is also relevant. If you are printing the score for piece "PieceA" and the currently processed instrument/group is "Instr", OrchestralLily will test the following variable names (in this order):
526 This particular order ensures that you can have a definition for each score-instrument combination, which overrides everything else (e.g. the definition of the music should probably use this variable). However, for piece titles, keys and so on, you can have one definition, which applies to all instruments in that piece (the third form). On the other hand, some instruments (e.g. transposing instruments) need some special settings, which should override the piece-wide settings (like the key). For this, the second form is provided.
528 In the following we will typically give the variable name in full form @code{\PieceAInstrSuffix} with the understanding that of course @code{\InstrSuffix} and @code{\PieceASuffix} will be used if the full form variable does not exist. If any part is written in square brackets [..], this indicates that this part is typically left out and instrument- or piece-wide variables are usually used in this place.
530 One word or care, though: Be careful with variables of the form @code{\InstrStaff}. If you define it, OrchestralLily will use that staff for the given instrument for each part of the whole work and never generate a staff for you!!! Similarly, if you define @code{\PieceAStaff}, all instruments in PieceA will get this staff, unless you manually define a staff for an instrument!
532 FIXME Add ...Transposition
534 @node Simple examples
535 @chapter Simple examples
537 An example says more than thousand explanations, so in this chapter, I will
538 present some advanced features of OrchestralLily using simple test cases. It
539 should be easy to tell how to adapt the example in your own score...
543 * Transposing music::
544 * Using custom staff definitions::
546 * Table of contents::
547 * Equally-spaced markup columns::
549 * Markup using header fields::
550 * Copyright notice not on first page::
551 * Default instrument names::
552 * Non-standard staves::
553 * Using your custom context definitions::
558 @section Figured Bass
560 Figured bass can be either inserted like a staff (i.e. a direct child of a score
561 or a staff group) or attached to a given staff (i.e. like a voice). These two
562 cases are handled differently:
564 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/figuredbass.ly}
568 @node Transposing music
569 @section Transposing music
571 OrchestralLily supports transposing staves by defining the pitches in [Piece][Instrument]TransposeFrom and [Piece][Instrument]TransposeTo. The meaning of the these pitches is exactly the same as in ''\transpose frompitch topitch music''. In one of them is not defined, middle c' is used.
573 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/transpose.ly}
577 @node Using custom staff definitions
578 @section Using custom staff definitions
580 By default, OrchestralLily generates the whole staff definition from the music
581 definition and the other settings. However, sometimes this is not desirable,
582 because you want some special settings for one particular staff. In this case,
583 you can simply define the staff yourself as ''[Piece][Instr]Staff'' and
584 OrchestralLily will make use of this staff definition:
586 @lilypondfile[quote,verbatim]{../testsuite/staff-variable.ly}
592 OrchestralLily provides a definition ''\\titlePageMarkup''for a nice title page, you only have to assign it as ''bookTitleMarkup'' in the header block. It uses fields from the header block and formats a title page suitable for a professionally published score:
594 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/titlepage.ly}
599 @node Table of contents
600 @section Table of contents
602 OrchestralLily automatically appends all piece headers to the internal table
603 of TOC entries, you only have to display them using ''\markuplines \table-of-contents''. Also, you can insert your own
604 headers using ''\createHeadline''.
606 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/auto-toc.ly}
610 @node Equally-spaced markup columns
611 @section Equally-spaced markup columns
613 The ''\fill-line'' markup command generates markup in columns, but unfortunately,
614 the columns of different markups are not aligned with each other. If you want
615 to insert translations to your score, you'll have to use the ''\columns''
616 command instead, defined in OrchestralLily:
618 @lilypondfile[quote,verbatim,line-width=15\cm]{../testsuite/markup-columns.ly}
623 @node Using cue notes
624 @section Using cue notes
628 @node Markup using header fields
629 @section Markup using header fields
631 By default, markup in Lilypond does not have access to header fields (unless the
632 markup is assigned to a header variable and called from one of the formatting
633 functions defined in the header). OrchestralLily provides a function
634 ''\markupWithHeaders'', which formats a given markup and allows access to header
635 fields from this markup.
637 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/markup-header-fields.ly}
640 @node Copyright notice not on first page
641 @section Copyright notice not on first page
643 By default, lilypond prints the copyright notice on the first page. Orchestral
644 scores, however, typically print the notice on the first real score page (after
645 the title page and the introduction). In OrchestralLily, you can define the
646 page for the copyright notice using #(set-copyright-page pagenr):
648 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/copyright-page.ly}
651 @node Default instrument names
652 @section Default instrument names
654 OrchestralLily defines a lot of instrument names and clefs for the most
655 common instrument abbreviations. In order not to clutter the default output,
656 these are defined in the include file oly_settings_names.ly:
658 @lilypondfile[quote,verbatim,line-width=12\cm]{../testsuite/default-instrument-names.ly}
660 @node Creating a TOC file for the Latex includepdf call
661 @section Creating a TOC file for a includepdf call in @latex
665 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
671 @node Non-standard staves
672 @section Non-standard staves
674 OrchestralLily also supports other staff types than the default. For example,
675 a DrumStaff and a RhythmicStaff can easily be generated by a proper score
676 structure definition. As the voice of a DrumStaff needs to be a DrumVoice,
677 we also have to set this voice type once in our definitions.
679 The supported staff group types are:
685 @item "InnerChoirStaff"
686 @item "InnerStaffGroup"
687 @item "ParallelMusic" and its equivalent "SimultaneousMusic".
690 The supported staff types are:
694 @item "RhythmicStaff"
696 @item "GregorianTranscriptionStaff"
697 @item "MensuralStaff"
698 @item "VaticanaStaff"
699 @item "PartCombinedStaff"
700 @item "ParallelVoicesStaff"
704 The supported voice types are:
707 @item "CueVoice" (for smaller notes)
710 @item "GregorianTranscriptionVoice"
713 @item "VaticanaVoice"
716 @lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/non-standard-staff-voice-types.ly}
719 @node Using your custom context definitions
720 @section Using your custom context definitions
722 Suppose, you want to define your own staff group type called "SquareStaffGroup", which uses a rectangle
723 for the bracket, and your own staff type "ThreeStaff", which uses only three
724 staff lines. Also, we want to define our own voice type "RedVoice", which prints
725 all note heads in red and the stems in blue.
726 Of course, you could simply use @code{\set} and @code{\override} with the corresponding
727 properties somewhere inside your music definitions, but the cleaner way is to
728 define your own contexts with these settings. The further advantage is then
729 that you can OrchestralLily to use these context without much additional work:
731 @lilypondfile[quote,verbatim]{../testsuite/custom-contexts-handlers.ly}
735 @node Settings defined by OrchestralLily
736 @chapter Settings defined/changed by OrchestralLily
739 @item Proper rest combination for staves with two voices:
741 \include "../orchestrallily.ly"
743 \context Staff << { c''4 r d'' r } \\ { f'4 r r r } >>
746 @item modern-cautionary style for auto-accidentals. Cautionary accidentals are shown in brackets for one bar, after that no cautionary accidental is shown any more.
748 \include "../orchestrallily.ly"
749 \relative c' { cis dis es fis | d d f f | c d e f }
751 @item FIXME lots of other things (not yet documented) in the context hierarchy. See the orchestrallily.ly file (at the end of the file)
755 @node Available functions
756 @chapter Available functions
759 \piece-titlepage "markup"
760 \orchestralScoreStructure '(structure list)
761 \orchestralVoiceTypes '(voice type list)
762 (oly:register_staff_type_handler type func)
763 (oly:register_voice_type_handler type func)
767 \createScore #"Piece" '("Instrument"...)
768 \createNoCuesScore #"Piece" '("Instrument"...)
769 \createHeadline "text of the headline"
772 \setClefCue "cueString" clef
773 \namedCueDuring "CueVoice" #DIR "InstrCue" "Instr" music
774 \namedTransposedCueDuring "CueVoice" #DIR "InstrCue" "Instr" Transposition music
775 \cleffedCueDuring "CueVoice" #DIR "InstrCue" ClefCue "Instr" ClefInst Transposition music
777 \tempoMark '(padding . padding) #"Marktext"
780 Dynamic text: \ffz, \pf, \sempp, \parenf, \parenp
781 Dynamic spanners: \setDim, \dim, \enddim, \setDecresc, \decresc, \enddecresc, \setCresc, \cresc, \endcresc
783 \newOrOldClef "new" "old" (depending on (ly:get-option 'old-clefs))
784 \filterArticulations music (removed all articulations, dynamics, text scripts and multi-measure text events)
786 \when-property symbol markup
789 \markupWithHeader markupVariable
792 \newInstrument "instrumentName" (set cue name with "+")
793 \cueText (= \setCue !!!!!)
798 \contentsTitle (title for the TOC)
799 \titlePageMarkup (book title as header)
800 \titleHeaderMarkup (book title as title page)
801 \titleScoreMarkup (score title as markup)
805 * createNoCuesScore::
806 * orchestralScoreStructure::
811 * namedTransposedCueDuring::
814 * markupWithHeaders::
820 @unnumberedsec \createScore
822 Generates the score for the given piece and the given instrument(s). If no appropriate *Staff or *Music can be found, a header with the *PieceName (or the *PieceNameTacet) string will be printed.
824 \createScore #"PieceID" #'("Instrument1" "Instrument2" ...)
827 @item Typical call: @code{\createScore #"IIIChor" #'("T")}
831 The identifier for the piece/movement, which is part of the variable names used to generate the score
832 @item @b{Instrument list}
833 The list of instruments/staff identifiers to be shown in the score. These identifiers either indicate a staff group (as defined in the score structure list) or a single instrument (where the *Staff or *Music variables are used to create the staff).
838 @node createNoCuesScore
839 @unnumberedsec \createNoCuesScore
841 Like @code{\createScore}, except that @code{\killCues} and @code{\removeWithTag 'cued} is applied to all the music/staves
843 \createNoCuesScore #"PieceID" #'("Instrument1" "Instrument2" ...)
846 @item Typical call: @code{\createNoCuesScore #"IIIChor" #'("T")}
850 @node orchestralScoreStructure
851 @unnumberedsec \orchestralScoreStructure
854 \orchestralScoreStructure #'( ("ID" 'StaffType ("List" "Of" "Instruments"))... ))
858 \orchestralScoreStructure #'(
859 ; Part-combined staves (one staff with two voices)
860 ("Fl" #t ("FlI" "FlII"))
861 ; Grouped staves (multiple staves either in a StaffGroup, or parallel without a bracket)
862 ("Str" 'StaffGroup ("V" "Va"))
863 ("Solo" 'ParallelMusic ("SSolo" "TSolo"))
864 ("Ch" 'ChoirStaff ("S" "A" "T" "B"))
865 ("Vocal" 'SimultaneousMusic ("Solo" "Ch"))
866 ; full scores, again as grouped staves, no over-all bracket
867 ("FullScore" 'ParallelMusic ("Fl" "Str" "Solo" "Ch"))
870 * Description: Defines the hierarchy tree of the score. Each staff group (or part-combined staff with two voices) is identified by an ID (the first element of each entry).
871 * Parameters: @b{Score structure} ... A list of group descriptions. Each entry describes such a group and has three possible forms:
873 ("Identifier" StaffGroupType ("List" "of" "child" "identifiers")) ; Staff group of given type
874 ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" )) ; Staves connected without a bracket
875 ("Identifier" #f ("List" "of" "voices")) ; One staff with multiple voices (not yet implemented!)
876 ("Identifier" #t ("Two" "voices")) ; Staff with two part-combined voices
878 The list can contain each identifier only once, but they do not have to form only one tree, you can define several different hierarchy trees in one list!
882 @unnumberedsec \setUseBook
887 * Typical call: @code{\setUseBook ##t}
888 * Description: Declare whether the scores are called within a @code{\book} section or as top-level.
889 * Explanation: Internally, a score needs to be created differently if it should be printed inside a @code{\book} environment. Unfortunately, it is not possible in lilypond to detect the current environment, so this function is needed to explicitly declare that the following scores are inserted inside a @code{\book} environment.
891 * @b{inside book} ... @code{##t} if the following scores are inside a @code{\book} environment, @code{##f} if not (default)
892 setUseBook = #(define-music-function (parser location usebook) (boolean?)
896 @unnumberedsec \setCreateMIDI
898 Set a flag to determine whether MIDI output should be generated (default: NO). If YES, then an empty @code{\midi@{@}} block is generated in the score to trigger the creation of the midi file.
902 * Typical call: @code{\setCreateMidi ##t}
907 @unnumberedsec \setCreatePDF
909 Set a flag to determine whether PDF output should be generated (default: YES). If no, no @code{\layout@{@}} block will be generated in the score. If create @code{MIDI == #t}, then only MIDI will be created. If create @code{MIDI == #f}, then the PDF output will still be generated (similar to the existence/non-existence of a @code{\midi} and @code{\layout} block in a score!).
913 * Typical call: @code{\setCreatePDF ##t}
918 @unnumberedsec \namedCueDuring
920 Like @code{\cueDuring}, but also adds the instrument name of the cue instrument at the beginning of the cue notes and the original instrument name after the cue notes.
922 \namedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" music
924 * Typical call: @code{\namedCueDuring #"vIQuote" #UP #"V.I" #"Sop." @{ R1*3 @}}
926 * @b{quote name}, @b{direction}, @b{music} ... Parameters of @code{\cueDuring}
927 * @b{cue instrument}, @b{original instrument} ... Instrument names (strings) to be printed as cue instrument name at the beginning of the cues and as original instrument name after the cue notes
930 @node namedTransposedCueDuring
931 @unnumberedsec \namedTransposedCueDuring
933 Like @code{\namedCueDuring}, but uses @code{\transposedCueDuring} instead of @code{\cueDuring}.
935 \namedTransposedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" centralCNote music
937 * Typical call: @code{\namedTransposedCueDuring #"vIQuote" #UP #"Piccolo" #"Sop." c' @{ R1*3 @}}
940 @node cleffedCueDuring
941 @unnumberedsec \cleffedCueDuring
943 Like @code{\namedCudDuring}, but shows the cue notes with a different clef.
945 \cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music
947 * Typical call: @code{\cleffedCueDuring #"vIQuote" #UP #"V.I" @{\clef "treble"@} #"Basso" @{\clef "bass"@} @{ R1*3 @}}
949 % Parameters: \cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music
950 % -) NameOfQuote CueDirection music are the parameters for \cueDuring
951 % -) CueInstrument and OriginalInstrument are the displayed instrument names
952 % -) CueClef and OriginalClef are the clefs for the the cue notes and the clef of the containing voice
954 % This adds the notes from vIQuote (defined via \addQuote) to three measures, prints "V.I" at
955 % the beginning of the cue notes and "Basso" at the end. The clef is changed to treble at the
956 % beginning of the cue notes and reset to bass at the end
960 @unnumberedsec \piece-title
963 \piece-title pieceTitleString
967 @node markupWithHeaders
968 @unnumberedsec \markupWithHeaders
971 @node Other functions
972 @unnumberedsec Other functions
973 FIXME: not yet documented
976 @node Extending OrchestralLily
977 @chapter Extending OrchestralLily
979 To produce a staff group, staff or voice of a given type as specified in the
980 score structure, OrchestralLily internally uses so-called handler functions.
981 In particular, each known staff or group type is assigned to a scheme function
984 (staff_group_handler_function parser piece name type children)
986 where parser is the internal parser (needed by some of the subsequently called
987 functions), piece is the name of the current score part (i.e. the first
988 argument given in @code{\createScore}), name. type and children are the three
989 entried given in the score structure. Each handler generates either a staff
990 music expression, a list of staff music expressions or an empty list.
992 Similarly, to produce a voice object (to be used as children of a staff),
993 OrchestralLily internally uses voice type handler functions, which have a
994 function signature of
996 (voice_handler_function parser piece name type)
999 To register a staff/group or a voice handler with OrchestralLily, there are two functions:
1001 #(oly:register_staff_type_handler type func)
1002 #(oly:register_voice_type_handler type func)
1006 If you want to add your own staff group, staff type or voice type, in most cases
1007 you can use the internal functions provided by OrchestralLily:
1008 If you own type can be treated exactly like any other staff,
1009 group or voice, only with a different context name (i.e. because all the
1010 settings are in the @code{\layout} section and the staff/group/voice definition
1011 itself does not need any special settings), you can simply re-use the internal
1012 functions @code{oly:staff_group_handler}, @code{oly:staff_handler} or
1013 @code{oly:voice_handler}. For example
1015 #(oly:register_staff_type_handler "MyOwnGroup" oly:staff_group_handler)
1016 \orchestral-score-structure #'(
1017 ("Group" "MyOwnGroup" ("InstrI" "InstrII" "InstrIII"))
1019 \createScore #"Test" #'("group")
1021 will produce the same as
1023 \context MyOwnGroup="TestGroupStaff" <<
1029 (notice that the only difference to the default case is that the context is now
1030 MyOwnGroup instead of StaffGroup).
1032 If your staves, groups or voices need special settings or should be created
1033 differently, of course, you'll have to implement your own handler function.
1034 As a guide, you can take a look at the implementation of the built-in handlers.
1038 @node Frequently asked questions
1039 @chapter Frequently asked questions
1042 * Can I use different variable names?::
1043 * Can I change the structure of the score hierarchy list?::
1046 @node Can I use different variable names?
1047 @unnumberedsec I don't like the variable names, can I use a different order?
1049 If you don't like that the variables are generated as @code{\PieceInstrumentVarname}, you can override this behavior by redefining the scheme function @code{(namedPieceInstrObject piece instr name)}. The default implementation is:
1051 #(define (namedPieceInstrObject piece instr name)
1053 (fullname (string->symbol (string-append piece instr name)))
1054 (instrname (string->symbol (string-append instr name)))
1055 (piecename (string->symbol (string-append piece name)))
1058 ((defined? fullname) (primitive-eval fullname))
1059 ((defined? instrname) (primitive-eval instrname))
1060 ((defined? piecename) (primitive-eval piecename))
1066 Now it's up to you to write a different implementation... (e.g. use varnames of the style @code{\VarnameInstrPiece})
1067 But be careful with the order of evaluation, since some large scores might depend on @code{instrname} overriding @code{piecename} (e.g. a globally-defined key for transposing instruments!).
1070 @node Can I change the structure of the score hierarchy list?
1071 @unnumberedsec I don't like the structure of the score hierarchy list, can I change it?
1073 Sure, there is only one function that interprets the entries (factory pattern!): @code{(oly:create_staff_or_group parser piece instr)}. It looks up the @code{\PieceInstrumentStaff} variable and if that does not exist, it looks at a possible entry in the score structure descriptions and depending on its form, calls different methods to create a staff, a group, a part-combined staff or a staff with multiple voices.
1075 If you redefine this function, you have complete control about the decision when to create each type of staff/group.
1078 @node Version History
1079 @chapter Version History
1082 @item @uref{releases/orchestrallily_0.01.ly, 0.01 (2008-03-02)}:
1084 @item @uref{releases/orchestrallily_0.02.ly, 0.02 (2008-03-06)}:
1085 Added basic MIDI support (...MidiInstrument and \setCreateMIDI)
1086 @item @uref{releases/orchestrallily_0.03.ly, 0.03 (2008-06-??)}:
1088 @item Add *TimeSignature variable, split settings for full/vocal/instrumental scores
1089 @item [Piece][Instrument]TransposeTo, if set, now specifies the pitch where c' should be shown in the applicable voices.
1090 @item interpreting markup using header fields
1091 @item Automatically add score title to TOC
1092 @item \createHeadline to create a headline and add it to the TOC
1093 @item Adapted cresc spanners to new syntax
1094 @item Nice title page (full page) and nicer title header (for instrumental scores)
1095 @item Default clefs and Instrument names for lots of common abbreviations
1096 @item Default cue names fo lots of instruments, function to show cue name
1097 @item Default score numbers for each instrument
1098 @item one can also specify voice types
1099 @item parallel voices in one staff work,
1100 @item Group types are given as strings
1101 @item Adding handlers for new group/staff or voice types supported
1102 @item Support for Drum staves/voices and figured bass
1107 @node Known limitations and missing features
1108 @chapter Known limitations and missing features
1111 @item FIXME @b{Staves with multiple voices} (using @code{\voiceOne}, @code{\voiceTwo}), mess up the \voiceOne and \voiceTwo setting for some weird reason.
1112 @item FIXME Add support for MIDI instrument names
1120 Of course, a huge project like OrchestralLily would have never been possible
1121 without the help of many others. In particular, I'm indebted to Han-Wen
1122 Niewenhuis and Jan Nieuwenhuizen, the two authors of Lilypond. The folks over at
1123 the lilypond-user and lilypond-devel mailinglist were also of great importance
1124 and helped me solve lots of problems I ran into. A particular thanks goes to
1125 Nicolas Sceaux, who help me enourmously with his deeps insight into the Lilypond
1126 internals and the tricks he provided on the mailinglist and in his own Lilypond
1127 package for operas. Of course, all the authors of snippets posted at the LSR
1128 (Lilypond Snippet Repository) also contributed their share to the success of
1131 @node OrchestralLily index
1132 @appendix OrchestralLily index