Pupil Labs pl-realtime-tui

A TUI to monitor, control and send synchronized events to multiple eye-trackers.

pl-realtime-tui is a Python-based Text User Interface (TUI) application designed to monitor, control, and send synchronized events to multiple Pupil Labs eye-trackers (Neon/Pupil Invisible). It leverages the pupil-labs-realtime-api for low-latency communication with devices and textual for a responsive terminal-based dashboard.

See the accompanying Alpha Lab article for more details and example use cases.

Installation

pip install pupil-labs-realtime-tui # or pip install git+https://github.com/pupil-labs/pl-realtime-tui.git

If you have UV installed. You can also run it as a one time:

uvx --from pupil-labs-realtime-tui pl-realtime-tui

or, if you want to run more than one time, you can install it as a tool.

uv tool install pupil-labs-realtime-tui

Run It

From there, you would be able to invoke it with just pl-realtime-tui from anywhere in the terminal, check out the -h help flag for other parameters.

[!IMPORTANT] Old terminals (e.g. macOS Terminal.app) do not support key-hold events, which can lead to performance issues when holding down event trigger keys. We attempt to bypass it by blocking new triggers during 0.3s, but key releases may not be detected. We recommend using modern terminals like WezTerm, Ghostty, Kitty, or Alacritty for the best experience. On those terminals, we will use Kitty protocol to detect key releases and support true key-hold events.

Related Work

We would like to also acknowledge the following published work using terminal-based interfaces for eye-tracking device management, concretely with our own devices:

• Neurolive
• SocialEyes

Key Features

• Discovery: Implements both standard mDNS discovery and a "Deep Scan" (ARP-based or brute-force subnet scan).
• Device Dashboard: Displays connected devices in a DataTable with real-time status, battery, storage, and last event info.
• Recording Control: Start/stop recordings on selected devices or all devices simultaneously.
• Event Triggers: Keyboard keys 0-9 trigger events sent to either the selected device or all connected devices if none is selected.
• Selection Logic: Clicking a device in the DataTable selects it, allowing targeted start/stop/event commands.
• Time Sync: Automatically estimates clock offsets periodically to maintain synchronization.

Tech Stack

• Language: Python (>=3.10, <4.0)
• TUI Framework: Textual
• CLI Framework: Typer
• API: pupil-labs-realtime-api
• Networking: aiohttp for HTTP API calls, scapy for deep network scans (ARP).

Development Conventions

• Code Quality: Strictly follows PEP 8 via ruff. Ensure all changes pass make check before committing.
• Typing: Uses static type hints throughout. mypy is used for verification.
• Asynchronous Code: Heavily relies on asyncio for non-blocking I/O with multiple devices. Textual workers (@work) are used for long-running tasks like network discovery.
• Time Synchronization: Uses TimeOffsetEstimator from the realtime API to calculate clock offsets between the host and eye-trackers, ensuring events are accurately timestamped in the device's clock domain.
• UI Styling: Uses Textual CSS (.tcss). Modifications to the UI look should be done in src/pupil_labs/realtime_tui/css/main.tcss.
• Pre-commit: Pre-commit hooks are configured to run linting and formatting on every commit.