xg-glass-sdk

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 35 Open GitHub ↗

One API for smart-glasses apps - camera, mic, display, audio - across Rokid, Meta Ray-Ban, Brilliant Labs Frame, RayNeo, Even Realities G1, INMO, Omi, and a simulator. Android, iOS, and CLI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h3 align="center">
xg.glass
</h3>

<h3 align="center">
Easy, fast, glasses application development for everyone
</h3>

<p align="center">
| <a href="https://xg.glass/developer-guide/"><b>Documentation</b></a> | <a href="https://xg.glass/blog/"><b>Blog</b></a> | <a href="https://github.com/hkust-spark/xg-glass-sample/"><b>Sample Applications</b></a>
</p>

🔥 We have built a xg.glass website to help you get started with xg.glass. Please visit [xg.glass](https://xg.glass) to learn more.

---

## About

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:

| Category | Products | Video stream | Battery events |
| --- | --- | --- | --- |
| Rokid | Rokid Glasses | No | No |
| Meta | Meta Wearables | No, phase 2 validation target | No |
| Brilliant Labs | Frame | No | No |
| RayNeo | x2 Glasses (validated), x3 Pro Glasses (untested) | Yes, JPEG on-glasses runtime | Yes, on-glasses runtime |
| INMO | Air3 (adapter shipped, hardware validation pending) | Yes, JPEG on-glasses runtime | Yes, on-glasses runtime |
| Omi | Omi Glass | No | Yes, when standard BLE Battery Service is discovered |
| Even Realities | G1 (adapter shipped, hardware validation pending) | No | No |
| *Simulation* | — | Yes, JPEG from camera/video | Synthetic |

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

Welcome the contributions from the community on more glasses!

## Getting Started

### App developers (build apps with the SDK)

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

#### Android (Maven Central)

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)](./docs/getting-started-android.md).

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](./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.

```kotlin
// 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 opt-in for Android

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.

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

```kotlin
// 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")
}
```

#### iOS (Swift Package)

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.

```swift
// 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](./docs/swift-package.md) and [iOS device support](./docs/ios-device-support.md).
Start with the [Swift Package quick start](./docs/swift-package.md#quick-start).

#### CLI (PyPI)

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

```bash
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](https://github.com/hkust-spark/xg-glass-sdk/issues/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`.

```bash
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:

```bash
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.

#### Device matrix by channel

| Channel | Works from the channel | Notes |
| --- | --- | --- |
| Android Maven `xgglass-universal` | Rokid, RayNeo, INMO Air3, Simulator, Omi, Even Realities G1, Frame bridge API | Frame is only the bridge API from Maven; a working Frame integration needs the source/CLI flow because the embedded Flutter module is not published. INMO Air3 and Even G1 hardware validation are pending; other hardware validation varies by device. |
| Android Maven `xgglass-device-meta` | Meta | Opt-in artifact. Requires Meta's GitHub Packages repository and a GitHub token with `read:packages`. |
| iOS Swift Package | Simulator, Omi, Even Realities G1, Meta | Frame is sample-only through Flutter add-to-app. Even G1 and Meta HFP microphone hardware validation are pending. Rokid and RayNeo are not available on iOS today; see [iOS device support](./docs/ios-device-support.md). |
| CLI/source flow | Android generated projects, Simulator, and current Frame integration | Use this path for Frame today. The template wires `device-frame-embedded` and the Flutter module from the SDK checkout. |

#### Simulator

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.

```bash
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](https://xg.glass/developer-guide/)
- [Your First App (Android)](./docs/getting-started-android.md)
- [API reference (ai-assistant-guide)](./docs/ai-assistant-guide.md)
- [Swift Package setup](./docs/swift-package.md)
- [iOS device support](./docs/ios-device-support.md)
- [Changelog](./CHANGELOG.md)
- [Contributing](./CONTRIBUTING.md)
- [Security policy](./SECURITY.md)

#### AI-assisted development

We also provide [`docs/ai-assistant-guide.md`](./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.

## Versioning and support

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](./CHANGELOG.md). 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.

## Repository layout

- `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.

### Contributors (extend the SDK)

If you want to **extend xg.glass itself** (new devices, new APIs, build tooling), start with [Contributor Guide](https://xg.glass/contributor-guide/).
For device ports, use the [Adding a Device Adapter](./docs/adding-a-device-adapter.md) guide.

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

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

## License

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

xg-glass-sdk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README