Recordings

List and fetch recordings for a twin or an environment, then inspect the fetched artifacts locally.

Defaults at a glance

recordings.list() deliberately narrows a request before it downloads catalog pages. Its defaults are the same for twin.recordings.list() and cw.environments.recordings.list(); twin-scoped calls additionally apply that twin filter on the server.

Argument	Default	Effect
`start`, `end`	both omitted	Calls availability and selects the most recent UTC day with eligible recordings.
`include_unready`	`False`	Returns ready recordings only. Set `True` to include materializing or failed rows when your access allows it.
`limit`	`200`	Returns at most 200 items, in HTTP pages of 50.
`limit=0`	—	Follows every page in the selected day or explicit date range.
`filter`	omitted	Applied locally after retrieval; it does not widen the selected day/range or search past `limit`.

Pass both start and end to select an older or wider UTC date range.

Twin-scoped

items = twin.recordings.list()                       # the twin's most recent recording day
cams = twin.recordings.list(filter=[twin.recordings.types.CAMERA])
pcs = twin.recordings.list().filter(twin.recordings.types.POINTCLOUD)

rec = twin.recordings.get(items[0])                  # downloads artifacts locally
rec.info()                                           # identity, types, available accessors
rec.read_robot()                                     # robot actuation table (if present)
rec.close()                                          # remove downloaded temp files

Environment-scoped

An environment id is always required.

items = cw.environments.recordings.list(environment_id="acme/envs/floor")
rec = cw.environments.recordings.get(items[0])

Date filtering

start/end accept a date, a datetime, or an ISO 8601 string (both date-only and full datetime forms, with or without a Z/offset suffix). Provide both bounds together — a one-sided window is rejected:

items = twin.recordings.list(start="2026-07-01", end="2026-07-05")
items = twin.recordings.list(start="2026-07-01T00:00:00Z", end="2026-07-05")

With no start/end, list() checks which days have recordings and lists the most recent one, rather than the environment’s whole history. Pass an explicit window to reach older recordings.

Paging

list() fetches recordings in pages of 50 and returns at most limit (default 200). Use limit=0 to keep following pages until the window is exhausted.

items = twin.recordings.list(limit=500)              # up to 500, 50 per request
items = twin.recordings.list(start="2026-07-01", end="2026-07-05", limit=0)  # everything in range

filter= narrows the recordings that were fetched, so widen limit (or the date window) rather than relying on filter to search further back. Like the replay picker, list() excludes materializing or failed recordings by default. Pass include_unready=True only when those rows are needed. list() warns when it returns a partial view, so a truncated result never looks complete:

recordings.list(): no start/end given, so only 2026-07-05 is listed — the most
recent day with recordings. Pass start=/end= to list a wider window.
recordings.list(): stopped at limit=200 and more recordings are available for
2026-07-05. Raise limit= or pass limit=0 to fetch every page.

Silence them with logging.getLogger("cyberwave.managers.recordings").setLevel(logging.ERROR). If the API gateway rejects a catalog response because its payload is too large, the SDK raises RecordingPayloadTooLargeError instead of exposing the opaque platform HTTP 500. Its message includes the selected window, cloud trace, and instructions to use a shorter start/end interval or lower limit.

Types & viewers

Recording types: camera, robot, pointcloud (colored/lidar points), depth (raw depth maps), audio. A depth camera typically matches camera + depth, and also pointcloud when colored points are produced. get() downloads every artifact to a temp directory. The readers require the data extra:

pip install 'cyberwave[data]'

The data extra installs headless OpenCV (decoding only). For GUI video playback with show_video(), also install a non-headless build: pip install opencv-python.

Contextual accessors

A fetched recording exposes only the accessors that apply to its streams — dir(rec) and autocomplete list just the relevant ones. info() is always available.

Method	Present when	Returns
`info()`	always	summary dict: uuid, twin, env, types, available accessors
`read_robot()`	recording has a robot stream	actuation table (`pyarrow.Table`)
`read_depth()`	recording has a depth stream	list of `{timestamp_us, frame}` (uint16 `H×W`)
`read_pointcloud()`	recording has a colored/lidar stream	list of `{timestamp_us, frame}` (float32 `N×cols`)
`show_video()`	recording has video	plays the video in a `cv2` window

rec = twin.recordings.get(items[0])

rec.info()
if hasattr(rec, "read_robot"):
    table = rec.read_robot()           # pyarrow.Table
if hasattr(rec, "show_video"):
    rec.show_video()
if hasattr(rec, "read_depth"):
    frames = rec.read_depth()          # [{"timestamp_us": ..., "frame": np.ndarray}, ...]
if hasattr(rec, "read_pointcloud"):
    points = rec.read_pointcloud()

Point-cloud frames come from the on-demand Parquet (see below); if it is still being prepared, read_* raises with a “retry in a few minutes” hint.

Point clouds as Parquet

When you get() a recording, point-cloud data is downloaded as a single Parquet file (one row per frame: timestamp_us, rows, cols, dtype, and the raw frame data). read_depth() / read_pointcloud() reconstruct the frames; to read the file directly with pyarrow:

import numpy as np
import pyarrow.parquet as pq

table = pq.read_table("<downloaded>.parquet")
row = table.slice(0, 1).to_pylist()[0]
frame = np.frombuffer(row["data"], dtype=row["dtype"]).reshape(row["rows"], row["cols"])

The Parquet is materialized on demand: the first time a recording is opened the server may still be preparing it. If so, get() logs a notice (“being generated / updated, retry in a few minutes”) — call get() again shortly to receive the complete file.

Getting started

Connecting to hardware

Tutorials · Code (SDK)

Tutorials · No-code (Workflows)

SDKs and Tools

Core Features

Built by the Community

Help & Support

Defaults at a glance

Twin-scoped

Environment-scoped

Date filtering

Paging

Types & viewers

Contextual accessors

Point clouds as Parquet

​Defaults at a glance

​Twin-scoped

​Environment-scoped

​Date filtering

​Paging

​Types & viewers

​Contextual accessors

​Point clouds as Parquet

Defaults at a glance

Twin-scoped

Environment-scoped

Date filtering

Paging

Types & viewers

Contextual accessors

Point clouds as Parquet