alphaTab (coderline/alphatabwebsite)

alphaTab

https://github.com/coderline/alphatabwebsite
Admin
This repository contains the website and documentation for alphaTab, a powerful tool for displaying...

Tokens:245,962
Snippets:2,724
Trust Score:6.2
Update:4 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# alphaTab

alphaTab is a JavaScript, .NET, and Android SDK for building music notation software and websites. It takes supported input files (Guitar Pro 3–8, MusicXML, CapXML, alphaTex) and renders interactive, feature-rich music sheets inside a web page, desktop application, or mobile app. alphaTab is structured into four cooperating modules: a **data model** holding all music information down to individual note level, **file importers** that parse input formats into the data model, a **render engine** that performs music engraving using the SMuFL/Bravura font via Canvas or SVG, and an **audio engine** (AlphaSynth) that synthesizes MIDI using SoundFont2 files. The library ships with zero runtime dependencies on the web, bundles the Bravura music font, and includes a SONiVOX SoundFont2 sample for playback.

The primary entry point on every platform is the `AlphaTabApi` class, which wraps all subsystems behind a unified API of methods, properties, and event emitters. The API is non-throwing and asynchronous by nature: operations complete in background workers and results are communicated through typed events. alphaTab is available as an NPM package (`@coderline/alphatab`) for JavaScript/TypeScript, as NuGet packages (`AlphaTab`, `AlphaTab.Windows`) for .NET, and as a Maven package (`net.alphatab:alphaTab`) for Android/Kotlin. All three platforms share the same transpiled source code, so every feature added is available on every platform simultaneously.

---

## Installation

### Web – NPM

Install the package and import it as an ES module or UMD global.

```bash
npm install @coderline/alphatab
```

```html
<!-- ESM from CDN -->
<div id="alphaTab">
  \title "Hello alphaTab"
  .
  :4 0.6 1.6 3.6 0.5 2.5 3.5 0.4 2.4 |
     3.4 0.3 2.3 0.2 1.2 3.2 0.1 1.1 |
     3.1.1
</div>
<script type="module">
  import * as alphaTab from 'https://cdn.jsdelivr.net/npm/@coderline/alphatab@latest/dist/alphaTab.min.mjs';
  const api = new alphaTab.AlphaTabApi(document.getElementById('alphaTab'), { tex: true });
</script>
```

### .NET – NuGet

```bash
# Core (.NET Standard 2.0)
dotnet add package AlphaTab

# WPF / WinForms (.NET 8)
dotnet add package AlphaTab.Windows
```

```cs
// Console – low-level API
var score = AlphaTab.Importer.ScoreLoader.LoadScoreFromBytes(File.ReadAllBytes("song.gp"));
var settings = new AlphaTab.Settings();
settings.Core.Engine = "skia";
var renderer = new AlphaTab.Rendering.ScoreRenderer(settings) { Width = 970 };
renderer.PartialRenderFinished.On(r => SaveImage((SKImage)r.RenderResult));
renderer.RenderScore(score, new double[] { 0 });
```

### Android – Maven (Gradle Kotlin DSL)

```kotlin
// build.gradle.kts
dependencies {
    implementation("net.alphatab:alphaTab:1.6.1")
}
```

```xml
<!-- layout/activity_main.xml -->
<alphaTab.AlphaTabView
    android:id="@+id/alphatab_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
```

```kotlin
// MainActivity.kt
val api = findViewById<AlphaTabView>(R.id.alphatab_view).api
```

---

## `AlphaTabApi` Constructor

Initializes alphaTab on a container element and accepts an optional settings object.

```js
// Minimal – reads alphaTex from element text content
const api = new alphaTab.AlphaTabApi(document.getElementById('alphaTab'), { tex: true });

// With player enabled and custom soundfont
const api = new alphaTab.AlphaTabApi(document.getElementById('alphaTab'), {
  core: { tex: false },
  player: {
    playerMode: alphaTab.PlayerMode.EnabledAutomatic,
    soundFont: '/assets/sonivox.sf2',
    scrollOffsetY: -30
  },
  display: {
    scale: 1.5,
    layoutMode: alphaTab.LayoutMode.Page
  }
});

api.error.on(err => console.error('alphaTab error:', err));
api.scoreLoaded.on(score => console.log('Loaded:', score.title, 'by', score.artist));
```

