User Documentation

This documentation

The main part of the documentation will use Haxe or JavaScript samples to show how to use alphaTab but it should be possible to implement the same code parts in any target language.This documentation is mainly a user-guide for developers who simply want to use alphaTab but don't want to extend it. There is a separate developer documentation for contribution to alphaTab on the top menu.

Samples

We have prepared a huge list of samples to show different alphaTab features by code. Those samples are the easiest way to understand what alphaTab is capable of and how to use it.

The Score Model

The alphatab.model.* classes represent the main data model which alphaTab is built around. This data model is based on the file structure of Guitar Pro 6 files and starts with the Score class as top level node. Then it goes hierarchically down till we reach a single note played by the instrument. Check out the API docs to learn more about the meanings, properties and relationships inbetween the model clases.

  • Score
    • Track 1
      • Bar 1
        • Voice 1
          • Beat 1
            • Note 1
            • ...
          • ...
        • ...
      • ...
    • ...

console.log("Title: " + score.title);
console.log("Artist: " + score.artist);
console.log("Tracks: " + score.tracks.length);
console.log("Bars: " + score.masterBars.length);

Loading Scores

The classes of the alphatab.importer package are responsible for reading the data model (a score object) from a data source.

A ScoreImporter is responsible for reading a score from a binary data source. They override the readScore() method where they read the data from the available binary input. Examples for ScoreImporters are

  • Gp3To5Importer - Can read the old Guitar Pro binary formats from version 3 to 5
  • AlphaTexImporter - Can read the built in alphaTex markup which allows textual writing of music notation
  • GpxImporter - Can read the new Guitar Pro 6 container format and parses the gpif.xml to a Score object

The ScoreLoader is a wrapper around the platform specific file loader and all available ScoreImporters. You can pass a path to the loadScore and loadScoreAsync methods which will make the file loader to load the binary data from the path. After loading the data the ScoreLoader will try all available ScoreImporters to read a score from the binary data. There is also a loadScoreFromBytes method which allows you to bypass the platform specific file loader and directly specify the binary data.

So if you want to get a score from a file, the ScoreLoader is what you are looking for. The loadScoreAsync will call the callback functions as soon the sccore is loaded or not while the loadScore function is blocking and will return the score directly.

var score = alphatab.importer.loadScore("MyScore.gp5");
console.log(score);
// or
alphatab.importer.loadScore("MyScore.gp5", function(score) {
console.log(score);
}, function(error) {
console.error(error);
});

Settings and ScoreRenderer

Okay, now after we know what our Score object is, and how we can load it from a data source it's time for some visuals. Since alphaTab is a music notation rendering engine there must be some way to draw this Score object onto a canvas. The main entry point for this task is the ScoreRenderer class which takes a Settings instance as configuration. The second constructor parameter is a platform specific argument. There are multiple rendering engines and depending on the engine used, this parameter tells the rendering engine where and how to draw. As you already know: alphaTab is available on multiple platforms. A rendering engine which is represented by a ICanvas implementation is used to actually draw the music notation. As always we recommend to read the API docs and checkout the samples to learn more about the those classes.

HTML5 canvas

This engine is available in the JavaScript version of alphaTab. When creating the ScoreRenderer you need to specify the DOM reference to the canvas element in the second parameter. This engine will resize and draw into the the specified canvas using the browser window.

SVG Canvas

This engine is available anywhere. As soon the rendering is finished, you can call the toSvg() method of the ICanvas object to receive a plain SVG-XML string. This string can be added to the browsers DOM or be displayed by any SVG renderer of your application.

GDI Canvas

This engine is available in the .net version and doesn't require the second constructor parameter of the ScoreRenderer to be set. After rendering you can call the getImage() method to receive a System.Drawing.Bitmap which contains the rendered music sheet.

WPF Canvas

This engine is available in the .net version. The second parameter of the ScoreRenderer needs to be a reference to the System.Windows.Controls.Canvas where the shapes should be added to.