LilyPond Notation Reference: 1.2.4 Beams

### 1.2.4 Beams

#### Automatic beams

By default, beams are inserted automatically:

>     \relative c'' {
>       \time 2/4 c8 c c c
>       \time 6/8 c8 c c c8. c16 c8
>     }

If these automatic decisions are not satisfactory, beaming can be entered explicitly; see Manual beams. Beams must be entered manually if beams are to be extended over rests.

If automatic beaming is not required, it may be turned off with `\autoBeamOff` and on with `\autoBeamOn`:

>     \relative c' {
>       c4 c8 c8. c16 c8. c16 c8
>       \autoBeamOff
>       c4 c8 c8. c16 c8.
>       \autoBeamOn
>       c16 c8
>     }

Note: If beams are used to indicate melismata in songs, then automatic beaming should be switched off with `\autoBeamOff` and the beams indicated manually. Using `\partCombine` with `\autoBeamOff` can produce unintended results. See the snippets for more information.

Beaming patterns that differ from the automatic defaults can be created; see Setting automatic beam behavior.

#### Predefined commands

`\autoBeamOff`, `\autoBeamOn`.

#### Selected Snippets

Beams across line breaks

Line breaks are normally forbidden when beams cross bar lines. This behavior can be changed as shown:

>     \relative c'' {
>       \override Beam.breakable = ##t
>       c8 c[ c] c[ c] c[ c] c[ \break
>       c8] c[ c] c[ c] c[ c] c
>     }

Changing beam knee gap

Kneed beams are inserted automatically when a large gap is detected between the note heads. This behavior can be tuned through the `auto-knee-gap` property. A kneed beam is drawn if the gap is larger than the value of `auto-knee-gap` plus the width of the beam object (which depends on the duration of the notes and the slope of the beam). By default `auto-knee-gap` is set to 5.5 staff spaces.

>     {
>       f8 f''8 f8 f''8
>       \override Beam.auto-knee-gap = #6
>       f8 f''8 f8 f''8
>     }

Partcombine and autoBeamOff

The function of `\autoBeamOff` when used with `\partCombine` can be difficult to understand.

It may be preferable to use

`\set Staff.autoBeaming = ##f`

instead, to ensure that autobeaming will be turned off for the entire staff.

`\partCombine` apparently works with 3 voices – stem up single, stem down single, stem up combined.

An `\autoBeamOff` call in the first argument to partcombine will apply to the voice that is active at the time the call is processed, either stem up single or stem up combined. An `\autoBeamOff` call in the second argument will apply to the voice that is stem down single.

In order to use `\autoBeamOff` to stop all autobeaming when used with `\partCombine`, it will be necessary to use three calls to `\autoBeamOff`.

>     {
>       %\set Staff.autoBeaming = ##f % turns off all autobeaming
>       \partCombine
>       {
>         \autoBeamOff % applies to split up stems
>         \repeat unfold 4 a'16
>         %\autoBeamOff % applies to combined up stems
>         \repeat unfold 4 a'8
>         \repeat unfold 4 a'16
>       }
>       {
>         \autoBeamOff % applies to down stems
>         \repeat unfold 4 f'8
>         \repeat unfold 8 f'16 |
>       }
>     }

#### See also

Notation Reference: Manual beams, Setting automatic beam behavior.

Installed Files: ‘`scm/auto-beam.scm`’.

Snippets: Rhythms.

Internals Reference: Auto_beam_engraver, Beam_engraver, Beam, BeamEvent, BeamForbidEvent, beam-interface, unbreakable-spanner-interface.

#### Known issues and warnings

The properties of a beam are determined at the start of its construction and any additional beam-property changes that occur before the beam has been completed will not take effect until the next, new beam starts.

#### Setting automatic beam behavior

When automatic beaming is enabled, the placement of automatic beams is determined by three context properties: `baseMoment`, `beatStructure`, and `beamExceptions`. The default values of these variables may be overridden as described below, or alternatively the default values themselves may be changed as explained in Time signature.

