Optionaloptions: FormatterOptionsProtectedcontextProtecteddurationProtectedformatterProtectedhasProtectedjustifyProtectedlossProtectedminProtectedmodifierProtectedtickProtectedtotalProtectedtotalProtectedvoicesStaticDEBUGFind all the rests in each of the voices and align them vertically to neighboring notes.
If false, only align rests within beamed groups of notes. If true, align all rests.
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.alignRests
to true to enable rest vertical alignment.
OptionaljustifyWidth: numberOptionaloptions: FormatParamsOptionaloptionsParam: FormatParamsGet minimum width required to render all voices. Either format or
preCalculateMinTotalWidth must be called before this method.
Get the AlignmentContexts of TickContexts that were created by createTickContexts. Returns undefined if createTickContexts has not yet been run.
Take all voices and create ModifierContexts out of them. This tells
the formatters that the voices belong on a single stave.
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.
Note: joinVoices has to be called before calling preCalculateMinTotalWidth.
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 retrieve widths without a canvas. This method sets the x positions
of all the tickables/notes in the formatter.
OptionalrenderingContext: RenderContextOptionalvoicesParam: Voice[]Optionalstave: StaveRun 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.
Optionaloptions: { alpha?: number }parameters for tuning, currently just "alpha".
StaticAlignAutomatically 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.
OptionalalignTuplets: booleanIf false, ignores tuplets.
StaticFormatHelper 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.)
Optionalparams: boolean | FormatParamsone of below:
autoBeam only (context, stave, notes, true) or
(ctx, stave, notes, {autoBeam: true})alignRests a struct is needed (context, stave, notes, {alignRests: true})(context, stave, notes, { autoBeam: true, alignRests: true})autoBeam automatically generates beams for the notes.alignRests aligns rests with nearby notes.StaticFormatHelper function to format and draw aligned tab and stave notes in two separate staves.
the rendering context
a TabStave instance on which to render TabNotes.
a Stave instance on which to render Notes.
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.alignRests aligns rests with nearby notes.StaticgetStaticplotHelper function to plot formatter debug info.
Optionaloptions: { stavePadding: number }StaticSimpleHelper function to layout "notes" one after the other without regard for proportions. Useful for tests and debugging.
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
xvalues of the notes in each tick.See
tests/formatter_tests.tsfor usage examples. The helper functions included here (FormatAndDraw,FormatAndDrawTab) also serve as useful usage examples.