Skip to content

Docs: link liblsl-specific content instead of repeating it #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cboulay merged 1 commit into from
Oct 14, 2026
Merged

Docs: link liblsl-specific content instead of repeating it #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions docs/dev/doc_syntax.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
====================
Documentation Syntax
====================
=================================
Contributing to the documentation
=================================

LSL's documentation lives in two places:

* **This site** (``docs/`` in the `labstreaminglayer repository <https://github.com/sccn/labstreaminglayer>`__):
what LSL is, getting started, devices, tools, language bindings, troubleshooting. Written in
reStructuredText, described below.
* **The liblsl documentation** (``docs/`` in the `liblsl repository <https://github.com/sccn/liblsl>`__):
getting, building and linking liblsl, its configuration, how it works on the network, and the
C/C++ API reference. Written in Markdown (MyST) with Mermaid diagrams; build it with
``pip install -r docs/requirements.txt`` and ``sphinx-build docs docs/_build/html`` (Doxygen
must be installed for the API reference).

Both are published on Read the Docs and rebuilt on every push.

Restructured Text (RST)
=======================
Expand All @@ -9,10 +22,7 @@ Restructured Text
(`Quickstart <https://docutils.sourceforge.io/docs/user/rst/quickstart.html>`_,
`another Quickstart <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_)
is a text based markup language like markdown.
In combination with `Sphinx <https://www.sphinx-doc.org/>`_) it is used to build this documentation,
most notable for the
`official Labstreaminglayer documentation <https://labstreaminglayer.readthedocs.io/>`_
hosted on ReadTheDocs and (some time in the future) a standalone PDF doc.
In combination with `Sphinx <https://www.sphinx-doc.org/>`_ it is used to build this documentation.

You can view the source code for
`this page <https://github.com/sccn/labstreaminglayer/blob/master/docs/dev/doc_syntax.rst>`_
Expand All @@ -26,10 +36,10 @@ The
is built on every commit to the
:repo:`Labstreaminglayer repository <sccn/labstreaminglayer>`.
In order to avoid several commits until you get the formatting right, install
the Python ``sphinx`` package (either with pip or conda) and build the
documentation with
the requirements (``pip install -r docs/requirements.txt``) and build the
documentation in the ``docs`` folder with
:samp:`make html`, or (if you don't have :command:`make` installed)
:samp:`sphinx-build . _build`.
:samp:`sphinx-build . _build/html`.



Expand Down Expand Up @@ -81,6 +91,10 @@ Some pages are linked to quite often, so there are some shortcuts configured in
:samp:`:lslrelease:`{LabRecorder}`` to an App's release page, i.e.
:samp:`https://github.com/labstreaminglayer/App-{LabRecorder}/releases`.

:samp:`:liblsl:`{link text} <{guide/linking.html}>`` links to a page of the liblsl
documentation, e.g. :liblsl:`Using liblsl in your project <guide/linking.html>`. Prefer this
for liblsl's guide pages (written in Markdown); for the API reference use the intersphinx links below.

`Intersphinx`_
~~~~~~~~~~~~~~

Expand Down
61 changes: 11 additions & 50 deletions docs/dev/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ API Documentation
*****************

It is recommended that you clone the repository to get the respective code. The documentation is at the following locations:
* C: `C header file <https://github.com/sccn/liblsl/blob/main/include/lsl_c.h>`__
* C++: `C++ header file <https://github.com/sccn/liblsl/blob/main/include/lsl_cpp.h>`__,
:doc:`in progress API documentation <liblsl:index>`
* C and C++: the :doc:`liblsl API reference <liblsl:index>` (from the
`C <https://github.com/sccn/liblsl/blob/main/include/lsl_c.h>`__ and
`C++ <https://github.com/sccn/liblsl/blob/main/include/lsl_cpp.h>`__ headers)
* Python: `pylsl module <https://github.com/labstreaminglayer/pylsl>`__
* Java: `JavaDocs <https://github.com/labstreaminglayer/liblsl-Java/blob/master/javadoc/index.html>`__
* C#: `LSL module <https://github.com/labstreaminglayer/liblsl-Csharp/blob/master/LSL.cs>`__
Expand All @@ -31,54 +31,15 @@ hopefully leave no questions unanswered.
Note that a typical application will only need a small subset of the API
(as used in the example programs).

C Example Programs: Basic to Advanced
*************************************
C and C++ Example Programs
**************************

These two example programs illustrate the bread-and-butter use of LSL as it is executing in almost any device module that comes with the distribution:
* `Sending a multi-channel time series into LSL. <https://github.com/sccn/liblsl/blob/main/examples/SendDataC.c>`__
* `Receiving a multi-channel time series from LSL. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveDataC.c>`__

These two example programs illustrate a more special-purpose use case, namely sending arbitrary string-formatted data at irregular sampling rate. Such streams are used by programs that produce event markers, for example:
* `Sending a stream of strings with irregular timing. <https://github.com/sccn/liblsl/blob/main/examples/SendStringMarkersC.c>`__
* `Receiving a stream of strings with irregular timing. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveStringMarkersC.c>`__

The last example shows how to attach properly formatted meta-data to a stream, and how to read it out again at the receiving end. While meta-data is strictly optional, it is very useful to make streams self-describing. LSL has adopted the convention to name meta-data fields according to the XDF file format specification whenever the content type matches (for example EEG, Gaze, MoCap, VideoRaw, etc); the spec is `here <https://github.com/sccn/xdf/wiki/Meta-Data>`__. Note that some older example programs (SendData/ReceiveData) predate this convention and name the channels inconsistently.
* `Handling stream meta-data. <https://github.com/sccn/liblsl/blob/main/examples/HandleMetaDataC.c>`__

C++ Example Programs: Basic to Advanced
***************************************

These two example programs illustrate the shortest amount of code that is necessary to get a C++ program linked to LSL:
* `Minimal data sending example. <https://github.com/sccn/liblsl/blob/main/examples/SendDataSimple.cpp>`__
* `Minimal data receiving example. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveDataSimple.cpp>`__

These two example programs demonstrate how to write more complete LSL clients in C++ (they are 1:1 equivalents of the corresponding C programs):
* `Sending a multi-channel time series into LSL. <https://github.com/sccn/liblsl/blob/main/examples/SendData.cpp>`__
* `Receiving a multi-channel time series from LSL. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveData.cpp>`__

These two programs transmit their data at the granularity of chunks instead of samples. This is mostly a convenience matter, since inlets and outlets can be configured to automatically batch samples into chunks for transmission. Note that for LSL the data is always a linear sequence of samples and data that is pushed as samples can be pulled out as chunks or vice versa. They also show how structs can be used to represent the sample data, instead of numeric arrays (which is mostly a syntactic difference):
* `Sending a multi-channel time series at chunk granularity. <https://github.com/sccn/liblsl/blob/main/examples/SendDataInChunks.cpp>`__
* `Receiving a multi-channel time series at chunk granularity. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveDataInChunks.cpp>`__

These two example programs illustrate a more special-purpose use case, namely sending arbitrary string-formatted data at irregular sampling rate. Such streams are used by programs that produce event markers, for example. These are 1:1 equivalents of the corresponding C programs:
* `Sending a stream of strings with irregular timing. <https://github.com/sccn/liblsl/blob/main/examples/SendStringMarkers.cpp>`__
* `Receiving a stream of strings with irregular timing. <https://github.com/sccn/liblsl/blob/main/examples/ReceiveStringMarkers.cpp>`__

The last example shows how to attach properly formatted meta-data to a stream, and how to read it out again at the receiving end. While meta-data is strictly optional, it is very useful to make streams self-describing. LSL has adopted the convention to name meta-data fields according to the XDF file format specification whenever the content type matches (for example EEG, Gaze, MoCap, VideoRaw, etc); the spec is `here <https://github.com/sccn/xdf/wiki/Meta-Data>`__. Note that some older example programs (SendData/ReceiveData) predate this convention and name the channels inconsistently.
* `Handling stream meta-data. <https://github.com/sccn/liblsl/blob/main/examples/HandleMetaData.cpp>`__

C/C++ Special-Purpose Example Programs
**************************************
These programs illustrate some special use cases of LSL that are also relevant for C programmers. See the lsl\_c.h header for the corresponding C APIs (they are very similar to the C++ code shown here).

This example illustrates in more detail how streams can be resolved on the network:
* `Resolving all streams on the lab network, one-shot and continuous. <https://github.com/sccn/liblsl/blob/main/examples/GetAllStreams.cpp>`__

This example shows how to query the full XML meta-data of a stream (which may be several megabytes large):
* `Retrieving the XML meta-data of a stream. <https://github.com/sccn/liblsl/blob/main/examples/GetFullinfo.cpp>`__

This example shows how to obtain time-correction values for a given stream. These time-correction values are offsets (in seconds) that are used to remap any stream's timestamps into the own local clock domain (just by adding the offset to the timestamp):
* `Querying the time-correction information for a stream. <https://github.com/sccn/liblsl/blob/main/examples/GetTimeCorrection.cpp>`__
liblsl's `examples folder <https://github.com/sccn/liblsl/tree/main/examples>`__ has C and C++
programs from basic to advanced: sending and receiving time series (sample by sample and in
chunks), string event markers, stream metadata, resolving all streams on the network, reading a
stream's full metadata, and querying time correction. Its
`README <https://github.com/sccn/liblsl/blob/main/examples/README.md>`__ walks through them, and
:liblsl:`Using liblsl in your project <guide/linking.html>` shows how to build them.

Python Example Programs: Basic to Advanced
******************************************
Expand Down
22 changes: 11 additions & 11 deletions docs/info/faqs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,9 +169,10 @@ pre-allocated buffer.
Make sure that you use a recent version of liblsl (1.10 or later offers a
faster network protocol) at both the sender and the receiver.

If you are writing an application that needs to push a lot of data, please show
your interest by commenting on the long-lingering `pull request to speed up pushes
<https://github.com/sccn/liblsl/pull/170>`_ by reducing the number of data copies.
For outlets that push a lot of data to few inlets, liblsl 1.18 adds a synchronous (zero-copy)
mode: create the outlet with the ``transp_sync_blocking`` transport option, and each push writes
directly to the connected inlets instead of copying through a buffer. See
:liblsl:`data transport <internals/streamfeed.html>` for its trade-offs.

Chunk sizes
-----------
Expand Down Expand Up @@ -256,20 +257,19 @@ how to name the file, i.e. :file:`lsl.dll` for Windows,
:file:`liblsl.dylib` for MacOS / OS X.

The `liblsl release page <https://github.com/sccn/liblsl/releases>`_
has multiple packages, generally called
:file:`liblsl-{version}-{system}.{extension}`, e.g.
:file:`liblsl-1.13.1-Linux64-bionic.deb` with the 64 bit Ubuntu Linux 18.04
(Codename Bionic Beaver) package or
:file:`liblsl-1.13.1-Win32.zip` with the 32 bit Windows DLLs.
has packages named for the system and processor, e.g.
:file:`liblsl-{version}-noble_{amd64}.deb` for 64-bit Ubuntu 24.04 (Noble) or
:file:`liblsl-{version}-Win_{i386}.zip` for 32-bit Windows;
:liblsl:`Getting liblsl <guide/getting.html>` lists them all.

.. warning
.. warning::

Android also has ``.so`` shared objects, but has a different
toolchain and architecture so the binaries (even if they're also named
:file:`liblsl.so`) are **not** interchangeable with ``.so`` files for regular
:file:`liblsl.so`) are **not** interchangeable with ``.so`` files for regular
Linuxes.

.. warning
.. warning::

Embedded Linux devices typically have an ARM processor instead of an x86 /
x64 processor so the default linux binaries won't work (resulting in an
Expand Down
29 changes: 6 additions & 23 deletions docs/info/getting_lsl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,30 +14,13 @@ What you need depends on what you want to do:
liblsl
======

liblsl is the C/C++ library that every LSL application and binding uses. Its own documentation
covers in detail how to :liblsl:`get it <guide/getting.html>`,
:liblsl:`use it in your project <guide/linking.html>` and
:liblsl:`build it <guide/building.html>`. In short:
liblsl, the C/C++ library under every LSL application and binding, comes as release downloads for
Windows, Linux, macOS and iOS, from package managers (conda-forge, vcpkg, Conan, Homebrew), or
built as part of your own CMake project. :liblsl:`Getting liblsl <guide/getting.html>` lists them
all; :liblsl:`Using liblsl in your project <guide/linking.html>` shows how to link it.

* **Build it with your project.** C/C++ projects using CMake can add liblsl with
``FetchContent`` and link the ``LSL::lsl`` target. This always gives you exactly the version
you ask for, built with your compiler.
* **Release downloads.** Every `liblsl release <https://github.com/sccn/liblsl/releases>`__
has builds for Windows (x64, x86, ARM64, and MinGW), Ubuntu (``.deb``, x64/ARM), macOS (an
installer for ``lsl.framework``) and an ``xcframework`` for macOS and iOS. These are built and
tested by the liblsl repository's own CI.
* **Package managers.** liblsl is also available from:

* `conda-forge <https://anaconda.org/conda-forge/liblsl>`__: ``conda install -c conda-forge liblsl``
* `vcpkg <https://vcpkg.io>`__: ``vcpkg install liblsl``
* `Conan <https://conan.io/center/liblsl>`__
* `Homebrew <https://brew.sh>`__: ``brew install labstreaminglayer/tap/lsl``

.. warning::
These packages are maintained separately from liblsl and are updated by hand after each
release, so they are often one or more releases behind (check the version they offer).
The best-supported routes are the release downloads and building liblsl with your project
through its CMake integration, which liblsl's CI tests on every change.
The package-manager versions are maintained separately and are often a release or more behind;
the release downloads and liblsl's own CMake integration are the best-supported routes.

Apps and the full source tree
=============================
Expand Down
Loading
Loading