Skip to content

Installation

How to install Secure LSL on your system.

Requirements

  • Operating System: macOS, Linux, or Windows
  • CMake: 3.16 or later
  • C++ Compiler: C++17 support (GCC 7+, Clang 5+, MSVC 2019+)
  • libsodium: 1.0.18 or later

Install Dependencies

# Using Homebrew
brew install cmake libsodium

sudo apt update
sudo apt install cmake libsodium-dev build-essential

sudo dnf install cmake libsodium-devel gcc-c++

# Using vcpkg
vcpkg install libsodium:x64-windows

# Or download CMake from cmake.org

Build from Source

Clone the Repository

git clone https://github.com/sccn/secureLSL.git
cd secureLSL/liblsl

Build liblsl

mkdir -p build && cd build
cmake -DLSL_SECURITY=ON ..
make -j$(nproc)

Build options:

Option Default Description
LSL_SECURITY ON Enable security features
LSL_BUILD_TOOLS ON Build lsl-keygen and lsl-config
CMAKE_BUILD_TYPE Release Build type (Release/Debug)

Windows Build

# Using vcpkg for dependencies
git clone https://github.com/sccn/secureLSL.git
cd secureLSL\liblsl
mkdir build && cd build

# Configure with vcpkg toolchain
cmake -DLSL_SECURITY=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ..

# Build
cmake --build . --config Release

Verify Build

# Check library was built (note: secure build produces liblsl-secure)
ls -la liblsl-secure.dylib  # macOS
ls -la liblsl-secure.so     # Linux
dir lsl-secure.dll          # Windows

# Check tools were built
./lsl-keygen --help
./lsl-config --help

# Verify it's a secure build
./lslver  # Should show "security:1.1.0-alpha" in output

Install the Library

System-wide Installation

sudo make install

This installs:

  • liblsl-secure.so / liblsl-secure.dylib / lsl-secure.dll to system library path
  • Header files to system include path
  • lsl-keygen and lsl-config to system bin path

Local Installation

For development or testing without system installation:

# Set library path (add to your shell profile)
export LD_LIBRARY_PATH=/path/to/secureLSL/liblsl/build:$LD_LIBRARY_PATH  # Linux
export DYLD_LIBRARY_PATH=/path/to/secureLSL/liblsl/build:$DYLD_LIBRARY_PATH  # macOS

Python (pylsl)

pylsl automatically finds liblsl. To use the secure version:

Option 1: Environment Variable

export PYLSL_LIB=/path/to/secureLSL/liblsl/build/liblsl-secure.dylib  # macOS
export PYLSL_LIB=/path/to/secureLSL/liblsl/build/liblsl-secure.so     # Linux
python your_script.py

Option 2: System Installation

If you installed liblsl system-wide, pylsl will find it automatically.

Verify Python Setup

import pylsl
print(f"Library: {pylsl.library_path()}")

# Test security API
info = pylsl.StreamInfo('Test', 'Test', 1, 100, 'float32', 'test123')
print(f"Security available: {hasattr(info, 'security_enabled')}")

MATLAB

MATLAB uses liblsl via its LSL library loader.

Setup

  1. Build secure liblsl as shown above
  2. Point MATLAB to the library:
% Add to your startup.m or script
addpath('/path/to/secureLSL/liblsl/build');

% Load the secure library
lib = lsl_loadlib('/path/to/secureLSL/liblsl/build/liblsl-secure.dylib');  % macOS
% lib = lsl_loadlib('/path/to/secureLSL/liblsl/build/liblsl-secure.so');   % Linux

Verify MATLAB Setup

lib = lsl_loadlib('/path/to/liblsl-secure.dylib');
info = lsl_streaminfo(lib, 'Test', 'Test', 1, 100, 'cf_float32', 'test123');
% Security is automatically enabled if configured

Pre-built Binaries

Pre-built binaries for common platforms are available on the releases page.

Platform File
macOS (Apple Silicon) liblsl-secure-macos-arm64.zip
macOS (Intel) liblsl-secure-macos-x64.zip
Linux (x64) liblsl-secure-linux-x64.tar.gz
Windows (x64) liblsl-secure-windows-x64.zip

Extract and use as described above.

Verify Installation

After installation, verify everything works:

# Generate keys
./lsl-keygen

# Check configuration
./lsl-config --check

# Expected output:
# Security configuration status:
#   Config file: /Users/you/.lsl_api/lsl_api.cfg
#   Security enabled: true
#   Key created: 2025-12-05T19:00:00Z
#   Key fingerprint: SHA256:70:14:e1:b5:...
#
# [OK] Configuration valid

Next Steps