@funindex \set
@funindex set
-The placement of automatic beams is determined by the context properties
-@code{baseMoment}, @code{beatStructure}, @code{beamExceptions},
-and @code{autoBeaming}.
-
-The following rules, in order of priority, apply when determining
-the appearance of beams:
-
-@itemize
-@item
-If a manual beam is specified with @code{[..]} set the beam
-as specified, otherwise
-
-@item
-if @code{\autoBeamOff} is in force do not beam, otherwise
-
-@item
-if a beam-ending rule is defined in @code{beamExceptions}
-for the beam-type, use it to determine the valid places where
-beams may end, otherwise
-
-@item
-if a beam-ending rule is defined in @code{beamExceptions}
-for a longer beam-type, use it to determined the valid places
-where beams may end, otherwise
-
-@item
-use the values of @code{baseMoment} and @code{beatStructure} to
-determine the ends of the beats in the measure, and
-end beams at the end of beats.
-
-@end itemize
-
-The beam-type is the duration of the shortest note in the beamed group.
-
-@i{@strong{Modifying the grouping of beats}}
-
-By default @code{baseMoment} is set by the @code{\time} command,
-normally to one over the denominator of the time signature.
-Any exceptions to this default
-can be found in @file{scm/@/time@/-signature@/-settings@/.scm}.
-Changing the default value of @code{baseMoment} for a given
-time signature is described in @ref{Time signature}.
-
-@code{baseMoment} is a @i{moment},
-a unit of musical duration. A quantity of type @i{moment} is
-created by the scheme function @code{ly:make-moment}. For more
-information about this function, see @ref{Time administration}.
-
-Special (i.e., other than at the end of the beat) autobeam settings
-are stored in the
-@code{beamExceptions} property. Default values of @code{beamExceptions}
-are established by the @code{\time} command. Default values of
-@code{beamExceptions} for a time signature
-are determined in @file{scm/@/time@/-signature@/-settings@/.scm}.
-Entries in @code{beamExceptions} are indexed by rule type and beam type.
-
-Rule type should be @code{#'end} for beam ending.
-
-The ending rules consist of a scheme alist
-(or list of pairs) that
-indicates the beam type and the grouping to be applied to
-beams containing notes with a shortest duration of that
-beam type.
-
-@example
-#'((beam-type1 . grouping-1)
- (beam-type2 . grouping-2)
- (beam-type3 . grouping-3))
-@end example
-
-Beam type is a scheme pair indicating the duration
-of the beam, e.g., @code{(1 . 16)}.
-
-Grouping is a scheme list indicating the grouping to be applied to
-the beam. The grouping is in units of the beam type.
-
-For reference, the default beaming rules are found in
-@file{scm/time-signature-settings.scm}.
-
-Alternate values for @code{beamExceptions}
-can be defined using the @code{\set} command.
-
-@warning{
-A @code{beamExceptions} value must be
-@emph{complete} exceptions list. That is, every exception that should
-be applied must be included in the setting.
-It is not possible to add, remove, or change only one of the exceptions.
-While this may seem cumbersome,
-it means that the current beaming settings need not be known
-in order to specify a new beaming pattern.}
+In most instances, automatic beams will end at the end of a beat.
+The ending points for beats are determined by the context properties
+@code{baseMoment} and @code{beatStructure}. @code{beatStructure}
+is a scheme list that defines the length of each beat in the measure
+in units of @code{baseMoment}. By default, @code{baseMoment} is
+the one over numerator of the time signature. By default,
+each unit of length @code{baseMoment} is a single beat.
@lilypond[quote,relative=2,verbatim]
\time 5/16
-c8^"beats" c16 c8 |
-\set beatStructure = #'(2 3)
-c8^"(2+3)" c16 c8
-\set beatStructure = #'(3 2)
-c8^"(3+2)" c16 c8
+c16^"default" c c c c |
+\set Timing.beatStructure = #'(2 3)
+c16^"(2+3)" c c c c |
+\set Timing.beatStructure = #'(3 2)
+c16^"(3+2)" c c c c |
@end lilypond
Beam setting changes can be limited to specific contexts. If no
@lilypond[quote,verbatim,relative=2]
\time 7/8
% rhythm 3-1-1-2
-% Context Voice specified -- does not work correctly
+% Change applied to Voice by default -- does not work correctly
% Because of autogenerated voices, all beating will
% be at baseMoment (1 . 8)
\set beatStructure = #'(3 1 1 2)
<< {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>
@end lilypond
-Beam settings can be set back to default behavior. This
-is accomplished by setting the time signature.
+The value of @code{baseMoment} can be adjusted to change
+the beaming behavior, if desired. When this is done,
+the value of @code{beatStructure} must be set to be
+compatible with the new value of @code{baseMoment}.
@lilypond[quote,verbatim,relative=2]
-\time 4/4
-\repeat unfold 8 {a8}
-% eliminate beam exception that groups beats 1, 2 and 3, 4
-\set Timing.beamExceptions = #'()
-\repeat unfold 8 {a8}
+\time 5/8
+\set Timing.baseMoment = #(ly:make-moment 1 16)
+\set Timing.beatStructure = #'(7 3)
+\repeat unfold 10 {a16}
+@end lilypond
+
+@code{baseMoment} is a @i{moment},
+a unit of musical duration. A quantity of type @i{moment} is
+created by the scheme function @code{ly:make-moment}. For more
+information about this function, see @ref{Time administration}.
+
+By default @code{baseMoment} is set
+to one over the denominator of the time signature.
+Any exceptions to this default
+can be found in @file{scm/@/time@/-signature@/-settings@/.scm}.
+
+Special autobeaming rules (other than ending a beam on a beat)
+are defined in the @code{beamExceptions} property.
+
+@lilypond[quote,relative=2,verbatim]
+\time 3/16
+\set Timing.beatStructure = #'(2 1)
+\set Timing.beamExceptions =
+ #'( ;start of alist
+ (end . ;entry for end of beams
+ ( ;start of alist of end points
+ ((1 . 32) . (2 2 2)) ;rule for 1/32 beams -- end each 1/16
+ ))) %close all entries
+c16 c c |
+\repeat unfold 6 {c32} |
+@end lilypond
+
+@code{beamExceptions} is an alist with a key of rule-type and
+a value of beaming-rules.
+
+At this time the only available value of rule-type is
+@code{#'end} for beam ending.
+
+Beaming-rules is a scheme alist (or list of pairs) that
+indicates the beam type and the grouping to be applied to
+beams containing notes with a shortest duration of that
+beam type.
+
+@example
+#'((beam-type1 . grouping-1)
+ (beam-type2 . grouping-2)
+ (beam-type3 . grouping-3))
+@end example
+
+Beam type is a scheme pair indicating the duration
+of the beam, e.g., @code{(1 . 16)}.
+
+Grouping is a scheme list indicating the grouping to be applied to
+the beam. The grouping is in units of the beam type.
+
+@warning{
+A @code{beamExceptions} value must be
+@emph{complete} exceptions list. That is, every exception that should
+be applied must be included in the setting.
+It is not possible to add, remove, or change only one of the exceptions.
+While this may seem cumbersome,
+it means that the current beaming settings need not be known
+in order to specify a new beaming pattern.}
+
+When the time signature is changed, default values of
+@code{Timing.baseMoment}, @code{Timing.beatStructure},
+and @code{Timing.beamExceptions} are set. Setting the time signature
+will reset the automatic beaming settings for the @code{Timing}
+context to the default behavior.
+
+@lilypond[quote,verbatim,relative=2]
+\time 6/8
+\repeat unfold 6 {a8}
+% group (4 + 2)
+\set Timing.beatStructure = #'(4 2)
+\repeat unfold 6 {a8}
% go back to default behavior
-\time 4/4
-\repeat unfold 8 {a8}
+\time 6/8
+\repeat unfold 6 {a8}
@end lilypond
+These default automatic beaming settings for a time signature
+are determined in @file{scm/@/time@/-signature@/-settings@/.scm}.
+The automatic beaming settings for a time signature can be changed
+as described in @ref{Time signature}.
+
+@i{@strong{How automatic beaming works}}
+
+When automatic beaming is enabled, the placement of automatic beams
+is determined by the context properties
+@code{baseMoment}, @code{beatStructure}, and @code{beamExceptions}.
+
+The following rules, in order of priority, apply when determining
+the appearance of beams:
+
+@itemize
+@item
+If a manual beam is specified with @code{[..]} set the beam
+as specified, otherwise
+
+@item
+if a beam-ending rule is defined in @code{beamExceptions}
+for the beam-type, use it to determine the valid places where
+beams may end, otherwise
+
+@item
+if a beam-ending rule is defined in @code{beamExceptions}
+for a longer beam-type, use it to determined the valid places
+where beams may end, otherwise
+
+@item
+use the values of @code{baseMoment} and @code{beatStructure} to
+determine the ends of the beats in the measure, and
+end beams at the end of beats.
+
+@end itemize
+
+In the rules above, the beam-type is the duration of the
+shortest note in the beamed group.
+
+For reference, the default beaming rules are found in
+@file{scm/time-signature-settings.scm}.
@snippets
projects / lilypond.git / commitdiff