Skip to content
Skills Library
Programming · Tool integration

client-sdk

/client-sdk

Use when working with the Aria Client SDK — device pairing, recording, streaming, CLI commands (aria_gen2), Python SDK (aria.sdk_gen2), streaming visualization, multi-device time domain mapping, and device management. Use whenever the user mentions aria_gen2 CLI, aria.sdk_gen2, device pairing, recording start/stop, streaming from Aria glasses, or asks about controlling Aria Gen2 devices programmatically.

Licence
Apache-2.0
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when working with the Aria Client SDK — device pairing, recording, streaming, CLI commands (aria_gen2), Python SDK (aria.sdk_gen2), streaming visualization, multi-device time domain mapping, and device management. Use whenever the user mentions aria_gen2 CLI, aria.sdk_gen2, device pairing, recording start/stop, streaming from Aria glasses, or asks about controlling Aria Gen2 devices programmatically.

Original author description

Use when working with the Aria Client SDK — device pairing, recording, streaming, CLI commands (aria_gen2), Python SDK (aria.sdk_gen2), streaming visualization, multi-device time domain mapping, and device management. Use whenever the user mentions aria_gen2 CLI, aria.sdk_gen2, device pairing, recording start/stop, streaming from Aria glasses, or asks about controlling Aria Gen2 devices programmatically.

How it works

  1. How to Use This Skill
  2. Installation
  3. Prerequisites
  4. Capabilities Overview
  5. CLI vs Python SDK
  6. Key Constraints
  7. Gen1 vs Gen2
  8. ⛔ MANDATORY: Troubleshooting
Original SKILL.md headings · 170 lines, 1,726 words
SKILL.md preview
---
name: client-sdk
description: Use when working with the Aria Client SDK — device pairing, recording, streaming, CLI commands (aria_gen2), Python SDK (aria.sdk_gen2), streaming visualization, multi-device time domain mapping, and device management. Use whenever the user mentions aria_gen2 CLI, aria.sdk_gen2, device pairing, recording start/stop, streaming from Aria glasses, or asks about controlling Aria Gen2 devices programmatically.
---

# Aria Client SDK

The Client SDK lets you control Aria Gen2 glasses from a host PC — pair devices, manage recordings, stream live sensor data, and configure multi-device setups. It ships as a pip package with both a CLI (`aria_gen2`) and a Python SDK (`aria.sdk_gen2`).

## How to Use This Skill

This skill teaches the concepts and capabilities. For exact API details:

- **CLI**: `aria_gen2 <subcommand> --help`
- **Python SDK**: Read `sdk_gen2.pyi` in the installed package (`site-packages/aria/`), or run `help(aria.sdk_gen2)`
- **Sample scripts**: `python -m aria.extract_sdk_samples --output ~/Downloads/`

## Installation

- **Install**: `pip install projectaria-client-sdk` (in a virtual environment, Python 3.10–3.12)
- **Verify**: `aria_doctor` — configures system ports and verifies connectivity
- **Supported**: Linux x64 (Ubuntu/Fedora), macOS Apple Silicon
- **Docs**: https://facebookresearch.github.io/projectaria_tools/gen2/ark/client-sdk/start

## Prerequisites

- Aria Gen2 device with Companion App paired
- USB cable connecting device to PC
- One-time authentication: `aria_gen2 auth pair` (requires approval in Companion App)

## Capabilities Overview

The SDK exposes five capability areas through both CLI and Python SDK:

### Authentication

One-time device-PC pairing. The PC generates a client hash, the user approves in the Companion App, and subsequent connections are automatic. Use `aria_doctor` to verify system readiness before pairing.

### Recording

Start/stop recordings on the device, list recordings, download as VRS files, delete. Recordings use configurable **profiles** that define which sensors are active and at what rate — predefined profiles (e.g. general-purpose, high-res RGB, streaming-optimized) are available on-device, plus custom profiles via JSON. Downloaded VRS files are processed with ProjectAriaTools (PAT).

