Optional options: FormatterOptionsStatic DEBUGFind 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.
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.
Optional justifyWidth: numberOptional options: FormatParamsOptional optionsParam: FormatParamsGet the AlignmentContexts of TickContexts that were created by createTickContexts. Returns undefined if createTickContexts has not yet been run.
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.
Optional renderingContext: RenderContextOptional voicesParam: Voice[]Optional stave: 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.
Optional options: { Optional alpha?: numberStatic AlignAutomatically 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.
Optional alignTuplets: booleanIf false, ignores tuplets.
Static FormatHelper 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.)
Optional params: boolean | FormatParamsone 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.Static FormatHelper 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.align_rests aligns rests with nearby notes.Static SimpleHelper function to layout "notes" one after the other without regard for proportions. Useful for tests and debugging.
Static getCalculate the resolution multiplier for voices.
Static plotHelper function to plot formatter debug info.
Optional options: {
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.