LilyPond Internals Reference: 3.1.20 Beam

### 3.1.20 Beam

Beam objects are created by: Auto_beam_engraver, Beam_engraver, Chord_tremolo_engraver, Grace_auto_beam_engraver and Grace_beam_engraver.

Standard settings:

> `auto-knee-gap` (dimension, in staff space):

>   `5.5`

>   If a gap is found between note heads where a horizontal beam fits and it is larger than this number, make a kneed beam.

> `beam-thickness` (dimension, in staff space):

>   `0.48`

>   Beam thickness, measured in `staff-space` units.

> `beamed-stem-shorten` (list):

>       '(1.0 0.5 0.25)

>   How much to shorten beamed stems, when their direction is forced. It is a list, since the value is different depending on the number of flags and beams.

> `beaming` (pair):

>   `ly:beam::calc-beaming`

>   Pair of number lists. Each number list specifies which beams to make. `0` is the central beam, `1` is the next beam toward the note, etc. This information is used to determine how to connect the beaming patterns from stem to stem inside a beam.

> `clip-edges` (boolean):

>   `#t`

>   Allow outward pointing beamlets at the edges of beams?

> `collision-interfaces` (list):

>       '(beam-interface
>          clef-interface
>          clef-modifier-interface
>          flag-interface
>          inline-accidental-interface
>          key-signature-interface
>          note-head-interface
>          stem-interface
>          time-signature-interface)

>   A list of interfaces for which automatic beam-collision resolution is run.

> `damping` (number):

>   `1`

>   Amount of beam slope damping.

> `details` (list):

>       '((secondary-beam-demerit . 10)
>         (stem-length-demerit-factor . 5)
>         (region-size . 2)
>         (beam-eps . 0.001)
>         (stem-length-limit-penalty . 5000)
>         (damping-direction-penalty . 800)
>         (hint-direction-penalty . 20)
>         (musical-direction-factor . 400)
>         (ideal-slope-factor . 10)
>         (collision-penalty . 500)
>         (collision-padding . 0.35)
>         (round-to-zero-slope . 0.02))

>   Alist of parameters for detailed grob behavior. More information on the allowed parameters for a grob can be found by looking at the top of the Internals Reference page for each interface having a `details` property.

> `direction` (direction):

>   `ly:beam::calc-direction`

>   If `side-axis` is `0` (or `X`), then this property determines whether the object is placed `LEFT`, `CENTER` or `RIGHT` with respect to the other object. Otherwise, it determines whether the object is placed `UP`, `CENTER` or `DOWN`. Numerical values may also be used: `UP`=`1`, `DOWN`=`-1`, `LEFT`=`-1`, `RIGHT`=`1`, `CENTER`=`0`.

> `font-family` (symbol):

>   `'roman`

>   The font family is the broadest category for selecting text fonts. Options include: `sans`, `roman`.

> `gap` (dimension, in staff space):

>   `0.8`

>   Size of a gap in a variable symbol.

> `neutral-direction` (direction):

>   `-1`

>   Which direction to take in the center of the staff.

> `normalized-endpoints` (pair):

>   `ly:spanner::calc-normalized-endpoints`

>   Represents left and right placement over the total spanner, where the width of the spanner is normalized between 0 and 1.

> `positions` (pair of numbers):

>   `beam::place-broken-parts-individually`

>   Pair of staff coordinates `(start . end)`, where start and end are vertical positions in `staff-space` units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

> `stencil` (stencil):

>   `ly:beam::print`

>   The symbol to print.

> `transparent` (boolean):

>   `#<procedure #f (grob)>`

>   This makes the grob invisible.

> `vertical-skylines` (pair of skylines):

>   `#<unpure-pure-container #<primitive-procedure ly:grob::vertical-skylines-from-stencil> #<primitive-procedure ly:grob::pure-simple-vertical-skylines-from-extents> >`

>   Two skylines, one above and one below this grob.

> `X-positions` (pair of numbers):

>   `ly:beam::calc-x-positions`

>   Pair of X staff coordinates of a spanner in the form `(left . right)`, where both left and right are in `staff-space` units of the current staff.

This object supports the following interface(s): beam-interface, grob-interface, spanner-interface, staff-symbol-referencer-interface and unbreakable-spanner-interface.

#### Internals Reference v2.22.2 (stable-branch).