| 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
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, list available recording/streaming profiles, and retrieve device calibration.
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.
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 DeviceTargets.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:
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 |
