Try Live
Add Docs
Rankings
Pricing
Enterprise
Docs
Install
Theme
Install
Docs
Pricing
Enterprise
More...
More...
Try Live
Rankings
Create API Key
Add Docs
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
Context
Skills
Chat
Benchmark
93.6
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# 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.