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

`stem-length-demerit-factor`

  Demerit factor used for inappropriate stem lengths.

`secondary-beam-demerit`

  Demerit used in quanting calculations for multiple beams.

`region-size`

  Size of region for checking quant scores.

`beam-eps`

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

`stem-length-limit-penalty`

  Penalty for differences in stem lengths on a beam.

`damping-direction-penalty`

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

`hint-direction-penalty`

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

`musical-direction-factor`

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

`ideal-slope-factor`

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

`round-to-zero-slope`

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

#### User settable properties:

> `annotation` (string)

>   Annotate a grob for debug purposes.

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

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

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

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

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

> `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?

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

> `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?

> `damping` (number)

>   Amount of beam slope damping.

> `details` (list)

>   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 quants to this position, and print the respective scores.

> `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 `(left . right)`, where both left and right are 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:

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

#### Internals Reference v2.18.2 (稳定分支).