### Install Git

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Install git using Homebrew.

```bash
brew install git
```

--------------------------------

### Install Homebrew

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Install Homebrew if it is not already present.

```bash
/bin/bash -c "$(curl -fsSLhttps://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

--------------------------------

### Install and link Qt5

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Install and force link Qt5 using Homebrew.

```bash
brew install qt5
brew link qt5 --force
```

--------------------------------

### JackTrip Version Output

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Example output indicating a successful installation.

```text
JackTrip VERSION: 2.x.x
Copyright (c) 2008-2020 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University
```

--------------------------------

### Install JackTrip from Debian Backports

Source: https://jacktrip.github.io/jacktrip/Install

Configure the Debian backports repository and install JackTrip from it, shown with an example for Debian Bullseye.

```bash
mkdir -p /etc/apt/sources.list.d/
echo "deb http://deb.debian.org/debian bullseye-backports main" | tee /etc/apt/sources.list.d/backports.list
apt-get update
apt-get install -t bullseye-backports jacktrip

```

--------------------------------

### Install Dependencies on Fedora (Qt5)

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use these commands to install the required Qt5 and development tools on Fedora.

```bash
dnf install qt5-qtbase-devel qt5-qtnetworkauth-devel qt5-qtwebsockets-devel qt5-qtquickcontrols2-devel qt5-qtsvg-devel
dnf groupinstall "C Development Tools and Libraries"
dnf groupinstall "Development Tools"
dnf install "pkgconfig(jack)" rtaudio-devel git help2man python3-jinja2 dbus-devel
```

--------------------------------

### Install Dependencies on macOS

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Installs Meson, Qt5, RtAudio, and help2man using Homebrew on macOS. Note that Jack installation might require a separate installer or Homebrew.

```bash
brew install meson qt5 rtaudio help2man

```

--------------------------------

### Install Dependencies on Fedora (Qt6)

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use these commands to install the required Qt6 and development tools on Fedora.

```bash
dnf install qt6-qtbase-devel qt5-qtnetworkauth-devel qt5-qtwebsockets-devel qt5-qtquickcontrols2-devel qt5-qtsvg-devel qt6-qtwebengine-devel qt6-qtwebchannel-devel qt6-qt5compat-devel qt6-qtshadertools-devel
dnf groupinstall "C Development Tools and Libraries"
dnf groupinstall "Development Tools"
dnf install "pkgconfig(jack)" rtaudio-devel git help2man python3-jinja2 dbus-devel
```

--------------------------------

### Install Dependencies on Ubuntu/Debian/Raspbian (Qt5)

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use these commands to install the required Qt5 and development tools on Debian-based systems.

```bash
apt install --no-install-recommends build-essential autoconf automake libtool make libjack-jackd2-dev git help2man python3-jinja2
apt install qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake qttools5-dev libqt5svg5-dev libqt5websockets5-dev qtdeclarative5-dev qtquickcontrols2-5-dev
```

--------------------------------

### Install JackTrip

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Install JackTrip after successful compilation. You will be prompted to enter your password for system-wide installation.

```bash
$ meson install -C builddir
```

--------------------------------

### Check Homebrew installation

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Verify if Homebrew is installed on the system.

```bash
brew -v
```

--------------------------------

### Build and Install VST3 SDK

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Clones the VST3 SDK repository, builds it using CMake, and installs the necessary components to /opt/vst3sdk.

```bash
git clone --recursive https://github.com/steinbergmedia/vst3sdk
mkdir vst3sdk/build
cd vst3sdk/build
cmake -DCMAKE_BUILD_TYPE=Release ../
cmake --build . --config Release
sudo mkdir -p /opt/vst3sdk
sudo cp -r lib/Release /opt/vst3sdk/lib
sudo cp -r bin/Release /opt/vst3sdk/bin
sudo cp -r ../base ../pluginterfaces ../public.sdk ../vstgui4 /opt/vst3sdk
```

--------------------------------

### Install MkDocs dependencies

Source: https://jacktrip.github.io/jacktrip/Documentation/MkDocs

Install the required Python packages for building and serving the documentation.

```bash
pip install mkdocs mkdocs-material mkdocs-macros-plugin
```

--------------------------------

### Verify JackTrip Installation

Source: https://jacktrip.github.io/jacktrip/Build/Windows

Run the executable with the version flag to confirm successful installation.

```bash
jacktrip.exe -v
```

--------------------------------

### Install JackTrip binaries

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Clone, build, and copy JackTrip binaries to /usr/local/bin.

```bash
$ git clone --recurse-submodules https://github.com/jacktrip/jacktrip.git
$ cd jacktrip
$ ./build
$ cd builddir
$ sudo cp qjacktrip /usr/local/bin/
  (enter your password when prompted)
