| Documentation | Blog | Sample Applications

🔥 We have built a xg.glass website to help you get started with xg.glass. Please visit xg.glass to learn more.

xg.glass is a fast and easy-to-use library for smart glasses application development.

Smart glasses development is supposed to be easy. If you want to build an application, all you need is the following four interfaces:

• Video input from the camera
• Audio input from the microphone
• Display output
• Audio output

This is what xg.glass has extracted for you from tens of smart glasses SDKs. We hide all details of communicating with difference glasses' SDKs and make sure that the code that you develop based on xg.glass can smoothly run on multiple glasses or a simulator without any single line of additional effort.

Currently we support:

We're working on and will support more glasses soon.

Welcome the contributions from the community on more glasses!

Choose one installation channel depending on the platform you are targeting.

Use Maven Central for normal Android apps. SDK artifacts use group io.github.hkust-spark, version 0.2.1, and prefixed artifact IDs such as xgglass-universal, xgglass-core, and xgglass-device-meta. Note that the Maven group is only the distribution namespace — Kotlin packages in code are com.xgglass.* (for example import com.xgglass.core.GlassesClient).

New to the SDK? Follow Your First App (Android).

The main Android artifact is xgglass-universal. It includes Rokid, RayNeo, INMO Air3, Simulator, Omi, and the Frame bridge API. The SDK minSdk is 28; Meta support and the RayNeo glasses host require minSdk 29. RayNeo support additionally requires the vendor AARs downloaded from RayNeo's developer docs; see third_party/rayneo/aar/README.md.

Besides google() and mavenCentral(), one extra repository is required: Rokid support pulls com.rokid.cxr:client-m from Rokid's Maven repository. Published SDK artifacts other than Rokid's vendor dependency resolve from Maven Central alone.

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        exclusiveContent {
            forRepository {
                maven { url = uri("https://maven.rokid.com/repository/maven-public/") }
            }
            filter {
                includeGroupByRegex("com\\.rokid(\\..+)?")
            }
        }
    }
}

// your app module's build.gradle.kts
dependencies {
    implementation("io.github.hkust-spark:xgglass-universal:0.3.0")
}

Meta is intentionally separate from xgglass-universal. Add xgglass-device-meta and Meta's GitHub Packages repository, then provide a GitHub username and token with read:packages scope.

# ~/.gradle/gradle.properties
github_user=YOUR_GITHUB_USERNAME
github_token=ghp_xxxxxxxxxxxxx

// settings.gradle.kts
val metaGithubUser = providers.gradleProperty("github_user").orNull
    ?: providers.environmentVariable("GITHUB_ACTOR").orNull
    ?: ""
val metaGithubToken = providers.gradleProperty("github_token").orNull
    ?: providers.environmentVariable("GITHUB_TOKEN").orNull
    ?: ""

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/facebook/meta-wearables-dat-android")
            credentials {
                username = metaGithubUser
                password = metaGithubToken
            }
        }
    }
}

// your app module's build.gradle.kts
dependencies {
    implementation("io.github.hkust-spark:xgglass-device-meta:0.3.0")
}

The Swift Package is hosted from this repository and requires iOS 16+. It publishes XgGlass for the core API plus Simulator/Omi adapters, and XgGlassMeta for the Meta adapter with Meta DAT 0.8.0.

// Package.swift
dependencies: [
    .package(url: "https://github.com/hkust-spark/xg-glass-sdk", from: "0.3.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "XgGlass", package: "xg-glass-sdk"),
            .product(name: "XgGlassMeta", package: "xg-glass-sdk")
        ]
    )
]

The XgGlassKit binary is downloaded automatically from the GitHub Release for the version you depend on — no local build step is needed. See Swift Package setup and iOS device support. Start with the Swift Package quick start.

Use the CLI for generated projects and source-based workflows, especially when you need Frame support today.

pip install xg-glass
xg-glass --help

Run xg-glass doctor to diagnose the Java, Android SDK, adb, emulator, Flutter, SDK cache, and network setup that the CLI will actually use.

Run xg-glass validate --devices <device> to generate a filtered validation app, install and launch it, guide a tester through the supported hardware checks, and write a paste-ready Markdown report for issue #63. The runner does not automate BLE pairing or glasses gestures; it uses generated-app logcat markers when available and prompts for manual PASS/FAIL/SKIP otherwise.