If a `beamExceptions` rule is defined for the time signature in force, that rule alone is used to determine the beam placement; the values of `baseMoment` and `beatStructure` are ignored.

If no `beamExceptions` rule is defined for the time signature in force, the beam placement is determined by the values of `baseMoment` and `beatStructure`.

#### Beaming based on `baseMoment` and `beatStructure`

By default, `beamExceptions` rules are defined for most common time signatures, so the `beamExceptions` rules must be disabled if automatic beaming is to be based on `baseMoment` and `beatStructure`. The `beamExceptions` rules are disabled by

>     \set Timing.beamExceptions = #'()

When `beamExceptions` is set to `#'()`, either due to an explicit setting or because no `beamExceptions` rules are defined internally for the time signature in force, the ending points for beams are on beats as specified by the context properties `baseMoment` and `beatStructure`. `beatStructure` is a scheme list that defines the length of each beat in the measure in units of `baseMoment`. By default, `baseMoment` is one over the denominator of the time signature. By default, each unit of length `baseMoment` is a single beat.

Note that there are separate `beatStructure` and `baseMoment` values for each time signature. Changes to these variables apply only to the time signature that is currently in force, hence those changes must be placed after the `\time` command which starts a new time signature section, not before it. New values given to a particular time signature are retained and reinstated whenever that time signature is re-established.

>     \relative c'' {
>       \time 5/16
>       c16^"default" c c c c |
>       % beamExceptions are unlikely to be defined for 5/16 time,
>       % but let's disable them anyway to be sure
>       \set Timing.beamExceptions = #'()
>       \set Timing.beatStructure = 2,3
>       c16^"(2+3)" c c c c |
>       \set Timing.beatStructure = 3,2
>       c16^"(3+2)" c c c c |
>     }

>     \relative {
>       \time 4/4
>       a'8^"default" a a a a a a a
>       % Disable beamExceptions because they are definitely
>       % defined for 4/4 time
>       \set Timing.beamExceptions = #'()
>       \set Timing.baseMoment = #(ly:make-moment 1/4)
>       \set Timing.beatStructure = 1,1,1,1
>       a8^"changed" a a a a a a a
>     }

Beam setting changes can be limited to specific contexts. If no setting is included in a lower-level context, the setting of the enclosing context will apply.

>     \new Staff {
>       \time 7/8
>       % No need to disable beamExceptions
>       % as they are not defined for 7/8 time
>       \set Staff.beatStructure = 2,3,2
>       <<
>         \new Voice = one {
>           \relative {
>             a'8 a a a a a a
>           }
>         }
>         \new Voice = two {
>           \relative {
>             \voiceTwo
>             \set Voice.beatStructure = 1,3,3
>             f'8 f f f f f f
>           }
>         }
>       >>
>     }

When multiple voices are used the `Staff` context must be specified if the beaming is to be applied to all voices in the staff:

>     \time 7/8
>     % rhythm 3-1-1-2
>     % 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
>     << \relative {a'8 a a a16 a a a a8 a} \\ \relative {f'4. f8 f f f} >>

>     % Works correctly with context Staff specified
>     \set Staff.beatStructure = 3,1,1,2
>     << \relative {a'8 a a a16 a a a a8 a} \\ \relative {f'4. f8 f f f} >>

The value of `baseMoment` can be adjusted to change the beaming behavior, if desired. When this is done, the value of `beatStructure` must be set to be compatible with the new value of `baseMoment`.