$ sudo cp jacktrip /usr/local/bin/

$ sudo chmod 755 /usr/local/bin/qjacktrip
  (now you can run jacktrip from any directory using Terminal)
```

--------------------------------

### Check XCode installation

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Verify if XCode is installed on the system.

```bash
xcodebuild -version
```

--------------------------------

### Install Dependencies on Debian/Ubuntu

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Installs required packages for Meson, build tools, Qt5, RtAudio, Jack, and Git on Debian/Ubuntu systems.

```bash
apt install meson build-essential qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake qttools5-dev libqt5svg5-dev libqt5networkauth5-dev libqt5websockets5-dev qtdeclarative5-dev qtquickcontrols2-5-dev libjack-jackd2-dev git help2man

```

--------------------------------

### Install Dependencies on Ubuntu/Debian/Raspbian (Qt6)

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use these commands to install the required Qt6 and development tools on Debian-based systems, including GUI dependencies.

```bash
apt install --no-install-recommends build-essential autoconf automake libtool make libjack-jackd2-dev git help2man libclang-dev libdbus-1-dev libdbus-1-dev python3-jinja2
apt install -y libqt6core6 libqt6gui6 libqt6network6 libqt6widgets6 libqt6qml6 libqt6qmlcore6 libqt6quick6 libqt6quickcontrols2-6 libqt6svg6  libqt6webchannel6 libqt6webengine6-data libqt6webenginecore6 libqt6webenginecore6-bin libqt6webenginequick6 libqt6websockets6 libqt6shadertools6 qt6-qpa-plugins qml6-module-qtquick-controls qml6-module-qtqml-workerscript qml6-module-qtquick-templates qml6-module-qtquick-layouts qml6-module-qt5compat-graphicaleffects qml6-module-qtwebchannel qml6-module-qtwebengine qml6-module-qtquick-window qml6-module-qtquick-dialogs
apt install qt6-base-dev qt6-base-dev-tools qmake6 qt6-tools-dev qt6-declarative-dev qt6-webengine-dev qt6-webview-dev qt6-webview-plugins libqt6svg6-dev libqt6websockets6-dev libqt6core5compat6-dev libqt6shadertools6-dev libgl1-mesa-dev
# for GUI builds
apt install libfreetype6-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev libx11-xcb-dev libdrm-dev libglu1-mesa-dev libwayland-dev libwayland-egl1-mesa libgles2-mesa-dev libwayland-server0 libwayland-egl-backend-dev libxcb1-dev libxext-dev libfontconfig1-dev libxrender-dev libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev '^libxcb.*-dev' libxcb-render-util0-dev libxcomposite-dev libgtk-3-dev
apt install librtaudio-dev # if building with RtAudio
```

--------------------------------

### Connection Setup and Handshake

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Outlines the different connection setup mechanisms JackTrip employs based on its deployment mode.

```APIDOC
## Connection setup and “handshake”

JackTrip supports multiple deployment styles. The relevant “protocol” differs depending on mode.

### P2P server mode (UDP-only)

In P2P server mode, there is **no TCP handshake**. Instead:
  * The server binds a UDP socket on its configured receive port.
  * It waits for the first UDP datagram.
  * It uses the datagram’s source address/port as the peer endpoint for subsequent UDP send/receive.

This supports basic NAT traversal by responding to the client’s observed source port.
See `JackTrip::serverStart()` and `JackTrip::receivedDataUDP()` in `src/JackTrip.cpp`.

### Hub / ping-server mode (TCP handshake + UDP audio)

When connecting to a hub/ping-server style endpoint, JackTrip uses a short-lived TCP connection to exchange UDP port information.
```

--------------------------------

### Install Dependencies on Fedora

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Installs necessary development packages for Meson, Qt5, RtAudio, Jack, and Python utilities on Fedora systems.

```bash
dnf install meson qt5-qtbase-devel qt5-qtquickcontrols2-devel qt5-qtsvg-devel qt5-qtnetworkauth-devel qt5-qtwebsockets-devel rtaudio-devel "pkgconfig(jack)" help2man python3-jinja2 python3-pyyaml

