# Beaming Beaming can follow the meter, divide a beat into a chosen pattern, or join particular notes. The same native model retains the notes, their voices and their written durations through these different ways of controlling the beam. ## Choose the control that matches the music | You want to | Write | What it changes | | --- | --- | --- | | Follow the beat groups | Let the meter group the notes | Automatic beams within each voice | | Retain a rhythmic subdivision | `[beams pattern]` | The beam tree for the selected music | | Join particular notes | `[--]` at both endpoints | The connected notes and their beam membership | | Widen or narrow secondary beams | `[--<]` or `[-->]` at both endpoints | Feathering over the connected passage | ## Start with the meter Eighth notes in simple meter group by its beats. Compound and additive meters provide their own groups; rests normally stop a group. Each voice keeps its own policy, including several voices written on one staff. ```scorescript-input meter 6/8 8C5 D E F G A ``` A pickup uses the end of the full meter's grouping. Rests occupy their written place in that count. An ordinary partial bar counts from its own start; it is not automatically treated as a pickup. ## Shape the groups with a pattern Use counts to describe the rhythm, rather than marking each beam beginning and end. A plus cuts the primary beam; braces keep a group together while subdividing its deeper beams. Counts use eighth notes unless you state a different unit. A single count repeats across the bar, with the remainder last. ```scorescript-input meter 4/4 [beams 2] 8C5 D E F G A B C ``` This requests pairs of eighths. To keep all eight sixteenths under one primary beam but divide the secondary beam into pairs, write the subdivision: ```scorescript-input meter 2/4 [beams s8{2+2+2+2}] 16C5 D E F G A B C ``` The instruction belongs directly to this music. You only need measure addresses when applying a policy from elsewhere or coordinating a longer passage. ## Cut a group once Put `;` immediately before the note that starts a new group. It cuts every beam level before that note; it adds no bar, silence or time. ```scorescript meter 2/4 16C5 D ;E F 4r ``` C–D and E–F form separate groups. A cut on a note already starting its group has no extra effect. A cut that cannot apply to a beam receives the native notation diagnostic. For a division only in a deeper beam, use a subdivision pattern instead. ## Attach a beam to chosen notes `[--]` connects a beam to chosen note endpoints. A trailing marker opens; a leading marker closes, using the same attachment rule as other connectors: ```scorescript meter 4/8 8C4[--] D [--]E F ``` C, D and E share a beam. F remains outside the connection. Written durations still determine the number of ribbons; the two dashes do not mean two beams. The reader first looks for the matching open span in the same voice. If there is none, one unique unnamed opening elsewhere can pair across voices or staves. It never chooses between ambiguous simultaneous destinations by source order. Add an identifier to both ends when needed: `[--@1]`, `[--@2]`, or `[--@phrase]`. Omit the `@` entirely for automatic pairing; `[--@]` is incomplete. Names and numbers belong to their span type, so `[--@1]` and `[~@1]` can coexist. A name may be reused after its pair closes. Spaces inside a marker are accepted; the formatter removes unnecessary spaces. A closer may precede a grace prefix: `[--@1]/sD`. A cross-voice/staff beam edge selects its two endpoints; additional members need additional links. `[~]` / `[~@phrase]` explicitly connect a slur, and `[/]` / `[/@slide]` explicitly connect a glissando. These are not a new plain-line or slide-style control. The ordinary bare tilde keeps its same-pitch tie behavior. Feather and tremolo instructions are described in [Rhythm](rhythm.md). Beam connections continue across system breaks at every written beam level. Feathered connections keep their progress across the break. The layout setting `beam_continuation_length` controls each continuation's length in staff spaces (default 1.5; range 0.25–6). Individual `(stem-up)` and `(stem-down)` requests stay attached to their notes. Opposing stems can share a sloping beam when a horizontal one does not fit. The engraving style's rise and slope limits still apply. ## Beam patterns across measures A count measures time in the preceding duration unit. Units stay in force among siblings; a child inherits its parent's unit. Changing a unit inside one child leaves its parent's following siblings alone. ```scorescript-input meter 4/4 [beams s4{2+2}+s4{2+2}+e2+2{2}] 16C4 D E F G A B C D C B A G F E D ``` Here the first two groups last four sixteenths each; the last two last two eighths each. Expanded children fill their parent exactly. A short child list repeats its last group; pair shorthand finishes an odd total with three. `+` at the outer level cuts all beams. Each pair of nested braces moves that cut one beam deeper. Curly subdivisions such as `4{2+2}` are the formatter's spelling: braces collect a count's children, while square brackets identify an inline instruction. A square child container is an error; use `8{4+4}`, never `8[4+4]`. An instruction around a passage already stands outside its music, so it needs no extra square wrapper. The music brace is separated from the pattern and opens on that same physical line: ```scorescript-input meter 1/8 beams {m1-2 ss8{8{4+4}}} 32C4 D E F | G F E D ``` The same pattern can live in the top map as `beams {m1-2 ss8{8{4+4}}}`, or in `at m1-2 { beams ss8{8{4+4}} }`. A range supplies its own complete-pattern meaning; a bare unaddressed header remains the meter's default grouping. Wrap a continuing row to give it one complete pattern: ```scorescript-input meter 2/4 beams {m1-2 s16{8|m2+8}} 16C4 D E F G A B C | D, E F G A B C D ``` The primary beam crosses the barline; the second beam divides there. `|m2` checks the start of measure 2 without adding a cut. Remove it and the music is identical. `s16{16{8+8}}` moves the division to the third beam; use thirty-seconds (`ss`) or shorter notes to see that third beam. The same control can stand above the music: ```scorescript-input meter 2/4 beams {m1-2 s16{8|m2+8}} m1-2 { 16C4 D E F G A B C | D, E F G A B C D } ``` Or place it in `at m1-2 { beams s16{8+8} }`. A complete pattern must fill its range exactly, including meter changes and partial bars. A pattern on a part controls that player's measures; one at score level applies to every player. Nested ranges can override a smaller passage. Two crossing ranges at the same scope are an error. For per-bar control, `~` is written on both sides. Closed child lists stop the deeper beams at the barline: ```scorescript-input meter 2/4 [beams s8{8}~] 16C4 D E F G A B C | [beams ~s8{8}] D, E F G A B C D ``` A full-range pattern is often easier to read because its nested boundaries show the continuation directly. `maps=top` extracts inline beam and meter controls into maps. These forms describe the same timing and beam divisions; choose the one that keeps the music easiest to read. ### Independent voice maps A voice qualifier also works inside an inline instruction: `[beams v2 s8]` addresses voice 2 of this part, even when placed in voice 1's row. Without a qualifier, an inline instruction belongs to its own voice. Formatting between inline and top maps keeps that target. Inside a part, name the voice after the measure address: ```scorescript-input meter 4/8 parts { pno } pno treble { beams {m1 v1 s8{2}, m1 v2 s8{4}} m1 { v1 [ 16C5 D E F G A B C ] v2 [ 16C4 B A G F E D C ] } } pno bass { } ``` `at m1 { beams v2 s8{4} }` is the equivalent addressed form. A range such as `m1-2 v2 s16{8+8}` supplies one complete pattern for that voice across both bars. Score maps supply defaults, part maps refine them, and a voice's inline instructions take precedence. Extracting to top maps retains the voice name. For a beam between particular notes, a part can also declare `span beam phrase m1:0 m1:q auto`. Both offsets must name note attacks. `feather-grow` and `feather-shrink` select the corresponding feather shape. These statements use the same membership rules as bracketed node connectors. ## Filling a subdivision A short child list repeats its last group to fill the containing count: ```scorescript-input meter 4/8 [beams s8{2}] 16C5 D E F G A B C ``` `8{2}` means `8{2+2+2+2}`. `7{2}` means `7{2+2+3}`; `8{3+2}` means `8{3+2+3}`. A complete explicit list retains every authored boundary. Counts follow their duration prefix, not the number of notes. A finer or shorter final group can be stated explicitly. The reader refuses to clip a nested subdivision or invent a fractional count in its declared unit. ## Feathered beams Use `[--<]` to spread the secondary beams toward the end and `[-->]` to converge them. The primary beam stays continuous. ```scorescript-input meter 4/8 16C5[--<] D E F G F E [--<]D ``` As with other node connections, the trailing instruction opens the span and the leading instruction closes it. Duration letters determine beam depth. Connected beams retain their continuing levels at a system break, including one-note fragments. Feathered beams continue the same widening or narrowing through each system; the shape does not restart at the left margin. Feathering changes the printed spacing, preserving the authored note times. Use explicit durations or the existing tempo controls for playback changes. Feathering changes engraving; the source durations still control playback. ## Let a beam pass a rest Write `~r` to attach the short rest to the beam reaching it, `r~` to use the beam leaving it, or `~r~` for both sides. The side matters at a grouping boundary. A quarter rest has no beam depth and cannot take this control. A rest attached to a beam still has no sounding attack. ```scorescript-input meter 4/8 [beams e4] 8C5 ~r~ E F ``` See [tuplets and rests](rhythm.md) for the interaction with a tuplet bracket. ## Keep stems with their notes `(stem-up)` and `(stem-down)` stay on their own notes. Opposing stems can share a sloping common rail when a level beam cannot fit. The engraver still respects the style's stem-length, rise and slope limits. ```scorescript-input meter 2/8 8C4(stem-up)[--] [--]8D5(stem-down) | 8D5(stem-down)[--] [--]8C4(stem-up) ``` Use the instrument's [staff routing](context.md) for a piano passage that changes physical staff. A staff change retains the notes' player and voice. A cross-voice edge does not collect every note between its endpoints: add the required connections explicitly. ## Hooks at the ends of a group A fractional secondary beam at the first or last note points inward, toward the group. Interior hooks follow the beat grouping. The policy applies to upward and downward stems, compound meters, rests and authored groups. A hook is not another note and does not change the performed rhythm. ## Through system breaks Connected beams retain their continuing levels through a system break, including one-note fragments at an edge. A feather keeps its progress across the break instead of restarting on each system. The native layout setting `beam_continuation_length` controls the extension in staff spaces (default 1.5; supported range 0.25–6). A layout break does not add a musical break. ## Explicit beam marks (reference) Older `(beam-break)` marks remain accepted and mean the same cut as `;` before their carrying note. For example, `8C5 D(beam-break) E F 2r` is `8C5 ;D E F 2r`. The semicolon is the concise form for a local cut. `(beam-begin)` and `(beam-end)` also retain an explicitly joined run. A break inside that run still cuts it. Unmatched endpoints and cuts that cannot be drawn, including an unsuitable rest or paired tremolo, receive a diagnostic. For a division at only a deeper beam level, use a recursive pattern. ## MusicXML interchange A run within one voice exports as beams at each depth. Routing that voice between staves remains a cross-staff beam. Feathering within a representable run uses MusicXML's fan control. A beam joining different voices or instrument parts cannot be expressed as one MusicXML beam. Export retains representable same-voice stretches and reports the missing crossing. ScoreScript metadata preserves the crossing for a return trip into ScoreScript; another notation tool may not draw it. Deep native durations and paired tremolos have further format limits. Review conversion diagnostics when exchanging a score. ## Depth, exact time and refusals Counts measure time in their duration unit, not printed note counts. Every extra `s` halves the duration. The native representation supports up to 28 `s` characters, 128 nested pattern containers and 16,384 count nodes, and 32 nested scoped beam blocks. MusicXML has narrower representational limits. A complete pattern must fill its exact meter and partial-bar range. Overflow, invalid subdivisions, crossing ranges, ambiguous endpoints and unavailable voices are diagnosed. The engine does not move an endpoint inside a held note or invent a fractional count to make the tree fit. Inspect diagnostics and the rendered result together for dense passages.