Release v1.16

Release v1.16

Oct 2, 2019

Oct 2, 2019

We are pleased to announce the release of Pupil v1.16!

Download the latest bundle and let us know what you think via the #pupil channel on Discord 😄


Pupil Invisible Support - #1596, #1623

Preparing for the upcoming public release of Pupil Invisible (PI), we are adding support for recordings made with PI in Pupil Player.

You will be able to download the raw recording from Pupil Cloud or copy them directly from the Companion device. Drag and drop the recordings onto Pupil Player as usual.

Most features of Player will support recordings made with PI. Currently not supported are: The iMotions exporter and blink detector.

Surface Tracker

Removed Robust Detection from SurfaceTracker - #1600

The robust detection mode was a remnant of the legacy surface marker system. The new Apriltags markers are by default more robust than even the old robust detection mode. This option did not have an effect anymore, so it was removed.


Disabled Hardware Timestamps on Windows Operating System - #1621

In the past we have received multiple reports of timestamps being out of sync on Windows. After some testing we discovered that the timestamps from the hardware were not always reliable on Windows. The exact cause of this is still unknown but we have disabled the use of hardware timestamps on Windows for now. We are now using software timestamps with an appropriate offset-mapping.

Improved Eye Overlay Visualizations - #1609

Previously, the Eye Overlay plugin would always display the closest eye frame to the current playback position. Therefore, in cases where the eye camera disconnected during a recording, the eye video was visualized incorrectly. Instead, now, we show a gray frame to indicate missing data.

Smaller Fixes

  • Fixed minor performance issues in Apriltag surface marker detector

  • Fixed broken SurfaceTracker heatmap rendering when no gaze data is available - #1584

  • Fixed SurfaceTracker timeline drawing performance issues - #1595

  • Fixed issues with EyeMovementDetector when using inconsistent 3D gaze data - #1587

  • Fixed UI/UX issues when editing surfaces in SurfaceTracker - #1591

  • Fixed flickering surface markers - #1600

  • Updated the app icons for the Windows bundles to the latest design

  • Fixed incorrect handling of missing projection matrices for HMD - #1603

  • Fixed performance-related crashes of the SurfaceTracker on Windows - #1605, #1606

  • Improved user feedback when opening invalid recordings - #1585

  • Fixed crashing offline detection in recordings with timing irregularities - #1615

  • Improved user feedback when trying to load an unknown plugin - #1613

  • Fixed a crash when trying to use Pupil Invisible with Capture - #1620

  • Fixed a crash when setting color values for CircleViz to 1.0 - #1624

  • Improved user feedback when recording from Pupil Mobile without TimeSync - #1629

Deprecated Recordings

Previously released versions of Pupil Player v1.16 do not support recordings created with

  • Pupil Capture v1.2 or earlier, and

  • Pupil Mobile r0.22.x or earlier.

This was due to the fact that these recordings are missing meta information that is required for the upgrade to our new Pupil Player Recording Format 2.0. For details see "Missing Meta Information" below.

With this PR, instead of aborting with a "Recording too old" warning, Pupil Player will attempt to infer the missing values from other data in the recording. This inference is not perfect and results in imprecise values and might cause issues when converting recorded Pupil time to wall clock time. For details see "Missing Meta Information" below.

Upgrading will only work in Player v1.16

Since this inference is limited, we will remove the upgrade functionality for deprecated recordings in v1.17. This means, that if you want to open a deprecated recording in v1.17 or later, you will have to convert them to the new format using v1.16 first.

Missing Meta Information

Specifically the following keys in the info.csv file are missing:

  • Start Time (System): Recording start time in Unix epoch

  • Start Time (Synced): Recording start time in Pupil time

Pupil Player assumes that these timestamps were measured at the same time. This allows for the after-the-effect synchronization of Pupil data with externally recorded data that uses the Unix epoch.

