Skip to main content

Python SDK Examples

The ClientSDK provides a comprehensive Python interface for programmatic control of your Aria Gen2 device. This page introduces the Python SDK and guides you through setting up the example code.

Overview​

The Python SDK enables you to:

  • Authenticate devices programmatically with your PC
  • Establish connections to devices via USB or wirelessly
  • Control recording - Start, stop, and download recordings
  • Manage streaming - Stream data with custom callbacks for real-time processing
  • Send commands - Control device features like text-to-speech

Prerequisites​

Before using the Python SDK, ensure you have:

One-Time Setup: Device Authentication Required

Before running any Python SDK examples that control the device (recording, streaming, TTS, etc.), you must authenticate your device by running aria_gen2 auth pair (see Device Authentication). This only needs to be done once per device-PC combination, but all device_client.connect() calls will fail without it.

Export Example Code​

The SDK includes example scripts that demonstrate common use cases. Extract them using:

# Export example codes
python -m aria.extract_sdk_samples --output ~/Downloads/

This creates a projectaria_client_sdk_samples_gen2 directory containing all example scripts:

ls ~/Downloads/projectaria_client_sdk_samples_gen2

device_auth.py          # Authentication example
device_connect.py       # Connection example
device_record.py        # Recording example
device_streaming.py     # Streaming example
device_tts.py           # Text-to-speech example

Available Examples​

The following example pages provide detailed walkthroughs of each script:

1. Authentication Example​

Learn how to programmatically authenticate your device with your PC. This is the first step before using any device features.

Topics covered:

  • Setting up DeviceClient
  • Initiating authentication
  • Handling authentication confirmation

2. Connection Example​

Understand how to establish a connection to a specific device using serial numbers or IP addresses.

Topics covered:

  • Configuring device selection
  • Establishing connections
  • Handling connection errors

3. Recording Example​

Learn how to control recording operations, including starting, stopping, and downloading recordings.

Topics covered:

  • Setting up recording configurations
  • Managing recording sessions
  • Downloading recordings to your local machine

4. Streaming Example​

Explore real-time data streaming with custom callback functions for processing sensor data.

Topics covered:

  • Configuring streaming profiles and interfaces
  • Implementing data callbacks (image, audio, IMU, eye gaze, hand tracking, VIO)
  • Recording streaming data to VRS files

5. Text-to-Speech Example​

Learn how to send text-to-speech commands to your device for audio feedback.

Topics covered:

  • Sending TTS commands
  • Controlling device audio output

6. Multi-Device Streaming Example​

Receive streams from multiple Aria Gen 2 devices in one server using the opt-in device_id callback parameter for per-device identity.

Topics covered:

  • Running an AriaGen2HttpServer that accepts multiple connections
  • The device_id callback parameter and how the SDK auto-detects it via inspect.signature()
  • Registering register_time_domain_mapping_callback for clock alignment
  • Aggregating per-device data with thread-safe state

Common Python SDK Patterns​

Basic Device Connection Pattern​

Most scripts follow this basic pattern:

import aria.sdk_gen2 as sdk_gen2

# Create device client
device_client = sdk_gen2.DeviceClient()

# Configure client (optional - defaults to first available device)
config = sdk_gen2.DeviceClientConfig()
config.device_serial = "1M0YDB5H7B0020"  # Optional: specify device
device_client.set_client_config(config)

# Connect to device
device = device_client.connect()
print(f"Connected to device: {device.connection_id()}")

# Use device for recording, streaming, etc.

Error Handling Pattern​

Always wrap device operations in try-except blocks:

try:
    device = device_client.connect()
    print(f"Successfully connected to device {device.connection_id()}")
except Exception as e:
    print(f"Failed to connect: {e}")
    return

Configuration Pattern​

Device operations (recording, streaming) typically require configuration:

# Recording configuration
recording_config = sdk_gen2.RecordingConfig()
recording_config.profile_name = "profile8"
recording_config.recording_name = "my_recording"
device.set_recording_config(recording_config)

# Streaming configuration
streaming_config = sdk_gen2.HttpStreamingConfig()
streaming_config.profile_name = "mp_streaming_demo"
device.set_streaming_config(streaming_config)

Per-Device Identity in Callbacks (Multi-Device)​

When streaming from multiple devices through a single server, declare an optional device_id parameter on any callback to receive the source device's serial:

def rgb_callback(image_data, image_record, device_id: str | None = None) -> None:
    serial = device_id or "unknown"
    print(f"[{serial}] RGB frame")

handler.register_rgb_callback(rgb_callback)

The SDK detects the device_id parameter via inspect.signature() at registration time. Existing single-device callbacks (no device_id) continue to work unchanged. See Multi-Device Streaming Example for a complete walkthrough.

Single-device recording and streaming are fully supported from Python — device.set_recording_config() + device.start_recording() and device.set_streaming_config() + device.start_streaming(). See Recording Example and Streaming Example.

Multi-device orchestration — starting/stopping recordings or streams across all connected devices in one call — is exposed only through the CLI by design (aria_gen2 recording start --all / streaming start --all). The Python SDK exposes the per-device primitives and receiver-side multi-device support (factory-per-connection in AriaGen2HttpServer, plus the optional device_id callback parameter for per-device identity); combine the CLI for orchestration with a Python receiver for end-to-end multi-device pipelines.

Next Steps​

  1. Start with basics: Begin with the Authentication Example
  2. Progress through examples: Work through each example in order
  3. Experiment: Modify the examples to fit your use case
  4. Build custom applications: Use the patterns to create your own scripts

Additional Resources​