Idiomatic Go bindings for the Java Native Interface and 53 Android Java API packages, auto-generated from YAML specs to ensure full coverage and easy maintenance.

For remote Android API access over gRPC, see jni-proxy.

This project is part of a family of three Go libraries that cover the major Android interface surfaces. Each wraps a different layer of the Android platform:

graph TD
    subgraph "Go application"
        GO["Go code"]
    end

    subgraph "Interface libraries"
        NDK["<b>ndk</b><br/>C API bindings via cgo"]
        JNI["<b>jni</b><br/>Java API bindings via JNI+cgo"]
        AIDL["<b>binder</b><br/>Binder IPC, pure Go"]
    end

    subgraph "Android platform"
        CAPI["NDK C libraries<br/>(libcamera2ndk, libaaudio,<br/>libEGL, libvulkan, ...)"]
        JAVA["Java SDK<br/>(android.bluetooth,<br/>android.location, ...)"]
        BINDER["/dev/binder<br/>kernel driver"]
        SYSSVCS["System services<br/>(ActivityManager,<br/>PowerManager, ...)"]
    end

    GO --> NDK
    GO --> JNI
    GO --> AIDL

    NDK -- "cgo / #include" --> CAPI
    JNI -- "cgo / JNIEnv*" --> JAVA
    AIDL -- "ioctl syscalls" --> BINDER
    BINDER --> SYSSVCS
    JAVA -. "internally uses" .-> BINDER
    CAPI -. "some use" .-> BINDER

• Start with ndk when the NDK provides a C API for what you need (camera, audio, sensors, EGL/Vulkan, media codecs). These are the lowest-latency, lowest-overhead bindings since they go straight from Go to the C library via cgo.

• Use jni when you need a Java Android SDK API that the NDK does not expose. Examples: Bluetooth discovery, WiFi P2P, NFC tag reading, location services, telephony, content providers, notifications. JNI is also the right choice when you need to interact with Java components (Activities, Services, BroadcastReceivers) or when you need the gRPC remote-access layer.

• Use binder when you want pure-Go access to Android system services without any cgo dependency. This is ideal for lightweight tools, CLI programs, or scenarios where you want to talk to the binder driver from a non-Android Linux system. AIDL covers the same system services that Java SDK wraps (ActivityManager, PowerManager, etc.) but at the wire-protocol level.

• Combine them when your application needs multiple layers. For example, a streaming app might use ndk for camera capture and audio encoding, jni for Bluetooth controller discovery, and binder for querying battery status from a companion daemon.

All three libraries talk to the same Android system services, but through different paths:

• The NDK C APIs are provided by Google as stable C interfaces to Android platform features. Some (camera, sensors, audio) internally use binder IPC to talk to system services; others (EGL, Vulkan, OpenGL) talk directly to kernel drivers. The ndk library wraps these C APIs via cgo.
• The Java SDK uses binder IPC internally for system service access (BluetoothManager, LocationManager, etc.), routing calls through the Android Runtime (ART/Dalvik). The jni library calls into these Java APIs via the JNI C interface and cgo.
• The AIDL binder protocol is the underlying IPC mechanism that system-facing NDK and Java SDK APIs use. The binder library implements this protocol directly in pure Go, bypassing both C and Java layers entirely.

import "github.com/AndroidGoLab/jni/bluetooth"

    adapter, _ := bluetooth.NewAdapter(ctx)
    defer adapter.Close()

    enabled, _ := adapter.IsEnabled()
    name, _ := adapter.GetName()
    addr, _ := adapter.GetAddress()
    fmt.Printf("Bluetooth: %s (%s), enabled=%v\n", name, addr, enabled)

import "github.com/AndroidGoLab/jni/location"

    mgr, _ := location.NewManager(ctx)
    defer mgr.Close()

    locObj, _ := mgr.GetLastKnownLocation(location.GpsProvider)
    fmt.Printf("Location: %v\n", locObj)

import "github.com/AndroidGoLab/jni/net/wifi"

    mgr, _ := wifi.NewManager(ctx)
    defer mgr.Close()

    enabled, _ := mgr.IsWifiEnabled()
    fmt.Println("WiFi enabled:", enabled)