---

## `api.load(scoreData, trackIndexes?)` — Load a File or Score

Initiates loading of a score from a URL, binary buffer, or existing `Score` object. The optional `trackIndexes` array controls which tracks are displayed (defaults to first track).

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

// Load from URL (browser)
api.load('/assets/song.gp');

// Load from ArrayBuffer (all platforms)
const response = await fetch('/assets/song.gp');
const buffer = await response.arrayBuffer();
api.load(new Uint8Array(buffer), [0, 1]); // show tracks 0 and 1

// Load a pre-parsed Score object
api.load(existingScore);

// React to completion
api.scoreLoaded.on(score => {
  console.log(`Loaded "${score.title}" with ${score.tracks.length} tracks`);
});
api.error.on(err => console.error('Load failed:', err));
```

---

## `api.tex(tex, tracks?)` — Render alphaTex Notation

Parses and renders an alphaTex string directly without a file. alphaTex is alphaTab's own text-based music notation language, inspired by LaTeX syntax.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

// Simple single bar
api.tex('\\title "Smoke on the Water" . :4 0.4 3.4 5.4 | 0.4 3.4 6.4 5.4');

// Multi-track: render only track index 0
api.tex(`
  \\title "Canon Rock"
  \\subtitle "JerryC"
  \\tempo 90
  .
  :2 19.2{v f} 17.2{v f} |
  15.2{v f} 14.2{v f} |
  12.2{v f} 10.2{v f}
`, [0]);
```

---

## `api.render()` — Trigger Re-Render

Initiates a re-render of the currently loaded score. Must be called after changes to `api.settings` (combined with `api.updateSettings()`) or after programmatic data-model changes.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

// Change layout and re-render
api.settings.display.scale = 2.0;
api.settings.display.layoutMode = alphaTab.LayoutMode.Horizontal;
api.updateSettings();
api.render();

api.renderFinished.on(() => {
  console.log('Re-render complete');
});
```

---

## `api.renderTracks(tracks, renderHints?)` — Render Specific Tracks

Selects and renders a subset of tracks from the currently loaded score. All supplied tracks must belong to the same score.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.scoreLoaded.on(score => {
  // Show tracks 0 (guitar) and 2 (bass) together
  api.renderTracks([score.tracks[0], score.tracks[2]]);
});

api.load('/assets/full-band.gp');
```

---

## `api.updateSettings()` — Apply Settings Changes

Propagates any in-place mutations to `api.settings` down to the renderer and other subsystems. Must be followed by `api.render()` to visually update the sheet.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  display: { scale: 1.0 }
});

document.getElementById('zoomIn').addEventListener('click', () => {
  api.settings.display.scale += 0.1;
  api.updateSettings();
  api.render();
});

document.getElementById('toggleLayout').addEventListener('click', () => {
  const isPage = api.settings.display.layoutMode === alphaTab.LayoutMode.Page;
  api.settings.display.layoutMode = isPage
    ? alphaTab.LayoutMode.Horizontal
    : alphaTab.LayoutMode.Page;
  api.updateSettings();
  api.render();
});
```

---

## `api.loadSoundFont(data, append?)` — Load a SoundFont2

Loads a SoundFont2 (`.sf2`) or SoundFont3 (`.sf3`) file for audio synthesis. The player must be enabled in settings. Setting `append` to `true` adds instruments from the new soundfont on top of existing ones.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: {
    playerMode: alphaTab.PlayerMode.EnabledAutomatic,
    soundFont: '/assets/default.sf2'
  }
});

// Load a second soundfont and merge (append=true)
api.loadSoundFont('/assets/custom-strings.sf2', true);

api.soundFontLoaded.on(() => console.log('SoundFont ready'));
api.error.on(err => console.error('SoundFont load error:', err));
```

---

## `api.play()` / `api.pause()` / `api.stop()` — Playback Control

Start, pause, or stop the MIDI synthesizer. `play()` returns `false` if the player is not ready or is already playing.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: {
    playerMode: alphaTab.PlayerMode.EnabledAutomatic,
    soundFont: '/assets/sonivox.sf2',
    enableCursor: true
  }
});

api.load('/assets/song.gp');

document.getElementById('play').onclick = () => {
  const started = api.play();
  if (!started) console.warn('Player not ready');
};
document.getElementById('pause').onclick = () => api.pause();
document.getElementById('stop').onclick  = () => api.stop();