```

--------------------------------

### Install JackTrip

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Installs the compiled JackTrip application and its associated files to the system. This command typically requires superuser privileges.

```bash
sudo ninja install

```

--------------------------------

### Install JackTrip on Debian/Ubuntu

Source: https://jacktrip.github.io/jacktrip/Install

Use the APT package manager to install JackTrip on Debian or Ubuntu systems.

```bash
sudo apt install jacktrip

```

--------------------------------

### Install JackTrip on Fedora

Source: https://jacktrip.github.io/jacktrip/Install

Use the DNF package manager to install JackTrip on Fedora systems.

```bash
sudo dnf install jacktrip

```

--------------------------------

### Install VST3 SDK Dependencies on Ubuntu/Debian

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Installs essential development libraries required for building the VST3 SDK on Ubuntu and Debian-based systems using apt.

```bash
sudo apt install -y libexpat-dev libxml2-dev libxcb-util-dev libxcb-cursor-dev libxcb-keysyms1-dev libxcb-xkb-dev libxkbcommon-dev libxkbcommon-x11-dev libgtkmm-3.0-dev libsqlite3-dev
```

--------------------------------

### Install VST3 SDK Dependencies on Fedora

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Installs essential development libraries required for building the VST3 SDK on Fedora using dnf.

```bash
sudo dnf install -y expat-devel freetype-devel pango-devel xcb-util-devel xcb-util-cursor-devel xcb-util-keysyms-devel libxkbcommon-x11-devel gtkmm3.0-devel libsqlite3x-devel
```

--------------------------------

### Configure Meson with Qt5 from Homebrew on macOS

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Configures the Meson build system, specifying the release build type and providing the pkg-config path for Qt5 installed via Homebrew. This is necessary when Meson cannot automatically find Qt5.

```bash
meson --buildtype release --pkg-config-path `brew --prefix qt5`/lib/pkgconfig build_release

```

--------------------------------

### Install pre-commit Hook Manager

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Install the pre-commit Python application using pip. This tool simplifies the management of git hooks.

```bash
pip install pre-commit
```

--------------------------------

### Add JackTrip PPA and Install on Ubuntu/Debian

Source: https://jacktrip.github.io/jacktrip/Install

Add the JackTrip PPA repository and update package lists before installing JackTrip on Ubuntu or Debian systems.

```bash
sudo add-apt-repository ppa:umlaeute/jacktrip
sudo apt update
sudo apt install jacktrip

```

--------------------------------

### GPL Notice for Interactive Programs

Source: https://jacktrip.github.io/jacktrip/About/License

This notice should be displayed by interactive programs when they start, informing users about the program's warranty status and redistribution conditions under the GPL. The commands 'show w' and 'show c' are placeholders for displaying warranty and conditions, respectively.

```text
<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

```

--------------------------------

### Install clang-format Git Pre-commit Hook

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Install the pre-commit hook for clang-format within the JackTrip repository's root directory. This ensures code is formatted before each commit.

```bash
pre-commit install
```

--------------------------------

### Run clang-format Pre-commit Hook on All Files

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Execute the pre-commit hook for clang-format across all files in the repository. This is useful for initial setup or a full project format check.

```bash
pre-commit run --all-files
```

--------------------------------

### Run Clang-Tidy on JackTrip

Source: https://jacktrip.github.io/jacktrip/DevTools/StaticAnalysis

Execute clang-tidy on the entire JackTrip codebase. Ensure clang-tidy is installed and a .clang-tidy file exists in the project directory. Meson generates a clang-tidy target.

```bash
ninja -C builddir clang-tidy
```

--------------------------------

### Run JACK with a Custom Name

Source: https://jacktrip.github.io/jacktrip/CustomJackServerName

Use the `--name` flag when starting the JACK daemon to assign it a custom name. This name will be used by JackTrip to connect to this specific JACK server instance.

```bash
jackd --name myfancyserver ...
```

--------------------------------

### Health-check Endpoint Request

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Use this GET request to check the health of the hub server's TLS and HTTP connectivity before attempting a WebSocket upgrade. The endpoint is available when the binary is built with WEBRTC_SUPPORT and TLS is configured.

```http
GET /ping HTTP/1.1