Out of the box, the PyPI CLI can build, install, and run inside an already-generated project that contains xg-glass.yaml. Commands that create a project from this SDK, such as xg-glass init and xg-glass run <file.kt>, need an SDK checkout passed with --sdk and, where needed, --template.

xg-glass build
xg-glass install
xg-glass run

For simulator generated projects, xg-glass run --sim uses the same one-shot path as quick mode: apply simulator settings, build, boot an Android Emulator if the selected serial is not online, install, and launch. Add --local_video /path/to/video.mp4 or --video_url <url> to feed simulator capturePhoto() and startVideoStream() from video.

Generated apps default to the all-device xgglass-universal-full path for demos. Production apps can opt into only the adapters they ship with xg-glass init --devices, for example:

xg-glass init ./myapp --devices even,simulator
xg-glass init ./myapp --devices rokid,rayneo
xg-glass init ./myapp --devices frame,simulator

Valid values are rokid, rayneo, meta, frame, omi, even, inmo, simulator, and all; --sim adds simulator to concrete selections. Explicit selections are recorded in xg-glass.yaml as devices: [even, simulator]. Based on the app-size spike, Frame/Flutter adds about 14.6 MiB to the arm64 APK and Meta adds about 15.9 MiB relative to the lean floor, so opt into them deliberately for production builds.

If you don't have glasses right now, the simulator supports development and testing. In source/CLI workflows, add --sim and your computer camera or a video dataset can act as the glasses camera.

xg-glass run --sdk /path/to/xg-glass-sdk --sim /path/to/MyEntry.kt
xg-glass run --sdk /path/to/xg-glass-sdk --sim --devices simulator /path/to/MyEntry.kt
xg-glass run --sdk /path/to/xg-glass-sdk --sim --local_video /path/to/video.mp4 /path/to/MyEntry.kt
xg-glass run --sdk /path/to/xg-glass-sdk --sim --video_url <youtube-or-bilibili-url> /path/to/MyEntry.kt

In quick mode, --devices is available only when passing a .kt file; generated-project runs keep the device set fixed by xg-glass init.

The launch of Android Emulator may take several minutes. You can keep it on to save time for the next run.

For more details, see the following documentation:

• Developer Guide
• Your First App (Android)
• API reference (ai-assistant-guide)
• Swift Package setup
• iOS device support
• Changelog
• Contributing
• Security policy

We also provide docs/ai-assistant-guide.md, a comprehensive reference specifically prepared for AI coding assistants such as ChatGPT, Claude, Cursor, and Copilot.

Developers can give this document directly to their AI assistant so it can reference the xg.glass SDK APIs, patterns, and examples when helping build applications.

xg.glass follows Semantic Versioning. While the major version is 0, minor releases (0.x to 0.y) may include breaking API changes; those changes are always listed in the CHANGELOG. Patch releases will not break public APIs.

Sealed hierarchies such as ConnectionState and GlassesEvent may gain new subtypes in minor releases, so keep an else branch in Kotlin when expressions. Deprecated APIs are kept with @Deprecated for at least one minor release before removal.

Supported toolchains:

• Android minSdk 28; minSdk 29 for Meta and the RayNeo glasses host.
• Android compileSdk 36.
• JDK 17+.
• Building from source needs Kotlin 2.4+ and Android Gradle Plugin 9.x.
• iOS 16+ with Xcode 15.4+.
• CLI Python 3.9+ on macOS/Linux.

Per-device hardware-validation status is listed in the device table above.

• kotlin/ — shared SDK modules (core, core-android, app-contract, universal) plus internal scaffolding (universal-full, app).
• devices/ — per-device adapters.
• Sources/ and Package.swift — Swift Package products.
• tools/ — the xg-glass CLI.
• templates/ — app template used by xg-glass init.
• samples/ — iOS sample.
• third_party/ — Flutter Frame module and the bring-your-own RayNeo AAR directory.
• scripts/ — build and release helpers.
• docs/ — documentation and design notes.

If you want to extend xg.glass itself (new devices, new APIs, build tooling), start with Contributor Guide. For device ports, use the Adding a Device Adapter guide.

For local development, clone the repository and use the editable CLI package under tools/, or invoke the root launcher directly:

git clone https://github.com/hkust-spark/xg-glass-sdk.git
cd xg-glass-sdk
pip install -e tools/
./xg-glass --help

xg.glass is licensed under the Apache License 2.0. Third-party dependency and redistributed asset notices are listed in THIRD-PARTY-NOTICES.md.