Visual Stimulation Daemon - vstimd

Status: Pre-alpha — under active development, not yet suitable for production use.

vstimd is a visual stimulus server with strong guarantees for accurate and precise frame timing as well as low-latency with broad compatibility with clients (Python/PsychoPy, MATLAB, Bonsai). This is achieved by handling rendering on a dedicated device and controlling it through cross-platform, cross-language user-friendly clients.

The primary deployment platform is the Direct Rendering Manager (DRM) on NVIDIA Jetson Orin Nano, Raspberry Pi 5, and other Linux-based systems. Using DRM and bypassing any windowing system enables stable and low-latency rendering with few skipped frames.

vstimd combines ideas and concepts from Michael Stephan's StimServer C++ visual stimulus server and Andreas Kreiter's VStim project.

This project is licensed under the GNU AGPLv3. Copyright (c) 2026 Joscha Schmiedt, University of Bremen.

Goals

• stable and low-latency rendering of visual stimuli for psychophysics experiments
• cross-platform client support (Linux, Windows, macOS) with different API flavours (PsychoPy, Bonsai, StimServer)
• Deterministic event logging for experiment replay and analysis latency

Quick Start

# Terminal 1 — start the server
cargo run --release
# Press D to spawn demo stimuli (cyan circle + magenta rect)
# Press F1 to toggle the debug overlay (frame timing, stimulus list, command log)

# Terminal 2 — run the flash example
cd client/python
uv run examples/flash_rects.py              # 4 flashes at 2 Hz
uv run examples/flash_rects.py --flashes 8 --hz 4

Or drive the server directly from Python:

from vstimd import Connection
from vstimd.stimuli import Vec2, Color

with Connection() as conn:
    h = conn.stimuli.shapes.create_rect(pos=Vec2(0, -200), width=300, height=200,
                                        color=Color(1.0, 0.0, 0.0))
    conn.stimuli.set_enabled(h, False)
    conn.stimuli.delete(h)
    info = conn.system.query_server_info()
    print(info.version)

Building

# Rust server
cargo build
cargo build --release
cargo test
cargo clippy

# Run options
cargo run --release                   # fullscreen (auto-detects DRM or desktop)
cargo run --release -- --windowed 1280x720
cargo run --release -- --null         # ZMQ only, no display (also: VSTIMD_NULL=1)

# Python client (requires uv)
cd client/python
uv sync
uv run examples/flash_rects.py

Documentation

• dev/PLAN.md — full design and roadmap
• docs/concepts/architecture.md — module structure, wire protocol, threading model, stack
• docs/getting-started/bare-metal.md — DRM/console rendering on Linux (Jetson, Pi)
• docs/api/python/index.md — Python client API and PsychoPy compatibility
• dev/INPUT_LATENCY.md — latency analysis for position input
• dev/3D_ROADMAP.md — 3-D stimulus roadmap