```

--------------------------------

### Build VST3 SDK for Windows

Source: https://jacktrip.github.io/jacktrip/Build/Windows

Commands to clone, configure, build, and copy the VST3 SDK files.

```bash
git clone --recursive https://github.com/steinbergmedia/vst3sdk
mkdir vst3sdk/build
cd vst3sdk/build
cmake -G "Visual Studio 17 2022" -A x64 -DSMTG_CREATE_PLUGIN_LINK=0 -DCMAKE_CXX_FLAGS="/MD" ../
cmake --build . --config Release
mkdir c:\vst3sdk
xcopy /E lib\Release c:\vst3sdk\lib\
xcopy /E bin\Release c:\vst3sdk\bin\
xcopy /E ..\base c:\vst3sdk\base\
xcopy /E ..\pluginterfaces c:\vst3sdk\pluginterfaces\
xcopy /E ..\public.sdk c:\vst3sdk\public.sdk\
xcopy /E ..\vstgui4 c:\vst3sdk\vstgui4\
```

--------------------------------

### Build JackTrip via Command Line

Source: https://jacktrip.github.io/jacktrip/Build/Windows

Commands to configure and build the project using qmake and mingw32-make.

```bash
$ cd builddir
$ qmake -spec win32-g++ ../src/jacktrip.pro # you may skip this step if you're building for the first time
$ mingw32-make clean # you may skip this step if you're building for the first time
$ qmake -spec win32-g++ ../src/jacktrip.pro
$ mingw32-make release
```

--------------------------------

### Build JackTrip using qmake

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Manually build the project using qmake if the build script fails.

```bash
$ qmake jacktrip.pro
$ make release
```

--------------------------------

### Prepare Meson Build Directory

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Initializes a Meson build directory. The first command creates a default debug build directory. Subsequent commands show how to create release and optimized debug build directories.

```bash
meson builddir                                  # defaults to debug build

## Additional build directories
meson --buildtype release build_release         # release build
Meson --buildtype debugoptimized build_debug    # optimized debug build

```

--------------------------------

### Build VST3 SDK for Mac

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Commands to clone, configure, and build the VST3 SDK.

```bash
git clone --recursive https://github.com/steinbergmedia/vst3sdk
mkdir vst3sdk/build
cd vst3sdk/build
cmake -DCMAKE_BUILD_TYPE=Release -DSMTG_CREATE_PLUGIN_LINK=0 -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" -DCMAKE_OSX_DEPLOYMENT_TARGET=12 ../
cmake --build . --config Release
sudo mkdir -p /opt/vst3sdk
sudo cp -r lib/Release /opt/vst3sdk/lib
sudo cp -r bin/Release /opt/vst3sdk/bin
sudo cp -r ../base ../pluginterfaces ../public.sdk ../vstgui4 /opt/vst3sdk
```

--------------------------------

### Configure JackTrip Build with Meson

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Configure the build using meson. The `-Drtaudio=enabled` option enables support for the RtAudio backend. Other options can be specified to customize the build.

```bash
$ meson setup -Drtaudio=enabled builddir
```

--------------------------------

### Build JackTrip using build script

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Compile JackTrip using the provided build script.

```bash
$ cd jacktrip
$ ./build
$ cd builddir
$ ls
```

--------------------------------

### Standard GPL License Notice

Source: https://jacktrip.github.io/jacktrip/About/License

Include this notice at the beginning of each source file to state the exclusion of warranty and specify the terms of redistribution under the GPL. Ensure a pointer to the full license is provided.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

```

--------------------------------

### Build JackTrip with Ninja

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Compiles the JackTrip project using the Ninja build system after Meson has configured the build environment. This command should be run from within the build directory.

```bash
cd builddir
ninja

```

--------------------------------

### Build JackTrip with Docker

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use Docker buildx to compile JackTrip for specific architectures and link configurations.

```bash
docker buildx build --target=artifact -f linux/Dockerfile.build --output type=local,dest=./ \
  --platform linux/amd64 --build-arg BUILD_CONTAINER=ubuntu:22.04 \
  --build-arg MESON_ARGS="-Ddefault_library=shared -Drtaudio=enabled -Drtaudio:jack=disabled -Drtaudio:default_library=static -Drtaudio:alsa=enabled -Drtaudio:pulse=enabled -Drtaudio:werror=false" .
```

