GNU LilyPond Notation Reference: 1.2.4 Beams

### 1.2.4 Beams

#### Automatic beams

By default, beams are inserted automatically:

>     \time 2/4 c8 c c c
>     \time 6/8 c c c c8. c16 c8

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

It is possible to define beaming patterns that differ from the defaults. The default beaming rules for most common time signatures are defined in ‘`scm/auto-beam.scm`’. If there are no beaming rules defined for a particular beam’s duration in the time signature being used, its beaming is controlled by the values of three context properties, `measureLength`, `beatLength` and `beatGrouping`. Both the beaming rules and the context properties can be overridden, see Setting automatic beam behavior.

Note: If beams are used to indicate melismata in songs, then automatic beaming should be switched off with `autoBeamOff` and the beams indicated manually.

Automatic beaming may be turned off and on with `\autoBeamOff` and `\autoBeamOn` commands:

>     c4 c8 c8. c16 c8. c16 c8
>     \autoBeamOff
>     c4 c8 c8. c16 c8.
>     \autoBeamOn
>     c16 c8

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

#### See also

Notation Reference: Manual beams, Setting automatic beam behavior.

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

Snippets: Rhythms.

Internals Reference: Beam.

#### Known issues and warnings

Automatically kneed cross-staff beams cannot be used together with hidden staves. See Hiding staves.

Beams can collide with note heads and accidentals in other voices

#### Setting automatic beam behavior

The placement of automatic beams is determined by the rules described in Automatic beams. There are two mutually exclusive ways in which these rules may be modified. The first, modifying the grouping of beats, applies to uncommon time signatures, i.e. those for which there are no predefined rules defining the beam end points. The second method, modifying the specification of the beam end points, can be used for any time signature. This second method must be used for those time signatures and beam durations combinations for which beam ending rules are pre-defined, unless these have all been reverted. There are predefined rules for time signatures of 3/2, 3/4, 4/4, 2/4, 4/8, 4/16, 6/8, 9/8 and 12/8.

Modifying the grouping of beats

If there are no beam-ending rules defined for the beam duration of a particular beam in the time signature in use, its beaming is controlled by three context properties: `measureLength`, `beatLength` and `beatGrouping`. These properties may be set in the `Score`, `Staff` or `Voice` contexts to delimit their scope. The default values are set while processing `\time` commands, so the `\set` commands must be placed after all `\time` commands.

These determine the beaming as follows:

Beams may begin anywhere (unless a beam is already active). Beams end at a time determined by the values of `beatGrouping` and `beatLength`, as follows:

- If `beatGrouping` and `beatLength` are consistent with `measureLength`, `beatGrouping` is used to determine the end points of beams.
- If `beatGrouping` and `beatLength` are inconsistent with `measureLength`, `beatLength` is used to determine the end points of beams.

Note: These three properties become effective for a particular beam only if there are no beam-ending rules predefined for that beam’s duration in the time signature in use, or if these beam-ending rules have all been reverted.

By default the `measureLength` and `beatLength` are derived from the time signature set by the `\time` command. The `measureLength` is set to be exactly the same length as the measure length given by the time signature, and the `beatLength` is set to be the same as one over the denominator of the time signature.

The default value of `beatGrouping` is taken from a table in ‘`scm/music-functions.scm`’. To find this, see Other sources of information. It defines the beat grouping for 5/8, 6/8, 8/8, 9/8 and 12/8 time signatures.

Both `measureLength` and `beatLength` are moments, units 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.

`beatGrouping` is a list of integers giving the number of beats in each group.

#### Selected Snippets

Grouping beats

Beaming patterns may be altered with the `beatGrouping` property:

>     \relative c'' {
>       \time 5/16
>       #(override-auto-beam-setting '(end * * 5 16) 5 16)
>       \set beatGrouping = #'(2 3)
>       c8^"(2+3)" c16 c8
>       \set beatGrouping = #'(3 2)
>       c8^"(3+2)" c16 c8
>     }

Specifying context with beatGrouping