api.playerStateChanged.on(args => {
  document.getElementById('play').disabled  = args.state === alphaTab.PlayerState.Playing;
  document.getElementById('pause').disabled = args.state !== alphaTab.PlayerState.Playing;
});
```

---

## `api.playbackSpeed` — Playback Speed Property

Gets or sets the playback speed as a percentage. `1.0` is normal speed; `0.5` is half speed.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

// Slow down for practice
api.playbackSpeed = 0.5;

// Speed selector UI
document.getElementById('speedSelect').addEventListener('change', e => {
  api.playbackSpeed = parseFloat(e.target.value);
  console.log('Playback speed set to', api.playbackSpeed);
});
```

---

## `api.masterVolume` — Master Volume Property

Gets or sets the master volume for audio output. `1.0` is 100%; `0.5` is 50%.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.masterVolume = 0.8; // 80%

document.getElementById('volumeSlider').addEventListener('input', e => {
  api.masterVolume = parseFloat(e.target.value); // slider range 0–2
});
```

---

## `api.changeTrackMute(tracks, mute)` — Mute Tracks

Mutes or unmutes the specified tracks at the MIDI channel level. If a track shares its MIDI channel with another, both are affected.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.scoreLoaded.on(score => {
  // Mute all tracks except track 0
  const otherTracks = score.tracks.slice(1);
  api.changeTrackMute(otherTracks, true);

  document.getElementById('unmuteAll').onclick = () => {
    api.changeTrackMute(score.tracks, false);
  };
});

api.load('/assets/song.gp');
```

---

## `api.changeTrackSolo(tracks, solo)` — Solo Tracks

Flags one or more tracks as solo. Any track marked solo plays while all others are silenced (unless they are also solo).

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.scoreLoaded.on(score => {
  // Solo the lead guitar (track 0)
  api.changeTrackSolo([score.tracks[0]], true);

  document.getElementById('clearSolo').onclick = () => {
    api.changeTrackSolo(score.tracks, false);
  };
});

api.load('/assets/band.gp');
```

---

## `api.changeTrackVolume(tracks, volume)` — Per-Track Volume

Adjusts the playback volume of specific tracks. `volume` is a percentage multiplier (e.g., `1.5` = 150%, `0.5` = 50%).

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.scoreLoaded.on(score => {
  // Boost lead track, reduce bass
  api.changeTrackVolume([score.tracks[0]], 1.5);
  api.changeTrackVolume([score.tracks[1]], 0.5);
});

api.load('/assets/song.gp');
```

---

## `api.downloadMidi(format?)` — Download MIDI (Web Only)

Generates an SMF 1.0 MIDI file of the currently loaded song and triggers a browser download.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.load('/assets/song.gp');

document.getElementById('downloadMidi').onclick = () => {
  api.downloadMidi(); // triggers browser file download
};
```

---

## `api.exportAudio(options)` — Export Raw Audio (since 1.6.0)

Starts an asynchronous audio export using the built-in synthesizer, returning an `IAudioExporter` for pull-based streaming of raw PCM samples. Useful for generating WAV/MP3 audio files.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});
api.load('/assets/song.gp');

document.getElementById('exportWav').onclick = async () => {
  const options = new alphaTab.synth.AudioExportOptions();
  options.sampleRate = 44100;

  const exporter = await api.exportAudio(options);

  const allSamples = [];
  let chunk;
  while ((chunk = await exporter.render(5000)) !== null) {
    // chunk.samples is a Float32Array (interleaved stereo)
    allSamples.push(...chunk.samples);
  }
  exporter.destroy();

  const wavBlob = buildWavBlob(new Float32Array(allSamples), 44100, 2);
  const url = URL.createObjectURL(wavBlob);
  document.getElementById('audioPlayer').src = url;
};
```

---

## `api.print(width?, additionalSettings?)` — Print (Web Only)

Opens a browser print dialog with the music sheet laid out for A4 paper (portrait for page layout, landscape for horizontal layout). Lazy loading is disabled and scale is reduced to 0.8 automatically.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.load('/assets/song.gp');

document.getElementById('print').onclick = () => {
  // Default A4 print
  api.print();
};