```bash
docker buildx build --target=artifact -f linux/Dockerfile.build --output type=local,dest=./ \
  --platform linux/amd64 --build-arg BUILD_CONTAINER=ubuntu:20.04 \
  --build-arg MESON_ARGS="-Ddefault_library=static -Drtaudio=enabled -Drtaudio:jack=disabled -Drtaudio:default_library=static -Drtaudio:alsa=enabled -Drtaudio:pulse=disabled -Drtaudio:werror=false -Dnogui=true" \
  --build-arg QT_DOWNLOAD_URL=https://files.jacktrip.org/contrib/qt/qt-6.8.3-static-linux-amd64.tar.gz .
```

```bash
docker buildx build --target=artifact -f linux/Dockerfile.build --output type=local,dest=./ \
  --platform linux/arm64 --build-arg BUILD_CONTAINER=ubuntu:22.04 \
  --build-arg MESON_ARGS="-Ddefault_library=shared -Drtaudio=enabled -Drtaudio:jack=disabled -Drtaudio:default_library=static -Drtaudio:alsa=enabled -Drtaudio:pulse=enabled -Drtaudio:werror=false" .
```

```bash
docker buildx build --target=artifact -f linux/Dockerfile.build --output type=local,dest=./ \
  --platform linux/arm64 --build-arg BUILD_CONTAINER=ubuntu:20.04 \
  --build-arg MESON_ARGS="-Ddefault_library=static -Drtaudio=enabled -Drtaudio:jack=disabled -Drtaudio:default_library=static -Drtaudio:alsa=enabled -Drtaudio:pulse=disabled -Drtaudio:werror=false -Dnogui=true" \
  --build-arg QT_DOWNLOAD_URL=https://files.jacktrip.org/contrib/qt/qt-6.8.3-static-linux-arm64.tar.gz .
```

```bash
docker buildx build --target=artifact -f linux/Dockerfile.build --output type=local,dest=./ \
  --platform linux/arm/v7 --build-arg BUILD_CONTAINER=debian:buster \
  --build-arg USE_SYSTEM_LIBSAMPLERATE=1 \
  --build-arg MESON_ARGS="-Ddefault_library=static -Drtaudio=enabled -Drtaudio:jack=disabled -Drtaudio:default_library=static -Drtaudio:alsa=enabled -Drtaudio:pulse=disabled -Drtaudio:werror=false -Dnogui=true -Dcpp_link_args='-no-pie'" \
  --build-arg QT_DOWNLOAD_URL=https://files.jacktrip.org/contrib/qt/qt-5.15.13-static-linux-arm32.tar.gz .
```

--------------------------------

### Enable RtAudio Subproject in Meson

Source: https://jacktrip.github.io/jacktrip/Build/Meson_build

Navigates into the build directory and configures Meson to explicitly enable RtAudio as a subproject. This is used when RtAudio is not found on the system and should be downloaded and built by Meson.

```bash
cd builddir
meson configure -Drtaudio=enabled

```

--------------------------------

### Clone JackTrip Repository

Source: https://jacktrip.github.io/jacktrip/Build/Windows

Use this command to download the repository with all necessary submodules.

```bash
git clone --recurse-submodules https://github.com/jacktrip/jacktrip.git
```

--------------------------------

### Navigate to JackTrip Directory

Source: https://jacktrip.github.io/jacktrip/Build/Linux

After cloning, change your current directory to the newly cloned JackTrip repository.

```bash
$ cd jacktrip
```

--------------------------------

### Run Scan-Build on JackTrip

Source: https://jacktrip.github.io/jacktrip/DevTools/StaticAnalysis

Use this command to perform basic static analysis on the entire JackTrip codebase. Meson automatically generates a scan-build target.

```bash
ninja -C builddir scan-build
```

--------------------------------

### Manage Parallel JackTrip Versions

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Commands for cloning, building, and running multiple versions of JackTrip side-by-side.

```bash
$ git clone --recurse-submodules https://github.com/jacktrip/jacktrip.git jacktrip-1.x.x
```

```bash
$ cd jacktrip-1.x.x
$ ./build
```

```bash
$ cd builddir
$ ./jacktrip -v
```

```bash
$ ./jacktrip -C serveraddress
```

```bash
$ pwd
```

--------------------------------

### Run JackTrip with Custom JACK Server Name

Source: https://jacktrip.github.io/jacktrip/CustomJackServerName

Set the JACK_DEFAULT_SERVER environment variable to the custom name of your JACK server before running JackTrip. This ensures JackTrip connects to the correct JACK instance.

```bash
JACK_DEFAULT_SERVER=myfancyserver jacktrip ...
```

