Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
78 commits
Select commit Hold shift + click to select a range
b99f856
testsfail: blow up on mac
lws-team Apr 7, 2026
de43fe2
core-net: Fix ISO C23 errors with strchr()
purofle Apr 8, 2026
c7ed609
Confirming path revert for ipv6 suffix
lws-team Apr 11, 2026
d642ddc
dnssec-monitor: support environmentally restrictive storage fallbacks
lws-team Apr 11, 2026
d65fd9e
dnssec-tls-selection
lws-team Apr 11, 2026
b8bdabc
oauth: stop assembling all cookies in place
lws-team Apr 11, 2026
5c6bbf8
h2: cookie parsing
lws-team Apr 11, 2026
bbf5578
tls: x509: generic LWS_TLS_CERT_INFO_DER_SPKI
lws-team Apr 12, 2026
f7754ad
auth-dnssec: support sring subst in zonefile processing
lws-team Apr 12, 2026
fa11f6c
dnssec-monitor: use verification port to enable tls
lws-team Apr 12, 2026
4e888f4
spawn:pty
lws-team Apr 12, 2026
a2482ee
Refresh of spawn-pty
lws-team Apr 12, 2026
a14e5f2
starttls
lws-team Apr 12, 2026
5d18b70
whois
lws-team Apr 12, 2026
4e6562a
priv2
lws-team Apr 13, 2026
0963bd9
whois-parsing-hardening
lws-team Apr 13, 2026
e7b0087
fixes
lws-team Apr 13, 2026
fdf5d95
oauth: auto refresh at the target client
lws-team Apr 13, 2026
7d04c80
CID 909251: CHECKED_RETURN
lws-team Apr 13, 2026
2dc42cd
CID 909250: CHECKED_RETURN
lws-team Apr 13, 2026
006e5c1
CID 909249: FORWARD_NULL
lws-team Apr 13, 2026
e34f0f9
CID 909248: DEADCODE
lws-team Apr 13, 2026
7e7f961
dnssec-monitor: adjust permissions
lws-team Apr 13, 2026
51dd8fd
Coverity: dismissed to silenced
lws-team Apr 13, 2026
456de8f
webrtc: auto-enable drm
lws-team Apr 13, 2026
1174720
webrtc: improve robustness
lws-team Apr 13, 2026
ceaff12
udp-shaper
lws-team Apr 13, 2026
9e5f0e1
dnssec-monitor: add live DNS status
lws-team Apr 14, 2026
46ec257
inet_pton: use lws api instead
lws-team Apr 15, 2026
e93fe35
windows: api-test-secure-streams-cleanup
lws-team Apr 15, 2026
f75d5a4
oauth: grant_level >=2 = admin for grant
lws-team Apr 15, 2026
d658ba6
h2: mqtt: handle all MORE_SERVICE variants
lws-team Apr 16, 2026
6747a0c
lws_login: inform dest of grant level
lws-team Apr 16, 2026
cf33224
h2: post: fixes
lws-team Apr 17, 2026
4b828d4
h1 hack
lws-team Apr 17, 2026
d0fe25b
oauth: robustness
lws-team Apr 18, 2026
d923dec
webrtc-vpn
lws-team Apr 19, 2026
7ce6981
plugins: docs update
lws-team Apr 20, 2026
429d8a8
ops-netlink: define IFA_FLAGS for older kernels
ThomasDevoogdt Apr 20, 2026
daf09ce
unix-sockets: drop the <linux/ipv6.h> on linux < 3.12.0
ThomasDevoogdt Apr 20, 2026
4fd5706
mixer: shift over to gstreamer
lws-team Apr 20, 2026
b422ba4
mqtt
lws-team Apr 22, 2026
46ad091
Refresh of mixer-0
lws-team Apr 23, 2026
b739fd1
dnssec-monitor-tls
lws-team Apr 23, 2026
65025c1
txpacer: 32-bit arithmetic
lws-team Apr 23, 2026
0a0dee8
tls: csr with gnutls mbedtls and schannel
lws-team Apr 23, 2026
27ba665
CID 909368: TOCTOU
lws-team Apr 23, 2026
133be89
CID 909366: CHECKED_RETURN
lws-team Apr 23, 2026
c05c7b1
CID 909365: NULL_RETURNS
lws-team Apr 23, 2026
056f248
CID 909364: CHECKED_RETURN
lws-team Apr 23, 2026
1ca0d7e
CID 909363: MISSING_LOCK
lws-team Apr 23, 2026
1545997
CID 90936: OVERRUN
lws-team Apr 23, 2026
15cd2ba
CID 909361: NULL_RETURNS
lws-team Apr 23, 2026
57f914b
CID 909359: INTEGER_OVERFLOW
lws-team Apr 23, 2026
111d491
CID 909356: TAINTED_SCALAR
lws-team Apr 23, 2026
bdb8ec3
CID 909354: INTEGER_OVERFLOW
lws-team Apr 23, 2026
3ce9ac7
CID 909353: CHECKED_RETURN
lws-team Apr 23, 2026
ff94d9d
CID 909352: FORWARD_NULL
lws-team Apr 23, 2026
296e472
sul_conect_timeout: ensure cancelled before wsi delete
lws-team Apr 23, 2026
745ff32
ctest: tests needing tls should depend on it
lws-team Apr 24, 2026
e03409f
tls: eliminate MORE_SERVICE
lws-team Apr 24, 2026
45a6450
http: extend timeout if data dribbling in
lws-team Apr 24, 2026
cf8d3a6
async dns: improve fallback
lws-team Apr 24, 2026
2863fee
CID 909372: DEADCODE
lws-team Apr 24, 2026
5b59c38
CID 909371: FORWARD_NULL
lws-team Apr 24, 2026
2b95c9d
CID 909359: INTEGER_OVERFLOW
lws-team Apr 24, 2026
334d929
CID 909355: TAINTED_SCALAR
lws-team Apr 24, 2026
cff2a9a
http-improve-to-extend-logging
lws-team Apr 24, 2026
7b475cb
CID 909359: INTEGER_OVERFLOW
lws-team Apr 24, 2026
3d9689a
CID 909355: TAINTED_SCALAR
lws-team Apr 24, 2026
d931993
wifi: select higher average rssi
lws-team Apr 24, 2026
1580eb1
dnssec-monitor: editor substs
lws-team Apr 25, 2026
7d80570
mount: exact-match
lws-team Apr 26, 2026
57ecf05
mixer: use separate LWS_WITH_WEBRTC_MIXER
lws-team Apr 28, 2026
399a45e
dnssec-monitor: tls
lws-team Apr 28, 2026
e0cfe16
esp32: stop power-saving
lws-team Apr 28, 2026
940d6c8
bearssl
lws-team Apr 26, 2026
b8f727e
Merge branch 'main' into fix-build-glibc
purofle Apr 28, 2026
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
8 changes: 6 additions & 2 deletions .sai.json
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,10 @@
"cmake": "-DLWS_WITH_GNUTLS=1",
"platforms": "none, rocky9/aarch64-a72a55-rk3588/gcc"
},
"bearssl": {
"cmake": "-DLWS_WITH_BEARSSL=1 -DLWS_BEARSSL_INCLUDE_DIRS=/opt/BearSSL/inc -DLWS_BEARSSL_LIBRARIES=/opt/BearSSL/build/libbearssl.so",
"platforms": "none, rocky9/aarch64-a72a55-rk3588/gcc"
},
"default-examples-awslc": {
"cmake": "-DLWS_WITH_AWSLC=1 -DLWS_OPENSSL_INCLUDE_DIRS=\"/usr/aws-lc/include\" -DLWS_OPENSSL_LIBRARIES=\"/usr/aws-lc/lib64/libssl.so;/usr/aws-lc/lib64/libcrypto.so\" -DLWS_WITH_MINIMAL_EXAMPLES=1",
"platforms": "none, rocky9/aarch64-a72a55-rk3588/gcc"
Expand Down Expand Up @@ -260,15 +264,15 @@
"coverity": {
"cmake": "-DLWS_WITHOUT_EXTENSIONS=0 -DLWS_WITH_CGI=1 -DLWS_IPV6=1 -DLWS_WITH_HTTP_PROXY=1 -DLWS_WITH_RANGES=1 -DLWS_WITH_THREADPOOL=1 -DLWS_WITH_CBOR=1 -DLWS_WITH_JOSE=1 -DLWS_WITH_COSE=1 -DLWS_WITH_SYS_DHCP_CLIENT=1 -DLWS_WITH_FTS=1 -DLWS_WITH_STRUCT_SQLITE3=1 -DLWS_ROLE_DBUS=1 -DLWS_WITH_SYS_ASYNC_DNS=1 -DLWS_WITH_SYS_ASYNC_DNS_DNSSEC=1 -DLWS_WITH_WEBRTC=1 -DLWS_WITH_DHT=1 -DLWS_WITH_ASYNC_QUEUE=1 -DLWS_WITH_SYS_FAULT_INJECTION=1 -DLWS_WITH_TLS_JIT_TRUST=1 -DLWS_ROLE_MQTT=1 -DLWS_ROLE_RAW_PROXY=1 -DLWS_WITH_EVENT_LIBS=1 -DLWS_WITH_LIBUV=1 -DLWS_WITH_STRUCT_JSON=1 -DLWS_WITH_LWS_DSH=1 -DLWS_WITH_SECURE_STREAMS_PROXY_API=1 -DLWS_WITH_AUTHORITATIVE_DNS=1 -DLWS_WITH_DHT=1 -DLWS_WITH_DHT_BACKEND=1 -DLWS_WITH_PLUGINS=1",
"platforms": "none, coverity/x86_64/gcc",
"cpack": "export STAMP=`git log -1 --pretty=format:%h` && rm -f libwebsockets.tgz && tar czvf libwebsockets.tgz cov-int && script -q -c \"cat /etc/coverity/secrets.sh | lws-minimal-http-client-post-form https://scan.coverity.com:443/builds?project=warmcat%2Flibwebsockets --form file=@libwebsockets.tgz --form version=${STAMP} --form 'description=lws qa'\" /dev/null",
"cpack": "export STAMP=`git log -1 --pretty=format:%h` && rm -f libwebsockets.tgz && tar czvf libwebsockets.tgz cov-int && script -e -q -c \"cat /etc/coverity/secrets.sh | lws-minimal-http-client-post-form --h1 https://scan.coverity.com:443/builds?project=warmcat%2Flibwebsockets --form file=@libwebsockets.tgz --form version=${STAMP} --form 'description=lws qa'\" /dev/null",
"branches": "coverity"
}
# ,
# awkward, we also want to test mbedtls, but coverity blocks on SSL build needing manual intervention
# "coverity-mbedtls": {
# "cmake": "-DLWS_WITH_MBEDTLS=1 -DLWS_WITHOUT_EXTENSIONS=0 -DLWS_WITH_CGI=1 -DLWS_IPV6=1 -DLWS_WITH_HTTP_PROXY=1 -DLWS_WITH_RANGES=1 -DLWS_WITH_THREADPOOL=1 -DLWS_WITH_CBOR=1 -DLWS_WITH_JOSE=1 -DLWS_WITH_COSE=1 -DLWS_WITH_SYS_DHCP_CLIENT=1 -DLWS_WITH_FTS=1 -DLWS_WITH_STRUCT_SQLITE3=1 -DLWS_ROLE_DBUS=1 -DLWS_WITH_SYS_ASYNC_DNS=1 -DLWS_WITH_SYS_ASYNC_DNS_DNSSEC=1 -DLWS_WITH_WEBRTC=1 -DLWS_WITH_DHT=1 -DLWS_WITH_ASYNC_QUEUE=1 -DLWS_WITH_SYS_FAULT_INJECTION=1 -DLWS_WITH_TLS_JIT_TRUST=1 -DLWS_ROLE_MQTT=1 -DLWS_ROLE_RAW_PROXY=1 -DLWS_WITH_EVENT_LIBS=1 -DLWS_WITH_LIBUV=1 -DLWS_WITH_STRUCT_JSON=1 -DLWS_WITH_LWS_DSH=1 -DLWS_WITH_SECURE_STREAMS_PROXY_API=1",
# "platforms": "none, coverity/x86_64/gcc",
# "cpack": "export STAMP=`git log -1 --pretty=format:%h` && rm -f libwebsockets.tgz && tar czvf libwebsockets.tgz cov-int && script -q -c \"cat /etc/coverity/secrets.sh | lws-minimal-http-client-post-form https://scan.coverity.com:443/builds?project=warmcat%2Flibwebsockets --form file=@libwebsockets.tgz --form version=${STAMP} --form 'description=lws qa'\" /dev/null",
# "cpack": "export STAMP=`git log -1 --pretty=format:%h` && rm -f libwebsockets.tgz && tar czvf libwebsockets.tgz cov-int && script -e -q -c \"cat /etc/coverity/secrets.sh | lws-minimal-http-client-post-form --h1 https://scan.coverity.com:443/builds?project=warmcat%2Flibwebsockets --form file=@libwebsockets.tgz --form version=${STAMP} --form 'description=lws qa'\" /dev/null",
# "branches": "coverity"
# }

Expand Down
17 changes: 13 additions & 4 deletions CMakeLists-implied-options.txt
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ if(IOS)
set(LWS_DETECTED_PLAT_IOS 1)
endif()

if (LWS_WITH_SCHANNEL OR LWS_WITH_GNUTLS OR LWS_WITH_MBEDTLS)
if (LWS_WITH_SCHANNEL OR LWS_WITH_GNUTLS OR LWS_WITH_MBEDTLS OR LWS_WITH_BEARSSL)
set(LWS_WITH_SSL 1)
endif()

Expand Down Expand Up @@ -130,6 +130,7 @@ if (LWS_WITH_SELFDNS)
set(LWS_WITH_SYS_ASYNC_DNS 1)
set(LWS_WITH_SYS_ASYNC_DNS_DNSSEC 1)
set(LWS_WITH_AUTH_SERVER 1)
set(LWS_WITH_SYS_WHOIS 1)
endif()

if (LWS_WITH_AUTH_SERVER)
Expand Down Expand Up @@ -169,12 +170,20 @@ if (LWS_WITH_TRANSPORT_SEQUENCER)
set(LWS_WITH_LWS_DSH 1)
endif()

if (LWS_WITH_WEBRTC_MIXER)
set(LWS_WITH_WEBRTC 1)
set(LWS_WITH_ALSA 1 CACHE BOOL "Enable alsa audio example" FORCE)
set(LWS_WITH_OPUS 1 CACHE BOOL "Enable opus audio codec" FORCE)
set(LWS_WITH_GSTREAMER 1 CACHE BOOL "Enable gstreamer" FORCE)
endif()

if (LWS_WITH_WEBRTC)
set(LWS_WITH_UDP 1)
set(LWS_WITH_DTLS 1)
set(LWS_WITH_ALSA 1 CACHE BOOL "Enable alsa audio example" FORCE)
set(LWS_WITH_OPUS 1 CACHE BOOL "Enable opus audio codec" FORCE)
set(LWS_WITH_PLUGINS 1 CACHE BOOL "Enable plugins" FORCE)
set(LWS_WITH_V4L2 1)
set(LWS_WITH_LIBV4L2 1)
set(LWS_WITH_DRM 1)
set(LWS_WITH_GENCRYPTO 1)
set(LWS_WITH_JOSE 1)
set(LWS_WITH_NETWORK 1)
Expand Down Expand Up @@ -474,7 +483,7 @@ if (LWS_SSL_SERVER_WITH_ECDH_CERT)
endif()

# LWS_OPENSSL_SUPPORT deprecated... use LWS_WITH_TLS
if (LWS_WITH_SSL OR LWS_WITH_MBEDTLS)
if (LWS_WITH_SSL OR LWS_WITH_MBEDTLS OR LWS_WITH_BEARSSL)
set(LWS_OPENSSL_SUPPORT 1)
set(LWS_WITH_TLS 1)
endif()
Expand Down
4 changes: 4 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,7 @@ option(LWS_WITH_SYS_ASYNC_DNS "Nonblocking internal IPv4 + IPv6 DNS resolver" OF
option(LWS_WITH_SYS_ASYNC_DNS_DNSSEC "Include DNSSEC parsing/validation in async-dns (requires crypto)" OFF)
option(LWS_WITH_AUTHORITATIVE_DNS "Authoritative DNS zone signer / server" OFF)
option(LWS_WITH_SYS_NTPCLIENT "Build in tiny ntpclient good for tls date validation and run via lws_system" OFF)
option(LWS_WITH_SYS_WHOIS "Build in tiny recursive whois client run via lws_system" OFF)
option(LWS_WITH_SYS_DHCP_CLIENT "Build in tiny DHCP client" OFF)
option(LWS_WITH_HTTP_BASIC_AUTH "Support Basic Auth" ON)
option(LWS_WITH_HTTP_DIGEST_AUTH "Support Digest Auth (caution deprecated crypto)" ON)
Expand All @@ -193,6 +194,7 @@ option(LWS_WITH_GZINFLATE "Enable internal minimal gzip inflator" ON)
option(LWS_WITH_JPEG "Enable stateful JPEG stream decoder" ON)
option(LWS_WITH_DLO "Enable Display List Objects" ON)
option(LWS_WITH_WEBRTC "Enable WebRTC" OFF)
option(LWS_WITH_WEBRTC_MIXER "Enable WebRTC mixer (gstreamer)" OFF)
option(LWS_WITH_TRANSCODE "Enable video transcoding support (requires ffmpeg)" OFF)
option(LWS_WITH_V4L2 "Enable V4L2 support (Linux only)" OFF)
option(LWS_WITH_LIBV4L2 "Link against libv4l2 if available" OFF)
Expand Down Expand Up @@ -231,6 +233,8 @@ option(LWS_CTEST_INTERNET_AVAILABLE "CTest will performs tests that need the Int
#
option(LWS_WITH_SSL "Include SSL support (defaults to OpenSSL or similar, mbedTLS if LWS_WITH_MBEDTLS is set)" ON)
option(LWS_WITH_MBEDTLS "Use mbedTLS (>=2.0) replacement for OpenSSL. When setting this, you also may need to specify LWS_MBEDTLS_LIBRARIES and LWS_MBEDTLS_INCLUDE_DIRS" OFF)
option(LWS_WITH_BEARSSL "Use BearSSL replacement for OpenSSL. When setting this, you also may need to specify LWS_BEARSSL_LIBRARIES and LWS_BEARSSL_INCLUDE_DIRS" OFF)
set(LWS_BEARSSL_PROFILE "full" CACHE STRING "BearSSL profile to use (e.g. full, client, minimal)")
option(LWS_WITH_SCHANNEL "Use Windows SChannel for SSL" OFF)
option(LWS_WITH_BORINGSSL "Use BoringSSL replacement for OpenSSL" OFF)
option(LWS_WITH_GNUTLS "Use GnuTLS for SSL" OFF)
Expand Down
10 changes: 10 additions & 0 deletions READMEs/README.build-windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,16 @@ additional CMake options on lws:
-DLWS_WITH_MBEDTLS=TRUE
```

### Alternative: BearSSL (or OpenSSL/MbedTLS, see above)

BearSSL is a highly optimized, minimalistic alternative to OpenSSL and MbedTLS. It is easily cross-compiled or built on Windows. Note that BearSSL currently does not support DTLS. To use it, simply provide the include and library paths:

```
-DLWS_WITH_BEARSSL=TRUE
-DLWS_BEARSSL_INCLUDE_DIRS=C:/path/to/bearssl/inc
-DLWS_BEARSSL_LIBRARIES=C:/path/to/bearssl/build/bearssl.lib
```

### Powershell

CMake wants it and the version that comes with windows is too old to have pwsh.exe.
Expand Down
20 changes: 14 additions & 6 deletions READMEs/README.build.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,8 @@ plugins and lwsws.
- If you are really restricted on memory, code size, or don't care about TLS
speed, mbedTLS is a good choice: `cmake .. -DLWS_WITH_MBEDTLS=1`

- If you want an extremely lightweight, highly optimized TLS library with a minimal memory footprint and fast execution speed, BearSSL is a strong alternative: `cmake .. -DLWS_WITH_BEARSSL=1`. Note that BearSSL currently does not support DTLS.

- If cpu and memory is not super restricted and you care about TLS speed,
OpenSSL or a directly compatible variant like Boring SSL is a good choice.

Expand All @@ -354,12 +356,18 @@ Lws supports both almost the same, so instead of taking my word for it you are
invited to try it both ways and see which the results (including, eg, binary
size and memory usage as well as speed) suggest you use.

NOTE: one major difference with mbedTLS is it does not load the system trust
store by default. That has advantages and disadvantages, but the disadvantage
is you must provide the CA cert to lws built against mbedTLS for it to be able
to validate it, ie, use -A with the test client. The minimal test clients
have the CA cert for warmcat.com and libwebsockets.org and use it if they see
they were built with mbedTLS.
NOTE: one major difference with mbedTLS and BearSSL is they do not natively load the OS trust
store by default in the same way OpenSSL does.

For mbedTLS, you must provide the CA cert to lws for it to be able
to validate it, ie, use `-A` with the test client.

For BearSSL, LWS implements a multi-cert PEM parser and fallback sequence to emulate OpenSSL's behavior:
1. It checks the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables for runtime overrides.
2. It falls back to probing standard OS locations (e.g. `/etc/ssl/certs/ca-certificates.crt`).
3. It defaults to the CMake-configured `LWS_OPENSSL_CLIENT_CERTS` if all else fails.

This allows BearSSL to validate most system certificates out of the box on Linux. The minimal test clients also automatically include the CA cert for warmcat.com if they see they were built with mbedTLS or BearSSL.

@section optee Building for OP-TEE

Expand Down
21 changes: 21 additions & 0 deletions READMEs/README.coding.md
Original file line number Diff line number Diff line change
Expand Up @@ -1335,3 +1335,24 @@ the user-selected text message and attempts to pull in `/error.css` for styling.
If this file exists, it can be used to style the error page. See
https://libwebsockets.org/git/badrepo for an example of what can be done (
and https://libwebsockets.org/error.css for the corresponding css).

@section spawn Process Spawning and PTY routing

libwebsockets provides a cross-platform API for spawning child processes and
redirecting their standard streams (stdin, stdout, stderr) into the lws event loop
as wsi handles: `lws_spawn_piped`.

It is controlled by `struct lws_spawn_piped_info`. By default, the streams are
redirected via standard anonymous pipes.

However, if you wish to run a process that expects a terminal (for example, to
preserve ANSI color codes or other TTY-specific behaviors), you can set
`info.pty_mode = 1` before calling `lws_spawn_piped()`.

- On POSIX systems, `pty_mode` will allocate a pseudoterminal via `posix_openpt()`
and securely fuse both the child's stdout and stderr into the single PTY
master file descriptor.
- On Windows (Windows 10+), `pty_mode` will attempt to dynamically instantiate a
`CreatePseudoConsole` (ConPTY) handle and route the standard pipes through it. If
the host system does not support ConPTY, it will gracefully fall back to pipes
or fail cleanly.
15 changes: 15 additions & 0 deletions READMEs/README.lwsws.md
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,21 @@ a mount.
After successful authentication, `WSI_TOKEN_HTTP_AUTHORIZATION` contains the
authenticated username.

8) You can also control the exact path matching and redirect behavior per-mount.

```json
{
"mountpoint": "/",
"origin": ">https://warmcat.com",
"exact-match": "1",
"append-path": "1"
}
```

- `"exact-match": "1"` forces the mount to only match if the request URL is exactly the `mountpoint` (no directory prefix matching).
- `"append-path": "1"` can be used with HTTP/HTTPS redirects (`>http://` or `>https://`). By default, redirects strictly redirect to the `origin` without appending the trailing path of the URL. Setting this flag will append the remainder of the request URL to the redirect destination.
- `"no-ws-upgrades": "1"` instructs the router to ignore this mount if the incoming HTTP request is a WebSocket upgrade request (contains an `Upgrade:` header). This is useful to prevent WSS connections from being accidentally swallowed by a broad alias or redirect mount (e.g. `/`) when they were intended for a different, overlapping protocol.

In the case you want to also protect being able to connect to a ws protocol on
a particular vhost by requiring the http part can authenticate using Basic
Auth before the ws upgrade, this is also possible. In this case, the
Expand Down
31 changes: 28 additions & 3 deletions READMEs/README.plugin-webrtc-mixer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,29 @@ This protocol implements a WebRTC video conferencing mixer. It works in conjunct

The WebRTC mixer plugin relies heavily on `protocol_lws_webrtc`. While `protocol_lws_webrtc` handles the low-level SDP signaling, ICE candidate gathering, and fundamental RTP/RTCP transport, the `lws-webrtc-mixer` protocol handles the high-level logic of mixing multiple WebRTC streams together. The `lws-webrtc` protocol must be loaded alongside `lws-webrtc-mixer` to function properly.

## GStreamer Video Composition

Video decoding, composition, and encoding (H.264/AV1) are handled entirely by GStreamer. This enables hardware-accelerated media pipelines that drastically reduce CPU usage and memory footprint compared to software-based transcoding.

### Build Requirements
To compile the mixer plugin, you must enable `LWS_WITH_WEBRTC_MIXER=ON` in CMake and install the GStreamer development headers:
- **Debian/Ubuntu**: `sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`
- **Fedora/RHEL**: `sudo dnf install gstreamer1-devel gstreamer1-plugins-base-devel`

### Runtime Requirements
At runtime, GStreamer relies on platform-specific plugins to utilize hardware acceleration for compositing and encoding. Ensure you have the appropriate GStreamer packages installed for your system.

* **Intel (VAAPI)**: Requires the VAAPI plugins.
- Debian/Ubuntu: `sudo apt install gstreamer1.0-vaapi intel-media-va-driver-non-free`
- *Example PVO*: `"vaapicompositor name=comp ! queue ! vaapih264enc byte-stream=true config-interval=1 ! appsink name=outsink sync=false"`

* **Rockchip (MPP)**: Requires Rockchip MPP plugins.
- *Example PVO*: `"mppcompositor name=comp ! queue ! mpph264enc byte-stream=true config-interval=1 ! appsink name=outsink sync=false"`

* **Software Fallback**: If no hardware acceleration is available, standard plugins are used.
- Debian/Ubuntu: `sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly`
- *Example PVO*: `"compositor name=comp background=black ! videoconvert ! videoscale ! video/x-raw,width=1280,height=720,framerate=25/1,format=I420 ! x264enc tune=zerolatency speed-preset=ultrafast ! h264parse config-interval=1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=outsink sync=false async=false"`

## Asset and Sound Installation

The user interface for the WebRTC mixer (HTML, CSS, JS) and the associated sound effects (WAV files) are located in the `assets/` and `sounds/` subdirectories of the plugin.
Expand All @@ -23,8 +46,9 @@ The WebRTC plugins support the following Per-Vhost Options (PVOs) to configure t
| `lws-webrtc` | `external-ip` | The external IPv4 address of the server used for ICE candidates. This is required for clients outside the local network to establish WebRTC connections. | `"10.199.0.10"` |
| `lws-webrtc` | `udp-port` | The UDP port used for the WebRTC transport. | `"1234"` |
| `lws-webrtc` | `lws-webrtc-ops` | Handled internally via code to provide the operational struct linking the core WebRTC protocol to higher-level protocols. | - |
| `lws-webrtc-mixer` | `gstreamer-pipeline` | The GStreamer pipeline string used to compose and encode the video. The pipeline *must* include a compositor element named `comp` and an appsink named `outsink` (or `outsink_h264` / `outsink_av1`). **IMPORTANT**: To ensure WebRTC compatibility and support for clients joining mid-session, your encoder should be configured for Annex-B (`byte-stream=true`) and periodic keyframe headers (`config-interval=1`). | `"vaapicompositor name=comp ! vaapih264enc byte-stream=true config-interval=1 ! appsink name=outsink sync=false"` |

*(Note: The `lws-webrtc-mixer` and `lws-webrtc-udp` plugins currently do not require specific PVOs of their own, but expect the base `lws-webrtc` plugin to be configured).*
*(Note: The `lws-webrtc-udp` plugin currently does not require specific PVOs of its own, but expects the base `lws-webrtc` plugin to be configured).*

## Example `lwsws` Configuration Fragment

Expand All @@ -40,7 +64,8 @@ The following is an example configuration fragment for `lwsws` that enables the
"status": "ok"
},
"lws-webrtc-mixer": {
"status": "ok"
"status": "ok",
"gstreamer-pipeline": "compositor name=comp background=black ! videoconvert ! videoscale ! video/x-raw,width=1280,height=720,framerate=25/1,format=I420 ! x264enc tune=zerolatency speed-preset=ultrafast ! h264parse config-interval=1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=outsink sync=false async=false"
}
}],
"mounts": [{
Expand All @@ -49,7 +74,7 @@ The following is an example configuration fragment for `lwsws` that enables the
"origin": "file://_lws_ddir_/libwebsockets-test-server/lws-webrtc-mixer",
"default": "index.html",
"headers": [{
"content-security-policy": "default-src 'none'; img-src 'self' data: https://scan.coverity.com https://bestpractices.coreinfrastructure.org https://img.shields.io ; script-src 'self' 'unsafe-inline'; media-src 'unsafe-inline'; font-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' wss://libwebsockets.org:443; frame-ancestors 'none'; base-uri 'none'; form-action 'self';",
"content-security-policy": "default-src 'none'; img-src 'self' data: https://scan.coverity.com ; script-src 'self' 'unsafe-inline'; media-src 'unsafe-inline'; font-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' wss://libwebsockets.org:443; frame-ancestors 'none'; base-uri 'none'; form-action 'self';",
"permissions-policy": "geolocation=(),microphone=(self),camera=(self),display-capture=(),document-domain=(),execution-while-not-rendered=(),execution-while-out-of-viewport=(),identity-credentials-get=(),local-fonts=(),payment=(),serial=(),usb=(),speaker-selection=()"
}],
"keepalive-timeout": "999"
Expand Down
1 change: 1 addition & 0 deletions changelog
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Changelog
Development
===========

- ACME: support DNS-01
- Async DNS: support DNSSEC
- Async DNS: support tcp fallback
- Support authoritative DNS server, like nsd, using own-signed zone files
Expand Down
2 changes: 2 additions & 0 deletions cmake/lws_config.h.in
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,7 @@
#cmakedefine LWS_WITH_LWSAC
#cmakedefine LWS_LOGS_TIMESTAMP
#cmakedefine LWS_WITH_MBEDTLS
#cmakedefine LWS_WITH_BEARSSL
#cmakedefine LWS_WITH_SCHANNEL
#cmakedefine LWS_WITH_GNUTLS
#cmakedefine LWS_WITH_MINIZ
Expand Down Expand Up @@ -257,6 +258,7 @@
#cmakedefine LWS_WITH_SYS_FAULT_INJECTION
#cmakedefine LWS_WITH_SYS_METRICS
#cmakedefine LWS_WITH_SYS_NTPCLIENT
#cmakedefine LWS_WITH_SYS_WHOIS
#cmakedefine LWS_WITH_LATENCY
#cmakedefine LWS_WITH_UPNG
#cmakedefine LWS_WITH_SYS_STATE
Expand Down
Loading
Loading