alphaTab Documentation

The playground architecture uses two layers of components:

1. Primitives: Generic, alphaTab-unaware UI bricks (e.g., IconButton, Slider, Dropdown). They take props in their constructor and expose typed methods and callbacks.
2. Composers: alphaTab-aware components (e.g., TransportBar, Footer). They take the AlphaTabApi in their constructor, declare a layout template with cmp-... placeholders, and mount primitives into those placeholders. They translate engine events into primitive method calls.

Composition Mechanics:

• Static Layout: Use parseHtml to define a template with cmp-... placeholders, then use mount(parent, '.cmp-x', component) to swap placeholders for the component's .root.
• Dynamic Layout: For lists or runtime-dependent content, declare a container in the template and use appendChild to add component roots directly.

// Static layout example
this.root = parseHtml(html`
    <div class="at-footer">
        <div class="cmp-waveform"></div>
        <div class="cmp-time-slider"></div>
        <div class="cmp-transport"></div>
    </div>
`);
this.waveform = mount(this.root, '.cmp-waveform', new Waveform(api));
this.timeSlider = mount(this.root, '.cmp-time-slider', new TimeSlider(api));
this.transport = mount(this.root, '.cmp-transport', new TransportBar(api));

// Dynamic layout example
this.root = parseHtml(html`<div class="at-track-list"></div>`);
api.scoreLoaded.on(score => {
    for (const item of this.items) item.dispose();
    this.items = [];
    for (const track of score.tracks) {
        const item = new TrackItem(api, track);
        this.root.appendChild(item.root);
        this.items.push(item);
    }
});

The Intermediate Representation (IR) is the central data structure used by the transpiler to bridge the gap between TypeScript source and the final C# or Kotlin output.

The Pipeline Stages

The IR moves through three distinct stages during every emission process:

1. AstTransformer: Performs a per-file walk of the TypeScript source to produce a raw IR SourceFile for every TypeScript root. This is the only stage allowed to allocate new tsSymbol-backed nodes.
2. PassPipeline: Executes named, whole-program passes that mutate the IR in place (e.g., resolve-types, rewrite-visibilities).
3. AstPrinter: Performs a per-file walk to emit the final .cs or .kt text. This stage is read-only and does not mutate the IR.

Importing the IR

To work with the IR definitions, import them using the following pattern:

import * as cs from '../src/ir/Ir'

Note: The cs alias is a historical convention; the namespace is the canonical IR shared by all targets.

For the AstPrinter to function correctly, the following invariants must be satisfied by the IR before it enters the printing stage:

1. No UnresolvedTypeNode: Every TypeNode reachable from a SourceFile must be a concrete kind (e.g., PrimitiveTypeNode, ArrayTypeNode, MapTypeNode, ArrayTupleNode, FunctionTypeNode, TypeReference, or a NamedTypeDeclaration).
2. Parent Links: Every node must have a parent (with the exception of specific paren-wrapping logic).
3. Override Propagation: After rewrite-visibilities, every method/property overriding a virtual base must have isOverride: true or isVirtual: true if it is an override target.
4. Naming Conventions: All identifier strings on member-access nodes must have already been processed by the target's toMethodNameCase or toPropertyNameCase.
5. Smart-cast Lowering: Any expression requiring runtime type narrowing must be wrapped by SmartCastResolver. Printers do not perform their own type inference.

The playground uses a framework-agnostic, class-based component model. Every UI piece implements the Mountable interface and follows these rules:

1. Constructor: Takes engine dependencies (like alphaTab.AlphaTabApi) and props. It builds the DOM detached as .root. It never takes a parent argument.
2. Parent → Child (Push API): Parents communicate with children via public methods, such as setReady(ready: boolean).
3. Child → Parent (Event API): Children communicate with parents via assignable callback fields (e.g., onPlayClick: (() => void) | null = null).
4. Lifecycle: The dispose() method must release all resources, including alphaTab event subscriptions (the () => void returned by api.event.on(...)), DOM listeners, intervals, and child components.
5. State: The AlphaTabApi is the single source of truth. Components subscribe directly to engine events rather than maintaining intermediate state containers.

class Transport implements Mountable {
    readonly root: HTMLElement;            // detached at construction; mounted by caller

    constructor(api: alphaTab.AlphaTabApi); // engine deps as args; never `parent`

    setReady(ready: boolean): void;         // parent → child push API
    onSomething: (() => void) | null = null; // child → parent event API

    dispose(): void;
}