--------------------------------

### Clone JackTrip Repository

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Use this command to clone the JackTrip repository and its submodules. Ensure you use the `--recurse-submodules` flag to include all necessary submodules.

```bash
$ git clone --recurse-submodules https://github.com/jacktrip/jacktrip.git
```

--------------------------------

### Compile JackTrip

Source: https://jacktrip.github.io/jacktrip/Build/Linux

Compile the JackTrip software after configuring the build directory. This command should be run from the root of the JackTrip repository.

```bash
$ meson compile -C builddir
```

--------------------------------

### Run Clang-Tidy on a Single File

Source: https://jacktrip.github.io/jacktrip/DevTools/StaticAnalysis

Analyze a specific C++ file using clang-tidy. Navigate to the 'src' directory and use the run-clang-tidy.py script, specifying the build directory and the file to analyze. The -j flag controls parallel instances.

```bash
cd src
run-clang-tidy.py -j 4 -p ../builddir singlefile.cpp
```

--------------------------------

### JackTrip version output

Source: https://jacktrip.github.io/jacktrip/Build/Mac

Expected output after running the version check command.

```text
JackTrip VERSION: 1.xx
Copyright (c) 2008-2020 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University
```

--------------------------------

### Pre-commit Configuration for clang-format

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

This YAML configuration sets up the pre-commit hook for clang-format. It specifies the repository, revision, hook ID, and applies it to C++ files in the src directory, excluding specific header files.

```yaml
fail_fast: false
repos:
  - repo: https://github.com/ssciwr/clang-format-hook
    rev: v13.0.1
    hooks:
    - id: clang-format
      files: ^src/
      types_or: [c++]
      exclude: '^src/.+dsp\.h'
```

--------------------------------

### Empty Header (EMPTY)

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Describes the scenario where no header is used, and the UDP payload contains only raw audio data.

```APIDOC
## Empty header (`EMPTY`)

No header; the UDP payload is raw audio data only.
```

--------------------------------

### Format Specific Files with clang-format

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Use this command to format individual C++ source and header files. Remove the -i flag to only check formatting without applying changes.

```bash
clang-format -i class.cpp class.h
```

--------------------------------

### Network Transports Overview

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Provides a high-level overview of the different network transport mechanisms used by JackTrip.

```APIDOC
## Transports at a glance
  * **UDP (audio)** : real-time audio is sent as UDP datagrams containing `PacketHeader` + raw audio payload.
  * **UDP (control)** : a small fixed-size “stop” datagram is used to signal shutdown.
  * **TCP (hub/ping-server handshake)** : a short-lived TCP connection is used to exchange ephemeral UDP port information (and optionally do TLS + credentials). The client sends 4 bytes representing the port number it is binding to, and the server responds by sending 4 bytes representing its own port number.
  * **WebRTC data channel (audio)** : JackTrip hub server’s WebRTC path uses a WebRTC data channel to carry the same packet format (header + planar audio payload) as the UDP stream. Signaling uses an encrypted WebSocket (`wss://`) on the hub TCP port; plain `ws://` is not accepted. The same interleaving conversion applies. See `WebRtcDataProtocol.cpp`.
  * **WebTransport / QUIC datagrams (audio)** : the hub server’s WebTransport path uses HTTP/3 over QUIC (via msquic) with unreliable QUIC datagrams (RFC 9221) to carry the same packet format as the UDP stream. The WebTransport session is established with an HTTP/3 CONNECT request before audio flows. See `src/webtransport/` and `src/http3/`.
```

--------------------------------

### UDP Redundancy

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Explains how JackTrip uses redundant UDP packets to mitigate audio artifacts caused by packet loss.

```APIDOC
## UDP redundancy (optional)

JackTrip can send redundant audio packets to reduce audible artifacts from packet loss.

### Framing

With redundancy factor (R), each UDP datagram contains **R full packets** concatenated:
  * The newest packet is first (`UDP[n]`), followed by older packets (`UDP[n-1]`, …).
  * Total UDP payload length becomes `R * full_packet_size`.

The sender implements this by shifting a buffer and prepending the newest full packet each period.
See `UdpDataProtocol::sendPacketRedundancy()` and the explanatory comment block in `src/UdpDataProtocol.cpp`.

### Receiver behavior

