Media over QUIC (MoQ) is a protocol suite for low-latency delivery of live media and other time-sensitive data over QUIC.
libquicr implements Media over QUIC Transport (MOQT) with a C++ API for client and server endpoints that publish, subscribe, fetch, and relay. It currently targets draft-ietf-moq-transport-18.
- ⚡ Low-latency media — prioritized streams, datagrams, and TTL-based expiry.
- 🚀 Flexible transport options — native QUIC and WebTransport over HTTP/3.
- 🧩 Handler-driven architecture — build publish, subscribe, fetch, and relay workflows.
- 🔌 C/C++ API — native interfaces for direct use and cross-language integration.
- 🌐 Cross-platform — desktop, mobile, and embedded targets.
- 🛡️ Modern foundation — C++20 with TLS 1.3 transport.
- 🛠️ Practical tooling — interactive MOQT client, capture and replay, examples, and metrics.
After installing the build requirements, configure and build the examples:
cmake -B build -DQUICR_BUILD_EXAMPLES=ON
cmake --build buildRun the subscriber and publisher in separate terminals:
./build/examples/simple_subscribe/simple_subscribe
./build/examples/simple_publish/simple_publishThe examples require an accessible MOQT relay. Both prompt for its URI, a track namespace, and a track name; use the same values to publish and receive messages.
Consume an installed libquicr package through its exported target:
find_package(quicr CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE quicr::quicr)For an installation outside standard search paths, add its prefix to CMAKE_PREFIX_PATH when
configuring the consuming project. When the C bridge is installed, its exported target is
quicr::bridge.
Installing or adding libquicr from source
Build and install
cmake -S . -B build -DQUICR_INSTALL=ON
cmake --build build
cmake --install build --prefix "/path/to/install"The local prefix avoids administrator permissions. Omit --prefix to use the configured
CMAKE_INSTALL_PREFIX.
FetchContent
include(FetchContent)
FetchContent_Declare(
libquicr
GIT_REPOSITORY https://github.com/Quicr/libquicr.git
GIT_TAG 980a887a6ca64b5a422102a0507a0a93fa0df081
)
FetchContent_MakeAvailable(libquicr)Vendored source
add_subdirectory(path/to/libquicr)CPMAddPackage("gh:Quicr/libquicr#980a887a6ca64b5a422102a0507a0a93fa0df081")All source integration methods expose the quicr::quicr target shown above.
See the API guide for session and handler usage.
- Support
- Requirements
- Dependencies
- CMake options
- Makefile Shortcuts
- Command-line tools
- TLS provider configuration
- C Bridge
- Documentation
Status: ✅ Supported · 🧪 Manually tested (not in CI) · 🚧 Planned
| Option | Status | Selection | Notes |
|---|---|---|---|
| Native QUIC | ✅ Supported | moq:// or moqt:// |
|
| WebTransport over HTTP/3 | ✅ Supported | https:// |
|
| QMUX | 🚧 Planned | To be determined | Tracking issue #1044 |
| Platform | Build | Automated tests |
|---|---|---|
| Linux | ✅ Supported | ✅ Tested in CI |
| macOS | ✅ Supported | ✅ Tested in CI |
| Windows | ✅ Supported | ✅ Tested in CI |
| Android | ✅ Supported | Not in CI |
| iOS | 🧪 Manually tested | Not in CI |
| ESP32 | 🧪 Manually tested | Not in CI |
| API | Status | Notes |
|---|---|---|
| C++ API | ✅ Supported | Requires C++20 |
| C bridge | ✅ Supported | Client-only API |
| C API | 🚧 Planned | Replacement tracked in PR #1046 |
TLS backend selection applies to both native QUIC and WebTransport.
| Backend | Status | Known versions | Notes |
|---|---|---|---|
| picotls-minicrypto | ✅ Supported | Bundled | Fallback when no external provider is selected |
| OpenSSL-compatible providers | ✅ Supported | OpenSSL 3 is tested through Ubuntu and Homebrew packages; see BoringSSL limitations | |
| Mbed TLS | ✅ Supported | Enable with WITH_MBEDTLS=ON |
See the TLS provider guide for setup details and backend-specific limitations.
- CMake 3.16 or newer
- Git for dependency fetching
- Supported C++20 toolchains:
- GCC 12 or newer
- Clang 17 or newer
- Apple Clang 17 or newer
- or MSVC
- CMake 3.26 or newer and Clang-Tidy 15 or newer when configuring with
-DQUICR_LINT=ON
Note
Ubuntu 22.04 defaults to GCC 11. Install GCC 12 or newer and select it before configuring, for
example with CC=/usr/bin/gcc-12 and CXX=/usr/bin/g++-12.
Most of libquicr's C/C++ dependencies are fetched at CMake configure time by
CPM.cmake. There are no submodules to initialise.
External TLS backends are optional and remain under the consuming application's control.
cmake/CPM.cmake first downloads a pinned CPM release and checks it against a recorded SHA-256,
and each fetched dependency is then pinned to its own tag or commit:
| Dependency | Purpose | Declared in |
|---|---|---|
| picoquic | QUIC transport | cmake/QuicrDependencies.cmake |
| picotls | TLS 1.3 implementation | cmake/QuicrDependencies.cmake |
| timeq | Timed task scheduling | cmake/QuicrDependencies.cmake |
| fmt | Formatting fallback when std::format is unavailable |
cmake/QuicrFormat.cmake |
Optional tests, benchmarks, tools, and examples may fetch additional dependencies. See their documentation for target-specific build and dependency notes.
See the dependency guide for source caching and third-party licence notices.
libquicr provides CMake options for selecting build targets and optional features. For example, configure a build with examples enabled:
cmake -B build -DQUICR_BUILD_EXAMPLES=ON
| Option | Default | Purpose |
|---|---|---|
QUICR_INSTALL |
Standalone: ON; subproject: OFF |
Enable install and CMake package rules |
QUICR_BUILD_C_BRIDGE |
Standalone: ON; subproject: OFF |
Build the C bridge |
QUICR_BUILD_EXAMPLES |
OFF |
Build examples |
QUICR_BUILD_TOOLS |
OFF |
Build testing and debugging tools |
QUICR_BUILD_TESTS |
Standalone: ON; subproject: OFF |
Build the test suite |
QUICR_BUILD_BENCHMARKS |
Standalone: ON; subproject: OFF |
Build benchmarks |
QUICR_BUILD_FUZZ |
OFF |
Build Clang fuzzing targets |
QUICR_BUILD_SHARED |
OFF |
Build libquicr as a shared library |
QUICR_ENABLE_SANITIZERS |
OFF |
Enable AddressSanitizer and UndefinedBehaviorSanitizer |
QUICR_GENERATE_THIRD_PARTY_LICENSES |
OFF |
Add the third-party-licenses target |
QUICR_LINT |
OFF |
Run Clang-Tidy while compiling a standalone build |
WITH_MBEDTLS |
OFF |
Select the picotls Mbed TLS backend |
WITH_BROTLI |
OFF |
Enable picotls Brotli TLS certificate compression |
BUILD_TESTING defaults to ON for standalone builds and gates tests, benchmarks, and fuzzers.
When both the C bridge and examples are enabled, the bridge examples are built automatically. The
WITH_* options configure picotls rather than libquicr itself.
| Command | Action |
|---|---|
make |
Build libquicr, tests, benchmarks, examples, tools, and the C bridge in Debug mode |
make test |
Build and run the test suite |
make cclean |
Remove the build directory |
make fuzz |
Build and run the control-message fuzzer |
make licenses |
Generate build/THIRD_PARTY_LICENSES.txt |
make doc |
Generate the Doxygen reference and API guide; requires Doxygen, Pandoc, Mermaid CLI, and mermaid-filter |
make package-lock |
Regenerate package-lock.cmake |
The tools directory contains utilities for testing and debugging
MoQ networking. It is separate from examples, which contains small programs
focused on demonstrating individual APIs.
The available tools are:
moq-cli, an interactive client for publishing, subscribing, fetching, and protocol test scenarios.moq_capture, a client for recording track objects and replaying recorded data.
Configure and build the tools with:
cmake -B build -DQUICR_BUILD_TOOLS=ON
cmake --build buildSee the tools documentation for usage.
An external TLS provider is optional: libquicr can use picotls-minicrypto on its own, or applications
can provide an OpenSSL-compatible provider or Mbed TLS when desired. OpenSSL-compatible providers
are used automatically when found; WITH_MBEDTLS=ON selects Mbed TLS instead. Use a fresh build
directory when switching providers so cached discovery results cannot select a previous
installation.
Warning
Use a currently supported provider release and apply security updates promptly. Do not mix headers and libraries from different installations or weaken TLS 1.3, certificate validation, or secure-random configuration.
Warning
The current picoquic minicrypto integration does not verify peer certificates, so clients do not authenticate servers in this mode. Use it only where peer authentication is not required.
See the TLS provider guide for provider selection and configuration.
The optional C bridge provides a client-only C wrapper around the C++ library. Enable it with
QUICR_BUILD_C_BRIDGE=ON; also enable QUICR_BUILD_EXAMPLES to build its examples. See the
C bridge documentation for API details.
Browse the pre-built documentation, or run
make doc from the repository root to generate the Doxygen API reference and
render the API guide locally. The output is written to docs/html/; open
docs/html/index.html in a browser to view it.
brew install doxygen node pandoc
npm install --global @mermaid-js/mermaid-cli
npm install --global mermaid-filterNote
mermaid-filter allows Pandoc to
render the Mermaid diagrams used by the API guide.