RenderAbc options
The renderAbc() call has a third parameter that is a list of options. It is not required. Any option that is not recognized is silently ignored. For example:
function callbackFn() {}
renderAbc("paper", abcString, { add_classes: true, clickListener: callbackFn });
accentAbove
Default: false
If true, then the accent mark (!>!) always goes above the note instead of being attached to the note head.
add_classes
Default: false
If true, then each element that is drawn on the SVG will have an identifying class with it that you can use to style, move, or hide the element. See the section on classes for more details.
afterParsing
Default: undefined
:::
Volatile
The contents of this is subject to change so if you use this function you will need to retest it whenever upgrading abcjs.
Callback function. If this is present then it is called right after the ABC string is parsed and before the music has started to display or be set up for audio.
This is useful if there is an extension to the parsing that you want to add.
function afterParsing(tune, tuneNumber, abcString)
tune: The object that is passed to both the renderer and the audio creator.
tuneNumber: Zero-based number of the tune. Useful if the abcstring contains more than one tune.
abcString: The original string that was passed in.
ariaLabel
Default: "Sheet Music" if no T: or "Sheet Music for %T" This is the text that is put in the <title> attribute of the svg.
clickListener
Default: null
Callback function. The signature of the function is: function(abcelem, tuneNumber, classes, analysis, drag) {}.
This is called whenever the user clicks on a note or selects a series of notes. For more details, see the page on the click listener.
dragColor
Default: same as selectionColor
This is the color of the elements currently being dragged.
dragging
See the dragging page for more information.
expandToWidest
Default: false
If you have a line of music that contains too many notes to fit in the staffwidth, then abcjs will do the best that it can and make that line as long as it needs to be. However, that will create a jagged edge on the right side because that line will push out farther than the others. To avoid that, you could set %%staffwidth 900 or whatever it takes, but then you would need to experiment to figure out the widest point. Instead, set this parameter and abcjs will find the widest then re-layout the other lines to that size.
foregroundColor
Default: currentColor
This sets the color of everything displayed. This can be overridden in CSS for particular elements. This color is applied to fill and stroke attributes.
format
Default: undefined
An object of any of the visual formatting options that can be specified with the %%option syntax in an ABC string.
For instance:
renderAbc("paper", "X:1\netc...", {
format: {
gchordfont: "Verdana 20",
partsbox: true
}
})
hint_measures
Default: false
Repeat the next measure at the end of the previous line, with a unique css class.
initialClef
Default: false
Show clef only on the first line.
jazzchords
Default: false
Format the chord symbols in a way that is sometimes found in fake books. The root of the chord (along with sharp or flat) is shown at the size that is specified. The rest of the chord is shown smaller and as a superscript. If there is a bass note, that is shown smaller and as a subscript.
For example, for the chord "F#m7b5/C#", F# is regular size, m7b5 is smaller and a superscript, and /C# is smaller and a subscript.
lineThickness
Default: 0
The amount to increase the line thickness - this is for the staff lines, the bar lines, the ledger lines, and the note stems. With some scaling, on some devices, and with some color schemes, the lines can appear thin so this is a way to tweak them.
A value of 0.3 is a nice place to start if you are experimenting with this.
germanAlphabet
Default: false
Display chords using German music alphabet. (H for English B and B for English Bb.) Several European countries have this music alphabet.
lineBreaks
Default: undefined
If you want to control exactly which measures are on each line, then you can pass this in. It is an array of numbers that represent the right-most measure number on a line (1-based). That is, if the first numbers passed are [ 3, 5, ... then the first line will have measures 1, 2, and 3 and the second line will have measures 4 and 5.
This parameter is primarily for the wrap mechanism to call internally, but it can be passed in if you have your own wrapping mechanism.
minPadding
Default: 0
The number of pixels that are added to the left of each staff item. This is not added to the fixed items at the beginning of the line (that is, clef, time signature and key signature) but is added to all other elements on the line. If the line is overly crowded the notes can't get any closer than this.
oneSvgPerLine
Default: false
Should each system of staves be rendered to a different SVG? This makes controlling with CSS easier, and makes it possible to paginate cleanly.
paddingbottom
Default: 30
The spacing that the music should have on the web page. This is in pixels.
paddingleft
Default: 15
The spacing that the music should have on the web page. This is in pixels.
paddingright
Default: 50
The spacing that the music should have on the web page. This is in pixels.
paddingtop
Default: 15
The spacing that the music should have on the web page. This is in pixels.
Default: false
Pay attention to margins and other formatting commands that don't make sense in a web page. This will display the header and footer, if specified, and try to lay out the music so that it can be printed cleanly.
responsive
Default: undefined
The strategy for responsiveness. The only option currently is "resize" which will make the svg take up whatever width is available for the container. For example:
<div style="width: 400px">
<div id="paper"></div>
</div>
renderAbc("paper", abcString, { responsive: "resize" })
This will scale the music down to fit in 400px, no matter what the original size was.
If you leave the width off and let the containing div change width with the browser width, you can see the music change size to accommodate changes in the browser width.
Note: a different strategy is the wrap parameter which changes the number of measures on a line depending on space. See the wrap section for details.
scale
Default: 1
If the number passed is between zero and one, then the music is printed smaller, if above one, then it is printed bigger.
scrollHorizontal
Default: false
Should there be a horizontal scrollbar if the music is wider than the viewport? (requires viewportHorizontal to be true.)
selectionColor
Default: "#ff0000"
This is the color of the note that the user has most recently clicked.
selectTypes
See the dragging page for more information.
showDebug
Default: []
This is an array of the types of debug information. It can be:
'grid'
This prints out lines showing where various parts of the music are calculated.
'box'
This prints a shaded box for each element. If you see elements either too far apart or too close together this will give you an idea of what is causing it.
stafftopmargin
Default: 0
This adds extra space to the top of each staff system. This is different from the directive systemsep because the latter specifies a minimum amount of space. This directive adds the specified space no matter what other space is used.
staffwidth
Default: 740
This is the width in pixels of the layout. It won't change where things are laid out, it will just change the amount of spacing between elements.
startingTune
Default: 0
The index of the tune in the tunebook to render (starting at zero for the first tune). This is only relevant if the abc string that is passed in contains multiple tunes.
textboxpadding
Default: 0.10
What percentage of the font size should the box that is drawn around the font be padded by?
timeBasedLayout
Default: undefined
{ minPadding?: number, minWidth?: number, align?: 'left' | 'center'}
This changes the horizontal spacing to be completely time-based. Normally, music is printed so that a whole note doesn't take up four times the space of a quarter note because that would create a lot of blank space. However, for some uses - for instance showing the music along with a timeline - that is desired.
To achieve this, first the line is scanned for the item that will take up the most space. For instance, if there is a sharp on a sixteenth note, that will take up more space than an eighth note. That is the minimum spacing that will be used.
The scale can be specified in two ways. If minPadding is passed in, then that is added to the minimum spacing. For instance, lets say that the largest item is a sixteenth note that is 15px wide. And minPadding: 5. Then all sixteenth notes will be 20px wide. All eighth notes will be 40px wide, etc.
If minWidth is set, then if the resultant size of the line is shorter than the specified width, extra space is added evenly to use up the space.
Either of those methods can be used by themselves. They also work together. For instance, if you pass in a width that is the width of the browser, then the music will take up the entire window. But if the width calculated by minPadding is larger than that, it will be used instead and there will be a horizontal scroll bar.
The notes can be placed either in the center of the area reserved or on the left side. If they are placed on the left side, they are offset by minPadding/2.
tablatures
Default: undefined
Add a tablature-style staff below the standard music output. See the tablature documentation for details.
viewportHorizontal
Default: false
Should the horizontal width be limited by the device's width?
viewportVertical
Default: false
visualTranspose
Default: 0
Transposes the written music by the number of half-steps passed. Use a negative number to transpose down in pitch.
wrap
Default: null
Tip
NOTE: this requires the parameter staffwidth to be set!
To have the parser ignore the line breaks, and figure out the line breaks based on the size of each measure.
This is an object of:
preferredMeasuresPerLine: How many measures per line if there is room. If there isn't room, then use the rest of the parameters. This is optional.
minSpacing: 1 means to pack the notes as close as possible, 2 means to double the spacing, etc..
maxSpacing: if there is very little music and a wide line, then the line is shortened so the notes are not too spread out.
lastLineLimit: if it works out that there is a single measure on the last line, then try a different layout.
minSpacingLimit values until the last line is no more spread out than this limit.
A reasonable thing to set these values to is { minSpacing: 1.8, maxSpacing: 2.7, preferredMeasuresPerLine: 4 }.