By specifying the context, the effect of `beatGrouping` can be limited to the context specified, and the values which may have been set in higher-level contexts can be overridden. The `\set` commands must be placed after all `\time` commands:

>     \score {
>       \new Staff <<
>         \time 7/8
>         \new Voice {
>           \relative c'' {
>             \set Staff.beatGrouping = #'(2 3 2)
>             a8 a a a a a a
>           }
>         }
>         \new Voice {
>           \relative c' {
>             \voiceTwo
>             \set beatGrouping = #'(1 3 3)
>             f8 f f f f f f
>           }
>         }
>       >>
>     }

Using beatLength and beatGrouping

The property `measureLength` determines where bar lines should be inserted and, with `beatLength` and `beatGrouping`, how automatic beams should be generated for beam durations and time signatures for which no beam-ending rules are defined. This example shows several ways of controlling beaming by setting these properties. The explanations are shown as comments in the code.

>     \relative c'' {
>       \time 3/4
>       % The default in 3/4 time is to beam in three groups
>       % each of a quarter note length
>       a16 a a a a a a a a a a a

>       \time 12/16
>       % No auto-beaming is defined for 12/16
>       a16 a a a a a a a a a a a

>       \time 3/4
>       % Change time signature symbol, but retain underlying 3/4 beaming
>       \set Score.timeSignatureFraction = #'(12 . 16)
>       a16 a a a a a a a a a a a

>       % The 3/4 time default grouping of (1 1 1) and beatLength of 1/8
>       % are not consistent with a measureLength of 3/4, so the beams
>       % are grouped at beatLength intervals
>       \set Score.beatLength = #(ly:make-moment 1 8)
>       a16 a a a a a a a a a a a

>       % Specify beams in groups of (3 3 2 3) 1/16th notes
>       % 3+3+2+3=11, and 11*1/16<>3/4, so beatGrouping does not apply,
>       % and beams are grouped at beatLength (1/16) intervals
>       \set Score.beatLength = #(ly:make-moment 1 16)
>       \set Score.beatGrouping = #'(3 3 2 3)
>       a16 a a a a a a a a a a a

>       % Specify beams in groups of (3 4 2 3) 1/16th notes
>       % 3+4+2+3=12, and 12*1/16=3/4, so beatGrouping applies
>       \set Score.beatLength = #(ly:make-moment 1 16)
>       \set Score.beatGrouping = #'(3 4 2 3)
>       a16 a a a a a a a a a a a
>     }

Sub-dividing beams

The beams of consecutive 16th (or shorter) notes are, by default, not sub-divided. That is, the three (or more) beams stretch unbroken over entire groups of notes. This behavior can be modified to sub-divide the beams into sub-groups by setting the property `subdivideBeams`. When set, multiple beams will be sub-divided at intervals defined by the current value of `beatLength` by reducing the multiple beams to just one beam between the sub-groups. Note that `beatLength` 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 `make-moment` function, as shown here:

>     \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 beatLength = #(ly:make-moment 1 8)
>       c32[ c c c c c c c]

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

Conducting signs, measure grouping signs

Options to group beats within a bar are available through the Scheme function `set-time-signature`, which takes three arguments: the number of beats, the beat length, and the internal grouping of beats in the measure. If the `Measure_grouping_engraver` is included, the function will also create `MeasureGrouping` signs. Such signs ease reading rhythmically complex modern music. In the example, the 9/8 measure is subdivided in 2, 2, 2 and 3. This is passed to `set-time-signature` as the third argument: `'(2 2 2 3)`:

>     \score {
>       \relative c'' {
>         #(set-time-signature 9 8 '(2 2 2 3))
>         #(revert-auto-beam-setting '(end * * 9 8) 3 8)
>         #(override-auto-beam-setting '(end 1 8 9 8) 1 4)
>         #(override-auto-beam-setting '(end 1 8 9 8) 2 4)
>         #(override-auto-beam-setting '(end 1 8 9 8) 3 4)
>         g8 g d d g g a( bes g) |
>         #(set-time-signature 5 8 '(3 2))
>         a4. g4
>       }
>       \layout {
>         \context {
>           \Staff
>           \consists "Measure_grouping_engraver"
>         }
>       }
>     }

