jni

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.

Android Interfaces for Go

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

Library	Interface	Requires	Best for
ndk	Android NDK C APIs	cgo + NDK toolchain	High-performance hardware access: camera, audio, sensors, OpenGL/Vulkan, media codecs
jni (this project)	Java Android SDK via JNI	cgo + JNI + JVM/ART	Java-only APIs with no NDK equivalent: Bluetooth, WiFi, NFC, location, telephony, content providers
binder	Binder IPC (system services)	pure Go (no cgo)	Direct system service calls without Java: works on non-Android Linux with binder, minimal footprint

When to use which

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.

How they relate to each other

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.

Usage Examples

Bluetooth

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)

Location

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

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

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

WiFi

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

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

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

Notifications

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)

Running Examples

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.

Supported Packages

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`

Architecture

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.

Layers

Raw CGo Layer (capi/) — Direct C bindings to JNI via vtable dispatch. Generated by jnigen.
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.
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.
gRPC Layer — See jni-proxy for gRPC remote access (proto/grpc generation lives in that repo).

Project Layout

.
├── *.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

Make Targets

Target	Description	Requires
`make generate`	Run all generators (specs + jni + java)	JDK + Android SDK
`make specs`	Generate YAML specs from .class files	JDK + Android SDK
`make jni`	Generate core JNI + capi	--
`make java`	Generate Android API packages	--
`make test`	Run all tests	JDK
`make test-tools`	Run generator tests only	--
`make examples`	Build all 53 example APKs	Android SDK + NDK
`make build`	Cross-compile for android/arm64	Android NDK
`make prove`	Verify Lean 4 proofs	elan/lake
`make lint`	Run golangci-lint	golangci-lint
`make clean`	Remove all generated files	--

E2E Test Verification

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

Verified platforms (click to expand)

Type	Device	Android	API	ABI	Build	Date	Passed	Total
Phone	Pixel 8a	16	36	arm64-v8a	BP4A.260205.001	2026-03-15	21	21
Emulator	sdk_gphone64_x86_64	15	35	x86_64		2026-03-14	21	21

Tests cover: JNI version, class operations, method lookup + call, string round-trip, object operations, handle lifecycle, field access, exception handling, and full integration workflows. Camera recording, microphone recording, GPS location, and battery status are also verified on the Pixel 8a.

Adding a New Android API Package

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

Name		Name	Last commit message	Last commit date
Latest commit History 193 Commits
.github/workflows		.github/workflows
accessibilityservice		accessibilityservice
accounts		accounts
adservices		adservices
animation		animation
annotation		annotation
app		app
appwidget		appwidget
bluetooth		bluetooth
capi		capi
companion		companion
content		content
credentials		credentials
crypto/hpke		crypto/hpke
database		database
devicelock		devicelock
docs		docs
drm		drm
examples		examples
gesture		gesture
graphics		graphics
hardware		hardware
health/connect		health/connect
icu		icu
inputmethodservice		inputmethodservice
internal		internal
java		java
javax/crypto		javax/crypto
location		location
media		media
mtp		mtp
net		net
nfc		nfc
opengl		opengl
os		os
preference		preference
print		print
printservice		printservice
proofs		proofs
provider		provider
ranging		ranging
ref/android		ref/android
renderscript		renderscript
sax		sax
se/omapi		se/omapi
security		security
service		service
spec		spec
speech		speech
system		system
telecom		telecom
telephony		telephony
templates		templates
tests/e2e		tests/e2e
text		text
tools		tools
transition		transition
util		util
view		view
webkit		webkit
widget		widget
window		window
.gitignore		.gitignore
.golangci.yml		.golangci.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
array.go		array.go
booleanarray.go		booleanarray.go
bytearray.go		bytearray.go
chararray.go		chararray.go
class.go		class.go
const.go		const.go
context7.json		context7.json
coverage.out		coverage.out
doublearray.go		doublearray.go
env.go		env.go
errors.go		errors.go
field_id.go		field_id.go
floatarray.go		floatarray.go
globalref.go		globalref.go
go.mod		go.mod
go.sum		go.sum
intarray.go		intarray.go
jni_coverage_test.go		jni_coverage_test.go
jni_difftest_test.go		jni_difftest_test.go
jni_extended_test.go		jni_extended_test.go
jni_proxy_test.go		jni_proxy_test.go
jni_test.go		jni_test.go
longarray.go		longarray.go
method_id.go		method_id.go
object.go		object.go
object_ref.go		object_ref.go
object_ref_type.go		object_ref_type.go
objectarray.go		objectarray.go
package.go		package.go
proxy.go		proxy.go
proxy_cgo.go		proxy_cgo.go
proxy_handler_full.go		proxy_handler_full.go
shortarray.go		shortarray.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

jni

Android Interfaces for Go

When to use which

How they relate to each other

Usage Examples

Bluetooth

Location

WiFi

Notifications

Running Examples

Supported Packages

Architecture

Layers

Project Layout

Make Targets

E2E Test Verification

Adding a New Android API Package

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

jni

Android Interfaces for Go

When to use which

How they relate to each other

Usage Examples

Bluetooth

Location

WiFi

Notifications

Running Examples

Supported Packages

Architecture

Layers

Project Layout

Make Targets

E2E Test Verification

Adding a New Android API Package

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages