LinkPython-extern 1.2.1__tar.gz → 1.3.0a2__tar.gz

linkpython_extern-1.3.0a2/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "modules/link"]
+	path = modules/link
+	url = https://github.com/Ableton/link.git

linkpython_extern-1.3.0a2/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.15...4.3)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+set(PYBIND11_FINDPYTHON ON)
+find_package(pybind11 CONFIG REQUIRED)
+
+include(modules/link/AbletonLinkConfig.cmake)
+pybind11_add_module(_link src/Link.cpp)
+target_link_libraries(_link PRIVATE Ableton::Link)
+install(TARGETS _link LIBRARY DESTINATION .)

linkpython_extern-1.3.0a2/MANIFEST.in

@@ -0,0 +1,12 @@
+graft modules
+graft src
+graft src-py
+include CMakeLists.txt
+global-exclude *.pdf
+prune example
+prune **/.github
+prune **/assets
+prune **/ci
+prune **/docs
+prune **/examples
+prune **/tests

linkpython_extern-1.3.0a2/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: LinkPython-extern
+Version: 1.3.0a2
+Summary: A Python wrapper for Ableton Link, wheels included!
+Keywords: ableton,ableton link,link,music,sync
+Author: gonzaloflirt
+Maintainer: thegamecracks
+License-Expression: Unlicense
+License-File: LICENSE.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python
+Classifier: Topic :: System :: Networking
+Project-URL: Homepage, https://github.com/thegamecracks/link-python
+Requires-Python: <3.15,>=3.9
+Description-Content-Type: text/markdown
+
+# LinkPython-extern
+
+[![PyPI](https://img.shields.io/pypi/v/LinkPython-extern?label=View%20on%20pypi&style=flat-square)](https://pypi.org/project/LinkPython-extern/)
+[![Build](https://github.com/thegamecracks/link-python/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/thegamecracks/link-python/actions/workflows/build_wheels.yml)
+[![Tests](https://github.com/thegamecracks/link-python/actions/workflows/pytest.yml/badge.svg)](https://github.com/thegamecracks/link-python/actions/workflows/pytest.yml)
+
+A Python wrapper for [Ableton Link], forked from gonzaloflirt's [link-python]
+to streamline the user experience with new methods, type stubs, and pre-built
+wheels.
+
+```py
+from link import Link
+
+link = Link(120)
+clock = link.clock()
+micros = clock.micros()
+
+state = link.captureAppSessionState()
+beat = state.beatAtTime(micros, 4)
+phase = state.phaseAtTime(micros, 4)
+```
+
+You can see the full API documentation in [`__init__.pyi`], or look at
+the [LinkHut.py] example which is equivalent to Ableton Link's
+[linkhut] example.
+
+For asyncio usage, consider trying out the [aalink] project!
+
+## Installation
+
+This project can be installed from PyPI under the [LinkPython-extern] name:
+
+```sh
+pip install LinkPython-extern
+```
+
+Note that we are *not* the same as [LinkPython], which is a different fork
+of link-python by munshkr.
+
+## Python compatibility
+
+|                | v1.0.0 | v1.0.1 | v1.0.4 | v1.1.0 | v1.2.0 | v1.3.0a1 | main |
+|----------------|:------:|:------:|:------:|:------:|:------:|:--------:|:----:|
+| CPython 3.6    |  ✅   |  ✅    |  ✅   |  ❌    |  ❌   |    ❌    |  ❌  |
+| CPython 3.7    |  ✅   |  ✅    |  ✅   |  ✅    |  ❌   |    ❌    |  ❌  |
+| CPython 3.8    |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ❌    |  ❌  |
+| CPython 3.9    |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.10   |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.11   |  ❌   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.12   |  ❌   |  ❌    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.13\* |  ❌   |  ❌    |  ❌   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.14   |  ❌   |  ❌    |  ❌   |  ❌    |  ✅   |    ✅    |  ✅  |
+| CPython 3.15   |  ❌   |  ❌    |  ❌   |  ❌    |  ❌   |    ❌    |  ❌  |
+| CPython 3.16+  |  ❌   |  ❌    |  ❌   |  ❌    |  ❌   |    ❌    |  ❌  |
+
+\* CPython 3.13's experimental free-threading builds are not supported.
+
+## Building from source
+
+If you want to build this package from source, you will need CMake installed.
+You however do not need to manually build the project, as scikit-build-core will
+handle invoking cmake when you install it with pip. To install directly
+from the main branch:
+
+```sh
+pip install git+https://github.com/thegamecracks/link-python
+```
+
+If building from the repository directly, make sure to clone all submodules using:
+
+```sh
+git clone --recurse-submodules https://github.com/thegamecracks/link-python
+# or, if already cloned:
+git submodule update --init --recursive
+```
+
+## License
+
+This project is written under [Unlicense] but also depends on,
+among other libraries, [Ableton Link] and [pybind11].
+Please mind the licenses of those libraries and their dependencies.
+
+[Ableton Link]: https://github.com/ableton/link.git
+[link-python]: https://github.com/gonzaloflirt/link-python
+[`__init__.pyi`]: https://github.com/thegamecracks/link-python/blob/master/src-py/link/__init__.pyi
+[LinkHut.py]: https://github.com/thegamecracks/link-python/blob/master/example/LinkHut.py
+[linkhut]: https://github.com/Ableton/link/blob/master/examples/linkhut/main.cpp
+[aalink]: https://github.com/artfwo/aalink
+[LinkPython-extern]: https://pypi.org/project/LinkPython-extern/
+[LinkPython]: https://github.com/munshkr/link-python
+[Unlicense]: /LICENSE.md
+[pybind11]: https://github.com/pybind/pybind11

linkpython_extern-1.3.0a2/README.md

@@ -0,0 +1,92 @@
+# LinkPython-extern
+
+[![PyPI](https://img.shields.io/pypi/v/LinkPython-extern?label=View%20on%20pypi&style=flat-square)](https://pypi.org/project/LinkPython-extern/)
+[![Build](https://github.com/thegamecracks/link-python/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/thegamecracks/link-python/actions/workflows/build_wheels.yml)
+[![Tests](https://github.com/thegamecracks/link-python/actions/workflows/pytest.yml/badge.svg)](https://github.com/thegamecracks/link-python/actions/workflows/pytest.yml)
+
+A Python wrapper for [Ableton Link], forked from gonzaloflirt's [link-python]
+to streamline the user experience with new methods, type stubs, and pre-built
+wheels.
+
+```py
+from link import Link
+
+link = Link(120)
+clock = link.clock()
+micros = clock.micros()
+
+state = link.captureAppSessionState()
+beat = state.beatAtTime(micros, 4)
+phase = state.phaseAtTime(micros, 4)
+```
+
+You can see the full API documentation in [`__init__.pyi`], or look at
+the [LinkHut.py] example which is equivalent to Ableton Link's
+[linkhut] example.
+
+For asyncio usage, consider trying out the [aalink] project!
+
+## Installation
+
+This project can be installed from PyPI under the [LinkPython-extern] name:
+
+```sh
+pip install LinkPython-extern
+```
+
+Note that we are *not* the same as [LinkPython], which is a different fork
+of link-python by munshkr.
+
+## Python compatibility
+
+|                | v1.0.0 | v1.0.1 | v1.0.4 | v1.1.0 | v1.2.0 | v1.3.0a1 | main |
+|----------------|:------:|:------:|:------:|:------:|:------:|:--------:|:----:|
+| CPython 3.6    |  ✅   |  ✅    |  ✅   |  ❌    |  ❌   |    ❌    |  ❌  |
+| CPython 3.7    |  ✅   |  ✅    |  ✅   |  ✅    |  ❌   |    ❌    |  ❌  |
+| CPython 3.8    |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ❌    |  ❌  |
+| CPython 3.9    |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.10   |  ✅   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.11   |  ❌   |  ✅    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.12   |  ❌   |  ❌    |  ✅   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.13\* |  ❌   |  ❌    |  ❌   |  ✅    |  ✅   |    ✅    |  ✅  |
+| CPython 3.14   |  ❌   |  ❌    |  ❌   |  ❌    |  ✅   |    ✅    |  ✅  |
+| CPython 3.15   |  ❌   |  ❌    |  ❌   |  ❌    |  ❌   |    ❌    |  ❌  |
+| CPython 3.16+  |  ❌   |  ❌    |  ❌   |  ❌    |  ❌   |    ❌    |  ❌  |
+
+\* CPython 3.13's experimental free-threading builds are not supported.
+
+## Building from source
+
+If you want to build this package from source, you will need CMake installed.
+You however do not need to manually build the project, as scikit-build-core will
+handle invoking cmake when you install it with pip. To install directly
+from the main branch:
+
+```sh
+pip install git+https://github.com/thegamecracks/link-python
+```
+
+If building from the repository directly, make sure to clone all submodules using:
+
+```sh
+git clone --recurse-submodules https://github.com/thegamecracks/link-python
+# or, if already cloned:
+git submodule update --init --recursive
+```
+
+## License
+
+This project is written under [Unlicense] but also depends on,
+among other libraries, [Ableton Link] and [pybind11].
+Please mind the licenses of those libraries and their dependencies.
+
+[Ableton Link]: https://github.com/ableton/link.git
+[link-python]: https://github.com/gonzaloflirt/link-python
+[`__init__.pyi`]: https://github.com/thegamecracks/link-python/blob/master/src-py/link/__init__.pyi
+[LinkHut.py]: https://github.com/thegamecracks/link-python/blob/master/example/LinkHut.py
+[linkhut]: https://github.com/Ableton/link/blob/master/examples/linkhut/main.cpp
+[aalink]: https://github.com/artfwo/aalink
+[LinkPython-extern]: https://pypi.org/project/LinkPython-extern/
+[LinkPython]: https://github.com/munshkr/link-python
+[Unlicense]: /LICENSE.md
+[pybind11]: https://github.com/pybind/pybind11

linkpython_extern-1.3.0a2/modules/link/.clang-tidy

@@ -0,0 +1,38 @@
+Checks: >
+  -*,
+  bugprone-infinite-loop,
+  bugprone-move-forwarding-reference,
+  bugprone-narrowing-conversions,
+  bugprone-use-after-move,
+  clang-analyzer-core.DivideZero,
+  clang-analyzer-core.NullDereference,
+  clang-analyzer-core.StackAddressEscape,
+  clang-analyzer-core.UndefinedBinaryOperatorResult,
+  clang-analyzer-cplusplus.Move,
+  clang-analyzer-cplusplus.NewDelete,
+  clang-analyzer-cplusplus.NewDeleteLeaks,
+  clang-analyzer-deadcode.DeadStores,
+  concurrency-mt-unsafe,
+  misc-move-constructor-init,
+  misc-unused-alias-decls,
+  misc-unused-using-decls,
+  modernize-raw-string-literal,
+  modernize-use-auto,
+  modernize-use-default,
+  modernize-use-emplace,
+  modernize-use-nullptr,
+  modernize-use-override,
+  modernize-use-using,
+  performance-for-range-copy,
+  performance-move-const-arg,
+  performance-move-constructor-init,
+  performance-unnecessary-copy-initialization,
+  readability-avoid-const-params-in-decls,
+  readability-braces-around-statements,
+  readability-make-member-function-const,
+  readability-redundant-member-init,
+  readability-redundant-string-cstr,
+  readability-redundant-string-init,
+  readability-static-definition-in-anonymous-namespace
+
+HeaderFilterRegex: 'include/|src/|examples/|extensions/'

linkpython_extern-1.3.0a2/modules/link/.github/workflows/ci.yml

@@ -0,0 +1,157 @@
+name: Link CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  macos:
+    strategy:
+      matrix:
+        include:
+          - os: macos-14
+            configuration: Debug
+            xcode-version: 15.4.0
+          - os: macos-14
+            configuration: Release
+            xcode-version: 16.2.0
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Configure
+        run: |
+          sudo xcode-select -s '/Applications/Xcode_${{ matrix.xcode-version }}.app/Contents/Developer'
+          cmake -B build -GNinja . -DCMAKE_BUILD_TYPE=${{ matrix.configuration }}
+      - name: Build
+        run: cmake --build build --config ${{ matrix.configuration }}
+      - name: Test
+        run: |
+          ./build/bin/LinkCoreTest
+          ./build/bin/LinkDiscoveryTest
+          ./build/bin/LinkAudioTest
+
+  linux:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-22.04
+            configuration: Debug
+            cxx: clang++-13
+            audio-driver: Alsa
+          - os: ubuntu-24.04
+            configuration: Release
+            cxx: clang++-18
+            audio-driver: Jack
+          - os: ubuntu-22.04
+            configuration: Debug
+            cxx: g++-10
+            audio-driver: Jack
+          - os: ubuntu-24.04
+            configuration: Release
+            cxx: g++-14
+            audio-driver: Alsa
+
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Set up
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake libjack-dev portaudio19-dev valgrind
+      - name: Configure
+        env:
+          CXX: ${{ matrix.cxx }}
+        run: |
+          args=(-Bbuild . -GNinja -DCMAKE_BUILD_TYPE=${{ matrix.configuration }})
+          if [[ "${{ matrix.audio-driver }}" == "Jack" ]]; then
+            args+=(-DLINK_BUILD_JACK=ON)
+          fi
+          cmake "${args[@]}"
+      - name: Build
+        run: cmake --build build --config ${{ matrix.configuration }}
+      - name: Test
+        run: |
+          valgrind --leak-check=full --show-reachable=yes --gen-suppressions=all --error-exitcode=1 --track-origins=yes --suppressions=ci/memcheck.supp build/bin/LinkCoreTest
+          valgrind --leak-check=full --show-reachable=yes --gen-suppressions=all --error-exitcode=1 --track-origins=yes --suppressions=ci/memcheck.supp build/bin/LinkDiscoveryTest
+          valgrind --leak-check=full --show-reachable=yes --gen-suppressions=all --error-exitcode=1 --track-origins=yes --suppressions=ci/memcheck.supp build/bin/LinkAudioTest
+
+  windows:
+    strategy:
+      matrix:
+        include:
+          - os: windows-2022
+            generator: "Visual Studio 17 2022"
+            configuration: Debug
+            audio-driver: Asio
+            thread-description: ON
+          - os: windows-2022
+            generator: "Visual Studio 17 2022"
+            configuration: Release
+            audio-driver: Wasapi
+            thread-description: OFF
+
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Configure
+        run: |
+          $args = @("-Bbuild", ".", "-DCMAKE_BUILD_TYPE=${{ matrix.configuration }}", "-G${{ matrix.generator }}")
+          if ("${{ matrix.audio-driver }}" -eq "Asio") {
+            $args += "-DLINK_BUILD_ASIO=ON"
+          }
+          if ("${{ matrix.audio-driver }}" -eq "Wasapi") {
+            $args += "-DLINK_BUILD_ASIO=OFF"
+          }
+          if ("${{ matrix.thread-description }}" -eq "ON") {
+            $args += "-DLINK_WINDOWS_SETTHREADDESCRIPTION=ON"
+          }
+          cmake @args
+      - name: Build
+        run: cmake --build build --config ${{ matrix.configuration }}
+      - name: Test
+        run: |
+          .\build\bin\${{ matrix.configuration }}\LinkCoreTest.exe
+          .\build\bin\${{ matrix.configuration }}\LinkDiscoveryTest.exe
+          .\build\bin\${{ matrix.configuration }}\LinkAudioTest.exe
+
+  esp-idf:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build ESP-IDF
+        run: docker run --rm -v ${{ github.workspace }}:/link -w /link/examples/esp32 -e LC_ALL=C.UTF-8 espressif/idf:v5.5 idf.py build
+
+  check-formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install clang-format 19
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y wget lsb-release gnupg
+          wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+          sudo bash -c 'echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs) main" > /etc/apt/sources.list.d/llvm.list'
+          sudo apt-get update
+          sudo apt-get install -y clang-format-19 python3
+      - name: Check Formatting
+        run: python3 ci/check-formatting.py -c /usr/bin/clang-format-19

linkpython_extern-1.3.0a2/modules/link/.github/workflows/clang-tidy.yml

@@ -0,0 +1,27 @@
+name: Run clang-tidy
+
+on:
+  workflow_dispatch:
+
+jobs:
+  clang-tidy:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Set up
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake ninja-build clang-18 clang-tidy-18 libjack-dev portaudio19-dev python3
+      - name: Configure
+        env:
+          CC: clang-18
+          CXX: clang++-18
+        run: |
+          cmake -B build -GNinja . -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DLINK_BUILD_JACK=ON
+      - name: Run clang-tidy
+        env:
+          CLANG_TIDY: clang-tidy-18
+        run: run-clang-tidy -p build -quiet -warnings-as-errors='*'

linkpython_extern-1.3.0a2/modules/link/AbletonLinkConfig.cmake

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.10)
+
+set(CMAKE_CXX_STANDARD 17)
+
+include(${CMAKE_CURRENT_LIST_DIR}/cmake_include/ConfigureAbletonLink.cmake)
+ConfigureAbletonLink(${CMAKE_CURRENT_LIST_DIR})
+

linkpython_extern-1.3.0a2/modules/link/README.md

@@ -0,0 +1,161 @@
+# Ableton Link
+
+This is the codebase for Ableton Link, a technology that synchronizes musical beat, tempo,
+and phase across multiple applications running on one or more devices. Applications on
+devices connected to a local network discover each other automatically and form a musical
+session in which each participant can perform independently: anyone can start or stop
+while still staying in time. Anyone can change the tempo, the others will follow. Anyone
+can join or leave without disrupting the session.
+
+# License
+
+Ableton Link is dual [licensed][license] under GPLv2+ and a proprietary license. If you
+would like to incorporate Link into a proprietary software application, please contact
+<link-devs@ableton.com>.
+
+# Building and Running Link Examples
+
+Link relies on `asio-standalone` as a submodule. After checking out the
+main repositories, those submodules have to be loaded using
+
+```
+git submodule update --init --recursive
+```
+
+Link uses [CMake][cmake] to generate build files for the [Catch][catch]-based
+unit-tests and the example applications.
+
+```
+$ mkdir build
+$ cd build
+$ cmake ..
+$ cmake --build .
+```
+
+The output binaries for the example applications and the unit-tests will be placed in a
+`bin` subdirectory of the CMake binary directory.
+
+# Integrating Link in your Application
+
+## Test Plan
+
+To make sure users have the best possible experience using Link it is important all apps
+supporting Link behave consistently. This includes for example playing in sync with other
+apps as well as not hijacking a jams tempo when joining. To make sure your app behaves as
+intended make sure it complies to the [Test Plan](TEST-PLAN.md).
+
+## Building Link
+
+Link is a header-only library, so it should be straightforward to integrate into your
+application.
+When using the basic version of Link, you should include `Link.hpp`. If you want Link with Link
+Audio support, include `LinkAudio.hpp`. The library does not follow the IWYU principles, so
+you will have to include the respective header in every compilation unit.
+
+### CMake-based Projects
+
+If you are using CMake, then you can simply add the following to your CMakeLists.txt file:
+
+```cmake
+include($PATH_TO_LINK/AbletonLinkConfig.cmake)
+target_link_libraries($YOUR_TARGET Ableton::Link)
+
+```
+
+You can optionally have your build target depend on `${link_HEADERS}`, which will make
+the Link headers visible in your IDE. This variable exported to the `PARENT_SCOPE` by
+Link's CMakeLists.txt.
+
+### Other Build Systems
+
+To include the Link library in your non CMake project, you must do the following:
+
+ - Add the `include` and `modules/asio-standalone/asio/include` directories to your
+   list of include paths
+ - Define `LINK_PLATFORM_MACOSX=1`, `LINK_PLATFORM_LINUX=1`, or `LINK_PLATFORM_WINDOWS=1`,
+   depending on which platform you are building on.
+
+If you get any compiler errors/warnings, have a look at
+[compile-flags.cmake](cmake_include/ConfigureCompileFlags.cmake), which might provide some
+insight as to the compiler flags needed to build Link.
+
+### Build Requirements
+
+| Platform | Minimum Required     | Optional (only required for examples) |
+|----------|----------------------|---------------------------------------|
+| Windows  | MSVC 17 2022         | Steinberg ASIO SDK 2.3                |
+| Mac      | Xcode 16.2.0         |                                       |
+| Linux    | Clang 13 or GCC 10   | libportaudio19-dev                    |
+
+
+Other compilers with good C++17 support should work, but are not verified.
+
+iOS developers should not use this repo. See http://ableton.github.io/linkkit for
+information on the LinkKit SDK for iOS.
+
+# Documentation
+
+An overview of Link concepts can be found at http://ableton.github.io/link. Those that
+are new to Link should start there. The [Link.hpp](include/ableton/Link.hpp) header
+contains the full Link public interface. See the LinkHut projects in this repo for an
+example usage of the `Link` type.
+Similarly, [LinkAudio.hpp](include/ableton/LinkAudio.hpp) contains the documentation for
+the `LinkAudio` type and example usage is implemented in LinkAudioHut.
+
+## Time and Clocks
+
+Link works by calculating a relationship between the system clocks of devices in a session.
+Since the mechanism for obtaining a system time value and the unit of these values differ
+across platforms, Link defines a `Clock` abstraction with platform-specific
+implementations. Please see:
+- `Link::clock()` method in [Link.hpp](include/ableton/Link.hpp)
+- OSX and iOS clock implementation in
+[platforms/darwin/Clock.hpp](include/ableton/platforms/darwin/Clock.hpp)
+- Windows clock implementation in
+[platforms/windows/Clock.hpp](include/ableton/platforms/windows/Clock.hpp)
+- C++ standard library `std::chrono::steady_clock`-based implementation in
+[platforms/stl/Clock.hpp](include/ableton/platforms/stl/Clock.hpp)
+
+Using the system time correctly in the context of an audio callback gets a little
+complicated. Audio devices generally have a sample clock that is independent of the system
+Clock. Link maintains a mapping between system time and beat time and therefore can't use
+the sample time provided by the audio system directly.
+
+On OSX and iOS, the CoreAudio render callback is passed an `AudioTimeStamp` structure with
+a `mHostTime` member that represents the system time at which the audio buffer will be
+passed to the audio hardware. This is precisely the information needed to derive the beat
+time values corresponding to samples in the buffer using Link. Unfortunately, not all
+platforms provide this data to the audio callback.
+
+When a system timestamp is not provided with the audio buffer, the best a client can do in
+the audio callback is to get the current system time and filter it based on the provided
+sample time. Filtering is necessary because the audio callback will not be invoked at a
+perfectly regular interval and therefore the queried system time will exhibit jitter
+relative to the sample clock. The Link library provides a
+[HostTimeFilter](include/ableton/link/HostTimeFilter.hpp) utility class that performs a
+linear regression between system time and sample time in order to improve the accuracy of
+system time values used in an audio callback. See the audio callback implementations for
+the various [platforms](examples/linkaudio) used in the examples to see how this is used
+in practice. Note that for Windows-based systems, we recommend using the [ASIO][asio]
+audio driver.
+
+## Latency Compensation
+
+As discussed in the previous section, the system time that a client is provided in an
+audio callback either represents the time at which the buffer will be submitted to the
+audio hardware (for OSX/iOS) or the time at which the callback was invoked (when the
+code in the callback queries the system time). Note that neither of these is what we
+actually want to synchronize between devices in order to play in time.
+
+In order for multiple devices to play in time, we need to synchronize the moment at which
+their signals hit the speaker or output cable. If this compensation is not performed,
+the output signals from devices with different output latencies will exhibit a persistent
+offset from each other. For this reason, the audio system's output latency should be added
+to system time values before passing them to Link methods. Examples of this latency
+compensation can be found in the [platform](examples/linkaudio) implementations of the
+example apps.
+
+[asio]: https://www.steinberg.net/en/company/developers.html
+[catch]: https://github.com/philsquared/Catch
+[cmake]: https://www.cmake.org
+[license]: LICENSE.md