3.2.14 beam-interface

A beam.

The beam-thickness property is the weight of beams, measured in staffspace. The direction property is not user-serviceable. Use the direction property of Stem instead. The following properties may be set in the details list.


Demerit factor used for inappropriate stem lengths.


Demerit used in quanting calculations for multiple beams.


Size of region for checking quant scores.


Epsilon for beam quant code to check for presence in gap.


Penalty for differences in stem lengths on a beam.


Demerit penalty applied when beam direction is different from damping direction.


Demerit penalty applied when beam direction is different from damping direction, but damping slope is <= round-to-zero-slope.


Demerit scaling factor for difference between beam slope and music slope.


Demerit scaling factor for difference between beam slope and damping slope.


Damping slope which is considered zero for purposes of calculating direction penalties.

User settable properties:

auto-knee-gap (dimension, in staff space)

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)

Beam thickness, measured in staff-space units.

beamed-stem-shorten (list)

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)

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.

break-overshoot (pair of numbers)

How much does a broken spanner stick out of its bounds?

clip-edges (boolean)

Allow outward pointing beamlets at the edges of beams?

collision-interfaces (list)

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

collision-voice-only (boolean)

Does automatic beam collsion apply only to the voice in which the beam was created?

concaveness (number)

A beam is concave if its inner stems are closer to the beam than the two outside stems. This number is a measure of the closeness of the inner stems. It is used for damping the slope of the beam.

damping (number)

Amount of beam slope damping.

details (alist, with symbols as keys)

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)

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.

gap (dimension, in staff space)

Size of a gap in a variable symbol.

gap-count (integer)

Number of gapped beams for tremolo.

grow-direction (direction)

Crescendo or decrescendo?

inspect-quants (pair of numbers)

If debugging is set, set beam and slur position to a (quantized) position that is as close as possible to this value, and print the demerits for the inspected position in the output.

knee (boolean)

Is this beam kneed?

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

neutral-direction (direction)

Which direction to take in the center of the staff.

positions (pair of numbers)

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.

skip-quanting (boolean)

Should beam quanting be skipped?

X-positions (pair of numbers)

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.

Internal properties:

annotation (string)

Annotate a grob for debug purposes.

beam-segments (list)

Internal representation of beam segments.

covered-grobs (array of grobs)

Grobs that could potentially collide with a beam.

least-squares-dy (number)

The ideal beam slope, without damping.

normal-stems (array of grobs)

An array of visible stems.

quantized-positions (pair of numbers)

The beam positions after quanting.

shorten (dimension, in staff space)

The amount of space that a stem is shortened. Internally used to distribute beam shortening over stems.

stems (array of grobs)

An array of stem objects.

This grob interface is used in the following graphical object(s): Beam.

LilyPond – Internals Reference v2.24.3 (stable-branch).