Description: A Lilypond package to easily generate orchestral scores and other complex scores.
Author: Reinhold Kainhofer, reinhold@kainhofer.com
Date: February 2008
Download: orchestrallily.ly (Version 0.02, 2008-03-06), licensed under the GPL v3.0
Development version:

• Web-Frontend: http://repo.or.cz/w/orchestrallily.git
• read-only git URL: git://repo.or.cz/orchestrallily.git (use git clone URL)

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 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

• generate appropriate staves and staff groups
• collate them in the proper (defined) order
• add correct instrument names (if defined by the user)
• add movement titles (if defined)
• add a header „Movement name tacet“ in an instrumental score for each movement where the instrument rests
• add correct clefs/keys/other settings into each staff (if defined by the user)
• etc.

This way, generating full scores, scores for individual instruments and for instrument groups are really simple and no additional manual work!

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!

As they all look really similar, why not automate their creation instead of manually writing them? That is exactly where OrchestralLily comes in.

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.

We will call the soprano staff SSolo and the cello staff 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 Dada-defs.ly. For the scores, we write a additional files, which generate the scores.

\version "2.11.40"
\include "orchestrallily.ly"
\paper { ragged-bottom = ##t }
\header { title = "A nonsensical work" }

DadaPieceName = "Dada song"
DadaPieceNameTacet = "Dada song - Tacet"

VcInstrumentName = "Violoncello"
VcShortInstrumentName = "Vc."
SSoloInstrumentName = "Soprano Solo"
SSoloShortInstrumentName = "S."

VcClef = \clef "bass"
DadaSettings = {\mark\markup{\bold "Slow."}}

DadaVcMusic = \relative c { c4 g' c, b' }
DadaSSoloMusic = \relative c'' {c2 c,8 e g c}
DadaSSoloLyrics = \lyricmode { Da, da -- da -- da -- da! }


\orchestralScoreStructure #'(
  ("FullScore" ParallelMusic ("Percussion" "SSolo" "Vc"))
  ("InvertedScore" StaffGroup ("Vc" "SSolo"))
)

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.

Finally, the call \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.

The above definitions are all that is needed by OrchestralLily to generate all various kinds of scores!

dada.ly file, generating some scores:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "Dada-defs.ly"

% the soprano score:
\createScore #"Dada" #'("SSolo")

% the Vc score:
\createScore #"Dada" #'("Vc")

% the percussion score, no notes defined -> Tacet
\createScore #"Dada" #'("Percussion")

% the full score:
\createScore #"Dada" #'("FullScore")

The actual score creation is done with a call to \createScore, with the part name („Dada“ in our case) as the first argument and a list of instrument / staff group identifiers as second argument.

Now, suppose we want to generate a score for Vc, including the soprano staff in smaller size. This is also really simple in OrchestralLily:

dada_vc_including_small_ssolo.ly, Vc score with smaller soprano staff:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "Dada-defs.ly"

\header { instrument = \VcInstrumentName }

% For the SSolo staff, use a smaller staff size!
DadaSSoloSettings = {
    \DadaSettings 
    \set fontSize = #-4
    \override Staff.StaffSymbol #'staff-space = #(magstep -4)
}

\createScore #"Dada" #'("InvertedScore")

In full scores, the violoncello and contrabasso 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):

dada_vc_staff_group.ly, Full score with square staff bracket for VcB:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "Dada-defs.ly"

\orchestralScoreStructure #'(
  ("VcB" StaffGroup ("Vc"))
  ("FullScore" ParallelMusic ("Percussion" "SSolo" "VcB"))
)

\createScore #"Dada" #'("FullScore")

Although it was not explicitly shown in this simple example, OrchestralLily of course supports also nested staff groups.

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, which becomes:

\version "2.11.40"
\include "orchestrallily.ly"
\paper { ragged-bottom = ##t }
\header { title = "A useless opus" }

TimKey = \key c \major
TimClef = \clef "bass"
TimInstrumentName = "Timpani"
TimShortInstrumentName = "Tim."
VcClef = \clef "bass"
VcInstrumentName = "Violoncello"
VcShortInstrumentName = "Vc."
SSoloInstrumentName = "Soprano Solo"
SSoloShortInstrumentName = "S."

DadaPieceName = "1) Dada song"
DadaPieceNameTacet = "1) Dada song - Tacet"
DadaSettings = {\mark\markup{\italic "Slow."}}
DadaVcMusic = \relative c { c4 g' c, b' }
DadaSSoloMusic = \relative c'' {c2 c,8 e g c}
DadaSSoloLyrics = \lyricmode { Da, da -- da -- da -- da! }

DidiPieceName = "2) Didi song"
DidiPieceNameTacet = "2) Didi song - Tacet"
DidiKey = \key fis \major
DidiTimMusic = \relative c { g1\startTrillSpan~ | g1\stopTrillSpan }
DidiSSoloMusic = \relative c' { fis8 cis'4. fis,8 cis'4. | fis8 cis'4. fis,8 cis'4.}
DidiSSoloLyrics = \lyricmode { Di -- di, di -- di, di -- di, di -- di! }

DodoPieceName = "3) Dodo song"
DodoPieceNameTacet = "3) Dodo song - Tacet"
DodoTimMusic = \relative c' { c1\<\startTrillSpan~ | c1\!\stopTrillSpan\ff }
DodoVcMusic = \relative c { c1:16\< | c1:16\!\ff }
DodoSSoloMusic = \relative c' { c4 d8 e f g a b | c1\ff }
DodoSSoloLyrics = \lyricmode { Do, do, do, do, do, do, do, do... }


\orchestralScoreStructure #'(
  ("FullScore" ParallelMusic ("Tim" "SSolo" "VcB"))
  ("VcB" StaffGroup ("Vc"))
; a nested staff to highlight nested groups:
  ("NestedScore" StaffGroup ("TimGr" "Solo" "VcB"))
  ("TimGr" GrandStaff ("Tim"))
  ("Solo" ChoirStaff ("SSolo"))
)

After these definitions, we can easily generate individual instrumental scores, as well as a full score:

Timpani score:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \TimInstrumentName }

\createScore #"Dada" #'("Tim")
\createScore #"Didi" #'("Tim")
\createScore #"Dodo" #'("Tim")

Soprano solo score:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \SSoloInstrumentName }

\createScore #"Dada" #'("SSolo")
\createScore #"Didi" #'("SSolo")
\createScore #"Dodo" #'("SSolo")

Violoncello score:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \VcInstrumentName }

\createScore #"Dada" #'("Vc")
\createScore #"Didi" #'("Vc")
\createScore #"Dodo" #'("Vc")

Full score:

<html><div style=„float:right“></html><html></div></html>

\version "2.11.40"
\include "dadafull-defs.ly"

\createScore #"Dada" #'("FullScore")
\createScore #"Didi" #'("FullScore")
\createScore #"Dodo" #'("FullScore")

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:

• „FullScore“ (parallel staves/groups)
  • „Woodwinds“ (staff group)
    • „Fl“ (staff with two voices)
    • „Ob“ (staff with two voices)
  • „Strings“ (staff group)
    • „Violins“ (grand staff)
      • „VI“ (simple staff)
      • „VII“ (simple staff)
    • „Va“ (simple staff)
  • „Vocal“ (parallel staves/groups)
    • „Solo“ (parallel staves)
      • „SSolo“ (simple staff)
      • „TSolo“ (simple staff)
    • „Choir“ (choir staff)
      • „S“ (simple staff)
      • „A“ (simple staff)
      • „T“ (simple staff)
      • „B“ (simple staff)
  • „VcB“ (staff group)
    • „Vc“ (simple staff)

So, the „FullScore“ consists of parallel music of the following staves/groups: „Woodwinds“, „Strings“, „Vocal“ and „VcB“. 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.

This structure can be easily defined in OrchestralLily by calling \orchestral-score-structure with a simple list describing the hierarchy:

\orchestral-score-structure #'(
  ("FullScore" SimultaneousMusic ("Woodwinds" "Strings" "Vocal" "VcB"))
  ("Woodwinds" StaffGroup ("Fl" "Ob"))
  ("Fl" #t ("FlI" "FlII"))
  ("Ob" #t ("ObI" "ObII"))
  ("Strings" StaffGroup ("Violins" "Va"))
  ("Violins" GrandStaff ("VI" "VII"))
  ("Vocal" SimultaneousMusic ("Solo" "Choir"))
  ("Solo" SimultaneousMusic ("SSolo" "TSolo"))
  ("Choir" ChoirStaff ("S" "A" "T" "B"))
  ("VcB" StaffGroup ("Vc"))
)

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!).

