viser4d
viser4d is a small extension of viser
for recorded 3D scenes with a time dimension.
Features include:
- Record scene updates across discrete timesteps with
with server.at(t):. - Play, pause, scrub, and step through the timeline directly in the browser.
- Stream long recordings in chunks and preload nearby timeline blocks for responsive scrubbing.
- Keep playback client-local so different browser tabs can explore the same recording independently.
- Attach timeline-synced audio tracks.
- Export recordings as
.viserfiles or standalone HTML.
The goal is to keep viser's live scene API while adding a separate recorded timeline API for playback and export.
Chunking is controlled by viser4d.StreamingConfig. By default,
Viser4dServer populates it from two environment variables, both plain
integers: VISER4D_BLOCK_SIZE (steps per block, default 32) and
VISER4D_CLIENT_CHUNK_CACHE_SIZE (per-client preload budget in bytes, default
1000000000). You can also pass streaming=viser4d.StreamingConfig(...) for
one server instance.
Playback controls are drawn by the viser4d runtime as an overlay bar at the bottom of the viewer (play/pause, scrubbing, stepping, speed, loop); playback state is client-local, so each browser tab explores the recording independently.
Installation
You can install viser4d with pip:
pip install viser4d
Quickstart
import numpy as np
import viser4d
server = viser4d.Viser4dServer(num_steps=10, fps=10)
server.scene.add_frame("/origin", axes_length=0.25)
server.scene.add_grid("/ground", width=10.0, height=10.0)
point_cloud = None
for t in range(10):
with server.at(t) as timeline:
points = np.random.uniform(-1.0, 1.0, size=(200, 3))
if point_cloud is None:
point_cloud = timeline.scene.add_point_cloud(
"/points",
points=points,
colors=(255, 200, 0),
)
else:
point_cloud.points = points
server.sleep_forever()
Open the viewer in your browser and use the built-in Playback controls to play, pause, scrub, and step through the recorded timeline.
Outside server.at(t), server.scene behaves like normal viser. Inside
server.at(t), writes to timeline.scene and timeline.audio are recorded
into the timeline.
More Examples
Export
blob = server.serialize()
html = server.as_html()
Use server.serialize() to export a .viser recording and server.as_html()
to export a self-contained HTML viewer.
Design
Every scene-mutating viser message reduces to a keyed put or a node delete,
so the scene at any timestep is a map key -> entry and each entry carries a
monotonic rev. Two entries are identical iff their revs match, so nothing ever
deep-compares payloads.
Each recorded timestep stores only its delta. Deltas are grouped into blocks of
block_size steps, spilled to disk as zstd+msgpack, and served to the browser
with a checkpoint: the folded state just before the block's first delta. The
browser folds checkpoint + deltas[0..offset], diffs by rev against what it has
already pushed into viser, and drives playback from its own clock — the server
sends data, not frames.
Writes made outside server.at(t) become overrides: a keyed overlay applied
on top of every step, where the node exists. Audio is a per-step event stream
folded into per-track waveform snapshots and scheduled against the same
transport clock, in live playback and in exported HTML alike.
Each module's docstring documents its own part in detail; _state.py holds the
key derivation table and the fold rules.
Development
uv sync --group dev
# Build the browser runtime (only needed for a non-editable checkout).
npm --prefix src/viser4d/client ci
npm --prefix src/viser4d/client run build
uv run --group dev ruff check . && uv run --group dev ruff format --check .
uv run --group dev ty check
uv run --group dev pytest -q
npm --prefix src/viser4d/client run typecheck
An editable install rebuilds the runtime automatically when the client sources
or the wire protocol change, using a nodeenv-sandboxed Node. Both
src/viser4d/runtime.js and src/viser4d/client/protocol.gen.ts are generated
and gitignored; protocol.gen.ts comes from src/viser4d/_protocol.py via
uv run python -m viser4d._codegen.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file viser4d-0.19.0.tar.gz.
File metadata
- Download URL: viser4d-0.19.0.tar.gz
- Upload date:
- Size: 69.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
30e84378b06626c5b0aecd33e812008a10dad083462162b8a64eaa76cb997358
|
|
| MD5 |
5e65fd53da1f125fb9813bf0dfdf9f43
|
|
| BLAKE2b-256 |
700504f4c90a35bec9517314f906e31b1c185e6654d8d59e048b20b5d2c59545
|
File details
Details for the file viser4d-0.19.0-py3-none-any.whl.
File metadata
- Download URL: viser4d-0.19.0-py3-none-any.whl
- Upload date:
- Size: 45.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
58b1fb4620fab791f1e7c02f5d462f59134e98e9735fc992d1e2e1b96a77f1f1
|
|
| MD5 |
6bce2aaa085873e45f13f7deb9d88389
|
|
| BLAKE2b-256 |
11323b4d33394675903b48a6a8e36f5db2eb7827b56c9657b61e76c47eafa1bc
|
