1 ;;;; define-music-types.scm --
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2006 Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
8 ;; TODO: should link back into user manual.
10 (define-public music-descriptions
14 (description . "Creates a dynamic mark.
16 Syntax: @var{note}@code{\\x},
17 where x is one of \\ppp, \\pp, \\p, \\mp, \\mf, \\f, \\ff, \\fff.")
18 (types . (general-music event dynamic-event absolute-dynamic-event))
22 (description . "Call the argument with the current context during interpreting phase")
23 (types . (general-music apply-context))
24 (iterator-ctor . ,ly:apply-context-iterator::constructor)
29 Call the argument with all current grobs during interpreting phase.
35 arguments to func are 1. the grob, 2. the originating context,
36 3. context where FUNC is called.
39 (iterator-ctor . ,ly:output-property-music-iterator::constructor)
40 (types . (general-music layout-instruction))
44 (description . "Make an arpeggio on this note.
47 @var{note}-@code{\\arpeggio}")
48 (types . (general-music arpeggio-event event))
51 ;; todo: use articulation-event for slur as well.
52 ;; separate non articulation scripts
55 (description . "Adds an articulation marking to a note.
58 @var{note}@code{X}@code{Y}, where X is a direction (up @code{^}, down
59 @code{_}, or LilyPond's choice (no direction specified)), and where Y
60 is an articulation (such as @code{-.}, @code{->}, @code{\\tenuto},
61 @code{\\downbow}). See the user manual for details.")
63 (types . (general-music event articulation-event script-event))
67 (description . "Used for making voices that switch between piano staves automatically.")
68 (iterator-ctor . ,ly:auto-change-iterator::constructor)
69 (start-callback . ,ly:music-wrapper::start-callback)
70 (length-callback . ,ly:music-wrapper::length-callback)
71 (types . (general-music music-wrapper-music auto-change-instruction))
76 "Check whether this music coincides with the start of the measure.")
77 (types . (general-music bar-check))
78 (iterator-ctor . ,ly:bar-check-iterator::constructor)
82 (description . "Print a bass-figure text")
84 (types . (general-music event rhythmic-event bass-figure-event))
88 (description . "Starts or stops a beam.
90 Syntax for manual control:
92 (types . (general-music event beam-event span-event))
96 (description . "Create a line break, Syntax: \\break or page break, Syntax: \\pagebreak.")
98 (types . (general-music break-event event))
102 (description . "Creates a `breath mark' or `comma'.
105 @var{note}\\breathe.")
107 (types . (general-music event breathing-event))
111 (description . "Used internally to signal beginning and ending of notes.")
113 (types . (general-music event busy-playing-event))
117 (description . "Change staffs in Piano staff.
119 Syntax @code{\\translator Staff = @var{new-id}}.")
120 (iterator-ctor . , ly:change-iterator::constructor)
121 (types . (general-music translator-change-instruction))
125 . ((description . "A note that is part of a cluster.")
127 ;; not a note-event, to ensure that Note_engraver doesn't eat it.
128 (types . (general-music cluster-note-event melodic-event rhythmic-event event))
133 (description . "Interpret the argument music within a specific context.")
134 (iterator-ctor . ,ly:context-specced-music-iterator::constructor)
135 (length-callback . ,ly:music-wrapper::length-callback)
136 (start-callback . ,ly:music-wrapper::start-callback)
137 (types . (context-specification general-music music-wrapper-music))
142 (description . "Begins or ends a crescendo.
144 Syntax: @var{note}\\cr
145 ... @var{note}\\rc (you can also use \\<, \\!, \\cresc, and
146 \\endcresc. See the user manual for details.).")
148 (types . (general-music dynamic-event crescendo-event event))
152 (description . "See @ref{CrescendoEvent}.")
154 (types . (general-music dynamic-event decrescendo-event event))
159 (description . "Extend lyrics.")
161 (types . (general-music extender-event event))
167 (description . "Internally used to group a set of events.")
168 (iterator-ctor . ,ly:event-chord-iterator::constructor)
169 (length-callback . ,ly:music-sequence::maximum-length-callback)
170 (to-relative-callback . ,ly:music-sequence::event-chord-relative-callback)
171 (types . (general-music event-chord simultaneous-music))
176 (description . "Specify what finger to use for this note.")
177 (types . (general-music fingering-event event))
181 (description . "Specify that a note may not auto-beamed ")
182 (types . (general-music event beam-forbid-event))
186 (description . "Start a glissando on this note.")
187 (types . (general-music glissando-event event))
192 (description . "Interpret the argument as grace notes. ")
193 (start-callback . ,ly:grace-music::start-callback)
194 (length . ,ZERO-MOMENT)
195 (iterator-ctor . ,ly:grace-iterator::constructor)
196 (types . (grace-music music-wrapper-music general-music))
200 (description . "Start or stop grouping brackets.")
201 (types . (general-music event note-grouping-event))
205 (description . "Mark a note as harmonic")
206 (types . (general-music event harmonic-event))
210 (description . "A hyphen between lyric syllables.")
212 (types . (general-music hyphen-event event))
217 (description . "Change the key signature.
219 Syntax: @code{\\key } @var{name} @var{scale}.")
220 (to-relative-callback . ,(lambda (x p) p))
221 (types . (general-music key-change-event event))
224 . ((description . "Don't damp this chord.
226 Syntax: @var{note}\\laissezVibrer.")
228 (types . (general-music event laissez-vibrer-event))
232 (description . "(docme).")
233 (span-type . ligature)
234 (types . (general-music span-event ligature-event event))
237 (OldLyricCombineMusic
239 (description . "Align lyrics to the start of notes.
241 Syntax @var{\\oldaddlyrics }@var{music} @var{lyrics}.")
243 (types . (general-music lyric-combine-music))
244 (length-callback . ,ly:lyric-combine-music::length-callback)
245 (start-callback . ,ly:music-sequence::first-start-callback)
246 (iterator-ctor . ,ly:old-lyric-combine-music-iterator::constructor)
251 (description . "Align lyrics to the start of notes.
253 Syntax @var{\\lyricsto }@var{voicename} @var{lyrics}.")
254 (length . ,ZERO-MOMENT)
255 (types . (general-music lyric-combine-music))
256 (iterator-ctor . ,ly:lyric-combine-music-iterator::constructor)
261 (description . "A lyric syllable. Must be entered in lyrics mode, i.e.
262 @code{\\lyrics @{ twinkle4 twinkle4 @} } .")
264 (types . (general-music rhythmic-event lyric-event event))
268 (description . "Insert a rehearsal mark.
270 Syntax: @code{\\mark} @var{marker},
271 e.g. @code{\\mark \"A\"}.")
273 (types . (general-music mark-event event))
277 (description . "Used internally to signal melismas.")
278 (types . (general-music melisma-playing-event event))
282 (description . "Start or stop a melisma.
284 Syntax: @code{c4\\melisma d\\melismaEnd}.")
285 (types . (general-music melisma-span-event event))
288 (MultiMeasureRestEvent
290 (description . "Rests that may be compressed into Multi rests.
293 @code{R2.*4} for 4 measures in 3/4 time. Note the capital R.")
294 (types . (general-music event rhythmic-event multi-measure-rest-event))
297 (MultiMeasureRestMusicGroup
299 (description . "Like sequential-music, but specifically intended
300 to group start-mmrest, skip, stop-mmrest sequence.
302 Syntax @code{R2.*5} for 5 measures in 3/4 time.")
303 (length-callback . ,ly:music-sequence::cumulative-length-callback)
304 (start-callback . ,ly:music-sequence::first-start-callback)
305 (iterator-ctor . ,ly:sequential-music-iterator::constructor)
306 (types . (general-music sequential-music))
309 (MultiMeasureTextEvent
311 (description . "Texts on mm rests.
314 @code{R-\\markup @{ \\roman \"bla\" @}}. Note the explicit font switch.")
315 (types . (general-music event multi-measure-text-event))
320 (description . "Generic type for music expressions.")
322 (types . (general-music))
326 (description . "A note.")
328 (types . (general-music event note-event rhythmic-event melodic-event))
331 (OutputPropertySetMusic
333 (description . "Set grob properties in objects
336 Syntax @code{\\outputproperty @var{predicate} @var{prop}
339 (iterator-ctor . ,ly:output-property-music-iterator::constructor)
340 (types . (general-music layout-instruction))
345 (description . "Extend the definition of a graphical object.
349 @code{\\override [ @var{Ctxt} . ] @var{Obj} @var{prop} = @var{val}}
351 (types . (general-music layout-instruction))
352 (iterator-ctor . ,ly:push-property-iterator::constructor)
356 (description . "Combine two parts on a staff, either merged or
357 as separate voices.")
358 (length-callback . ,ly:music-sequence::maximum-length-callback)
359 (start-callback . ,ly:music-sequence::minimum-start-callback)
360 (types . (general-music part-combine-music))
361 (iterator-ctor . ,ly:part-combine-iterator::constructor)
365 (description . "Start or end phrasing slur.
367 Syntax NOTE \\( and \\) NOTE")
368 (types . (general-music span-event event phrasing-slur-event))
373 (description . "Set a context property.
375 Syntax: @code{\\property @var{context}.@var{prop} = @var{scheme-val}}.")
376 (types . (layout-instruction general-music))
377 (iterator-ctor . ,ly:property-iterator::constructor)
382 (description . "Remove the definition of a context @code{\\property}.")
384 (types . (layout-instruction general-music))
385 (iterator-ctor . ,ly:property-unset-iterator::constructor)
390 (description . "Within a ligature, mark the previous and the
391 following note to form a pes (if melody goes up) or a flexa (if melody
394 (types . (general-music pes-or-flexa-event event))
399 (description . "Quote preprocessed snippets of music. ")
400 (iterator-ctor . ,ly:quote-iterator::constructor)
401 (length-callback . ,ly:music-wrapper::length-callback)
402 (start-callback . ,ly:music-wrapper::start-callback)
403 (types . (general-music music-wrapper-music))
407 . ((description . "Check if a pitch is in the correct octave.")
408 (to-relative-callback . ,ly:relative-octave-check::relative-callback)
409 (types . (general-music relative-octave-check))
414 (description . "Repeat music in different ways")
415 (types . (general-music repeated-music))
419 (description . "Ties for starting a second volta bracket.")
420 (types . (general-music event repeat-tie-event))
424 (description . "Atomic music event.")
425 (types . (general-music event))
430 (description . "A Rest.
432 Syntax @code{r4} for a quarter rest. ")
434 (types . (general-music event rhythmic-event rest-event))
438 (description . "The opposite of @ref{OverrideProperty}: remove a
439 previously added property from a graphical object definition
442 (types . (general-music layout-instruction))
443 (iterator-ctor . , ly:pop-property-iterator::constructor)
448 (description . "Music expressions concatenated.
450 Syntax \\sequential @{..@} or simply @{..@} .")
452 (length-callback . ,ly:music-sequence::cumulative-length-callback)
453 (start-callback . ,ly:music-sequence::first-start-callback)
454 (iterator-ctor . ,ly:sequential-music-iterator::constructor)
455 (types . (general-music sequential-music))
460 (description . "Print Solo.1")
461 (part-combine-status . solo1)
462 (types . (general-music event part-combine-event))
466 (description . "Print Solo.2")
467 (part-combine-status . solo2)
468 (types . (general-music event part-combine-event))
471 . ((description . "Print a2")
472 (part-combine-status . unisono)
473 (types . (general-music event part-combine-event))))
477 (description . "Music playing together.
481 @code{ \\simultaneous @{ .. @}} or << .. >>.")
483 (iterator-ctor . ,ly:simultaneous-music-iterator::constructor)
484 (start-callback . ,ly:music-sequence::minimum-start-callback)
485 (length-callback . ,ly:music-sequence::maximum-length-callback)
486 (to-relative-callback . ,ly:music-sequence::simultaneous-relative-callback)
488 (types . (general-music simultaneous-music))
493 (description . "Start or end slur.
495 Syntax NOTE( and NOTE) ")
497 (types . (general-music span-event event slur-event))
501 . ((description . "Start or stop a staff symbol.")
502 (types . (general-music event span-event staff-span-event))
507 (description . "Used internally to signal beginning of notes.")
509 (types . (general-music event start-playing-event))
514 (description . "Start a text spanner like 8va.....|")
515 (types . (general-music span-event event text-span-event))
520 (description . "Start a trill spanner tr~~~")
521 (types . (general-music span-event event trill-span-event))
526 (description . "Multiply durations, as in tuplets.
528 Syntax @code{\\times @var{fraction} @var{music}}, e.g.
529 @code{\\times 2/3 @{ ... @}} for triplets.
531 (length-callback . ,ly:music-wrapper::length-callback)
532 (start-callback . ,ly:music-wrapper::start-callback)
533 (iterator-ctor . ,ly:time-scaled-music-iterator::constructor)
534 (types . (time-scaled-music music-wrapper-music general-music))
539 (description . "Music that has been transposed.")
540 (iterator-ctor . ,ly:music-wrapper-iterator::constructor)
541 (start-callback . ,ly:music-wrapper::start-callback)
542 (length-callback . ,ly:music-wrapper::length-callback)
543 (to-relative-callback . ,ly:relative-octave-music::no-relative-callback)
544 (types . (music-wrapper-music general-music transposed-music))
549 (description . "Music that can not be converted from relative to absolute notation.
550 For example, transposed music.")
551 (to-relative-callback . ,ly:relative-octave-music::no-relative-callback)
552 (iterator-ctor . ,ly:music-wrapper-iterator::constructor)
553 (length-callback . ,ly:music-wrapper::length-callback)
554 (types . (music-wrapper-music general-music unrelativable-music))
559 (description . "Music that was entered in relative octave notation.")
560 (to-relative-callback . ,ly:relative-octave-music::relative-callback)
561 (iterator-ctor . ,ly:music-wrapper-iterator::constructor)
562 (length-callback . ,ly:music-wrapper::length-callback)
563 (start-callback . ,ly:music-wrapper::start-callback)
564 (types . (music-wrapper-music general-music relative-octave-music))
568 (description . "Add an articulation mark to a note. ")
570 (types . (general-music event))
575 (description . "Filler that takes up duration, does not print anything, and also
576 does not create staffs or voices implicitly.
580 Syntax: @code{\\skip }@var{duration}.")
581 (length-callback . ,ly:music-duration-length)
582 (iterator-ctor . ,ly:simple-music-iterator::constructor)
583 (types . (general-music event rhythmic-event skip-event))
588 (description . "Filler that takes up duration, but does not print anything.
592 Syntax: @code{s}@var{duration}")
594 (types . (general-music event rhythmic-event skip-event))
598 (description . "Event for anything that is started at a different time than stopped.")
600 (types . (general-music event))
605 (description . "Depress or release sustain pedal. ")
606 (types . (general-music event pedal-event sustain-pedal-event))
611 (description . "Depress or release sostenuto pedal. ")
612 (types . (general-music event pedal-event sostenuto-pedal-event))
617 (description . "Depress or release una-corda pedal.")
618 (types . (general-music event pedal-event una-corda-pedal-event))
623 (description . "Specify on which string to play this note.
625 Syntax: @code{\\@var{number}}.")
627 (types . (general-music string-number-event event))
630 (MetronomeChangeEvent
632 (description . "Change tempo setting (in beats per minute).")
633 (types . (general-music metronome-change-event tempo-event event))
639 (types . (general-music script-event text-script-event event))
643 (description . "A tie. Entered as @var{note}-~.")
644 (types . (general-music tie-event event))
648 (description . "Un measured tremolo.")
649 (types . (general-music event tremolo-event))
654 (description . "Separate polyphonic voices in simultaneous music.
656 Syntax: @code{\\\\}")
658 (types . (separator general-music))
663 (iterator-ctor . ,ly:volta-repeat-iterator::constructor)
665 (start-callback . ,ly:repeated-music::first-start)
666 (length-callback . ,ly:repeated-music::volta-music-length)
667 (types . (general-music repeated-music volta-repeated-music))
670 (UnfoldedRepeatedMusic
672 (iterator-ctor . ,ly:unfolded-repeat-iterator::constructor)
674 (start-callback . ,ly:repeated-music::first-start)
675 (types . (general-music repeated-music unfolded-repeated-music))
676 (length-callback . ,ly:repeated-music::unfolded-music-length)
678 (PercentRepeatedMusic
680 (description . "Repeats encoded by percents.")
681 (iterator-ctor . ,ly:percent-repeat-iterator::constructor)
682 (start-callback . ,ly:repeated-music::first-start)
683 (length-callback . ,ly:repeated-music::unfolded-music-length)
684 (types . (general-music repeated-music percent-repeated-music))
687 (TremoloRepeatedMusic
689 (iterator-ctor . ,ly:chord-tremolo-iterator::constructor)
690 (description . "Repeated notes denoted by tremolo beams.")
691 (start-callback . ,ly:repeated-music::first-start)
693 ;; the length of the repeat is handled by shifting the note logs
694 (length-callback . ,ly:repeated-music::folded-music-length)
695 (types . (general-music repeated-music tremolo-repeated-music))
701 (description . "Repeats with alternatives placed in parallel. ")
702 (iterator-ctor . ,ly:folded-repeat-iterator::constructor)
703 (start-callback . ,ly:repeated-music::minimum-start)
704 (length-callback . ,ly:repeated-music::folded-music-length)
705 (types . (general-music repeated-music folded-repeated-music))
709 (set! music-descriptions
710 (sort music-descriptions alist<?))
712 (define-public music-name-to-property-table (make-vector 59 '()))
715 ;; transport description to an object property.
719 (set-object-property! (car x)
721 (cdr (assq 'description (cdr x))))
723 (set! lst (assoc-set! lst 'name (car x)))
724 (set! lst (assq-remove! lst 'description))
725 (hashq-set! music-name-to-property-table (car x) lst)
729 (define-safe-public (make-music name . music-properties)
730 "Create a music object of given name, and set its properties
731 according to `music-properties', a list of alterning property symbols
733 (make-music 'OverrideProperty
735 'grob-property 'thickness
736 'grob-value (* 2 1.5))"
737 (if (not (symbol? name))
738 (ly:error (_ "symbol expected: ~S") name))
739 (let ((props (hashq-ref music-name-to-property-table name '())))
740 (if (not (pair? props))
741 (ly:error (_ "can't find music object: ~S") name))
742 (let ((m (ly:make-music props)))
743 (define (set-props mus-props)
744 (if (and (not (null? mus-props))
745 (not (null? (cdr mus-props))))
747 (set! (ly:music-property m (car mus-props)) (cadr mus-props))
748 (set-props (cddr mus-props)))))
749 (set-props music-properties)
752 (define-public (make-repeated-music name)
753 (let* ((handle (assoc name '(("volta" . VoltaRepeatedMusic)
754 ("unfold" . UnfoldedRepeatedMusic)
755 ("percent" . PercentRepeatedMusic)
756 ("tremolo" . TremoloRepeatedMusic)
757 ("fold" . FoldedRepeatedMusic))))
758 (music-name (if (pair? handle)
761 (ly:warning (_ "unknown repeat type `~S'") name)
762 (ly:warning (_ "See music-types.scm for supported repeats"))
763 'VoltaRepeatedMusic))))
764 (make-music music-name)))