### Streaming

Stream live sensor data from the device to the host PC in real-time. Three **streaming interfaces** with different tradeoffs:

- **USB** — most reliable, no thermal concern, best for development
- **WiFi Station** — untethered, device and PC on same network, needs message batching for thermal management
- **Device Hotspot** — direct connection for field use without external network, limited to ~20 min sessions due to thermal

Available sensor streams include: RGB camera, SLAM cameras, eye tracking cameras, IMU, magnetometer, barometer, GPS, audio, eye gaze, hand tracking, VIO (visual-inertial odometry), and more.

In the **Python SDK**, streaming uses a callback pattern: create a `StreamDataInterface`, register per-sensor callbacks (e.g. `register_rgb_callback`, `register_imu_callback`, `register_eye_gaze_callback`), then start streaming. Each callback fires when data arrives for that sensor. `StreamDataInterface` also supports `record_to_vrs()` to capture streamed data into a local VRS file on the host — this is the only way to save data during streaming, since on-device recording and streaming cannot run simultaneously.

### Device Management

Query device status (battery, temperature, WiFi, recording state), connect to WiFi networks, start the on-device hotspot, send text-to-speech, manage recording/streaming profiles, and retrieve device calibration.

**Profiles**: `aria_gen2 device profile --help` — list, pull, add, remove. Pull to get a base worth customizing; add won't overwrite an existing name; only profiles you added are removable. To author the JSON, use the **`custom-profile`** skill.

### Multi-Device Time Domain Mapping

Temporal alignment across multiple Aria Gen2 devices using sub-GHz radio hardware. One device is configured as **broadcaster**, others as **receivers**. The broadcaster transmits its timestamps; receivers record timestamp pairs enabling clock conversion. Configure via `TimeDomainMappingConfig` (Python) or `--all` (CLI) on recording or streaming configs. Post-processing uses PAT's `TimeDomain.SUBGHZ` to query receiver data in the broadcaster's time domain.

### Multi-Device Streaming Server

When you need to stream from multiple devices into a **single host process** (e.g. a headless collection server or a live cross-device visualizer), use the **`AriaGen2HttpServer` + per-connection handler factory** pattern. One server listens on `:6768`; every device that connects gets its own fresh `StreamDataInterface` from a factory callback you supply.

**Per-device data via the `device_id` callback param**: declare `device_id: str | None = None` as a keyword argument on any streaming callback. The SDK detects this via `inspect.signature()` at registration time and starts passing the device's serial number on every fire. Callbacks without the param keep working unchanged — single- and multi-device code can share the same callback.

```python
def rgb_callback(image_data, image_record, device_id: str | None = None):
    print(f"[{device_id}] RGB frame")

def setup_stream_handler() -> StreamDataInterface:
    handler = StreamDataInterface(enable_image_decoding=True, enable_raw_stream=False)
    handler.register_rgb_callback(rgb_callback)
    return handler

server = AriaGen2HttpServer(
    HttpServerConfig(address="0.0.0.0", port=6768),
    setup_stream_handler,
)
```

Start streaming on every device pointing at the same server URL (`aria_gen2 streaming start --all ...` is the quickest path). Each device opens an independent HTTPS connection — verify both are live with `lsof -i :6768`. If only one shows up, the second device probably failed the TLS handshake — **both devices must use the same streaming certificate**. The persistent certificate lives at `~/.aria/streaming-certs/persistent/` on the host PC; both devices receive it on first `aria_gen2 streaming start` from that host. If a device was previously paired against a different host, re-run `aria_gen2 streaming install-certificates` from the current host to overwrite it.

**Cross-thread state needs locking.** Callbacks fire from internal SDK threads, not the main thread. Any per-device dict you read or write from a callback (frame counters, recent TDM offsets, frame buffers) must be guarded by a `threading.Lock`. Even simple counter increments are not safe without it.

