Skip to content

Quick Start

WIP

1. Start the server

# Fullscreen (auto-detects DRM or desktop)
cargo run --release

# Windowed, for development
cargo run --release -- --windowed 1280x720

# No display — ZMQ server only (for testing without a monitor)
cargo run --release -- --null

Press D to spawn demo stimuli, F1–F7 to show overlay panels (Stimuli, Log, Virtual Trigger, Animations, System, Config, Benchmarks; Shift+F–key hides), Esc to exit.

2. Send your first stimulus

cd client/python
uv run examples/flash_rects.py

Or from a script:

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

with Connection() as conn:         # default: tcp://localhost:5555
    # Create a red rectangle centred on screen
    h = conn.stimuli.shapes.create_rect(
        pos=Vec2(0, 0), width=300, height=150,
        color=Color(1.0, 0.0, 0.0),
    )
    input("Press Enter to remove...")
    conn.stimuli.delete(h)

The MATLAB client is planned — it does not exist yet.

conn = vstimd.Connection();   % default: tcp://localhost:5555
h = conn.stimuli.create_rect('x', 0, 'y', 0, ...
                             'width', 300, 'height', 150, ...
                             'r', 1.0, 'g', 0.0, 'b', 0.0);
input('Press Enter to remove...');
conn.stimuli.delete(h);
conn.close();

3. Deferred mode

Use deferred mode to make multiple changes visible on the exact same frame:

from vstimd.stimuli import Vec2, Color

with Connection() as conn:
    h1 = conn.stimuli.shapes.create_rect(pos=Vec2(-200, 0), width=100, height=100,
                                         color=Color(1, 0, 0))
    h2 = conn.stimuli.shapes.create_rect(pos=Vec2(200, 0), width=100, height=100,
                                         color=Color(0, 0, 1))

    conn.system.set_deferred_mode(active=True)
    conn.stimuli.set_enabled(h1, True)
    conn.stimuli.set_enabled(h2, True)
    conn.system.set_deferred_mode(active=False)
    # Both stimuli appear on the same frame

4. Query server info

with Connection() as conn:
    info = conn.system.query_server_info()
    print(info.width, info.height, info.frame_rate)

Next steps