document.getElementById('printCompact').onclick = () => {
  // Custom width, 5 bars per row
  api.print(undefined, { display: { barsPerRow: 5 } });
};
```

---

## `api.destroy()` — Destroy Instance

Destroys the alphaTab instance and restores the original state of the container element. After calling `destroy()`, the API object must not be used again.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
api.load('/assets/song.gp');

// In a single-page app, clean up before navigating away
window.addEventListener('beforeunload', () => {
  api.destroy();
});
```

---

## `api.scoreLoaded` Event — Score Loaded

Fired whenever a new score becomes active (after `load()`, `tex()`, `renderScore()`, or `renderTracks()`). Fired after transposition pitches are applied but before MIDI generation or rendering starts, making it the correct place for data-model mutations.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.scoreLoaded.on(score => {
  document.getElementById('title').textContent  = score.title;
  document.getElementById('artist').textContent = score.artist;

  // Populate track selector
  const select = document.getElementById('trackSelect');
  select.innerHTML = '';
  score.tracks.forEach((track, i) => {
    const opt = document.createElement('option');
    opt.value = i;
    opt.textContent = track.name;
    select.appendChild(opt);
  });
});

api.load('/assets/song.gp');
```

---

## `api.renderFinished` Event — Render Finished

Fired when the render engine completes laying out and drawing the entire music sheet. Visual DOM updates (e.g., element resizing) may still be in progress.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
const spinner = document.getElementById('loadingSpinner');

api.renderFinished.on(() => {
  spinner.style.display = 'none';
  console.log('Sheet rendered successfully');
});

spinner.style.display = 'block';
api.load('/assets/song.gp');
```

---

## `api.playerStateChanged` Event — Player State Changed

Fired whenever the playback state transitions (playing ↔ paused ↔ stopped). `args.state` is a `PlayerState` enum value; `args.stopped` is `true` when the song reaches its end.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});

const playBtn = document.getElementById('playPause');
api.playerStateChanged.on(args => {
  if (args.state === alphaTab.PlayerState.Playing) {
    playBtn.textContent = '⏸ Pause';
  } else {
    playBtn.textContent = args.stopped ? '▶ Play' : '▶ Resume';
  }
});

playBtn.onclick = () => api.playPause();
api.load('/assets/song.gp');
```

---

## `api.playerPositionChanged` Event — Playback Position

Fired repeatedly during playback to report the current song position. The event args (`PositionChangedEventArgs`) include `currentTime` (ms), `endTime` (ms), `currentTick`, `endTick`, and beat reference data.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});

const timeDisplay = document.getElementById('time');
const progressBar  = document.getElementById('progress');

api.playerPositionChanged.on(args => {
  const current = Math.floor(args.currentTime / 1000);
  const total   = Math.floor(args.endTime    / 1000);
  const mm = s => `${String(Math.floor(s / 60)).padStart(2,'0')}:${String(s % 60).padStart(2,'0')}`;
  timeDisplay.textContent = `${mm(current)} / ${mm(total)}`;
  progressBar.value = (args.currentTime / args.endTime) * 100;
});

api.load('/assets/song.gp');
```

---

## `api.activeBeatsChanged` Event — Active Beats (since 1.2.3)

Fired when the set of currently playing beats changes across all tracks and voices (not just the rendered ones). Useful for building custom cursor or highlight logic.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});

api.activeBeatsChanged.on(args => {
  // args.activeBeats: Beat[] – one entry per active track/voice
  for (const beat of args.activeBeats) {
    highlightBeat(beat); // custom highlight function
  }
});

api.load('/assets/song.gp');
```

---

## `api.midiEventsPlayed` + `api.midiEventsPlayedFilter` — MIDI Event Playback

Fired when buffered MIDI events are actually sent to the audio device. Subscribe to specific event types via the filter to avoid performance overhead.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});

// Only notify for metronome events
api.midiEventsPlayedFilter = [alphaTab.midi.MidiEventType.AlphaTabMetronome];
api.metronomeVolume = 1;

const counter = document.getElementById('counter');
api.playerStateChanged.on(e => {
  if (e.stopped) counter.textContent = '1';
});
api.midiEventsPlayed.on(e => {
  for (const midi of e.events) {
    if (midi.isMetronome) {
      counter.textContent = midi.metronomeNumerator + 1;
      const halfBeat = (midi.metronomeDurationInMilliseconds / 2) / api.playbackSpeed;
      setTimeout(() => { counter.textContent = 'and'; }, halfBeat);
    }
  }
});

api.load('/assets/song.gp');
```

