alphaTab.EngravingSettings

This class holds all all spacing, thickness and scaling metrics related to engraving the music notation. While general layout settings are configurable via the display settings, these settings go deeper into how the individual music symbols are scaled and aligned targeting specification compliance with the Standard Music Font Layout (SMuFL).

Unless specified differently the settings here are available since 1.7.0

If properties are marked with a SMuFl tag, it means that the values are part of the SMuFL specification and should be filled from the respective metadata files shipped with the fonts or aligned generally with the specification. Other properties are custom to alphaTab.

In SmuFL Sizes and coordinates are expressed in "staff space" units which is 1/4 of the configured font size. In this data structure the values are converted to pixels.

 class EngravingSettings

Properties

accidentalPadding

The horizontal padding between individual accidentals when multiple ones are applied.

JavaScript

accidentalPadding: number;

C#

double AccidentalPadding { get; set; }

Kotlin

var accidentalPadding: Double

alternateEndingsPadding

The padding used for aligning the alternate ending brackets and texts.

JavaScript

alternateEndingsPadding: number;

C#

double AlternateEndingsPadding { get; set; }

Kotlin

var alternateEndingsPadding: Double

arrowShaftThickness

The thickness of the line used for the shaft of an arrow

JavaScript

arrowShaftThickness: number;

C#

double ArrowShaftThickness { get; set; }

Kotlin

var arrowShaftThickness: Double

barlineContentPadding

The minimum horizontal padding between the content of the last beat in a bar and the bar line. Additional space is only added where the content would come closer than this. Behind Bars: stems must never come closer to a barline than one stave-space.

JavaScript

barlineContentPadding: number;

C#

double BarlineContentPadding { get; set; }

Kotlin

var barlineContentPadding: Double

barlineSeparation

The default distance between multiple thin barlines when locked together, e.g. between two thin barlines making a double barline, measured from the right-hand edge of the left barline to the left-hand edge of the right barline.

JavaScript

barlineSeparation: number;

C#

double BarlineSeparation { get; set; }

Kotlin

var barlineSeparation: Double

beamSpacing

The distance between the inner edge of the primary and outer edge of subsequent secondary beams

JavaScript

beamSpacing: number;

C#

double BeamSpacing { get; set; }

Kotlin

var beamSpacing: Double

beamThickness

The thickness of a beam

JavaScript

beamThickness: number;

C#

double BeamThickness { get; set; }

Kotlin

var beamThickness: Double

beatContentPadding

The minimum horizontal padding between the content of two adjacent beats (e.g. a notehead and the accidental or grace notes of the following beat). Additional space is only added between beats where their content would come closer than this. Behind Bars: where space is limited, characters should not be closer than 1/2 stave-space and never collide.

JavaScript

beatContentPadding: number;

C#

double BeatContentPadding { get; set; }

Kotlin

var beatContentPadding: Double

beatTimerPadding

The padding between the border and text of beat timers.

JavaScript

beatTimerPadding: number;

C#

double BeatTimerPadding { get; set; }

Kotlin

var beatTimerPadding: Double

bendNoteHeadElementPadding

The additional padding applied to helper note heads shown on bends.

JavaScript

bendNoteHeadElementPadding: number;

C#

double BendNoteHeadElementPadding { get; set; }

Kotlin

var bendNoteHeadElementPadding: Double

bracketThickness

The thickness of the vertical line of a bracket grouping staves together

JavaScript

bracketThickness: number;

C#

double BracketThickness { get; set; }

Kotlin

var bracketThickness: Double

bravuraDefaults

A EngravingSettings copy filled with the settings of the Bravura font used by default in alphaTab.

JavaScript

static readonly bravuraDefaults: EngravingSettings;

C#

static EngravingSettings BravuraDefaults { get; }

Kotlin

companion object { val bravuraDefaults: EngravingSettings }

bravuraMetadata

(no description)

JavaScript

static readonly bravuraMetadata: SmuflMetadata;

C#

static SmuflMetadata BravuraMetadata { get; }

Kotlin

companion object { val bravuraMetadata: SmuflMetadata }

brokenBeamWidth

The width of broken beams e.g. when combining a 32nd and 16th note