Modifying the beam end points

In common time signatures, automatic beams can start on any note but can end at only a few positions within the measure, namely at durations specified by the properties in `autoBeamSettings`. These properties consist of a list of rules defining where beams can end. The default `autoBeamSettings` rules are defined in ‘`scm/auto-beam.scm`’. To find this, see Other sources of information.

This method must be used for the time signatures for which beam-ending rules are defined by default, unless these have all been reverted. It is also particularly suitable for many other time signatures if the time signature of the measures changes frequently, or if the beaming should be different for different beam durations.

In order to add a rule to the list, use

>     #(override-auto-beam-setting
>       '(beam-limit
>         beam-numerator  beam-denominator
>         time-signature-numerator time-signature-denominator)
>       moment-numerator moment-denominator [context])

where

- `beam-limit` is the type of automatic beam limit defined. This can be either `begin` or `end` but only `end` is effective.
- `beam-numerator/beam-denominator` is the beam duration to which the rule is to apply. A beam is considered to have the duration of its shortest note. Set `beam-numerator` and `beam-denominator` to `'*'` to have this rule apply to beams of any duration.
- `time-signature-numerator/time-signature-denominator` specifies the time signature to which this rule should apply. If `time-signature-numerator` and `time-signature-denominator` are set to `'*'` this rule will apply in any time signature.
- `monent-numerator/moment-denominator` is the position in the bar at which the beam should end.
- `context` is optional, and it specifies the context at which the change should be made. The default is `'Voice`.

  `#(score-override-auto-beam-setting '(A B C D) E F)` is equivalent to `#(override-auto-beam-setting '(A B C D) E F 'Score)`.

For example, if automatic beams should always end on the first quarter note, whatever the time signature or beam duration, use

>     a8 a a a a a a a
>     #(override-auto-beam-setting '(end * * * *) 1 4)
>     a8 a a a a a a a

You can force the beam settings to take effect only on beams whose shortest note is a certain duration

>     \time 2/4
>     % end 1/16 beams for all time signatures at the 1/16 moment
>     #(override-auto-beam-setting '(end 1 16 * *) 1 16)
>     a16 a a a a a a a |
>     a32 a a a a16 a a a a a |
>     % end 1/32 beams for all time signatures at the 1/16 moment
>     #(override-auto-beam-setting '(end 1 32 * *) 1 16)
>     a32 a a a a16 a a a a a |

You can force the beam settings to take effect only in certain time signatures

>     \time 5/8
>     % end beams of all durations in 5/8 time signature at the 2/8 moment
>     #(override-auto-beam-setting '(end * * 5 8) 2 8)
>     c8 c d d d
>     \time 4/4
>     e8 e f f e e d d
>     \time 5/8
>     c8 c d d d

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
>     % Context not specified - does not work correctly
>     #(override-auto-beam-setting '(end * * 7 8) 3 8)
>     #(override-auto-beam-setting '(end * * 7 8) 4 8)
>     #(override-auto-beam-setting '(end * * 7 8) 5 8)
>     << {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>

>     % Works correctly with context specified
>     #(override-auto-beam-setting '(end * * 7 8) 3 8 'Staff)
>     #(override-auto-beam-setting '(end * * 7 8) 4 8 'Staff)
>     #(override-auto-beam-setting '(end * * 7 8) 5 8 'Staff)
>     << {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>

Note: If any unexpected beam behavior occurs, check the default automatic beam settings in ‘`scm/auto-beam.scm`’ for possible interference, because the beam endings defined there will still apply in addition to your own.

Any unwanted or conflicting default endings must be reverted for your time signature(s). Existing auto-beam rules are removed by using

>     #(revert-auto-beam-setting
>       '(beam-limit
>         beam-numerator  beam-denominator
>         time-signature-numerator time-signature-denominator)
>       moment-numerator moment-denominator [context])

`beam-limit`, `beam-numerator`, `beam-denominator`, `time-signature-numerator`, `time-signature-denominator`, `moment-numerator`, `moment-denominator` and `context` are the same as above.

