Melange
Platform IntegrationAndroid

Setup

Set up ZETIC Melange in your Android project.

This guide targets the planned ZeticMLange Android 1.13.0 release. The Android API reference pages use the same version.

This guide walks you through adding the ZETIC Melange SDK to your Android project. Melange abstracts the complexity of NPU execution: you do not need to write any C++ or OpenCL code.

Prerequisites

  • Android Studio Arctic Fox or later
  • A physical Android device (emulators do not have NPU hardware)
  • Minimum SDK 24 (Android 7.0)
  • A Personal Key from the Melange Dashboard

Your project structure should look like this:

build.gradle
MainActivity.kt
build.gradle
settings.gradle

Add Melange Dependency

The Android SDK is published as Gradle artifacts in ZeticMLangeAndroid GitHub releases. Add its Ivy repository to your project-level settings.gradle.kts (or merge the ivy entry into your existing dependency repositories):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        ivy {
            name = "ZeticMLangeAndroidGitHubRelease"
            url = uri("https://github.com/zetic-ai/ZeticMLangeAndroid/releases/download")
            patternLayout {
                artifact("[revision]/[artifact]-[revision](-[classifier]).[ext]")
            }
            metadataSources {
                gradleMetadata()
            }
            content {
                includeGroup("com.zeticai.mlange")
                includeGroup("com.zeticai.mlange.backend")
            }
        }
    }
}

Google and Maven Central remain configured for the SDK's public transitive dependencies. The Ivy repository serves the Android SDK artifacts.

Integrate the Melange AAR (Android Archive), which contains the Unified HAL for Android devices, in your app module:

build.gradle.kts

android {
    ...
    packaging {
        jniLibs {
            useLegacyPackaging = true
        }
    }
}

dependencies {
    implementation("com.zeticai.mlange:mlange:1.13.0")
}

build.gradle

android {
    ...
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

dependencies {
    implementation 'com.zeticai.mlange:mlange:1.13.0'
}

The useLegacyPackaging setting is required. It packages native libraries in compressed form so they can be extracted to the installed app's native library directory. Without extraction, loading Melange native runtime libraries may fail with java.lang.UnsatisfiedLinkError.

AndroidManifest.xml

The final merged Android manifest must allow native library extraction (android:extractNativeLibs="true"). Check the Merged Manifest in Android Studio, including any build-variant overrides. Do not set this attribute to false.

In app/src/main/AndroidManifest.xml, add android:extractNativeLibs="true" to the existing <application> element, or change it to true if already present. Keep your other application attributes and components; do not replace the whole manifest with this minimal example:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:extractNativeLibs="true">
        <!-- Keep your existing application configuration here. -->
    </application>
</manifest>

On modern Android Gradle Plugin versions, useLegacyPackaging is the supported build setting for native library packaging and replaces the manifest attribute as the configuration mechanism. Keep the Gradle setting above even when your source manifest explicitly enables extraction. See the Android Gradle Plugin documentation.

Sync and Build

  1. Click Sync Now in the Gradle notification bar.
  2. Build your project to verify the dependency resolves correctly.

Verify Setup

Add a simple initialization test to confirm the SDK is working:

import com.zeticai.mlange.core.model.ZeticMLangeModel

// Test initialization (use in onCreate or a background thread)
val model = ZeticMLangeModel(this, PERSONAL_KEY, MODEL_NAME)

If the initialization completes without error, your setup is ready.

The constructor performs a network call on first use to download the model binary. Call it from a background thread or use Kotlin coroutines to avoid blocking the UI.


Next Steps

On this page