JavaScript

brokenBeamWidth: number;

C#

double BrokenBeamWidth { get; set; }

Kotlin

var brokenBeamWidth: Double

chordDiagramFretHeight

The height of the individual fret lines.

JavaScript

chordDiagramFretHeight: number;

C#

double ChordDiagramFretHeight { get; set; }

Kotlin

var chordDiagramFretHeight: Double

chordDiagramFretSpacing

The spacing between frets on chord diagrams.

JavaScript

chordDiagramFretSpacing: number;

C#

double ChordDiagramFretSpacing { get; set; }

Kotlin

var chordDiagramFretSpacing: Double

chordDiagramLineWidth

The width of all other lines drawn on chord diagrams.

JavaScript

chordDiagramLineWidth: number;

C#

double ChordDiagramLineWidth { get; set; }

Kotlin

var chordDiagramLineWidth: Double

chordDiagramNutHeight

The height of the nut on chord diagrams..

JavaScript

chordDiagramNutHeight: number;

C#

double ChordDiagramNutHeight { get; set; }

Kotlin

var chordDiagramNutHeight: Double

chordDiagramPaddingX

The horizontal padding applied to individual chord diagrams.

JavaScript

chordDiagramPaddingX: number;

C#

double ChordDiagramPaddingX { get; set; }

Kotlin

var chordDiagramPaddingX: Double

chordDiagramPaddingY

The vertical padding applied to individual chord diagrams.

JavaScript

chordDiagramPaddingY: number;

C#

double ChordDiagramPaddingY { get; set; }

Kotlin

var chordDiagramPaddingY: Double

chordDiagramStringSpacing

The spacing between strings on chord diagrams.

JavaScript

chordDiagramStringSpacing: number;

C#

double ChordDiagramStringSpacing { get; set; }

Kotlin

var chordDiagramStringSpacing: Double

dashedBarlineDashLength

The length of the dashes to be used in a dashed barline

JavaScript

dashedBarlineDashLength: number;

C#

double DashedBarlineDashLength { get; set; }

Kotlin

var dashedBarlineDashLength: Double

dashedBarlineGapLength

The length of the gap between dashes in a dashed barline

JavaScript

dashedBarlineGapLength: number;

C#

double DashedBarlineGapLength { get; set; }

Kotlin

var dashedBarlineGapLength: Double

dashedBarlineThickness

The thickness of a dashed barline

JavaScript

dashedBarlineThickness: number;

C#

double DashedBarlineThickness { get; set; }

Kotlin

var dashedBarlineThickness: Double

deadSlappedLineWidth

The width of the lines drawn for dead slapped beats.

JavaScript

deadSlappedLineWidth: number;

C#

double DeadSlappedLineWidth { get; set; }

Kotlin

var deadSlappedLineWidth: Double

directionsScale

The relative scale of any directions glyphs drawn like coda or segno.

JavaScript

directionsScale: number;

C#

double DirectionsScale { get; set; }

Kotlin

var directionsScale: Double

ghostParenthesisPadding

The padding between the parenthesis and wrapped elements on ghost notes and free time time signatures

JavaScript

ghostParenthesisPadding: number;

C#

double GhostParenthesisPadding { get; set; }

Kotlin

var ghostParenthesisPadding: Double

ghostParenthesisWidth

The width of the parenthesis shown on ghost notes and free time time signatures.

JavaScript

ghostParenthesisWidth: number;

C#

double GhostParenthesisWidth { get; set; }

Kotlin

var ghostParenthesisWidth: Double

glyphBottom

A lookup containing the offset from the glyph center to the visual bottom of the glyph. The glyph center is the origin coordinate at which the glyph paths start when drawn on the alphabetic baseline.

JavaScript

glyphBottom: Map<MusicFontSymbol, number>;

C#

Map<MusicFontSymbol, double> GlyphBottom { get; set; }

Kotlin

var glyphBottom: alphaTab.collections.ObjectDoubleMap<MusicFontSymbol, Double>

glyphHeights

A lookup for the heights of the visual bounding box for the glyphs.

JavaScript

glyphHeights: Map<MusicFontSymbol, number>;

C#

