Sharing LSL streams over the network: bridge and relay

Lab Streaming Layer finds streams with multicast, so it only works where multicast reaches: usually one local network. A web browser can't use LSL at all, because it has no raw sockets. The LSL bridge in lsl_tools carries streams over a WebSocket instead:

• Across networks: another building, a VPN, a cloud server.
• To browsers: the web version of LSL Viewer can view live streams and publish its own.
• Between browsers: as a relay, what one client publishes the others receive, e.g. an XDF recording replayed in one browser and viewed in another.

You can run it from the LSL Viewer desktop app (no command line needed) or with the lsl command line tool.

Contents

• Which setup do I need?
• Getting the tools
• Quick start: view lab streams in a browser
• Setup 1: streams from one LSL network to another
• Setup 2: a browser publishes into LSL
• Setup 3: a relay between browsers
• Security: tokens, origins and TLS
• Running a relay on a server (wss://)
• Timing: clock offsets, drift and latency
• Command reference
• Limitations
• Troubleshooting

Which setup do I need?

Setup 1   [LSL network A] ──lsl share──▶ ws ──▶ lsl bridge ──▶ [LSL network B]
                                          └───▶ browser (LSL Viewer on the web)

Setup 2   browser ──publish──▶ ws ──▶ lsl share --accept ──▶ [LSL on that computer]
                                                        └──▶ other clients

Setup 3   browser A ──publish──▶ ws ──▶ lsl relay ──▶ ws ──▶ browser B, C, lsl bridge…
          [LSL lab] ──lsl publish──▶ ┘

Streams that clients publish are always shared with every other client. On a share or share + accept server they also become ordinary LSL streams on that computer. A relay only passes them between clients, so it doesn't need LSL.

Getting the tools

• LSL Viewer (desktop): download from the releases page (lsl_viewer <version>). The sharing controls are under LSL > Share or relay streams….
• lsl command line tool: each LSL Viewer release also has lsl-cli-<version>-<os> archives. Unpack one and run bin/lsl (bin\lsl.exe on Windows). Keep the lib/ folder next to bin/, because it holds liblsl. The Linux and Windows viewer archives also include it under cli/.
• From source: in a clone of this repository, run dart run lsl_tools:lsl <command> from packages/lsl_tools. Alternatively, dart build cli builds the same bundle as the releases.

In the examples below, lsl means whichever of these you use.

Quick start: view lab streams in a browser

On a computer on the lab network (where the LSL streams are):

lsl share --token choose-a-secret
# Sharing EEG, Markers on port 8765 (address 0.0.0.0)

Or in LSL Viewer: LSL > Share or relay streams…, choose Share, set a token, then click Share. The panel lists the addresses to connect to.

Then, in a browser, open LSL Viewer:

• The same computer: use the hosted web viewer. Choose Connect to an LSL bridge…, enter ws://localhost:8765 and the token.
• Another computer: the hosted viewer is an https:// page, and browsers only let it reach wss:// addresses (see Running a relay on a server). Use the desktop viewer, or serve the web build over plain http:// on your own network. A plain http:// page can connect to ws://lab-pc:8765.

Click View next to a stream to open it in a tab.

Setup 1: streams from one LSL network to another

On network A (where the streams are):

lsl share -s EEG -s Markers --token s3cret

• -s picks streams by name or type, and * is a wildcard. Without -s every stream is shared.
• --rescan 5 also shares matching streams that appear later.
• In the viewer: tick Share every LSL stream, also new ones.

On network B:

lsl bridge ws://lab-pc.example.org:8765 --token s3cret --suffix " (lab)"

• What bridge does: it publishes each shared stream as an LSL stream on network B, named with the suffix. LabRecorder, your analysis scripts or another viewer can then use it as if it were local.
• It follows the bridge: streams that appear or go away there appear or go away here.
• In the viewer: use Connect to an LSL bridge…, then switch on Publish its streams on LSL here.

Port 8765 (or the one you pick with -p) must be reachable from network B: open it in the firewall, forward it on the router, or use a VPN.

Setup 2: a browser publishes into LSL

On the computer that should receive the streams:

lsl share --accept --token s3cret

In the browser, Connect to an LSL bridge… that computer, then:

• Live device: open it (e.g. a Cyton over WebSerial) and use LSL > Forward this stream…, choosing LSL on <host> (through its bridge).
• XDF recording: open the file, move to where playback should start, then either:
• use LSL > Replay this recording from here for every stream, or
• use Forward… on one stream's tab.

The streams appear as LSL streams on the --accept computer (look for them with lsl list). Other clients of the bridge see them too.

Setup 3: a relay between browsers

lsl relay --token s3cret

Every client connects to the relay:

• One publishes, with Forward… or Replay… as in Setup 2.
• The others see the published stream in Connect to an LSL bridge… and click View.
• lsl bridge ws://relay:8765 on a native computer turns them into LSL streams there.

A relay needs no LSL on its computer, so it can run on a server with no lab network (next sections). In the viewer, use Share or relay streams… and choose Relay only.

Security: tokens, origins and TLS

The bridge is built for a trusted group, such as a lab or a class. It is not meant to be exposed to the open internet unattended.

• Token: with --token, clients must give it to connect. The viewer can generate a random one. Anyone who has it can see every stream and publish new ones.
• The token travels in the URL (?token=). Over plain ws:// anyone on the path can read it. Use wss:// (TLS) outside a network you trust, and keep it out of proxy access logs.
• Origins: --allow-origin https://nexusdynamic.org (repeatable) makes browsers on other websites unable to connect. Native clients such as lsl bridge and the desktop viewer send no origin and are not affected.
• Binding: --host 127.0.0.1 listens only on this computer, which is what you want behind a reverse proxy.

Running a relay on a server (wss://)

Browsers on https:// pages, including the hosted viewer, need wss://. The bridge speaks plain ws://. Put a reverse proxy with a certificate in front of it.

On the server:

lsl relay --host 127.0.0.1 --port 8765 --token "$(openssl rand -hex 16)" \
  --allow-origin https://nexusdynamic.org

Caddy gets and renews the certificate itself. In the Caddyfile:

relay.example.org {
    reverse_proxy 127.0.0.1:8765
}

nginx (with a certificate from e.g. certbot):

server {
    listen 443 ssl;
    server_name relay.example.org;
    # ssl_certificate / ssl_certificate_key ...

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 1h;
        access_log off;   # the token is in the URL
    }
}

Clients then connect to wss://relay.example.org with the token.

To keep the relay running, use a systemd unit such as:

[Service]
ExecStart=/opt/lsl-cli/bin/lsl relay --host 127.0.0.1 --token <token>
Restart=always

To send a lab's LSL streams to the relay, run this on a lab computer. It connects out, so the lab needs no open ports:

lsl publish wss://relay.example.org --token <token> -s EEG -s Markers --rescan 5

Everyone connected to the relay then sees them. lsl bridge wss://relay.example.org elsewhere turns them back into LSL streams.

Timing: clock offsets, drift and latency

A sample keeps the time stamp its origin gave it all the way through a bridge or relay. Nothing on the way rewrites it. Beside the samples, every two seconds, travels the stream's clock chain: one entry per hop, each with

• the offset between that hop's two clocks and its drift, measured the way LSL measures an outlet's clock (bursts of probes, the fastest round trip of each, a line fitted through the last minute);
• the uncertainty: the round trip of the measurement, so the true offset is within ± half of it;
• the latency: how long after its time stamp a sample arrived at that hop (cumulative, so the difference between two hops is what the second one added), and its jitter.

The receiving end adds the hops up and puts time stamps on its own clock, smoothed like an LSL inlet's unless it is told not to. So by default a bridged stream lines up with local ones, and the error bound is the sum of the hops' uncertainties: well under a millisecond per hop on a LAN, a few ms per hop over the internet.

Where to see the chain:

• lsl bridge --stats 5 prints it for each stream every 5 seconds: the totals, then each hop, which shows which hop is slow or noisy.
• The BridgeTiming stream that lsl bridge publishes beside the others (a string stream, one JSON sample per stream every two seconds: stream, offset, uncertainty, drift_ppm, latency, hops). Record it with the data and the figures are in the file. --no-timing-stream turns it off.
• LSL Viewer: the stream's Info shows the bound, the latency and each hop.
• In code: LslInlet.chain() and LslInlet.timeCorrectionEx(). Open a bridge inlet with LslInletOptions(clockSync: false) to get the raw time stamps with the correction beside them, as a recorder wants.

The same chain continues through a peer_coordinator session (WebRTC): LslDataStreamPump sends an inlet's samples through a DataStream and DataStreamInlet receives them as an inlet again, for a BridgeOutlet, an LSL outlet or LslRecorder.fromInlets.

Command reference

lsl share shares LSL streams, and with --accept takes published ones.

lsl relay passes streams between clients only. It takes -p, --host, --token and --allow-origin.

lsl publish <ws://host:port> publishes LSL streams from here on a bridge that accepts them (--accept or a relay). It takes -s (default: all), --token and --rescan (see above). It skips streams that came from a bridge, so they don't go round in circles.

lsl bridge <ws://host:port> publishes a bridge's streams on LSL here, and follows them as they come and go.

--peer <address> goes before any command and looks for LSL streams on a computer multicast doesn't reach, e.g. lsl --peer 10.0.0.5 share.

The library API is LslBridgeServer.start, LslBridgeClient.connect and LslBridgeRepublisher.start in package:lsl_tools/lsl_tools.dart. The protocol (JSON control messages and binary sample frames) is documented in lib/src/bridge/protocol.dart.

Limitations

• Values travel in the stream's own format: double64, the integer formats and every channel of a string stream arrive exactly. The one exception is the browser, whose numbers hold integers exactly only up to 2^53: an int64 stream above that is rounded in or out of the web viewer, which then says so on the stream's tab. Between lsl and desktop viewers it is exact. The format and its codec are in lsl_core.
• Time stamps are as good as the network is symmetric: each hop's offset is off by up to half the difference between its two directions' delays, and the bounds add up over hops. The chain reports the bound (see Timing); it cannot make it smaller. In a browser the clock is also only as fine as the browser allows (5 µs to 1 ms).
• Every program must speak protocol 3. An older lsl or viewer is refused when it connects, rather than given time stamps it would misread.
• No automatic reconnect. If the connection drops, connect again.
• Trusted groups only: see Security.

Troubleshooting

• The browser can't connect and the console mentions "mixed content" or "insecure": the page is https:// and the address is ws://. Use wss:// behind a proxy, or ws://localhost on the same computer.
• Connection refused or timed out: the port is blocked. Check the firewall on the sharing computer, and whether it listens on 127.0.0.1 only (--host).
• 403 Forbidden: the token is wrong, or the page's origin isn't in --allow-origin.
• lsl share says No streams to share.: no LSL streams were found in 2 s. Check with lsl list, use --peer where multicast doesn't reach, or use --accept/relay to start without any.
• Chrome asks to allow access to devices on the local network: this is Chrome's Local Network Access check for public pages reaching private addresses. Allow it, or use the desktop viewer.