buildai-data 0.3.1

The standard API for egocentric data.

BuildAI

The standard API for egocentric data. $1/hr.

Quickstart

pip install buildai-data

from buildai import BuildAI

client = BuildAI(api_key="build_data_xxxx")
client.download(hours=10, output_dir="./data")

That's it. Ten shards download to ./data/. Each shard is one hour of egocentric video with frame-synced IMU data.

What you get

Each shard is a tar file containing 20 three-minute clips:

shard-000001.tar
  ├── 000001.mp4       # H.265, 1080p, 30fps, no audio
  ├── 000001.imu.npy   # (5400, 6) float32, frame-synced
  ├── 000002.mp4
  ├── 000002.imu.npy
  └── ...              # 20 clips total

Video: H.265, 1080p, 30fps, no audio. Three minutes per clip.

IMU: NumPy array, shape (5400, 6), float32. Columns: [acc_x, acc_y, acc_z, gyro_x, gyro_y, gyro_z]. Row N = frame N (30 fps x 180 seconds = 5400 frames). Units: accelerometer in m/s2, gyroscope in rad/s.

Shard size: ~2 GB per shard, ~1 hour of footage, 20 clips.

Shards are standard WebDataset format. If you already have a WebDataset pipeline, point it at the downloaded tars directly.

Download

from buildai import BuildAI

client = BuildAI(api_key="build_data_xxxx")

# Download 100 hours of data
client.download(hours=100, output_dir="/data/buildai/")

# Download more - you'll get new shards you haven't seen before
client.download(hours=1000, output_dir="/data/buildai/")

Every call gets new shards. You never receive the same shard twice. Shards are downloaded sequentially. Every researcher gets the same sequence.

Downloads resume on failure. If a shard already exists locally and the checksum matches, it's skipped.

Parameter	Default	Description
hours	required	Number of hours to download (1 shard = 1 hour)
output_dir	./buildai-data	Where to save shard tars
workers	8	Parallel download threads
verify_checksum	True	SHA-256 verification after download

Visualize

from buildai import BuildAI

BuildAI.visualize(source="/data/buildai/")

Opens a local web viewer in your browser. Shows a grid of all clips across your downloaded shards. Click any clip to watch the video with accelerometer and gyroscope data graphed below, time-synced.

No data is uploaded. Everything runs locally. Press Ctrl+C to stop.

No API key needed. visualize is a static method that works on any directory of shard tars.

Pricing

$1 per hour. Billed monthly. No minimum, no commitment.

API key

Get your API key at build.ai. You can also set it via environment variable:

export BUILDAI_API_KEY=build_data_xxxx

# Picks up BUILDAI_API_KEY automatically
client = BuildAI()

Account

info = client.account
print(info["total_hours"])
print(info["total_spent_usd"])
print(info["shards_remaining"])

Requirements

• Python 3.10+
• httpx (HTTP client)
• numpy (IMU data)