Map<MusicFontSymbol, double> GlyphHeights { get; set; }

Kotlin

var glyphHeights: alphaTab.collections.ObjectDoubleMap<MusicFontSymbol, Double>

glyphTop

A lookup containing the offset from the visual top to the glyph center. The glyph center is the origin coordinate at which the glyph paths start when drawn on the alphabetic baseline.

JavaScript

glyphTop: Map<MusicFontSymbol, number>;

C#

Map<MusicFontSymbol, double> GlyphTop { get; set; }

Kotlin

var glyphTop: alphaTab.collections.ObjectDoubleMap<MusicFontSymbol, Double>

glyphWidths

A lookup for the widths of the visual bounding box for the glyphs.

JavaScript

glyphWidths: Map<MusicFontSymbol, number>;

C#

Map<MusicFontSymbol, double> GlyphWidths { get; set; }

Kotlin

var glyphWidths: alphaTab.collections.ObjectDoubleMap<MusicFontSymbol, Double>

hairpinThickness

The thickness of a crescendo/diminuendo hairpin

JavaScript

hairpinThickness: number;

C#

double HairpinThickness { get; set; }

Kotlin

var hairpinThickness: Double

leftHandTabTieWidth

The width of ties drawn for left-hand-tapped notes.

JavaScript

leftHandTabTieWidth: number;

C#

double LeftHandTabTieWidth { get; set; }

Kotlin

var leftHandTabTieWidth: Double

legerLineExtension

The amount by which a leger line should extend either side of a notehead, scaled proportionally with the notehead's size, e.g. when scaled down as a grace note

JavaScript

legerLineExtension: number;

C#

double LegerLineExtension { get; set; }

Kotlin

var legerLineExtension: Double

legerLineThickness

The thickness of a leger line (normally somewhat thicker than a staff line)

JavaScript

legerLineThickness: number;

C#

double LegerLineThickness { get; set; }

Kotlin

var legerLineThickness: Double

lineRangedGlyphDashGap

The gap between dashes on line ranged glyphs (like let-ring)

JavaScript

lineRangedGlyphDashGap: number;

C#

double LineRangedGlyphDashGap { get; set; }

Kotlin

var lineRangedGlyphDashGap: Double

lineRangedGlyphDashSize

The size between dashes on line ranged glyphs (like let-ring)

JavaScript

lineRangedGlyphDashSize: number;

C#

double LineRangedGlyphDashSize { get; set; }

Kotlin

var lineRangedGlyphDashSize: Double

multiVoiceDisplacedNoteHeadSpacing

The spacing between displaced displaced note heads in case of multi-voice note head overlaps.

JavaScript

multiVoiceDisplacedNoteHeadSpacing: number;

C#

double MultiVoiceDisplacedNoteHeadSpacing { get; set; }

Kotlin

var multiVoiceDisplacedNoteHeadSpacing: Double

musicFontSize

The font size of the music font in pixel.

JavaScript

musicFontSize: number;

C#

double MusicFontSize { get; set; }

Kotlin

var musicFontSize: Double

numberedBarRendererBarSize

The size of the bars drawn in numbered notation to indicate the durations.

JavaScript

numberedBarRendererBarSize: number;

C#

double NumberedBarRendererBarSize { get; set; }

Kotlin

var numberedBarRendererBarSize: Double

numberedBarRendererBarSpacing

The spacing between the bars drawn in numbered notation to indicate the durations.

JavaScript

numberedBarRendererBarSpacing: number;

C#

double NumberedBarRendererBarSpacing { get; set; }

Kotlin

var numberedBarRendererBarSpacing: Double

numberedDashGlyphPadding

The padding minimum between the duration dashes.

JavaScript

numberedDashGlyphPadding: number;

C#

double NumberedDashGlyphPadding { get; set; }

Kotlin

var numberedDashGlyphPadding: Double

numberedDashGlyphWidth

The width of the dashed drawn in numbered notation to indicate the durations.

JavaScript

numberedDashGlyphWidth: number;

C#

double NumberedDashGlyphWidth { get; set; }

Kotlin

var numberedDashGlyphWidth: Double

octaveLineThickness