import "github.com/AndroidGoLab/jni/app/notification"

    mgr, _ := notification.NewManager(ctx)
    defer mgr.Close()

    ch, _ := notification.NewChannel(vm, "alerts", "Alerts",
        int32(notification.ImportanceHigh))
    mgr.CreateNotificationChannel(ch.Obj)

    b, _ := notification.NewBuilder(vm, appCtx, "alerts")
    b.SetSmallIcon1_1(iconResID)
    b.SetContentTitle("Hello from Go!")
    b.SetContentText("Posted via JNI — no Java code")
    notif, _ := b.Build()
    mgr.Notify2(1, notif)

All 53 examples are self-contained NativeActivity apps — zero Java code. Each lives in examples/<name>/ with its own Makefile:

cd examples/alarm
make run          # build APK → install → grant permissions → launch

Build and install all examples at once from the repo root:

make examples     # builds all 53 APKs

See examples/ for the full list.

53 Android API packages organized in a Java SDK-mirroring hierarchy:

Android API	Go Package	Import Path
Application Framework
	app	github.com/AndroidGoLab/jni/app
	alarm	github.com/AndroidGoLab/jni/app/alarm
	download	github.com/AndroidGoLab/jni/app/download
	job	github.com/AndroidGoLab/jni/app/job
	notification	github.com/AndroidGoLab/jni/app/notification
	usage	github.com/AndroidGoLab/jni/app/usage
	accounts	github.com/AndroidGoLab/jni/accounts
Bluetooth
	bluetooth	github.com/AndroidGoLab/jni/bluetooth
Content & Storage
	clipboard	github.com/AndroidGoLab/jni/content/clipboard
	pm	github.com/AndroidGoLab/jni/content/pm
	preferences	github.com/AndroidGoLab/jni/content/preferences
	resolver	github.com/AndroidGoLab/jni/content/resolver
	permission	github.com/AndroidGoLab/jni/content/permission
Graphics
	pdf	github.com/AndroidGoLab/jni/graphics/pdf
Hardware
	biometric	github.com/AndroidGoLab/jni/hardware/biometric
	camera	github.com/AndroidGoLab/jni/hardware/camera
	ir	github.com/AndroidGoLab/jni/hardware/ir
	lights	github.com/AndroidGoLab/jni/hardware/lights
	usb	github.com/AndroidGoLab/jni/hardware/usb
Health
	connect	github.com/AndroidGoLab/jni/health/connect
Location
	location	github.com/AndroidGoLab/jni/location
Media
	audiomanager	github.com/AndroidGoLab/jni/media/audiomanager
	player	github.com/AndroidGoLab/jni/media/player
	projection	github.com/AndroidGoLab/jni/media/projection
	recorder	github.com/AndroidGoLab/jni/media/recorder
	session	github.com/AndroidGoLab/jni/media/session
Networking
	net	github.com/AndroidGoLab/jni/net
	nsd	github.com/AndroidGoLab/jni/net/nsd
	wifi	github.com/AndroidGoLab/jni/net/wifi
	p2p	github.com/AndroidGoLab/jni/net/wifi/p2p
	rtt	github.com/AndroidGoLab/jni/net/wifi/rtt
NFC
	nfc	github.com/AndroidGoLab/jni/nfc
OS Services
	battery	github.com/AndroidGoLab/jni/os/battery
	build	github.com/AndroidGoLab/jni/os/build
	environment	github.com/AndroidGoLab/jni/os/environment
	keyguard	github.com/AndroidGoLab/jni/os/keyguard
	power	github.com/AndroidGoLab/jni/os/power
	storage	github.com/AndroidGoLab/jni/os/storage
	vibrator	github.com/AndroidGoLab/jni/os/vibrator
Providers
	documents	github.com/AndroidGoLab/jni/provider/documents
	media	github.com/AndroidGoLab/jni/provider/media
	settings	github.com/AndroidGoLab/jni/provider/settings
Security
	keystore	github.com/AndroidGoLab/jni/security/keystore
	credentials	github.com/AndroidGoLab/jni/credentials
	omapi	github.com/AndroidGoLab/jni/se/omapi
Telecom
	telecom	github.com/AndroidGoLab/jni/telecom
	telephony	github.com/AndroidGoLab/jni/telephony
UI
	display	github.com/AndroidGoLab/jni/view/display
	inputmethod	github.com/AndroidGoLab/jni/view/inputmethod
	toast	github.com/AndroidGoLab/jni/widget/toast
