client-sdk
/client-sdk
Prowadzi przez pracę z Aria Client SDK: parowanie urządzeń, nagrywanie, streaming, polecenia CLI aria_gen2, Python SDK aria.sdk_gen2 i zarządzanie okularami Aria Gen2.
- Autor
- facebookresearch ↗
- Repozytorium
- projectaria-plugins ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 20.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Prowadzi przez pracę z Aria Client SDK: parowanie urządzeń, nagrywanie, streaming, polecenia CLI aria_gen2, Python SDK aria.sdk_gen2 i zarządzanie okularami Aria Gen2.
Oryginalny opis (EN)
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.
Jak działa
- How to Use This Skill
- Installation
- Prerequisites
- Capabilities Overview
- CLI vs Python SDK
- Key Constraints
- Gen1 vs Gen2
- ⛔ MANDATORY: Troubleshooting
Podgląd SKILL.md
---
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` |
Wersje
W bazie nie ma innych skilli o nazwie client-sdk.
Migawka bazy z 13.11.2026 · wersja paczki 11b97923ad89 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100client-sdk-ros2-integration
Pomaga zintegrować strumienie czujników Aria Gen 2 z ROS2: publikowanie danych przez tematy, dekodowanie w węzłach subskrybujących i współdzielenie kalibracji urządzenia. - 100cloud-streaming
Konfiguruje okulary Aria Gen 2 do strumieniowania danych z czujników bezpośrednio na publiczny endpoint HTTPS, do wdrożeń terenowych, zbierania z wielu urządzeń i potoków przetwarzania w chmurze. - 100react-aria
Pomaga budować dostępne komponenty UI z React Aria: kontrolki formularzy, wzorce ARIA, systemy projektowe i naprawa problemów z dostępnością. - 100aria-attribute-helper
Prawdopodobnie pomaga konfigurować atrybuty ARIA w ramach tworzenia frontendu i dostępności interfejsu. - 95anthropic-python
Pokazuje integrację z Claude API przez Anthropic Python SDK: Messages API, streaming, tool use, vision i obsługa błędów, przy budowie aplikacji w Pythonie. - 90fe-a11y-aria
Dobiera poprawne nazwy, role, stany i komunikaty ARIA zgodnie z WCAG 2.2 AA, zaczynając od natywnych elementów HTML.