Upon receiving a redundant datagram, the receiver:
  * Reads the first packet’s `SeqNumber`.
  * If it is not the next expected sequence, scans forward through the concatenated packets looking for the expected next one.
  * May “revive” and deliver multiple packets from the redundant datagram in order.
  * Treats large negative or implausibly large sequence jumps as **out-of-order** and ignores them.

See `UdpDataProtocol::receivePacketRedundancy()` in `src/UdpDataProtocol.cpp`.
```

--------------------------------

### UDP Audio Payload Structure

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Details the size calculation, channel ordering, and sample encoding for UDP audio payloads.

```APIDOC
## UDP audio payload

### Size

For a single full packet (no redundancy), the UDP payload length is:

`headerBytes + (N * C * bytesPerSample)`

Where:
  * (N) is `BufferSize` (samples per channel)
  * (C) is the number of channels present in the payload
  * `bytesPerSample` is `BitResolution / 8`

### Channel/sample ordering (planar / non-interleaved)

On the wire, the payload is **planar** (non-interleaved) by channel:
  * First (N) samples for channel 0
  * Then (N) samples for channel 1
  * …

This is explicit in `UdpDataProtocol` which converts between:
  * **Internal** : interleaved layout (`[n][c]`)
  * **Network** : planar layout (`[c][n]`)

For **mono** ((C = 1)) there is no difference between planar and interleaved layouts, so no conversion is needed. Multi-channel conversion also applies on the WebRTC data channel path (see `WebRtcDataProtocol.cpp`) and the WebTransport path.

See `UdpDataProtocol::sendPacketRedundancy()` and `UdpDataProtocol::receivePacketRedundancy()` in `src/UdpDataProtocol.cpp`.

### Sample encoding (bit resolution)

JackTrip processes audio internally as `float` (`sample_t`), but the network payload uses the selected bit resolution via `AudioInterface::fromSampleToBitConversion()` / `fromBitToSampleConversion()`.

Behavior by bit resolution (`AudioInterface::audioBitResolutionT`):
  * **8-bit (`BIT8`)**: signed 8-bit integer, scaled from float in ([-1, 1]).
  * **16-bit (`BIT16`)**: signed 16-bit integer, written **little-endian**.
  * **24-bit (`BIT24`)**: a **non-standard 3-byte format** : a 16-bit signed integer plus an 8-bit unsigned “remainder” byte.
  * **32-bit (`BIT32`)**: raw 32-bit float bytes (`memcpy` of `float`), which implicitly assumes IEEE-754 and matching endianness.

See `src/AudioInterface.cpp`.
```

--------------------------------

### Apply Clang-Tidy Fixes to a Single File

Source: https://jacktrip.github.io/jacktrip/DevTools/StaticAnalysis

Automatically apply fixes suggested by clang-tidy to a specific C++ file. Use the -fix flag along with the parallel job count and build directory. Review applied fixes carefully.

```bash
run-clang-tidy.py -fix -j 4 -p ../builddir singlefile.cpp
```

--------------------------------

### UDP Audio Datagrams

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Details the structure and framing of UDP datagrams used for real-time audio transmission in JackTrip.

```APIDOC
## UDP Audio Datagrams

### High-level framing
Each UDP datagram carries one of:
  * **Audio datagram** : one or more **full packets** (header + audio payload). When redundancy is disabled, there is exactly one full packet per UDP datagram. When redundancy is enabled, multiple full packets are concatenated into a single UDP datagram to provide forward error correction (FEC) (see “UDP redundancy”).
  * **Stop/control datagram** : exactly 63 bytes of `0xFF` (see “UDP stop/control datagram”).

### Packet header types
The header is selected by `DataProtocol::packetHeaderTypeT`:
  * **DEFAULT** : `DefaultHeaderStruct` (the standard JackTrip header).
  * **JAMLINK** : `JamLinkHeaderStuct` (JamLink compatibility).
  * **EMPTY** : no header (payload only).

See `src/PacketHeader.h` and `src/PacketHeader.cpp`.

### Default header (`DEFAULT`)
On-wire layout is the in-memory `DefaultHeaderStruct` copied with `memcpy()` (no explicit endian conversions).
Fields (in order):
Field | Type | Meaning  
---|---|---
`TimeStamp` | `uint64_t` | Timestamp in microseconds since Unix epoch (see `PacketHeader::usecTime()`).  
`SeqNumber` | `uint16_t` | Sequence number; increments once per audio period and wraps at 16 bits.  
`BufferSize` | `uint16_t` | Audio period size (N) in **samples per channel**.  
`SamplingRate` | `uint8_t` | Encoded sample-rate enum value (`AudioInterface::samplingRateT`), **not** Hz.  
`BitResolution` | `uint8_t` | Bits per sample (8/16/24/32).
`NumIncomingChannelsFromNet` | `uint8_t` | Channel count expected from the peer “from network” direction (see notes below).  
`NumOutgoingChannelsToNet` | `uint8_t` | Channel count the sender is placing into the payload (see notes below).  