>     \time 5/8
>     % No need to disable beamExceptions
>     % as they are not defined for 5/8 time
>     \set Timing.baseMoment = #(ly:make-moment 1/16)
>     \set Timing.beatStructure = 7,3
>     \repeat unfold 10 { a'16 }

`baseMoment` is a moment; a unit of musical duration. A quantity of type moment is created by the scheme function `ly:make-moment`. For more information about this function, see Time administration.

By default `baseMoment` is set to one over the denominator of the time signature. Any exceptions to this default can be found in ‘`scm/time-signature-settings.scm`’.

#### Beaming based on `beamExceptions`

Special autobeaming rules (other than ending a beam on a beat) are defined in the `beamExceptions` property.

The value for `beamExceptions`, a somewhat complex Scheme data structure, is easiest generated with the `\beamExceptions` function. This function is given one or more manually beamed measure-length rhythmic patterns (measures have to be separated by a bar check `|` since the function has no other way to discern the measure length). Here is a simple example:

>     \relative c'' {
>       \time 3/16
>       \set Timing.beatStructure = 2,1
>       \set Timing.beamExceptions =
>         \beamExceptions { 32[ 32] 32[ 32] 32[ 32] }
>       c16 c c |
>       \repeat unfold 6 { c32 } |
>     }

Note: A `beamExceptions` value must be 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 `Timing.baseMoment`, `Timing.beatStructure`, and `Timing.beamExceptions` are set. Setting the time signature will reset the automatic beaming settings for the `Timing` context to the default behavior.

>     \relative a' {
>       \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 6/8
>       \repeat unfold 6 { a8 }
>     }

The default automatic beaming settings for a time signature are determined in ‘`scm/time-signature-settings.scm`’. Changing the default automatic beaming settings for a time signature is described in Time signature.

Many automatic beaming settings for a time signature contain an entry for `beamExceptions`. For example, 4/4 time tries to beam the measure in two if there are only eighth notes. The `beamExceptions` rule can override the `beatStructure` setting if `beamExceptions` is not reset.

>     \time 4/4
>     \set Timing.baseMoment = #(ly:make-moment 1/8)
>     \set Timing.beatStructure = 3,3,2
>     % This won't beam (3 3 2) because of beamExceptions
>     \repeat unfold 8 {c''8} |
>     % This will beam (3 3 2) because we clear beamExceptions
>     \set Timing.beamExceptions = #'()
>     \repeat unfold 8 {c''8}

In a similar fashion, eighth notes in 3/4 time are beamed as a full measure by default. To beam eighth notes in 3/4 time on the beat, reset `beamExceptions`.