---

## `api.error` Event — Error Handling

Global error event for all asynchronous failures. alphaTab never throws synchronously from API calls; all errors are routed here.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

api.error.on(error => {
  console.error('alphaTab error:', error.message ?? error);
  document.getElementById('errorBanner').textContent = `Error: ${error.message}`;
  document.getElementById('errorBanner').style.display = 'block';
});

api.load('/assets/missing-file.gp'); // triggers error event
```

---

## alphaTex — Text-Based Music Notation

alphaTex is alphaTab's own text-based music notation language. Enable it via `settings.core.tex = true` (loads from element text) or call `api.tex(string)` programmatically.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));

// Syntax:  <fret>.<string>.<duration>{effects}
// Duration codes: 1=whole 2=half 4=quarter 8=eighth 16=sixteenth 32=thirty-second
// Effects: h=hammer-on, b=bend, v=vibrato, g=ghost, d=dead, x=mute
api.tex(`
  \\title "Metallica – Nothing Else Matters (intro)"
  \\tempo 147
  \\tuning E4 B3 G3 D3 A2 E2
  .
  :8
  0.1 0.2 0.3 2.2 0.1 2.3 0.1 0.2 |
  0.1 0.2 0.3 2.2 0.1 2.3 0.1 0.2 |
  // Second track voice with chord
  \\track "Rhythm"
  \\staff {score tabs}
  (0.1 0.2 2.3 2.4 0.5).2 r.2 | (0.1 0.2 2.3 2.4 0.5).2 r.2
`);
```

---

## Low-Level API: `ScoreLoader` — Parse Files Without UI

`ScoreLoader.loadScoreFromBytes` parses a binary buffer into a `Score` object without needing a DOM element or full `AlphaTabApi`. Useful in Node.js or server environments.

```js
import * as alphaTab from '@coderline/alphatab';
import { readFileSync } from 'fs';

const data     = new Uint8Array(readFileSync('./song.gp'));
const settings = new alphaTab.Settings();
try {
  const score = alphaTab.importer.ScoreLoader.loadScoreFromBytes(data, settings);
  console.log(`Title: ${score.title}`);
  console.log(`Artist: ${score.artist}`);
  console.log(`Tracks: ${score.tracks.length}`);
  score.tracks.forEach(t => console.log(` - ${t.name}`));
} catch (e) {
  console.error('Unsupported format:', e.message);
}
```

---

## Low-Level API: `ScoreRenderer` — Render Without UI

`ScoreRenderer` performs layout and drawing independently of any UI layer. Results are emitted as partial SVG/image chunks via events, enabling server-side rendering or custom display logic.

```js
import * as alphaTab from '@coderline/alphatab';

const score    = alphaTab.importer.ScoreLoader.loadScoreFromBytes(data, settings);
const settings = new alphaTab.Settings();
settings.core.engine = 'svg';

const renderer = new alphaTab.rendering.ScoreRenderer(settings);
renderer.width = 1200;

const chunks = [];
renderer.preRender.on(() => chunks.length = 0);
renderer.partialLayoutFinished.on(r => renderer.renderResult(r.id));
renderer.partialRenderFinished.on(r => chunks.push({ svg: r.renderResult, w: r.width, h: r.height }));
renderer.renderFinished.on(r => {
  console.log(`Total size: ${r.totalWidth} x ${r.totalHeight}`);
  chunks.forEach(c => displaySvgChunk(c.svg, c.w, c.h));
});

renderer.renderScore(score, [0]); // render track 0
```

---

## Low-Level API: `MidiFileGenerator` — Generate MIDI

Converts a `Score` into a standard MIDI file (SMF) that can be saved to disk or fed into a custom synthesizer.

```js
import * as alphaTab from '@coderline/alphatab';

const score    = alphaTab.importer.ScoreLoader.loadScoreFromBytes(data, new alphaTab.Settings());
const settings = new alphaTab.Settings();

const midiFile = new alphaTab.midi.MidiFile();
const handler  = new alphaTab.midi.AlphaSynthMidiFileHandler(midiFile, true /* SMF 1.0 */);
const generator = new alphaTab.midi.MidiFileGenerator(score, settings, handler);
generator.generate();

// midiFile.tracks[n].events contains MidiEvent objects
console.log('MIDI events:', midiFile.tracks[0].events.length);
// Serialize / save with any standard MIDI writer library
```