The broadcaster does NOT fire TDM callbacks (its `DEVICE_TIME` is the reference, so it has nothing to map). Only receivers report TDM offsets. If you see TDM-callback output for N−1 of your N devices, that's expected — the missing one is the broadcaster.

Worked example: https://facebookresearch.github.io/projectaria_tools/gen2/ark/client-sdk/python-sdk/multi-device-streaming-example

## CLI vs Python SDK

Pick by intent:

- **CLI** (`aria_gen2`): One-shot operations, inspection, or chaining a few sequential actions.
- **Python SDK** (`import aria.sdk_gen2 as sdk_gen2`): Streaming with per-sensor callbacks, conditional logic during streaming, host-side VRS capture, or integration into a Python pipeline.
- **Default**: CLI for one-shot, Python SDK for callback-driven workflows.

### Python SDK Architecture

The SDK follows a client → device → operation model:

- `DeviceClient` — discovers and connects to devices. Supports multi-device via `usb_network_devices()` and connecting to specific `DeviceTarget`s.
- `Device` — represents a connected device. All operations (recording, streaming, device management) go through this object.
- `StreamDataInterface` — handles streaming data reception. Register per-sensor callbacks, set queue sizes, and optionally record to local VRS.
- Config objects: `RecordingConfig`, `HttpStreamingConfig`, `TimeDomainMappingConfig` — set on the device before starting operations.

### Streaming Visualization

Default to `aria_streaming_viewer` — more polished and actively maintained. `aria_rerun_viewer` is for playback of downloaded VRS files, not live streaming.

**`aria_streaming_viewer` is a persistent GUI window** — it displays live sensor data for as long as the streaming session lasts. It does NOT exit after launch. When launching it:

- Start streaming first (`aria_gen2 streaming start`), then launch the viewer.
- Run it as a background process (`run_in_background` or `&`) — it blocks the terminal indefinitely.
- Do NOT wait for it to exit, kill it, or treat it as a one-shot command.
- It stays alive until the user closes the window or streaming stops.

### Streaming Certificates (TLS)

Streaming between device and host uses TLS with self-signed certificates. Two cert types exist:

- **Persistent** — stored in `~/.aria/streaming-certs/persistent/`, survive across sessions, installed via `aria_gen2 streaming install-certificates` or auto-generated on first `aria_gen2 streaming start`
- **Ephemeral** — stored in `~/.aria/streaming-certs/ephemeral/`, regenerated each session

The CLI `aria_gen2 streaming start` auto-installs a persistent cert if none exists — no manual cert setup needed for the typical workflow.

**Viewer only loads persistent certs.** Both `aria_streaming_viewer` and the multi-device streaming viewer hardcode to `~/.aria/streaming-certs/persistent/`. If streaming was started with ephemeral certs (e.g. via Python SDK with `StreamingSecurityOptions.use_ephemeral_certs = True`), the viewer's TLS handshake will silently fail — the viewer appears to start but shows no data. There is no error message indicating a cert mismatch.

**Rule**: When using the viewer, always ensure streaming uses persistent certs (the default). If you must use ephemeral certs for a custom Python SDK workflow, do not use `aria_streaming_viewer` — handle stream data via SDK callbacks instead.

## Key Constraints

- **Auth before anything**: All connections fail without prior `aria_gen2 auth pair`.
- **Recording and streaming are exclusive**: Cannot run both on-device simultaneously. Use `record_to_vrs()` for host-side capture during streaming.
- **USB required for control**: USB connection is needed to start/stop streaming, even when streaming wirelessly.
- **Streaming before viewer**: The viewer connects to an active stream — start streaming first.
- **Viewer requires persistent certs**: The viewer only loads certs from `~/.aria/streaming-certs/persistent/`. Streaming with ephemeral certs will silently fail to display in the viewer.
- **Guest WiFi won't work**: Guest networks block peer-to-peer communication required for streaming.
- **Errors → Troubleshooting section FIRST**: When any SDK command fails or returns unexpected output, you MUST check the Troubleshooting section below and the official troubleshooting page before attempting your own diagnosis. Do not guess root causes from training data — Aria errors have Aria-specific causes that generic debugging will miss.

