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.

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.