Their value can be inferred from the existing recording, given a roughly known imprecision:

  • Start Time (System): The system start time can be inferred using the existing Start Date and Start Time fields (precision: one second). Unfortunately, the Start Time is subject to the system's timezone while Start Time (System) is not. Therefore, its inference is off by the recording's amount of timezone offset.

  • Start Time (Synced): This timestamp can be replaced by the earliest known recorded video timestamp in the given recording. In this case, the inference error depends on the startup delay of the cameras. This delay is typically less than a second for Pupil Capture recordings, and 2-5 seconds for Pupil Mobile recordings.

Incorrect Playback

In some cases, deprecated recordings might not be played back correctly in Pupil Player. If this is the case for you, please contact for support.

Developers Notes

Changed Requirements

  • Updated pyndsi dependency to v1.0

pip install git+ -U
  • Added packaging dependency

pip install packaging

Pupil Player Recording Format 2.0

Variable Framerate Videos

Instead of writing videos with equally distant presentation timestamps, Capture now saves videos with their original timing. This means, that newly recorded videos can be played back correctly in VLC without having to export them first with Pupil Player.

Recording Info Files

Due to slight differences in how Capture, Mobile and Invisible store recording meta info, we introduced a unified recording meta info file for Pupil Player: info.player.json. When opening a recording made with Pupil Mobile, Pupil Invisible, or older versions of Pupil Capture, we are transforming the recording into the new format (as we did before already) and aggregate all necessary meta infos in info.player.json without changing the original meta info file. The original meta info files will be renamed in order to uniquely identify the origin of this meta info:

  • Older versions of Pupil Capture*: info.csv -> info.old_style.csv

  • Pupil Mobile: info.csv ->

  • Pupil Invisible: info.json -> info.invisible.json

*Note that e.g. when a Pupil Mobile recording has been opened in an older version of Pupil Player before, we also rename to info.old_style.csv as the original info.csv will have been adjusted by Player before.

You can read about the exact specification of the new info.player.json format here.

Pretty Plugin Class Names - #1597

Custom plugin classes don't have to rely on underscores in their names anymore for displaying them nicely in the UI. You can now name your plugin classes in accordance with PEP 8 - Class Names:

class MyAwesomePlugin(Analysis_Plugin_Base):
    def parse_pretty_class_name(cls) -> str:
        return "Awesome Plugin"

Note that currently all existing pupil classes (e.g. Analysis_Plugin_Base) keep their names with underscores for backward compatibility.

We Are Hiring Python Developers!

Hey - you're reading the developer notes, so this is for you! We're looking to hire developers to contribute to Pupil source code. If you love Python and enjoy writing code that is a joy to read, get in touch. Experience with the scientific Python stack is a plus, but not required. We have a lot of exciting projects in the pipeline.

We are also looking for Dev Ops engineers that have experience with kubernetes, docker, and server-side Python.

Send an email to with a CV to start a discussion. We look forward to hearing from you.

Release Note Updates

17.09.2019 22:40: Missing Microsoft Visual C++ Redistributable

We have received reports from two users that Pupil Capture failed to start on Windows with the following error message:

ImportError: DLL load failed: The specified module could not be found.

In both cases the "Microsoft Visual C++ Redistributable for Visual Studio" was missing on their system. If you should encounter the same error message, please download and run the vc_redist.x64.exe file from the official Microsoft support page. Afterwards, Pupil should start up as expected.

23.09.2019 17:22: Additional Bug Fixes

The following issues have been fixed in Pupil v1.16-43:

  • Remove remaining dependencies on the info.csv file - #1652

  • Fix frameless/worldless recordings in Pupil Capture - #1653

30.09.2019 15:30: Offline Calibration Bug Fix

The v1.16-71 release fixes #1656 Player will not create/ allow edits on new calibrations.

02.10.2019 15:35: Deprecated Recordings and Offline Calibration Bug Fix

The following issues have been addressed in Pupil v1.16-80:

  • Deprecated Recordings - #1668: Recordings made with earlier versions than Capture v1.3 or Pupil Mobile r0.21.0 have been deprecated. Please see the dedicated section above for more information.

  • Fixed issue with creating offline calibrations - #1667