## Gen1 vs Gen2

The pip package includes both. Gen1 uses `aria` CLI and `import aria.sdk`. Gen2 uses `aria_gen2` CLI and `import aria.sdk_gen2`. Type stubs: `sdk.pyi` (Gen1), `sdk_gen2.pyi` (Gen2). Gen1 and Gen2 SDK are **NOT interchangeable**.

## ⛔ MANDATORY: Troubleshooting

**When any Client SDK command fails or returns unexpected output, you MUST consult this section and the official troubleshooting page BEFORE attempting your own diagnosis.** This is not optional. Aria failures have Aria-specific root causes (sandbox blocks, cert mismatches, thermal shutdowns, mDNS issues) that generic debugging will misdiagnose.

Anti-patterns:

- ❌ "I think I know what's wrong" — check the table first; your guess wastes the user's time when the documented fix is one row away.
- ❌ "Let me try a different approach" — the documented fix exists for a reason. Try it before improvising.
- ❌ "This looks like a generic Python/network error" — it almost certainly has an Aria-specific cause.

**Resources**:

- **First step always**: `aria_doctor` — configures ports and diagnoses connectivity.
- **Official troubleshooting page**: https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/sdk — covers symptoms not listed below.

### Common Issues

| Symptom | Action |
|---------|--------|
| Device not detected | Run `aria_doctor`. Try different USB 3.0+ port/cable. Disable VPN. |
| `auth pair` hangs | Open Companion App, navigate to pairing screen. Check phone internet. |
| Streaming disconnects | USB: use quality cable, avoid hubs. WiFi: check signal/firewall. |
| Device overheating | Shuts down at ~44°C. Cool 5-10 min. Limit hotspot streaming to ~20 min. |
| Viewer starts but no data | Cert mismatch: streaming used ephemeral certs but the viewer only loads persistent certs. Restart streaming without `use_ephemeral_certs`, or run `aria_gen2 streaming install-certificates` then restart streaming. |
| `GLIBCXX_3.4.31 not found` (Ubuntu 22) | `sudo apt install g++-13` |

Versions

The database has no other skills named client-sdk.

Database snapshot: 13.11.2026 · package version 11b97923ad89 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100client-sdk-ros2-integration
    Use when integrating Aria Gen 2 sensor streams with ROS2 — publishing raw Aria sensor data through ROS2 topics, decoding it in subscriber nodes, sharing device calibration across nodes. The integration uses a custom `AriaRaw` message (a thin FlatBuffer wrapper) and a required…
  • 100cloud-streaming
    Use when configuring Aria Gen 2 glasses to stream sensor data directly to an internet-accessible HTTPS endpoint — instead of the default local USB / same-network WiFi streaming to a nearby PC. For field deployments, centralized multi-device collection, and cloud processing…
  • 100react-aria
    Build accessible UI components with React Aria. Use when creating accessible form controls, implementing ARIA patterns, building design systems, or fixing accessibility issues.
  • 100aria-attribute-helper
    Configure with aria attribute helper operations. Auto-activating skill for Frontend Development. Triggers on: aria attribute helper, aria attribute helper Part of the Frontend Development skill category. Use when working with aria attribute helper functionality. Trigger with…
  • 95anthropic-python
    Anthropic Python SDK for Claude API integration. Covers messages API, streaming, tool use, vision, error handling, and best practices. Use when building Python applications that call the Claude API. USE WHEN: user mentions "anthropic", "claude api", "anthropic sdk",…
  • 90fe-a11y-aria
    Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages.…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.