The thickness of the dashed line used for an octave line

JavaScript

octaveLineThickness: number;

C#

double OctaveLineThickness { get; set; }

Kotlin

var octaveLineThickness: Double

oneStaffSpace

The staff space in pixel

JavaScript

oneStaffSpace: number;

C#

double OneStaffSpace { get; set; }

Kotlin

var oneStaffSpace: Double

onNoteEffectPadding

The padding between effects and glyphs placed above/blow the note heads e.g. staccato

JavaScript

onNoteEffectPadding: number;

C#

double OnNoteEffectPadding { get; set; }

Kotlin

var onNoteEffectPadding: Double

pedalLineThickness

The thickness of the line used for piano pedaling

JavaScript

pedalLineThickness: number;

C#

double PedalLineThickness { get; set; }

Kotlin

var pedalLineThickness: Double

postNoteEffectPadding

The padding between effects and glyphs placed after the note heads, e.g. slides or bends

JavaScript

postNoteEffectPadding: number;

C#

double PostNoteEffectPadding { get; set; }

Kotlin

var postNoteEffectPadding: Double

preBeatGlyphSpacing

The padding between glyphs shown before any beats e.g. clefs and time signatures

JavaScript

preBeatGlyphSpacing: number;

C#

double PreBeatGlyphSpacing { get; set; }

Kotlin

var preBeatGlyphSpacing: Double

preNoteEffectPadding

The padding between effects and glyphs placed before the note heads, e.g. accidentals or brushes

JavaScript

preNoteEffectPadding: number;

C#

double PreNoteEffectPadding { get; set; }

Kotlin

var preNoteEffectPadding: Double

repeatBarlineDotSeparation

The default horizontal distance between the dots and the inner barline of a repeat barline, measured from the edge of the dots to the edge of the barline.

JavaScript

repeatBarlineDotSeparation: number;

C#

double RepeatBarlineDotSeparation { get; set; }

Kotlin

var repeatBarlineDotSeparation: Double

repeatEndingLineThickness

The thickness of the brackets drawn to indicate repeat endings

JavaScript

repeatEndingLineThickness: number;

C#

double RepeatEndingLineThickness { get; set; }

Kotlin

var repeatEndingLineThickness: Double

repeatOffsetX

Holds the x-coordinate offsets for glyphs which are drawn repeatedly (like vibrato waves).

JavaScript

repeatOffsetX: Map<MusicFontSymbol, number>;

C#

Map<MusicFontSymbol, double> RepeatOffsetX { get; set; }

Kotlin

var repeatOffsetX: alphaTab.collections.ObjectDoubleMap<MusicFontSymbol, Double>

rowContainerGap

The innter gap for glyphs arranged in a grid like fashion, like the tunings and chord diagrams.

JavaScript

rowContainerGap: number;

C#

double RowContainerGap { get; set; }

Kotlin

var rowContainerGap: Double

rowContainerPadding

The outer padding for glyphs arranged in a grid like fashion, like the tunings and chord diagrams.

JavaScript

rowContainerPadding: number;

C#

double RowContainerPadding { get; set; }

Kotlin

var rowContainerPadding: Double

simpleSlideHeight

The height of simple slides like slide out down which do slide to a defined target note.

JavaScript

simpleSlideHeight: number;

C#

double SimpleSlideHeight { get; set; }

Kotlin

var simpleSlideHeight: Double

simpleSlideWidth

The width of simple slides like slide out down which do slide to a defined target note.

JavaScript

simpleSlideWidth: number;

C#

double SimpleSlideWidth { get; set; }

Kotlin

var simpleSlideWidth: Double

slurMidpointThickness

The thickness of the mid-point of a slur (i.e. its thickest point)

JavaScript

slurMidpointThickness: number;

C#

double SlurMidpointThickness { get; set; }

Kotlin

var slurMidpointThickness: Double

songBookWhammyDipHeight

The height of simple dip whammys when using the songbook mode.

JavaScript

songBookWhammyDipHeight: number;

C#

double SongBookWhammyDipHeight { get; set; }

Kotlin

var songBookWhammyDipHeight: Double

staffContentPadding

