Skip to main content

JVM Quickstart

Build a desktop or server program that analyzes audio with VoxaTrace on the JVM (macOS or Linux).

Requires JDK 17+

The VoxaTrace JVM target needs JDK 17 or newer at build and runtime.

1. Add the dependency​

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.musicmuni:voxatrace-jvm:3.0.0")

    // Native libraries for your platform — pick one:
    runtimeOnly("com.musicmuni:voxatrace-jvm:3.0.0:natives-macos-arm64")
    // runtimeOnly("com.musicmuni:voxatrace-jvm:3.0.0:natives-linux-x64")
}

The native code is loaded from the classpath automatically; there is nothing to put on java.library.path.

2. Initialize​

VoxaTrace must be initialized once before any API call. On the JVM, use the server initializer with your API key (registration happens over the network, so connectivity is required):

import com.musicmuni.voxatrace.VT

VT.initializeForServer(apiKey = System.getenv("VOXATRACE_API_KEY"))

3. Detect pitch from a file​

import com.musicmuni.voxatrace.tona.PitchDetection
import com.musicmuni.voxatrace.tona.model.ContourExtractorConfig
import com.musicmuni.voxatrace.tona.model.PitchAlgorithm

fun main() {
    VT.initializeForServer(apiKey = System.getenv("VOXATRACE_API_KEY"))

    // 16 kHz mono float samples (decode/resample with your audio library).
    val samples: FloatArray = loadMono16k("recording.wav")

    // MELODIA is octave-robust — recommended for offline/batch analysis.
    val extractor = PitchDetection.createContourExtractor(
        ContourExtractorConfig(algorithm = PitchAlgorithm.MELODIA)
    )
    try {
        val contour = extractor.extract(samples, sampleRate = 16000)
        val voiced = contour.samples.filter { it.pitch > 0f }
        println("Voiced frames: ${voiced.size}")
        println("Median pitch: ${voiced.map { it.pitch }.sorted()[voiced.size / 2]} Hz")
    } finally {
        extractor.release()
    }
}

Audio I/O on the JVM​

Sonix players, recorders and the mixer are available on the JVM via javax.sound (best-effort latency; the hardware-clock timestamping used on mobile is not available). For desktop apps with mobile-grade latency requirements, follow issue #29.

AI-backed features (optional)​

Neural pitch (SwiftF0) and voice-activity detection (SileroVAD) require the AI native artifact:

runtimeOnly("com.musicmuni:voxatrace-jvm:3.0.0:natives-ai-macos-arm64")

It is a large download (the ONNX runtime is bundled), so add it only if you use those features.

Next Steps​