Use in Node.js

since 1.2.3

The JavaScript version of alphaTab is primarily optimized for usage in Browsers. At least the top level AlphaTabApi which is a UI focused interface to alphaTab. But this does not mean that alphaTab cannot be used in other JavaScript environments like Node.js or headless JavaScript engines. The core of alphaTab is platform independent and simply requires certain APIs to be available. If you are able to make a HTML5 canvas compatible API available to the runtime (e.g. via node-canvas, skia-canvas) the built-in HTML5 renderer might also work.

In this guide we will setup a Node.js example which is using alphaTab to render a given input file to an SVG. This SVG could then be sent to a browser for display.

1. Setup project

The start is quite simple:

1. Run npm init in a new directory
2. Run npm install @coderline/alphatab to install alphaTab
3. Create a new index.js into which our code will go .

2. The basic code structure

In our code we will first load alphaTab and load the Score from a given input file path:

// load alphaTab
const alphaTab = require("@coderline/alphatab");
// needed for file load
const fs = require("fs");

// Load the file
const fileData = fs.readFileSync(process.argv[2]);
const settings = new alphaTab.Settings();
const score = alphaTab.importer.ScoreLoader.loadScoreFromBytes(
  new Uint8Array(fileData),
  settings
);
console.log(score.title);

And when we run this file on the command line we already have a loaded data model:

3. Using the Low Level APIs

From this point on we will use the Low Level APIs to render the Score into an SVG. As of now there are no render engines shipped with alphaTab which would allow rendering into raster graphics so we will render it to an SVG. Feel free to open new discussions on GitHub if you have special needs for your project.

The code below is mainly taken from the Low Level API guide.

const alphaTab = require("@coderline/alphatab");
const fs = require("fs");

// 1. Load File
const fileData = fs.readFileSync(process.argv[2]);
const settings = new alphaTab.Settings();
const score = alphaTab.importer.ScoreLoader.loadScoreFromBytes(
  new Uint8Array(fileData),
  settings
);

// 2. Setup renderer
settings.core.engine = "svg";
const renderer = new alphaTab.rendering.ScoreRenderer(settings);
renderer.width = 1200;

// 3. Listen to Events
let svgChunks = [];
renderer.preRender.on((isResize) => {
  svgChunks = []; // clear on new rendering
});
renderer.partialRenderFinished.on((r) => {
  svgChunks.push({
    svg: r.renderResult, // svg string
    width: r.width,
    height: r.height,
  });
});
renderer.renderFinished.on((r) => {
  displayResult(svgChunks, r.totalWidth, r.totalHeight);
});

// 4. Fire off rendering
renderer.renderScore(score, [0]);

// log the SVG chunks
console.log(svgChunks.map((c) => c.svg).join("\n"));

Running the script again, we can see the output.

4. The CSS dependency

The rendered SVG assumes some CSS specific parts to be available for the Music Font. Normally alphaTab adds a style tag to the page which loads the Music Symbol Font (Bravura) via as Web Font. Without these styles the SVG will not display the symbols correctly.

The related CSS template is:

@font-face {
    font-family: 'alphaTab';
        src: url('path-to-font/Bravura.eot');
        src: url('path-to-font/Bravura.eot?#iefix') format('embedded-opentype')
            , url('path-to-font/Bravura.woff') format('woff')
            , url('path-to-font/Bravura.otf') format('opentype')
            , url('path-to-font/Bravura.svg#Bravura') format('svg');
        font-weight: normal;
        font-style: normal;
}
.at-surface * {
    cursor: default;
    vertical-align: top;
    overflow: visible;
}
.at {
    font-family: 'alphaTab';
    speak: none;
    font-style: normal;
    font-weight: normal;
    font-variant: normal;
    text-transform: none;
    line-height: 1;
    line-height: 1;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    font-size: 34px;
    overflow: visible !important;
}