>     \time 4/4
>     a16 a a a a a a a a a a a a a a a
>     % undo a rule ending 1/16 beams in 4/4 time at 1/4 moment
>     #(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
>     a16 a a a a a a a a a a a a a a a

The rule in a `revert-auto-beam-setting` statement must exactly match the original rule. That is, no wildcard expansion is taken into account.

>     \time 1/4
>     #(override-auto-beam-setting '(end 1 16 1 4) 1 8)
>     a16 a a a
>     #(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
>     a a a a
>     #(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
>     a a a a

#### Selected Snippets

Beam grouping in 7/8 time

There are no default automatic beam groupings specified for 7/8 time, so if automatic beams are required the grouping must be specified. For example, to group all beams 2-3-2 in 7/8 time, specify beam endings at 2/8 and 5/8:

>     \relative c'' {
>       \time 7/8
>       % rhythm 2-3-2
>       a8 a a a a a a
>       #(override-auto-beam-setting '(end * * 7 8) 2 8)
>       #(override-auto-beam-setting '(end * * 7 8) 5 8)
>       a8 a a a a a a
>     }

Reverting default beam endings

To typeset beams grouped `3-4-3-2` in 12/8 it is necessary first to override the default beam endings in 12/8, and then to set up the new beaming endings:

>     \relative c'' {
>       \time 12/8

>       % Default beaming
>       a8 a a a a a a a a a a a

>       % Revert default values in scm/auto-beam.scm for 12/8 time
>       #(revert-auto-beam-setting '(end * * 12 8) 3 8)
>       #(revert-auto-beam-setting '(end * * 12 8) 3 4)
>       #(revert-auto-beam-setting '(end * * 12 8) 9 8)
>       a8 a a a a a a a a a a a

>       % Set new values for beam endings
>       #(override-auto-beam-setting '(end * * 12 8) 3 8)
>       #(override-auto-beam-setting '(end * * 12 8) 7 8)
>       #(override-auto-beam-setting '(end * * 12 8) 10 8)
>       a8 a a a a a a a a a a a
>     }

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
>       #(score-override-auto-beam-setting '(end * * 5 4) 3 8)
>       #(score-override-auto-beam-setting '(end * * 5 4) 7 8)
>       <<
>         \new Staff {
>           c8 c c c c c c c c c
>         }
>         \new Staff {
>           % Modify beaming for just this staff
>           #(override-auto-beam-setting '(end * * 5 4) 6 8 'Staff)
>           #(revert-auto-beam-setting '(end * * 5 4) 7 8 'Staff)
>           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
>               #(override-auto-beam-setting '(end * * 5 4) 6 8)
>               #(revert-auto-beam-setting '(end * * 5 4) 7 8)
>               a8 a a a a a a a a a
>             }
>           >>
>         }
>       >>
>     }

#### Predefined commands

`\autoBeamOff`, `\autoBeamOn`.

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

#### See also

Snippets: Rhythms.

#### 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 `]`

>     {
>       r4 r8[ g' a r8] r8 g[ | a] r8
>     }

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

>     \time 2/4 c8 c\noBeam c c

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.

>     a8[ r16 f g a]
>     a8[ r16
>     \set stemLeftBeamCount = #2
>     \set stemRightBeamCount = #1
>     f
>     \set stemLeftBeamCount = #1
>     g a]

#### 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 `c'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
>           c16[]
>         }

>         % Example 3
>         \new RhythmicStaff {
>           c16 c
>           \set stemRightBeamCount = #2
>           c16 r r
>           \set stemLeftBeamCount = #2
>           c16 c c
>         }

>         % Example 4
>         \new RhythmicStaff {
>           c16 c
>           \set stemRightBeamCount = #2
>           c16 r
>           c16[]
>           r16
>           \set stemLeftBeamCount = #2
>           c16 c
>         }
>       >>
>     }

#### 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 `featheredDurations` 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.

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

#### Known issues and warnings

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

#### See also

Snippets: Rhythms.

Other languages: français, español, deutsch.

#### Notation Reference