>     \time 3/4
>     % by default we beam in (6) due to beamExceptions
>     \repeat unfold 6 {a'8} |
>     % This will beam (1 1 1) due to default baseMoment and beatStructure
>     \set Timing.beamExceptions = #'()
>     \repeat unfold 6 {a'8}

In engraving from the Romantic and Classical periods, beams often begin midway through the measure in 3/4 time, but modern practice is to avoid the false impression of 6/8 time (see Gould, p. 153). Similar situations arise in 3/8 time. This behavior is controlled by the context property `beamHalfMeasure`, which has effect only in time signatures with 3 in the numerator:

>     \relative a' {
>       \time 3/4
>       r4. a8 a a |
>       \set Timing.beamHalfMeasure = ##f
>       r4. a8 a a |
>     }

#### How automatic beaming works

When automatic beaming is enabled, the placement of automatic beams is determined by the context properties `baseMoment`, `beatStructure`, and `beamExceptions`.

The following rules, in order of priority, apply when determining the appearance of beams:

- If a manual beam is specified with `[…]` set the beam as specified, otherwise
- if a beam-ending rule is defined in `beamExceptions` for the beam-type, use it to determine the valid places where beams may end, otherwise
- if a beam-ending rule is defined in `beamExceptions` for a longer beam-type, use it to determine the valid places where beams may end, otherwise
- use the values of `baseMoment` and `beatStructure` to determine the ends of the beats in the measure, and end beams at the end of beats.

In the rules above, the beam-type is the duration of the shortest note in the beamed group.

The default beaming rules can be found in ‘`scm/time-signature-settings.scm`’.

#### Selected Snippets

Subdividing beams

The beams of consecutive 16th (or shorter) notes are, by default, not subdivided. That is, the three (or more) beams stretch unbroken over entire groups of notes. This behavior can be modified to subdivide the beams into sub-groups by setting the property `subdivideBeams`. When set, multiple beams will be subdivided at intervals defined by the current value of `baseMoment` by reducing the multiple beams to the number of beams that indicates the metric value of the subdivision. If the group following the division is shorter than the current metric value (usually because the beam is incomplete) the number of beams reflects the longest possible subdivision group. However, if there is only one note left after the division this restriction isn’t applied. Note that `baseMoment` defaults to one over the denominator of the current time signature if not set explicitly. It must be set to a fraction giving the duration of the beam sub-group using the `ly:make-moment` function, as shown in this snippet. Also, when `baseMoment` is changed, `beatStructure` should also be changed to match the new `baseMoment`:

>     \relative c'' {
>       c32[ c c c c c c c]
>       \set subdivideBeams = ##t
>       c32[ c c c c c c c]

>       % Set beam sub-group length to an eighth note
>       \set baseMoment = #(ly:make-moment 1/8)
>       \set beatStructure = 2,2,2,2
>       c32[ c c c c c c c]

>       % Set beam sub-group length to a sixteenth note
>       \set baseMoment = #(ly:make-moment 1/16)
>       \set beatStructure = 4,4,4,4
>       c32[ c c c c c c c]

>       % Shorten beam by 1/32
>       \set baseMoment = #(ly:make-moment 1/8)
>       \set beatStructure = 2,2,2,2
>       c32[ c c c c c c] r32

>       % Shorten beam by 3/32
>       \set baseMoment = #(ly:make-moment 1/8)
>       \set beatStructure = 2,2,2,2
>       c32[ c c c c] r16.
>       r2
>     }

Strict beat beaming

Beamlets can be set to point in the direction of the beat to which they belong. The first beam avoids sticking out flags (the default); the second beam strictly follows the beat.

>     \relative c'' {
>       \time 6/8
>       a8. a16 a a
>       \set strictBeatBeaming = ##t
>       a8. a16 a a
>     }

Conducting signs, measure grouping signs

Beat grouping within a measure is controlled by the context property `beatStructure`. Values of `beatStructure` are established for many time signatures in `scm/time-signature-settings.scm`. Values of `beatStructure` can be changed or set with `\set`. Alternatively, `\time` can be used to both set the time signature and establish the beat structure. For this, you specify the internal grouping of beats in a measure as a list of numbers (in Scheme syntax) before the time signature.

`\time` applies to the `Timing` context, so it will not reset values of `beatStructure` or `baseMoment` that are set in other lower-level contexts, such as `Voice`.

If the `Measure_grouping_engraver` is included in one of the display contexts, measure grouping signs will be created. Such signs ease reading rhythmically complex modern music. In the example, the 9/8 measure is grouped in two different patterns using the two different methods, while the 5/8 measure is grouped according to the default setting in `scm/time-signature-settings.scm`:

>     \score {
>       \new Voice \relative c'' {
>         \time 9/8
>         g8 g d d g g a( bes g) |
>         \set Timing.beatStructure = 2,2,2,3
>         g8 g d d g g a( bes g) |
>         \time 4,5 9/8
>         g8 g d d g g a( bes g) |
>         \time 5/8
>         a4. g4 |
>       }
>       \layout {
>         \context {
>           \Staff
>           \consists "Measure_grouping_engraver"
>         }
>       }
>     }

Beam endings in Score context

Beam-ending rules specified in the `Score` context apply to all staves, but can be modified at both `Staff` and `Voice` levels:

>     \relative c'' {
>       \time 5/4
>       % Set default beaming for all staves
>       \set Score.baseMoment = #(ly:make-moment 1/8)
>       \set Score.beatStructure = 3,4,3
>       <<
>         \new Staff {
>           c8 c c c c c c c c c
>         }
>         \new Staff {
>           % Modify beaming for just this staff
>           \set Staff.beatStructure = 6,4
>           c8 c c c c c c c c c
>         }
>         \new Staff {
>           % Inherit beaming from Score context
>           <<
>             {
>               \voiceOne
>               c8 c c c c c c c c c
>             }
>             % Modify beaming for this voice only
>             \new Voice {
>               \voiceTwo
>               \set Voice.beatStructure = 6,4
>               a8 a a a a a a a a a
>             }
>           >>
>         }
>       >>
>     }

#### See also

Notation Reference: Time signature.

Installed Files: ‘`scm/time-signature-settings.scm`’.

Snippets: Rhythms.

Internals Reference: Auto_beam_engraver, Beam, BeamForbidEvent, beam-interface.

#### Known issues and warnings

If a score ends while an automatic beam has not been ended and is still accepting notes, this last beam will not be typeset at all. The same holds for polyphonic voices, entered with `<< … \\ … >>`. If a polyphonic voice ends while an automatic beam is still accepting notes, it is not typeset. The workaround for these problems is to manually beam the last beam in the voice or score.

By default, the `Timing` translator is aliased to the `Score` context. This means that setting the time signature in one staff will affect the beaming of the other staves as well. Thus, a time signature setting in a later staff will reset custom beaming that was set in an earlier staff. One way to avoid this problem is to set the time signature in only one staff.

>     <<
>       \new Staff {
>         \time 3/4
>         \set Timing.baseMoment = #(ly:make-moment 1/8)
>         \set Timing.beatStructure = 1,5
>         \set Timing.beamExceptions = #'()
>         \repeat unfold 6 { a'8 }
>       }
>       \new Staff {
>         \repeat unfold 6 { a'8 }
>       }
>     >>

The default beam settings for the time signature can also be changed, so that the desired beaming will always be used. Changes in automatic beaming settings for a time signature are described in Time signature.

>     <<
>       \new Staff {
>         \overrideTimeSignatureSettings
>           3/4               % timeSignatureFraction
>           1/8               % baseMomentFraction
>           1,5               % beatStructure
>           #'()		% beamExceptions
>         \time 3/4
>         \repeat unfold 6 { a'8 }
>       }
>       \new Staff {
>         \time 3/4
>         \repeat unfold 6 { a'8 }
>       }
>     >>

#### Manual beams

In some cases it may be necessary to override the automatic beaming algorithm. For example, the autobeamer will not put beams over rests or bar lines, and in choral scores the beaming is often set to follow the meter of the lyrics rather than the notes. Such beams can be specified manually by marking the begin and end point with `[` and `]`.

>     \relative { r4 r8[ g' a r] r g[ | a] r }

Beaming direction can be set manually using direction indicators:

>     \relative { c''8^[ d e] c,_[ d e f g] }

Individual notes may be marked with `\noBeam` to prevent them from being beamed:

>     \relative {
>       \time 2/4
>       c''8 c\noBeam c c
>     }

Grace note beams and normal note beams can occur simultaneously. Unbeamed grace notes are not put into normal note beams.

>     \relative {
>       c''4 d8[
>       \grace { e32 d c d }
>       e8] e[ e
>       \grace { f16 }
>       e8 e]
>     }

Even more strict manual control with the beams can be achieved by setting the properties `stemLeftBeamCount` and `stemRightBeamCount`. They specify the number of beams to draw on the left and right side, respectively, of the next note. If either property is set, its value will be used only once, and then it is erased. In this example, the last `f` is printed with only one beam on the left side, i.e., the eighth-note beam of the group as a whole.

>     \relative a' {
>       a8[ r16 f g a]
>       a8[ r16
>       \set stemLeftBeamCount = #2
>       \set stemRightBeamCount = #1
>       f16
>       \set stemLeftBeamCount = #1
>       g16 a]
>     }

#### Predefined commands

`\noBeam`.

#### Selected Snippets

Flat flags and beam nibs

Flat flags on lone notes and beam nibs at the ends of beamed figures are both possible with a combination of `stemLeftBeamCount`, `stemRightBeamCount` and paired `[]` beam indicators.

For right-pointing flat flags on lone notes, use paired `[]` beam indicators and set `stemLeftBeamCount` to zero (see Example 1).

For left-pointing flat flags, set `stemRightBeamCount` instead (Example 2).

For right-pointing nibs at the end of a run of beamed notes, set `stemRightBeamCount` to a positive value. And for left-pointing nibs at the start of a run of beamed notes, set `stemLeftBeamCount` instead (Example 3).

Sometimes it may make sense for a lone note surrounded by rests to carry both a left- and right-pointing flat flag. Do this with paired `[]` beam indicators alone (Example 4).

(Note that `\set stemLeftBeamCount` is always equivalent to `\once \set`. In other words, the beam count settings are not “sticky”, so the pair of flat flags attached to the lone `16[]` in the last example have nothing to do with the `\set` two notes prior.)

>     \score {
>       <<
>         % Example 1
>         \new RhythmicStaff {
>           \set stemLeftBeamCount = #0
>           c16[]
>           r8.
>         }
>         % Example 2
>         \new RhythmicStaff {
>           r8.
>           \set stemRightBeamCount = #0
>           16[]
>         }
>         % Example 3
>         \new RhythmicStaff {
>           16 16
>           \set stemRightBeamCount = #2
>           16 r r
>           \set stemLeftBeamCount = #2
>           16 16 16
>         }
>         % Example 4
>         \new RhythmicStaff {
>           16 16
>           \set stemRightBeamCount = #2
>           16 r16
>           16[]
>           r16
>           \set stemLeftBeamCount = #2
>           16 16
>         }
>       >>
>     }

#### See also

Notation Reference: Direction and placement, Grace notes.

Snippets: Rhythms.

Internals Reference: Beam, BeamEvent, Beam_engraver, beam-interface, Stem_engraver.

#### Feathered beams

Feathered beams are used to indicate that a small group of notes should be played at an increasing (or decreasing) tempo, without changing the overall tempo of the piece. The extent of the feathered beam must be indicated manually using `[` and `]`, and the beam feathering is turned on by specifying a direction to the `Beam` property `grow-direction`.

If the placement of the notes and the sound in the MIDI output is to reflect the ritardando or accelerando indicated by the feathered beam the notes must be grouped as a music expression delimited by braces and preceded by a `featherDurations` command which specifies the ratio between the durations of the first and last notes in the group.

The square brackets show the extent of the beam and the braces show which notes are to have their durations modified. Normally these would delimit the same group of notes, but this is not required: the two commands are independent.

In the following example the eight 16th notes occupy exactly the same time as a half note, but the first note is one half as long as the last one, with the intermediate notes gradually lengthening. The first four 32nd notes gradually speed up, while the last four 32nd notes are at a constant tempo.

>     \relative c' {
>       \override Beam.grow-direction = #LEFT
>       \featherDurations #(ly:make-moment 2/1)
>       { c16[ c c c c c c c] }
>       \override Beam.grow-direction = #RIGHT
>       \featherDurations #(ly:make-moment 2/3)
>       { c32[ d e f] }
>       % revert to non-feathered beams
>       \override Beam.grow-direction = #'()
>       { g32[ a b c] }
>     }

The spacing in the printed output represents the note durations only approximately, but the MIDI output is exact.

#### Predefined commands

`\featherDurations`.

#### See also

Snippets: Rhythms.

#### Known issues and warnings

The `\featherDurations` command only works with very short music snippets, and when numbers in the fraction are small.

#### LilyPond — Notation Reference v2.22.2 (stable-branch).