---

## Low-Level API: `Gp7Exporter` / `AlphaTexExporter` — Export Data Model

Export a loaded `Score` back to Guitar Pro 7 (`.gp`) or alphaTex (`.atex`) format.

```js
// Guitar Pro 7 export (since 1.2.0)
const gp7 = new alphaTab.exporter.Gp7Exporter();
const gpData = gp7.export(api.score, api.settings); // Uint8Array

const a = document.createElement('a');
a.download = (api.score.title || 'Untitled') + '.gp';
a.href = URL.createObjectURL(new Blob([gpData]));
a.click();

// alphaTex export (since 1.7.0)
const atex = new alphaTab.exporter.AlphaTexExporter();
const texString = atex.exportToString(api.score, api.settings);
console.log(texString); // human-readable alphaTex code

const texData = atex.export(api.score, api.settings); // Uint8Array
const b = document.createElement('a');
b.download = (api.score.title || 'Untitled') + '.atex';
b.href = URL.createObjectURL(new Blob([texData]));
b.click();
```

---

## Low-Level API: `JsonConverter` — Serialize/Deserialize the Data Model

Converts `Score` and `Settings` objects to/from plain JavaScript objects or JSON strings for transmission over WebSockets, REST APIs, or cross-worker messaging.

```js
// Serialize
const map  = alphaTab.model.JsonConverter.scoreToJsObject(api.score);
const json = alphaTab.model.JsonConverter.scoreToJson(api.score); // web only

// Deserialize
const score = alphaTab.model.JsonConverter.jsObjectToScore(map, api.settings);
const scoreFromJson = alphaTab.model.JsonConverter.jsonToScore(json, api.settings);

// Example: send score over WebSocket and restore on receipt
socket.send(alphaTab.model.JsonConverter.scoreToJson(api.score));
socket.onmessage = e => {
  const score = alphaTab.model.JsonConverter.jsonToScore(e.data, new alphaTab.Settings());
  api.load(score);
};
```

---

## Custom Coloring — Styling the Data Model (since 1.5.0)

Individual notes, beats, bars, voices, tracks, or score-level elements can be colored by mutating the `style` property on data-model objects and calling `api.render()`.

```js
const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'), {
  player: { playerMode: alphaTab.PlayerMode.EnabledAutomatic, soundFont: '/assets/sonivox.sf2' }
});

api.scoreLoaded.on(score => {
  // Color every note in the first track red
  score.tracks[0].staves.forEach(staff => {
    staff.bars.forEach(bar => {
      bar.voices.forEach(voice => {
        voice.beats.forEach(beat => {
          beat.notes.forEach(note => {
            note.style = new alphaTab.model.NoteStyle();
            note.style.color = new alphaTab.model.Color(255, 0, 0, 255); // RGBA red
          });
        });
      });
    });
  });

  // Apply – must call render after modifying the data model
  api.render();
});

api.load('/assets/song.gp');
```

---

## Summary

alphaTab's primary use cases are: (1) **interactive music sheet viewers** embedded in web pages or desktop apps, where users can load Guitar Pro / MusicXML files, control playback with a real-time cursor, and follow along with synchronized note highlighting; (2) **music education platforms** that need programmatic control over which tracks are visible, speed-adjusted practice playback, per-track mute/solo, and visual metronome feedback via MIDI events; and (3) **composition and transcription tools** that read existing files, allow in-browser editing via alphaTex, and export back to Guitar Pro or alphaTex format.

Integration patterns follow three tiers. At the **high level**, instantiate `AlphaTabApi` on a DOM element and interact entirely through its methods and event emitters — this is the recommended path for web, WPF/WinForms, and Android. At the **mid level**, combine `ScoreLoader` with `ScoreRenderer` for headless rendering (server-side PDF generation, CI sheet snapshots) without needing a UI platform. At the **low level**, chain `ScoreLoader` → `MidiFileGenerator` → `AlphaSynth` directly to build fully custom audio pipelines, or use `JsonConverter` to transmit the data model over a network and reload it on any alphaTab instance running the same version. All three tiers share the same data model and settings object, making it straightforward to mix them within a single application.