Tutorial 3: Jitter monitoring and drift correction

  • NB: Tutorial updated for OpenViBE 2.0.0 (24-Nov-2017)


The OpenViBE framework provides some mechanisms to alter the behaviour of your acquisition drivers. These services are given by the IDriverContext. We present in this tutorial the jitter monitoring and drift correction service.

You can ask the driver to compare in real-time the number of samples sent by the driver to the theorical sample count, based on the sampling frequency. If the difference between these values goes too high, you can ask the driver to correct the drift automatically by removing or adding dummy samples. Note that this equals tampering with the data, and an assumption that the computer clock is more accurate than the acquisition device clock. This may or may not be the case.

In late 2017 and early 2018 we are revisiting the investigations into this issue and consider alternatives, e.g. letting the acquisition device provide the clock.

The automatic drift correction mechanism is optional. It was enabled by default in OpenViBE up to 1.3.0 and disabled in 2.0.0 due to largely relying on TCP Tagging to align stimulation markers to the EEG. If you need the drift correction in 2.0, you can always manually enable it in the Acquisition Server. Note that the drift correction can introduce artifacts to the signal and it can mask a potential bug in the driver. If you are 100% sure that your driver is fully functionnal, and nothing in the code could possibly cause that kind of problem, and you are still experiencing intolerable drifting then you can try to use the automatic corrector.

Shifting latency and jitter

It is relatively common that the internal clock of the acquisition device does not match precisely the acquisition computer clock frequency. Most of the time, a latency appears with a jitter, but stays in a reasonnable range. For example, 10 samples missing in 1 minute of acquisition, for a 512Hz theorical sampling frequency represents roughly 20 ms shift. However it is critical to control this latency and minimize it, otherwise it can drift to an intelorable value (e.g. 1sec) resulting in misprocessing in OpenViBE, especially if TCP Tagging is not used. OpenViBE relies on precisely dated data. The drift monitoring service is always enabled, and the acquisition server will print a message in the console when you stop the acquisition if it detects that the jitter went beyond a defined threshold. This threshold is given in the GUI and the openvibe configuration file, in ms:

  • AcquisitionServer_DriftToleranceDuration = 2

It means that the acquisition server will raise a warning if the drift rises above 2 ms, when the user stopped the acquisition. Of course, you can redefine this value to suit your needs better.

A warning message should look like this:

[WARNING] After 124.385 seconds, theorical samples per second
          does not match real samples per second
[WARNING]   Received : 64320 samples.
[WARNING]   Should have received : 63684 samples.
[WARNING]   Difference was : 636 samples.
[WARNING]   The driver did not try to correct this difference.
[WARNING]   Please submit a bug report (including the
            acquisition server log file or at least
            this complete message) for the driver you are using.

In this example, the driver sent 636 excedent samples in a 124 seconds window. The sampling fequency is 512Hz, so we reached a drift of 1.24 seconds.


If the monitoring suggests that the driver is drifting, we can try to use correction mechanism. To do so, you can rely on the given functions in the driver context :

 virtual OpenViBE::int64    getDriftSampleCount (void)
   Gets jitter sample count.
 virtual OpenViBE::int64    getDriftToleranceSampleCount (void)
   Gets the jitter sample count tolerance.
 virtual OpenViBE::int64    getSuggestedDriftCorrectionSampleCount (void)
   Gets the suggested jitter correction sample count.
 virtual OpenViBE::boolean  correctDriftSampleCount (OpenViBE::int64 i64SampleCount)
   Corrects a drifting device.

Please read the full documentation on the IDriverContext page. You can try to correct the drift by the suggested value, as shown in this loop function in the driver:

boolean CDriverFooBarDevice::loop(void)
    return false;

    //... read data from device and fill the buffer


    //... and finally, correct drift according to what the
    // acquisition server suggests !

  return true;

Please note that the jitter drift has to be implemented after call to setSamples(m_pSample), as the correction is performed on the buffer to be sent. If the correction functions did not detect any intolerable drift, nothing will be done on the buffer.

This entry was posted in Acquisition drivers and tagged , , . Bookmark the permalink.