Each entry of the list describes one grouping of staves or voices and has three possible forms:

  ("Identifier" StaffGroupType ("List" "of" "child" "identifiers"))    ; Staff group of given type
  ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" ))  ; Staves connected without a bracket
  ("Identifier" #f ("List" "of" "voices"))                             ; One staff with multiple voices (not yet implemented!)
  ("Identifier" #t ("Two" "voices"))                                   ; Staff with two part-combined voices

The first entry creates a staff group of type StaffGroupType (e.g. StaffGroup, GrandStaff, PianoStaff, 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 « Staff1 Staff2 ». 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 (\voiceOne, \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, \partcombine is used for this (with all its limitations!).

If an identifier from the list of child identifiers is not defined in that hierarchy list, it is assumed to be a simple staff.

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.

Say you have the following structure of your score:

'(
  ("V" GrandStaff ("VI" "VII"))
  ("Strings" StaffGroup ("V" "Va"))
  ("FullScore" ParallelMusic ("Strings" "SSolo"))
)

in you score structure definition. This means you have two violins, one viola and a soprano solo.

If you call

\createScore #"PieceA" #"FullScore"

in your lilypond file, OrchestralLily will generate a score for you that is similar to the following hand-written score:

\score {
  <<
    \PieceAStringsStaff
    \PieceASSoloStaff
  >>
  \header { piece = \PieceA[FullScore]PieceName }
}

If there exists e.g. a variable \PieceAStringsStaff, it is used, otherwise the staff (group) will be generated by OrchestralLily as described below.

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:

\markup \piece-title \PieceA[FullScore]PieceNameTacet

Here, piece-title is the function used by OrchestralLily to format piece headings. It simply returns the proper markup definition for the given string.

If there is no definition for \PieceAStringsStaff, it is generated (as a StaffGroup as defined in the score structure) by OrchestralLily and is equivalent to the following manual definition:

\context StaffGroup = "\PieceAStringsSt" \with {
         instrumentName = \PieceAStringsInstrumentName
         shortInstrumentName = \PieceAStringsShortInstrumentName 
} <<
  \PieceAVStaff
  \PieceAVaStaff  
>>

Again, if any of the PieceAVStaff or 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!).

If the definition of the Strings group in the score structure were a ParallelMusic or SimultaneousMusic, the generated code would be equivalent to

<<
  \PieceAVStaff
  \PieceAVaStaff  
>>

without the possibility to have an instrument name attached.

If the staff for e.g. „SSolo“ is not manually defined, OrchestralLily generates it in a form equivalent to

\context Staff = "PieceASSoloSt" \with {
         instrumentName = \PieceASSoloInstrumentName
         shortInstrumentName = \PieceASSoloShortInstrumentName 
} <<
  \context Voice = "PieceASSoloVoice" << 
    \dynamicUp
    \PieceA[SSolo]Settings
    \PieceA[SSolo]Key
    \[PieceA]SSoloClef
    \PieceA[SSolo]TimeSignature
    \PieceASSoloMusic
  >>
  \context Lyrics = "PieceASSoloLyrics" \lyricsto "PieceASSoloVoice" \PieceASSoloLyrics
>>

If no lyrics are defined (i.e. the variable \PieceASSoloLyrics is not defined), the \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 \PieceASSoloMusic is not defined), no staff will be generated and it will simply be left out in the parent group.

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):

  \PieceAInstrSuffix
  \InstrSuffix
  \PieceASuffix

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.

In the following we will typically give the variable name in full form \PieceAInstrSuffix with the understanding that of course \InstrSuffix and \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.

One word or care, though: Be careful with variables of the form \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 \PieceAStaff, all instruments in PieceA will get this staff, unless you manually define a staff for an instrument!

Add …Transposition

• Proper rest combination
• modern-cautionary style for auto-accidentals
• lots of other things (not yet documented) in the context hierarchy. See the orchestrallily.ly file (at the end of the file)

• Typical call:

  \createScore #"IIIChor" #'("T")

• Description: 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.
• Parameters:
  • PieceID … The identifier for the piece/movement, which is part of the variable names used to generate the score
  • Instrument list … 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).

• Typical call:

  \createNoCuesScore #"IIIChor" #'("T")

• Description: Like \createScore, except that \killCues and \removeWithTag 'cued is applied to all the music/staves