The minimum vertical padding between the content of two adjacent staves (e.g. a stem below one staff and a fret number above the next one). Additional space is only added between staves where their content would come closer than this. Behind Bars: characters should not be closer than 1/2 stave-space and never collide.

JavaScript

staffContentPadding: number;

C#

double StaffContentPadding { get; set; }

Kotlin

var staffContentPadding: Double

staffLineThickness

The thickness of each staff line

JavaScript

staffLineThickness: number;

C#

double StaffLineThickness { get; set; }

Kotlin

var staffLineThickness: Double

standardStemLength

The standard stem length of a quarter note.

JavaScript

standardStemLength: number;

C#

double StandardStemLength { get; set; }

Kotlin

var standardStemLength: Double

stemDown

Holds information about where to place downwards pointing stems on glyphs.

JavaScript

stemDown: Map<MusicFontSymbol, EngravingStemInfo>;

C#

Map<MusicFontSymbol, EngravingStemInfo> StemDown { get; set; }

Kotlin

var stemDown: alphaTab.collections.Map<MusicFontSymbol, EngravingStemInfo>

stemFlagHeight

The space needed by flags on the stem-side from top to bottom to place.

JavaScript

stemFlagHeight: Map<Duration, number>;

C#

Map<Duration, double> StemFlagHeight { get; set; }

Kotlin

var stemFlagHeight: alphaTab.collections.ObjectDoubleMap<Duration, Double>

stemFlagOffsets

The additional offsets stems need to have enough space for flags.

JavaScript

stemFlagOffsets: Map<Duration, number>;

C#

Map<Duration, double> StemFlagOffsets { get; set; }

Kotlin

var stemFlagOffsets: alphaTab.collections.ObjectDoubleMap<Duration, Double>

stemThickness

The thickness of a stem

JavaScript

stemThickness: number;

C#

double StemThickness { get; set; }

Kotlin

var stemThickness: Double

stemUp

Holds information about where to place upwards pointing stems on glyphs.

JavaScript

stemUp: Map<MusicFontSymbol, EngravingStemInfo>;

C#

Map<MusicFontSymbol, EngravingStemInfo> StemUp { get; set; }

Kotlin

var stemUp: alphaTab.collections.Map<MusicFontSymbol, EngravingStemInfo>

stringNumberCirclePadding

The padding between the circles around string numbers.

JavaScript

stringNumberCirclePadding: number;

C#

double StringNumberCirclePadding { get; set; }

Kotlin

var stringNumberCirclePadding: Double

sustainPedalLinePadding

The padding between the sustain pedal glyphs and lines.

JavaScript

sustainPedalLinePadding: number;

C#

double SustainPedalLinePadding { get; set; }

Kotlin

var sustainPedalLinePadding: Double

tabBendDashSize

The size of the dashes on bends (e.g. on holds)

JavaScript

tabBendDashSize: number;

C#

double TabBendDashSize { get; set; }

Kotlin

var tabBendDashSize: Double

tabBendLabelPadding

The padding applied between the line and text of bends.

JavaScript

tabBendLabelPadding: number;

C#

double TabBendLabelPadding { get; set; }

Kotlin

var tabBendLabelPadding: Double

tabBendPerValueHeight

The height applied per quarter-note.

JavaScript

tabBendPerValueHeight: number;

C#

double TabBendPerValueHeight { get; set; }

Kotlin

var tabBendPerValueHeight: Double

tabBendStaffPadding

The additional padding between the staff and the point where bend values are calculated from.

JavaScript

tabBendStaffPadding: number;

C#

double TabBendStaffPadding { get; set; }

Kotlin

var tabBendStaffPadding: Double

tabLineSpacing

The staff space in pixel for tablature fonts. This is typically 1.5 of the standard staff space.

JavaScript

tabLineSpacing: number;

C#

double TabLineSpacing { get; set; }

Kotlin

var tabLineSpacing: Double

tabWhammyDashSize

The size of the dashes on whammys (e.g. on holds)

JavaScript

tabWhammyDashSize: number;

C#

double TabWhammyDashSize { get; set; }

Kotlin

var tabWhammyDashSize: Double

tabWhammyPerHalfHeight

The height applied per half-note whammy.

