Find all the rests in each of the voices
and align them to neighboring notes.
If false
, only align rests within beamed groups of notes. If true
, align all rests.
Create a ModifierContext
for each tick in voices
.
Create a TickContext
for each tick in voices
. Also calculate the
total number of ticks in voices.
Calculate the total cost of this formatting decision.
Align rests in voices, justify the contexts, and position the notes
so voices are aligned and ready to render onto the stave. This method
mutates the x
positions of all tickables in voices
.
Voices are full justified to fit in justifyWidth
pixels.
Set options.context
to the rendering context. Set options.align_rests
to true to enable rest alignment.
Get minimum width required to render all voices. Either format
or
preCalculateMinTotalWidth
must be called before this method.
This is the top-level call for all formatting logic completed
after x
and y
values have been computed for the notes
in the voices.
Estimate the width required to render 'voices'. This is done by:
The last 2 quantities estimate a 'width entropy', where notes might need more room than the proportional formatting gives them. A measure of all same duration and width will need no extra padding, and all these quantities will be zero in that case.
the voices that contain the notes
the estimated width in pixels
This is the core formatter logic. Format voices and justify them
to justifyWidth
pixels. renderingContext
is required to justify elements
that can't retreive widths without a canvas. This method sets the x
positions
of all the tickables/notes in the formatter.
Run a single iteration of rejustification. At a high level, this method calculates the overall "loss" (or cost) of this layout, and repositions tickcontexts in an attempt to reduce the cost. You can call this method multiple times until it finds and oscillates around a global minimum.
Automatically set the vertical position of rests based on previous/next note positions.
an array of Tickables.
If false
, only align rests that are within a group of beamed notes.
If false
, ignores tuplets.
Helper function to format and draw a single voice. Returns a bounding box for the notation.
the rendering context
the stave to which to draw (Stave
or TabStave
)
array of Note
instances (Note
, TextNote
, TabNote
, etc.)
one of below:
autobeam
only (context, stave, notes, true)
or
(ctx, stave, notes, {autobeam: true})
align_rests
a struct is needed (context, stave, notes, {align_rests: true})
(context, stave, notes, { autobeam: true, align_rests: true})
autobeam
automatically generates beams for the notes.align_rests
aligns rests with nearby notes.Helper function to format and draw aligned tab and stave notes in two separate staves.
the rendering context
a TabStave
instance on which to render TabNote
s.
a Stave
instance on which to render Note
s.
array of Note
instances for the tab stave (TabNote
, BarNote
, etc.)
array of Note
instances for the stave (Note
, BarNote
, etc.)
automatically generate beams.
a configuration object:
autobeam
automatically generates beams for the notes.align_rests
aligns rests with nearby notes.Helper function to layout "notes" one after the other without regard for proportions. Useful for tests and debugging.
Calculate the resolution multiplier for voices
.
Helper function to plot formatter debug info.
Format implements the formatting and layout algorithms that are used to position notes in a voice. The algorithm can align multiple voices both within a stave, and across multiple staves.
To do this, the formatter breaks up voices into a grid of rational-valued
ticks
, to which each note is assigned. Then, minimum widths are assigned to each tick based on the widths of the notes and modifiers in that tick. This establishes the smallest amount of space required for each tick.Finally, the formatter distributes the left over space proportionally to all the ticks, setting the
x
values of the notes in each tick.See
tests/formatter_tests.ts
for usage examples. The helper functions included here (FormatAndDraw
,FormatAndDrawTab
) also serve as useful usage examples.