Other
	companion	github.com/AndroidGoLab/jni/companion
	print	github.com/AndroidGoLab/jni/print
	speech	github.com/AndroidGoLab/jni/speech

The project converts Android Java API specifications into safe, idiomatic Go packages through four code generation stages:

flowchart TD
    JNISPEC["spec/jni.yaml"]
    JNIOVER["spec/overlays/jni.yaml"]
    JNITMPL["templates/jni/"]
    JAVASPEC["spec/java/*.yaml"]
    JAVAOVER["spec/overlays/java/*.yaml"]
    JAVATMPL["templates/java/"]
    CAPI["capi/*.go"]
    ROOT["*.go (VM, Env, Class, Object, ...)"]
    PKGS["{package}/*.go (53 packages)"]

    JNISPEC --> S1
    JNIOVER --> S1
    JNITMPL --> S1
    subgraph S1["jnigen"]
        direction LR
        S1D["Generates CGo bindings + idiomatic JNI types"]
    end
    S1 --> CAPI
    S1 --> ROOT

    JAVASPEC --> S2
    JAVAOVER --> S2
    JAVATMPL --> S2
    subgraph S2["javagen"]
        direction LR
        S2D["Generates Android API wrapper packages"]
    end
    S2 --> PKGS

    style JNISPEC fill:#fff3cd,color:#000
    style JNIOVER fill:#fff3cd,color:#000
    style JNITMPL fill:#fff3cd,color:#000
    style JAVASPEC fill:#fff3cd,color:#000
    style JAVAOVER fill:#fff3cd,color:#000
    style JAVATMPL fill:#fff3cd,color:#000
    style CAPI fill:#d4edda,color:#000
    style ROOT fill:#cce5ff,color:#000
    style PKGS fill:#cce5ff,color:#000

Legend: Yellow = hand-written inputs, Green = generated intermediates, Blue = final consumer-facing output.

1. Raw CGo Layer (capi/) — Direct C bindings to JNI via vtable dispatch. Generated by jnigen.

2. Idiomatic JNI Layer (root package) — Safe Go types: VM, Env, Class, Object, Value, String, Array, MethodID, FieldID. All JNI exceptions converted to Go errors. Thread safety via VM.Do(). Generated by jnigen.

3. Android API Layer (53 packages) — High-level wrappers for Android system services. Each package provides a Manager type obtained via NewManager(ctx), with methods that call through JNI. Generated by javagen.

4. gRPC Layer — See jni-proxy for gRPC remote access (proto/grpc generation lives in that repo).

.
├── *.go                          # Core JNI types (VM, Env, Class, Object, ...)
├── capi/                         # Raw CGo bindings to JNI C API
├── internal/                     # Internal: exception handling, test JVM
│
├── app/                          # Android API wrappers (Java SDK hierarchy)
│   ├── alarm/, download/, ...
├── bluetooth/
├── hardware/
│   ├── camera/, usb/, ...
├── media/
│   ├── audiomanager/, player/, ...
├── net/
│   ├── wifi/, nsd/, ...
├── os/
│   ├── power/, battery/, ...
├── ...                           # (53 packages total)
│
├── tools/                        # Code generators
│   ├── jnigen/                   #   Core JNI + capi generation
│   ├── javagen/                  #   Android API package generation
│   └── specgen/                  #   YAML spec generation from .class files
├── spec/                         # YAML API specifications
│   ├── jni.yaml                  #   JNI C API spec
│   ├── java/                     #   Per-package Android API specs
│   └── overlays/                 #   Hand-written customizations
├── templates/                    # Go text templates for code generation
│   ├── jni/
│   └── java/
│
├── ref/android/                  # Reference .class files
└── examples/                     # Per-package usage examples (53 NativeActivity apps)
    ├── common/ui/                #   Shared NativeActivity lifecycle + Canvas renderer
    ├── alarm/, battery/, ...     #   One directory per package
    └── apk.mk                   #   Shared APK build rules

The JNI bindings and generated Android API packages are verified via jni-proxy E2E tests against real hardware.

1. Create spec/java/{package}.yaml with the Java class, methods, and go_import path.
2. Optionally create spec/overlays/java/{package}.yaml for customizations (extra methods, type overrides, name overrides).
3. Run make java to generate the Go package.
4. For gRPC support, see jni-proxy.