LibXDF – a C++ library for loading XDF files

LibXDF is a cross-platform C++ library for loading multimodal signals stored in XDF files. It is used in the biosignal viewing application SigViewer and the LSL application XDFStreamer and can also be integrated into other C++ applications.

Quick start

The source code and prebuilt binaries are available as releases (you may need to expand the list of assets to find the downloads).

If a particular release does not have assets for your platform or they do not work for you for some other reason, then libXDF can be built with CMake using the following two commands:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -DCMAKE_BUILD_TYPE=Release
cmake --build build -j --target install

This builds and installs a static library in ./build/install, but you can build a shared library by adding -DBUILD_SHARED_LIBS=ON to the first CMake command.

Integrating into C++ applications

If you want to use libXDF in C++ applications, follow these steps:

1. Install a prebuilt binary release or build libXDF from source as described above.

2. If you use CMake, add the following lines to your CMakeLists.txt to find and link against libXDF:

   find_package(libxdf REQUIRED
       HINTS ${XDF_INSTALL_ROOT}
       PATH_SUFFIXES share
   )
   target_link_libraries(${PROJECT_NAME}
       PRIVATE
       # ... other dependencies
       XDF::xdf
   )

   If libxdf is not in a standard system library location, pass -DXDF_INSTALL_ROOT=path/to/libxdf to specify its path.

3. In your source code, #include "xdf.h", instantiate an object of the Xdf class, and call the load_xdf method.

   For example:

   #include "xdf.h"
   
   Xdf XDFdata;
   XDFdata.load_xdf("example.xdf");

Functions must be called in a specific order. For example, calling subtractMean before loading data leads to undefined behavior.

The recommended order is shown below:

XDFdata.load_xdf(std::string filepath);
XDFdata.subtractMean();
XDFdata.createLabels();
XDFdata.resample(int sampleRate);
XDFdata.freeUpTimeStamps();

Releasing

Releases are built and published automatically by .github/workflows/cppcmake.yml whenever a tag matching v*.* is pushed to the upstream xdf-modules/libxdf repository: it builds and packages the library on Ubuntu, Windows, and macOS, then attaches the resulting archives to a new GitHub release. To cut a new release:

1. Bump the version in project(... VERSION X.Y.Z ...) in CMakeLists.txt.

2. Add an entry for the new version to CHANGELOG.md.

3. Commit and push these changes to main on xdf-modules/libxdf — this is where CI runs and releases are published, so pushing to a personal fork's main won't trigger anything.

4. Tag the commit following the vX.Y.Z scheme (e.g. v0.99.11) and push the tag to the same upstream repository (adjust the remote name below to whatever points to xdf-modules/libxdf in your local checkout):

   git tag vX.Y.Z
   git push upstream vX.Y.Z

5. CI builds, packages, and publishes the release automatically — check the Actions and Releases tabs to confirm it succeeded. The release step rejects any tag that does not match vX.Y.Z (e.g. v0.99.11), so no release is created if the tag format is wrong.

References

If you use libXDF in your project, please consider citing the following conference paper:

Yida Lin, Clemens Brunner, Paul Sajda and Josef Faller. SigViewer: Visualizing Multimodal Signals Stored in XDF (Extensible Data Format) Files. The 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society.

LibXDF depends on third party libraries pugixml for XML parsing and Smarc for resampling.