VRrec

A zero-coding, open-source VR body-motion capture tool for behavioral research.

VRrec is a lightweight MS Windows application that records VR motion data, including positional and rotational data, from VR tracking devices exposed to VRrec through SteamVR — headset, controllers, and auxiliary trackers — directly to a tab-separated plain-text file (TSV), while running unobtrusively in the background alongside third-party PC VR applications running through SteamVR. It is aimed at researchers who want to add body-motion recording to existing VR study designs without writing code or building, rebuilding, or extending the target VR application.

Associated paper: Kobylinski P., Muczynski B., Cnotkowski D., Wierzbowski M., Biele C. VRrec: A zero-coding open-source VR body-motion capture tool for behavioral research. Manuscript submitted to Behavior Research Methods.

• Zero-coding — operates entirely via a graphical interface; no scripting, programming, or extension of the target VR application required
• Non-intrusive — runs in the background alongside third-party PC VR applications running through SteamVR
• Up to 16 simultaneously tracked devices — HMD, controllers, and auxiliary trackers (e.g., Vive Trackers)
• Configurable nominal sampling rate — 30, 60, 90, 125, 250, or 500 Hz
• Continuous data writing — samples are streamed directly to disk in real time, reducing the risk of losing already acquired data if a session is interrupted
• Event markers — keyboard-triggered markers (gated by Caps Lock) are embedded inline in the data stream
• Plain-text TSV output — tab-separated values importable into R, Python, MATLAB, or any spreadsheet application
• Persistent device aliases — assign human-readable labels (e.g., LeftLeg) to tracker serial numbers; stored as JSON across sessions

Users should pilot-test their own VR setup before research use to confirm that the intended devices are exposed correctly through SteamVR.

Download the latest installer or portable .zip from the Releases page and run the executable. SteamVR must be running before VRrec is started.

VRrec presents a single main window with seven numbered steps:

1. Specify location for the data file — select the folder where recordings will be saved. Available disk space is shown immediately. The default path is Documents\VRrec.
2. Specify name for the data file — enter a custom filename, or leave the field empty to use an auto-generated timestamp (yyyy-MM-dd--HH-mm-ss).
3. Select and name tracked devices — click Tracked device configuration to open the device management window. All devices currently exposed to VRrec through SteamVR are listed by serial number. Assign a human-readable alias (e.g., RightLeg) to each device you intend to record; aliases are saved across sessions.
4. Register keystrokes as markers — select the checkbox to enable keyboard-triggered event markers. Markers are recorded only when Caps Lock is ON, which prevents accidental key logging during a session. The current marker state (ON / OFF) is shown in the main window.
5. Data sampling frequency — select the nominal sampling rate: 30, 60, 90, 125, 250, or 500 Hz. Higher rates increase file size proportionally (approximately 200 kB per Hz per minute at full device configuration).
6. START — begins data recording. The main window turns red to indicate an active session.
7. STOP — finalizes and flushes the data file. Device configuration and aliases are preserved for the next session.

If the application is closed during recording, VRrec finalizes the data-output file before exiting, preserving the acquired data as if the STOP button had been pressed first.

VRrec writes a tab-separated values (TSV) text file. The first row contains column headers; each subsequent row represents one recorded sample with its own timestamp.

Per-device column names follow this general pattern:

[DeviceType]_[Alias]_[SerialNumber]_[Parameter]_[DataType]

Examples:

• Controller_LeftHand_LHR-493D7BY62_PosX_Float — X-position of the left-hand controller
• GenericTracker_LHR-75733G128_PoseValid_Bool — pose validity flag for a tracker without an alias

When no alias is assigned to a device, the alias segment is omitted and the serial number follows the device type directly. Avoid underscores in aliases, because underscores are used as separators in column names.

System (present in every row)

Marker (present in every row)

Per-device fields (repeated for each selected device, prefixed with device type, optional alias, and serial number)

Timestamp precision note: Timestamps are derived from a high-resolution Stopwatch anchored to UTC at application startup. The stopwatch is automatically restarted between recording sessions.

An example VRrec data-output file recorded with an example set of connected devices (HMD, controllers, and multiple Vive Trackers) is provided in the examples/ directory. It can be used to inspect the file structure and test analysis pipelines without requiring VR hardware.

An R validation script is provided in the scripts/ directory. It reads a VRrec TSV file and helps inspect parsing problems, timestamp differences, effective sampling frequencies, missing-data patterns, and per-variable descriptive statistics. The script's functionality description and operating instructions are included as comments inside the script.

If you use VRrec in your research, please cite the associated paper:

Kobylinski, P., Muczynski, B., Cnotkowski, D., Wierzbowski, M., & Biele, C. (manuscript submitted).
VRrec: A zero-coding open-source VR body-motion capture tool for behavioral research.
Manuscript submitted to Behavior Research Methods.

Correspondence: pawel.kobylinski@opi.org.pl

VRrec is released under the GNU Affero General Public License v3.0.