Skip to main content

Installation (Kotlin)

alphaTab for Kotlin runs on any JVM, for servers, command-line tools and headless rendering, and in Android apps with a native AlphaTabView.

Install​

Two packages on Maven Central cover the Kotlin target:

  • net.alphatab:alphaTab-core runs on any JVM 17 or newer. It contains the importers and exporters, the renderer and the synthesizer, and is used through the low-level APIs. It has no UI control and no audio output.
  • net.alphatab:alphaTab is the Android library (minSdk 26). It adds the AlphaTabView, the Android canvas and the audio output, and brings in alphaTab-core as a dependency.

Always use both packages in the same version: net.alphatab:alphaTab requires exactly its own version of alphaTab-core. Pre-release snapshots are published to central.sonatype.com/repository/maven-snapshots.

repositories {
    google()
    mavenCentral()
    // Pre-release snapshots:
    // maven("https://central.sonatype.com/repository/maven-snapshots/")
}

dependencies {
    // Android apps:
    implementation("net.alphatab:alphaTab:1.10.0")

    // JVM applications, with the native Skia library of the target OS:
    // implementation("net.alphatab:alphaTab-core:1.10.0")
    // implementation("net.alphatab:alphaSkia-linux:3.5.147")
}

Render on the JVM​

On a JVM, alphaTab renders through alphaSkia, which needs a native library per operating system: net.alphatab:alphaSkia-windows, alphaSkia-linux or alphaSkia-macos, with the entry points AlphaSkiaWindows, AlphaSkiaLinux and AlphaSkiaMacOs. Use alphaSkia 3.5.147, the version alphaTab-core depends on.

alphaSkia also needs the Bravura music font. It ships as dist/font/Bravura.otf in the @coderline/alphatab npm package.

This command-line program loads a file, renders it 970 pixels wide and writes one PNG per rendered part:

import alphaTab.Environment
import alphaTab.Settings
import alphaTab.alphaSkia.AlphaSkiaLinux
import alphaTab.collections.DoubleList
import alphaTab.core.ecmaScript.Uint8Array
import alphaTab.importer.ScoreLoader
import alphaTab.platform.skia.AlphaSkiaImage
import alphaTab.rendering.ScoreRenderer
import java.io.File
import kotlin.contracts.ExperimentalContracts

@OptIn(ExperimentalUnsignedTypes::class, ExperimentalContracts::class)
fun main(args: Array<String>) {
    AlphaSkiaLinux.INSTANCE.initialize()
    Environment.enableAlphaSkia(File("Bravura.otf").readBytes().asUByteArray(), null)

    val score = ScoreLoader.loadScoreFromBytes(Uint8Array(File(args[0]).readBytes().asUByteArray()), null)

    val settings = Settings()
    settings.core.engine = "skia"
    settings.core.enableLazyLoading = false

    val renderer = ScoreRenderer(settings)
    renderer.width = 970.0

    var index = 0
    renderer.partialRenderFinished.on { result ->
        (result.renderResult as AlphaSkiaImage).use { image ->
            File("score-${index++}.png").writeBytes(image.toPng()!!.asByteArray())
        }
    }
    renderer.renderFinished.on { result ->
        println("Rendered $index images, ${result.totalWidth}x${result.totalHeight}")
    }

    renderer.renderScore(score, DoubleList(0.0), null)
}
  • enableLazyLoading = false renders every part right away. With lazy loading, a part is only rendered once a UI requests it.
  • Text uses the fonts installed on the system. On a server without fonts, register them with Environment.registerAlphaSkiaCustomFont.
  • Set settings.core.engine = "svg" to receive every part as an SVG string instead. Initialize alphaSkia anyway: alphaTab measures text through it.

The low-level API guide shows MIDI generation, audio synthesis and JSON serialization with the same classes.

Render on Android​

Add the AlphaTabView control to any layout. This example places it inside a ConstraintLayout that fills the activity:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/main_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="net.alphatab.android.MainActivity">

    <alphaTab.AlphaTabView
        android:id="@+id/alphatab_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Get a reference to the view from your activity and use its api property to drive alphaTab:

import alphaTab.AlphaTabView

class MainActivity : ComponentActivity() {
    private lateinit var alphaTabView: AlphaTabView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        alphaTabView = findViewById(R.id.alphatab_view)
        val api = alphaTabView.api
        // load a score, subscribe to events, drive playback here
    }
}

The Android library bundles the Bravura font and the default SoundFont and initializes alphaSkia itself. More samples live at github.com/CoderLine/alphaTabSamplesAndroid.

Jetpack Compose​

alphaTab does not currently ship a Compose control. Two options:

Dependencies​

alphaTab for Kotlin carries a small number of third-party dependencies:

  • Rendering. alphaSkia, which wraps the Skia engine used by Chrome, or the SVG output. On Android the built-in Android Canvas is available as well; alphaSkia is significantly faster.
  • Async. org.jetbrains.kotlinx:kotlinx-coroutines-core powers alphaTab's asynchronous operations.

There is no UI control for desktop JVM toolkits such as Swing or JavaFX. Reach out on GitHub if you need alphaTab wired to a different UI framework or audio backend.