#### Important interoperability notes
  * **Endianness / ABI** : this header is serialized by raw `memcpy()` of a C struct. In practice this assumes:
  * both sides are using compatible ABI/layout for the struct, and
  * both sides are on the same endianness (typically **little-endian** on modern desktop platforms).
  * **Channel fields are asymmetric** : the implementation uses these fields to convey “incoming vs outgoing” channel counts, including a couple of sentinel behaviors:
  * `NumIncomingChannelsFromNet` is populated from local _audio interface output_ channel count.
  * `NumOutgoingChannelsToNet` may be set to `0` when in/out channel counts match, or to `0xFF` when there are zero audio interface input channels.

These behaviors come from `DefaultHeader::fillHeaderCommonFromAudio()` in `src/PacketHeader.cpp`.
```

--------------------------------

### Client PROTOCOL_DETECT Message

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

The initial message sent by the client to detect the protocol version and identify itself. This is part of the WebRTC signaling flow.

```json
{"type": "protocol_detect", "protocol": 2, "clientName": "…", "version": 1}

```

--------------------------------

### JamLink Header (JAMLINK)

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Details the obsolete JamLink header format, used for describing audio stream properties.

```APIDOC
## JamLink header (`JAMLINK`)

Please note that JamLink is an obsolete device.
JamLink uses a compact header:

### Fields

| Field       | Type     | Meaning                                                                    |
|-------------|----------|----------------------------------------------------------------------------|
| `Common`    | `uint16_t` | Bitfield describing mono/stereo, bit depth, sample rate, and samples-per-packet (JamLink “streamType”). |
| `SeqNumber` | `uint16_t` | Sequence number.                                                           |
| `TimeStamp` | `uint32_t` | Timestamp.                                                                 |

The current implementation primarily fills this for JamLink constraints (mono, 48kHz, 64-sample buffers). See `JamLinkHeader::fillHeaderCommonFromAudio()` in `src/PacketHeader.cpp`.
```

--------------------------------

### Bypass Git Hooks During Commit

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Use the --no-verify flag with git commit to skip the execution of pre-commit hooks, including clang-format. This is useful for temporary bypasses.

```bash
git commit -am "Commit all my stuff" --no-verify
```

--------------------------------

### Verify Health-check Endpoint Connectivity with curl

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

A plain curl command to verify TLS and HTTP connectivity to the health-check endpoint. Ensure to replace <host> and <port> with the correct values.

```bash
curl -k https://<host>:<port>/ping

```

--------------------------------

### Disable clang-format for Code Sections

Source: https://jacktrip.github.io/jacktrip/DevTools/Formatting

Enclose code blocks that should not be formatted within // clang-format off and // clang-format on comments. This prevents clang-format from altering specific lines.

```c++
this = is.formatted;
// clang-format off
this+=   isnot     ;
// clang-format on
this = again;
```

--------------------------------

### UDP Stop/Control Datagram

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

Describes the specific UDP datagram used by JackTrip to signal a shutdown.

```APIDOC
## UDP stop/control datagram

JackTrip uses a special fixed-size UDP datagram to signal shutdown:
  * **Length** : 63 bytes
  * **Contents** : every byte is `0xFF`

The receiver checks for this exact pattern and treats it as “Peer Stopped”.
See `UdpDataProtocol::processControlPacket()` and the shutdown path in `UdpDataProtocol::run()` in `src/UdpDataProtocol.cpp`.
```

--------------------------------

### Signaling Message Framing

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

All signaling messages are JSON objects framed with a 4-byte big-endian length prefix over the TCP socket. This ensures proper message delimitation.

```plaintext
[4-byte length (BE)] [JSON payload]

```

--------------------------------

### Health-check Endpoint Response

Source: https://jacktrip.github.io/jacktrip/Documentation/NetworkProtocol

A successful health-check response from the hub server. The connection is closed immediately after this response.

```http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 15
Connection: close

{"status":"OK"}


```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.