27 rules

Stems and flags

Which way does the stem go, and how long is it?

The most-asked question in notation and the one with the most exceptions. Direction pivots on the true middle line of the clef, chords follow the notehead furthest from it, beamed groups decide once for the whole group, and a shared stave overrides all of it with voice identity. Length is a formula, not a feel.

Breaks the readingCheckable from the score alone
A short note not adjacent to another short note in the same beat gets a flag; two or more in the same beat get a beam instead
Flags and beams are mutually exclusive renderings of sub-quarter-note duration: an isolated eighth/sixteenth surrounded by longer notes or rests takes a flag; two or more consecutive eighths/sixteenths within the same beamable beat-group take a beam, with flags suppressed.
Breaks the readingCheckable from the score alone
All notes under one beam share a single stem direction, computed from the whole group
A beam is a single connected line; every stem it touches must point the same way. Mixed up/down stems under one beam is not a permitted convention in common-practice notation. Beyond simple uniformity, Gould and Ross both describe the beam-level decision as taking the group's overall position relative to the middle line, not any single note's.
Breaks the readingCheckable from the score alone
Articulation marks always render above the notehead in Gradus, regardless of stem direction — a confirmed bug, not a rendering-library question
Default: an articulation mark (staccato dot, accent, tenuto, marcato, fermata, staccatissimo) is placed on the notehead side opposite the stem — below for a stem-up note, above for a stem-down note. Exception: when the notehead is outside the staff, the mark sits toward the staff regardless of stem direction.
Breaks the readingCheckable from the score alone
Chord stem direction follows the notehead furthest from the middle line, not simply the top note
For a chord, stem direction is decided by whichever notehead — top or bottom — sits furthest from the middle line, not 'use the top note.' Wrong exactly when a chord straddles the middle line asymmetrically (a bass note far below the staff paired with a treble note only just above the middle line).
Breaks the readingNeeds the rendered page
Flag count is fixed by duration: none for quarter/half/whole, one for eighth, two for sixteenth, three for thirty-second
Flag count is a direct function of duration relative to the quarter note: quarter and longer get no flag (unbeamed), eighth gets one, sixteenth gets two, thirty-second gets three.
Breaks the readingCheckable from the score alone
Grace notes always render stem-up in Gradus, regardless of pitch or clef — a confirmed, previously-unflagged bug distinct from the main-note pivot bug
A grace note's stem follows the same pitch-vs-middle-line rule as any other note (Gould/Read state no exception for grace notes' stem direction, only for their proportionally smaller size and shorter stem length).
Breaks the readingCheckable from the score alone
Non-SATB stem direction must be requested via VexFlow's auto_stem flag, not left to an omitted stem_direction default
Where no cross-voice disambiguation is needed, stem direction is pure pitch-vs-middle-line arithmetic with no exceptions — exactly the calculation VexFlow's own `StaveNote.calculateOptimalStemDirection` already performs when explicitly requested via `auto_stem: true`.
Breaks the readingNeeds both
Noteheads a second apart on one stem must be displaced to opposite sides, not overlapped
When a chord contains an interval of a second, the two noteheads cannot sit at the same horizontal position without colliding. One stays on the stem's normal (primary) side; the other is displaced to the opposite side. The notehead closer to the stem's own side stays in the primary column; its second-neighbor is bumped to the far side.
Breaks the readingNeeds the rendered page
Stem attaches to the correct side of the notehead for its direction
An up-stem attaches to the right side of the notehead and rises; a down-stem attaches to the left side and descends. Universal (Gould p.16-17, Read, Ross; SMuFL's `stemUpSE`/`stemDownNW` anchor points defined per notehead glyph).
Breaks the readingCheckable from the score alone
Stem direction is dictated by voice identity, not pitch, whenever two voices share a stave
When two independent voices are notated on one staff (SATB short score, two-voice counterpoint on one stave), stem direction is assigned by voice — upper voice always up, lower voice always down — regardless of relative pitch at any instant, including voice crossings.
Breaks the readingCheckable from the score alone
Stem direction pivot must equal the true middle line of the clef
A note's stem points down if the notehead is on or above the staff's middle line, and up if it is below the middle line. Stated identically by Gould (Behind Bars, Stems chapter, pp.16-19) and Read (Music Notation, Stems chapter). The middle line differs by clef: treble = B4, bass = D3, alto = C4 (middle C sits ON the alto middle line — the entire reason alto clef exists), tenor = A3.
Misleads the readerCheckable from the score alone
A slash through the grace note's stem distinguishes acciaccatura from appoggiatura — Gradus's schema cannot express either intent
A single small grace note with a diagonal slash through its stem means acciaccatura — played as fast as possible, before the beat, 'crushed' against the main note. The same grace note WITHOUT the slash means appoggiatura — a more deliberate, often on-the-beat, leaning note.
Misleads the readerCheckable from the score alone
Equidistant chord extremes default to stem down
When a chord's top and bottom notes are equally far from the middle line, the stem defaults down — the same default used for a single note sitting exactly on the middle line.
Misleads the readerNeeds both
Flags must not overlap ledger lines or staff lines illegibly
A flag on a stem whose far end lands near or among ledger lines can visually merge with those lines. Engraving practice compensates via the stem-length extension for far-out notes (see `stem-length-extension-for-ledger-line-notes`) so the flag has clear space.
Misleads the readerNeeds the rendered page
Standard stem length is one octave (3.5 staff spaces)
A stem on a notehead within or near the staff is drawn to a length of about one octave (3.5 staff spaces) from the notehead, scaled to the staff, not a fixed pixel length.
Misleads the readerNeeds the rendered page
Stem length under a beam is determined by the beam's slant, not the note's own standard/extended length
Within a beamed group, individual stem lengths vary along the beam's slope so every stem meets the (single, straight) beam line — the group's overall stem length is set by the extreme note (closest to or furthest from the beam), and every other note's stem is stretched or compressed to reach the same beam, not drawn to its own independent standard length.
Misleads the readerNeeds both
Stems lengthen for notes requiring several ledger lines, by a formula, not by feel
As a notehead moves further from the staff, its stem lengthens beyond the standard octave so the far end still reaches meaningfully toward the staff.
Misleads the readerNeeds both
Tie and slur curvature already follows stem direction automatically in VexFlow — which means it also inherits any stem-direction bug
A tie or slur curves away from the stem — above the notehead for a stem-down note, below for a stem-up note — so the curve doesn't cross or crowd the stem.
Misleads the readerCheckable from the score alone
Two or more grace notes before a main note should render as one beamed cluster, not separately flagged notes
When a main note is preceded by multiple grace notes, the conventional rendering beams them together under a single beam (with, in the acciaccatura case, only the first note carrying the slash) rather than giving each its own individual flag.
Misleads the readerNeeds both
Two voices coinciding in pitch and duration on a shared stave should share one notehead (or Gradus should deliberately choose the double-notehead alternative)
When two voices sharing a stave land on identical pitch for identical duration at the identical position, the traditional engraved convention is a single notehead with stems drawn in both directions, not two independent overlapping noteheads.
Misleads the readerNeeds both
Whole notes have no stem, so voice identity cannot be read from stem direction alone
Whole notes are never stemmed. On a shared stave where stem direction is normally the reader's voice cue, a whole note removes that cue — engravers compensate with horizontal notehead offset rather than any stem-based device.
Falls short of best practiceCheckable from the score alone
A flag hooks toward the notehead side matching its stem's direction — Up-variant glyph for up-stems, Down-variant for down-stems
SMuFL defines separate Up and Down glyph variants for every flagged duration (e.g. `flag8thUp` vs `flag8thDown`); the flag is not a single symmetric glyph reused for both directions — an up-stem note must render the Up variant hooking down-and-right from the stem tip, a down-stem note the Down variant hooking up-and-left.
Falls short of best practiceCheckable from the score alone
Beams break at rests (Gradus's pedagogical default)
A beam group does not extend across a rest — the rest breaks the beam, each side gets its own (shorter) beam or reverts to flags. Traditional default; some contemporary instrumental engraving (Stone) permits beaming through short rests, but that is a stylistic departure not appropriate for Gradus's pedagogical content.
Falls short of best practiceCheckable from the score alone
Open score uses natural pitch-based stems; short score forces stems by voice
When each voice of a polyphonic texture gets its own dedicated staff (open score — traditional fugue engraving), there is no cross-voice disambiguation problem, so stems follow the ordinary pitch-vs-middle-line rule with no forcing. Only when voices are compressed onto a shared staff (short score / SATB) does voice-identity override pitch.
Falls short of best practiceCheckable from the score alone
Rest vertical placement on a shared stave follows the same voice-separation axis as the forced stems, computed correctly
On a shared stave with two voices, rests for each voice are displaced to opposite sides of the staff's center (upper voice's rests higher, lower voice's rests lower) so simultaneous rests in both voices don't collide — mirroring, but logically independent of, the stem-direction convention.
Falls short of best practiceCheckable from the score alone
Stem shortening below the standard length has no code path in Gradus's current pipeline — treat any occurrence as a distinct, deliberate API call
In dense chord voicings, engravers occasionally trim a stem slightly for legibility, but never below a practical floor of roughly 2.5-3 staff-spaces.
Falls short of best practiceCheckable from the score alone
Stemlets are dormant because rests never appear inside a beam group here
A stemlet (a short stub stem on a rest inside an otherwise-beamed group, used to keep the beam visually continuous through the rest) is a real named convention, but only applies when beaming-through-rests is itself in use.

Loading…

A short note not adjacent to another short note in the same beat gets a flag; two or more in the same beat get a beam instead

All notes under one beam share a single stem direction, computed from the whole group

Articulation marks always render above the notehead in Gradus, regardless of stem direction — a confirmed bug, not a rendering-library question

Chord stem direction follows the notehead furthest from the middle line, not simply the top note

Flag count is fixed by duration: none for quarter/half/whole, one for eighth, two for sixteenth, three for thirty-second

Grace notes always render stem-up in Gradus, regardless of pitch or clef — a confirmed, previously-unflagged bug distinct from the main-note pivot bug

Non-SATB stem direction must be requested via VexFlow's auto_stem flag, not left to an omitted stem_direction default

Noteheads a second apart on one stem must be displaced to opposite sides, not overlapped

Stem attaches to the correct side of the notehead for its direction

Stem direction is dictated by voice identity, not pitch, whenever two voices share a stave

Stem direction pivot must equal the true middle line of the clef

A slash through the grace note's stem distinguishes acciaccatura from appoggiatura — Gradus's schema cannot express either intent

Equidistant chord extremes default to stem down

Flags must not overlap ledger lines or staff lines illegibly

Standard stem length is one octave (3.5 staff spaces)

Stem length under a beam is determined by the beam's slant, not the note's own standard/extended length

Stems lengthen for notes requiring several ledger lines, by a formula, not by feel

Tie and slur curvature already follows stem direction automatically in VexFlow — which means it also inherits any stem-direction bug

Two or more grace notes before a main note should render as one beamed cluster, not separately flagged notes

Two voices coinciding in pitch and duration on a shared stave should share one notehead (or Gradus should deliberately choose the double-notehead alternative)

Whole notes have no stem, so voice identity cannot be read from stem direction alone

A flag hooks toward the notehead side matching its stem's direction — Up-variant glyph for up-stems, Down-variant for down-stems

Beams break at rests (Gradus's pedagogical default)

Open score uses natural pitch-based stems; short score forces stems by voice

Rest vertical placement on a shared stave follows the same voice-separation axis as the forced stems, computed correctly

Stem shortening below the standard length has no code path in Gradus's current pipeline — treat any occurrence as a distinct, deliberate API call

Stemlets are dormant because rests never appear inside a beam group here