• Typical call:

  \orchestralScoreStructure #'(
  ; Part-combined staves (one staff with two voices)
    ("Fl" #t ("FlI" "FlII"))
  ; Grouped staves (multiple staves either in a StaffGroup, or parallel without a bracket)
    ("Str" 'StaffGroup ("V" "Va"))
    ("Solo" 'ParallelMusic ("SSolo" "TSolo"))
    ("Ch" 'ChoirStaff ("S" "A" "T" "B"))
    ("Vocal" 'SimultaneousMusic ("Solo" "Ch"))
  ; full scores, again as grouped staves, no over-all bracket
    ("FullScore" 'ParallelMusic ("Fl" "Str" "Solo" "Ch"))
  )

• 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).
• Parameters: Score structure … A list of group descriptions. Each entry describes such a group and has three possible forms:

  ("Identifier" StaffGroupType ("List" "of" "child" "identifiers"))    ; Staff group of given type
  ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" ))  ; Staves connected without a bracket
  ("Identifier" #f ("List" "of" "voices"))                             ; One staff with multiple voices (not yet implemented!)
  ("Identifier" #t ("Two" "voices"))                                   ; Staff with two part-combined voices

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!

• Typical call:

  \setUseBook ##t

• Description: Declare whether the scores are called within a \book section or as top-level.
• Explanation: Internall, a score needs to be created differently if it should be printed inside a \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 \book environment.
• Parameters:
  • inside book … ##t if the following scores are inside a \book environment, ##f if not (default)

setUseBook = #(define-music-function (parser location usebook) (boolean?)

• Typical call:

  \setCreateMidi ##t

• Descriptions: Set a flag to determine whether MIDI output should be generated (default: NO). If YES, then an empty \midi {} block is generated in the score to trigger the creation of the midi file.

• Typical call:

  \setCreatePDF ##t

• Descriptions: Set a flag to determine whether PDF output should be generated (default: YES). If no, no \layout{} block will be generated in the score. If create MIDI == #t, then only MIDI will be created. If create MIDI == #f, then the PDF output will still be generated (similar to the existence/non-existence of a \midi and \layout block in a score!).

• Typical call:

  \namedCueDuring #"vIQuote" #UP #"V.I" #"Sop." { R1*3 }

• Description: Like \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
• Parameters:
  • quote name, direction, music … Parameters of \cueDuring
  • cue instrument, 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

• Typical call:

  \namedTransposedCueDuring #"vIQuote" #UP #"Piccolo" #"Sop." c' { R1*3 }

• Description: Like \namedCueDuring, but uses \transposedCueDuring instead of \\cueDuring

• Typical call:

  \cleffedCueDuring #"vIQuote" #UP #"V.I" {\clef "treble"} #"Basso" {\clef "bass"} { R1*3 }

• Description: Like \namedCudDuring, but shows the cue notes with a different clef

% generate a cue music section with instrument names and clef changes % Parameters: \cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music % -) NameOfQuote CueDirection music are the parameters for \cueDuring % -) CueInstrument and OriginalInstrument are the displayed instrument names % -) CueClef and OriginalClef are the clefs for the the cue notes and the clef of the containing voice

% This adds the notes from vIQuote (defined via \addQuote) to three measures, prints „V.I“ at % the beginning of the cue notes and „Basso“ at the end. The clef is changed to treble at the % beginning of the cue notes and reset to bass at the end

If you don't like that the variables are generated as \PieceInstrumentVarname, you can override this behaviour by redefining the scheme function (namedPieceInstrObject piece instr name). The default implementation is:

#(define (namedPieceInstrObject piece instr name)
  (let* (
         (fullname  (string->symbol (string-append piece instr name)))
         (instrname (string->symbol (string-append instr name)))
         (piecename (string->symbol (string-append piece name)))
        )
    (cond
      ((defined? fullname) (primitive-eval fullname))
      ((defined? instrname) (primitive-eval instrname))
      ((defined? piecename) (primitive-eval piecename))
      (else '())
    )
  )
)

Now it's up to you to write a different implementation… (e.g. use varnames of the style \VarnameInstrPiece) But be careful with the order of evaluation, since some large scores might depend on instrname overriding piecename (e.g. a globally-defined key for transposing instruments!).

Sure, there is only one function that interprets the entries (factory pattern!): (oly:create_staff_or_group parser piece instr). It looks up the \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.

If you redefine this function, you have complete control about the decision when to create each type of staff/group.

• 0.01 (2008-03-02): Initial Version
• 0.02 (2008-03-06): Added basic MIDI support (…MidiInstrument and \setCreateMIDI)

• Staves with multiple voices (using \voiceOne, \voiceTwo), possibly with lyrics attached, are not yet implemented. Currently, you'll still have to define those staves manually.
• Support for transposing instruments is missing. You'd define the music in sounding pitch, but the displayed staff would be automatically transposed to the defined key (via a \[Piece]InstrTransposition variable). Thus, all cue notes will also be correct automatically.
• Support for other staff types (DrumStaff, RhythmicStaff, TabStaff) and the corresponding voices
• Add flag to generate MIDI