JavaScript

tabWhammyPerHalfHeight: number;

C#

double TabWhammyPerHalfHeight { get; set; }

Kotlin

var tabWhammyPerHalfHeight: Double

tabWhammyTextPadding

The padding between the text and whammy lines.

JavaScript

tabWhammyTextPadding: number;

C#

double TabWhammyTextPadding { get; set; }

Kotlin

var tabWhammyTextPadding: Double

tempoNoteScale

The relative scale of the note drawn on tempo markers

JavaScript

tempoNoteScale: number;

C#

double TempoNoteScale { get; set; }

Kotlin

var tempoNoteScale: Double

thickBarlineThickness

The thickness of a thick barline, e.g. in a final barline or a repeat barline

JavaScript

thickBarlineThickness: number;

C#

double ThickBarlineThickness { get; set; }

Kotlin

var thickBarlineThickness: Double

thinBarlineThickness

The thickness of a dashed barline

JavaScript

thinBarlineThickness: number;

C#

double ThinBarlineThickness { get; set; }

Kotlin

var thinBarlineThickness: Double

thinThickBarlineSeparation

The default distance between a pair of thin and thick barlines when locked together, e.g. between the thin and thick barlines making a final barline, or between the thick and thin barlines making a start repeat barline.

JavaScript

thinThickBarlineSeparation: number;

C#

double ThinThickBarlineSeparation { get; set; }

Kotlin

var thinThickBarlineSeparation: Double

tieHeight

The height of ties.

JavaScript

tieHeight: number;

C#

double TieHeight { get; set; }

Kotlin

var tieHeight: Double

tieMidpointThickness

The thickness of the mid-point of a tie

JavaScript

tieMidpointThickness: number;

C#

double TieMidpointThickness { get; set; }

Kotlin

var tieMidpointThickness: Double

tripletFeelBracketPadding

The padding between the bracket lines and numbers of tuplets

JavaScript

tripletFeelBracketPadding: number;

C#

double TripletFeelBracketPadding { get; set; }

Kotlin

var tripletFeelBracketPadding: Double

tuningGlyphCircleNumberScale

The scale of string numbers shown on tuning glyphs.

JavaScript

tuningGlyphCircleNumberScale: number;

C#

double TuningGlyphCircleNumberScale { get; set; }

Kotlin

var tuningGlyphCircleNumberScale: Double

tuningGlyphStringColumnScale

The scale factor applied to the width of the columns of string on tuning glyphs.

JavaScript

tuningGlyphStringColumnScale: number;

C#

double TuningGlyphStringColumnScale { get; set; }

Kotlin

var tuningGlyphStringColumnScale: Double

tuningGlyphStringRowPadding

The padding between rows of strings on tuning glyphs.

JavaScript

tuningGlyphStringRowPadding: number;

C#

double TuningGlyphStringRowPadding { get; set; }

Kotlin

var tuningGlyphStringRowPadding: Double

tupletBracketThickness

The thickness of the brackets drawn either side of tuplet numbers

JavaScript

tupletBracketThickness: number;

C#

double TupletBracketThickness { get; set; }

Kotlin

var tupletBracketThickness: Double

Methods

fillFromSmufl

Fills the engraving settings from the provided smufl metdata.

JavaScript

fillFromSmufl(smufl: SmuflMetadata, musicFontSize?: number): void

C#

void FillFromSmufl(SmuflMetadata smufl, double? musicFontSize)

Kotlin

fun fillFromSmufl(smufl: SmuflMetadata, musicFontSize: Double?): Unit

Parameter	Summary
smuflAll	The metadata shipped together with the SMuFL fonts.
musicFontSizeAll	The font size to configure in alphaTab for the music font.

getStemLength

Calculates the stem height for a note of the given duration.

JavaScript

getStemLength(duration: Duration, hasFlag: boolean): number

C#

double GetStemLength(Duration duration, bool hasFlag)

Kotlin

fun getStemLength(duration: Duration, hasFlag: Boolean): Double

Parameter	Summary
durationAll	The duration to calculate the height respecting flag sizes.
hasFlagAll	True if we need to respect flags, false if we have beams.

Returns

The total stem height