From 937d9284d59e495b65f1f065d50e5ff3d4df1f07 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 02:30:39 +0000 Subject: [PATCH 1/8] docs: replaces all instances of matrix-rtc to livekit to match rest of page --- docs/calls/livekit.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index 854e6fd19..7a67b23d1 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -132,7 +132,7 @@ By default, all routes should be forwarded to Livekit with the exception of the
Example caddy config ``` - matrix-rtc.example.com { + livekit.example.com { # for lk-jwt-service @lk-jwt-service path /sfu/get* /healthz* /get_token* @@ -150,7 +150,7 @@ By default, all routes should be forwarded to Livekit with the exception of the Example nginx config ``` server { - server_name matrix-rtc.example.com; + server_name livekit.example.com; # for lk-jwt-service location ~ ^/(sfu/get|healthz|get_token) { @@ -249,7 +249,7 @@ turn: udp_port: 3478 relay_range_start: 50300 relay_range_end: 50400 - domain: matrix-rtc.example.com + domain: livekit.example.com ``` ```yaml From a2a5658d2c262c9ce9c5d5e66ef5c6842fbdbb38 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 02:43:05 +0000 Subject: [PATCH 2/8] docs: rework Related Documentation section for livekit page * separate links into categories in order of importance: guides, specs, source codes * add short description to included community guides * add Element Call, lk-jwt-service, and the livekit MSCs too --- docs/calls/livekit.mdx | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index 7a67b23d1..a072d227d 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -260,9 +260,23 @@ turn: ### Related Documentation -- [LiveKit GitHub](https://github.com/livekit/livekit) -- [LiveKit Connection Tester](https://livekit.io/connection-test) - use with the token returned by `/sfu/get` or `/get_token` -- [MatrixRTC proposal](https://half-shot.github.io/msc-crafter/#msc/4143) -- [Synapse documentation](https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md) -- [Community guide](https://tomfos.tr/matrix/livekit/) -- [Community guide](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) +For testing, use the [LiveKit Connection Tester](https://livekit.io/connection-test) with the token returned by `/sfu/get` or `/get_token` + +Guides: + +- [Element Call self-hosting documentation](https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md) +- [Community guide with overview of Livekit's mechanisms](https://tomfos.tr/matrix/livekit/) +- [Community guide (using systemd)](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) + +Specifications: + +- [MatrixRTC proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4143) +- [Livekit proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4195) + +Source codes: + +- [Element Call](https://github.com/element-hq/element-call) +- [lk-jwt-service](https://github.com/element-hq/lk-jwt-service) +- [LiveKit server](https://github.com/livekit/livekit) + + From 98a72110155511f29a2a647d9632bf817ccb2c45 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 02:58:12 +0000 Subject: [PATCH 3/8] docs: move Livekit's inbuilt TURN guide to top The purpose is to simplify new deployments, which are more likely to use Livekit-only calls. This also makes docs flow a bit better --- docs/calls/livekit.mdx | 47 +++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index a072d227d..ddb0ba903 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -203,7 +203,30 @@ Start up the services using your usual method - for example `docker compose up - ## Additional Configuration -### TURN Integration +### Using LiveKit's built in TURN server + +Livekit includes a built in TURN server which can be used in place of an external option. This TURN server will only work with Livekit, so you can't use it for legacy Matrix calling or anything else. + +If you don't want to set up a separate TURN server, you can enable this with the following changes: + +```yaml +### add this to livekit.yaml ### +turn: + enabled: true + udp_port: 3478 + relay_range_start: 50300 + relay_range_end: 50400 + domain: livekit.example.com +``` + +```yaml +### Add these to docker-compose ### +ports: + - "3478:3478/udp" + - "50300-50400:50300-50400/udp" +``` + +### Integration with an external TURN server If you've already set up coturn, there may be a port clash between the two services. To fix this, make sure the `min-port` and `max-port` for coturn so it doesn't overlap with LiveKit's range: @@ -236,28 +259,6 @@ rtc: secret: "COTURN_SECRET" ``` -## LiveKit's built in TURN server - -Livekit includes a built in TURN server which can be used in place of an external option. This TURN server will only work with Livekit, so you can't use it for legacy Matrix calling - or anything else. - -If you don't want to set up a separate TURN server, you can enable this with the following changes: - -```yaml -### add this to livekit.yaml ### -turn: - enabled: true - udp_port: 3478 - relay_range_start: 50300 - relay_range_end: 50400 - domain: livekit.example.com -``` - -```yaml -### Add these to docker-compose ### -- "3478:3478/udp" -- "50300-50400:50300-50400/udp" -``` - ### Related Documentation For testing, use the [LiveKit Connection Tester](https://livekit.io/connection-test) with the token returned by `/sfu/get` or `/get_token` From a462db2f6cb8746099a53f72117ee29a89840a49 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 03:03:30 +0000 Subject: [PATCH 4/8] docs: replace personal links and small fixes in docs for Livekit TURN --- docs/calls/livekit.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index ddb0ba903..ba00b0cfe 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -228,7 +228,7 @@ ports: ### Integration with an external TURN server -If you've already set up coturn, there may be a port clash between the two services. To fix this, make sure the `min-port` and `max-port` for coturn so it doesn't overlap with LiveKit's range: +If you've already set up coturn, there may be a port clash between the two services. To fix this, make sure coturn's `min-port` and `max-port` do not overlap with LiveKit's range: ```ini min-port=50201 @@ -239,21 +239,21 @@ To improve LiveKit's reliability, you can configure it to use your coturn server Generate a long random secret for LiveKit, and add it to your coturn config under the `static-auth-secret` option. You can add as many secrets as you want - so set a different one for each thing using your TURN server. -Then configure livekit, making sure to replace `COTURN_SECRET`: +Then configure livekit, making sure to replace `COTURN_SECRET` with the ones you generated: ```yaml # livekit.yaml rtc: turn_servers: - - host: coturn.ellis.link + - host: coturn.example.com port: 3478 protocol: tcp secret: "COTURN_SECRET" - - host: coturn.ellis.link + - host: coturn.example.com port: 5349 protocol: tls # Only if you've set up TLS in your coturn secret: "COTURN_SECRET" - - host: coturn.ellis.link + - host: coturn.example.com port: 3478 protocol: udp secret: "COTURN_SECRET" From 38fb955226fbb0ba2677fc3578826fddcd76693a Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 03:07:23 +0000 Subject: [PATCH 5/8] docs: specify both inbuilt + external options for livekit TURN in calls page --- docs/calls.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/calls.mdx b/docs/calls.mdx index 681783ca9..1038b9e46 100644 --- a/docs/calls.mdx +++ b/docs/calls.mdx @@ -10,4 +10,4 @@ Both types of calls are supported by different sets of clients, but most clients For either one to work correctly, you have to do some additional setup. - For legacy calls to work, you need to set up a TURN/STUN server. [Read the TURN guide for tips on how to set up coturn](./calls/turn.mdx) -- For MatrixRTC / Element Call to work, you have to set up the LiveKit backend (foci). LiveKit also uses TURN/STUN to increase reliability, so you might want to configure your TURN server first. [Read the LiveKit guide](./calls/livekit.mdx) +- For MatrixRTC / Element Call to work, you have to set up the LiveKit backend (foci). LiveKit also uses TURN/STUN to increase reliability - you can setup its inbuilt TURN server, or integrate with an existing one. [Read the LiveKit guide](./calls/livekit.mdx) From dece29f19f2e35b5b1cb82fbcce1594603e86ed9 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 04:02:57 +0000 Subject: [PATCH 6/8] docs: add livekit testing instructions against new /get_token endpoint --- docs/calls/livekit.mdx | 50 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index ba00b0cfe..1372c025c 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -259,15 +259,59 @@ rtc: secret: "COTURN_SECRET" ``` -### Related Documentation +## Testing -For testing, use the [LiveKit Connection Tester](https://livekit.io/connection-test) with the token returned by `/sfu/get` or `/get_token` +To test that Livekit is successfully integrated with Continuwuity, you will need to replicate its [Token Exchange Flow](https://github.com/element-hq/lk-jwt-service?tab=readme-ov-file#%EF%B8%8F-how-it-works--token-exchange-flow). First, request an OpenID token from your Matrix server: + +```bash +curl -X POST -H "Authorization: Bearer " \ + https://matrix.example.com/_matrix/client/v3/user/@user:example.com/openid/request_token +``` + +Your `` can be found in your client device, or via [this website](https://timedout.uk/mxtoken.html). The step above will respond with an `access_token` for use with the lk-jwt-service. + +Next, create a `payload.json` file with the following content: + +
+ +`payload.json` + +```json +{ + "room_id": "abc", + "slot_id": "xyz", + "openid_token": { + "matrix_server_name": "example.com", + "access_token": "", + "token_type": "Bearer" + }, + "member": { + "id": "xyz", + "claimed_device_id": "DEVICEID", + "claimed_user_id": "@user:example.com" + } +} +``` + +Replace `matrix_server_name` and `claimed_user_id` with your information, and `` with the one you got from the previous step. Other values can be left as-is. + +
+ +You can then send this payload to the lk-jwt-service with: + +```bash +curl -X POST -d @payload.json https://livekit.example.com/get_token +``` + +The JWT service will respond with a `jwt` token. Use this token to test at the [LiveKit Connection Tester](https://livekit.io/connection-test) - if everything works there, then you have set up Livekit successfully! + +## Related Documentation Guides: - [Element Call self-hosting documentation](https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md) - [Community guide with overview of Livekit's mechanisms](https://tomfos.tr/matrix/livekit/) -- [Community guide (using systemd)](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) +- [Community guide using systemd](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) Specifications: From 5244c55bf977d6cfe2b43d154ba818294503beb5 Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 21 Feb 2026 16:53:19 +0000 Subject: [PATCH 7/8] docs: apply changes from feedback turn all the things into LiveKit --- docs/calls/livekit.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index 1372c025c..b4b762d14 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -14,7 +14,7 @@ Make sure the DNS record for the (sub)domain you plan to use is pointed to your ### 2. Services -Using LiveKit with Matrix requires two services - Livekit itself, and a service (`lk-jwt-service`) that grants Matrix users permission to connect to it. +Using LiveKit with Matrix requires two services - LiveKit itself, and a service (`lk-jwt-service`) that grants Matrix users permission to connect to it. You must generate a key and secret to allow the Matrix service to authenticate with LiveKit. `LK_MATRIX_KEY` should be around 20 random characters, and `LK_MATRIX_SECRET` should be around 64. Remember to replace these with the actual values! @@ -123,7 +123,7 @@ The final file should look something like this: Reverse proxies can be configured in many different ways - so we can't provide a step by step for this. -By default, all routes should be forwarded to Livekit with the exception of the following path prefixes, which should be forwarded to the JWT/Authentication service: +By default, all routes should be forwarded to LiveKit with the exception of the following path prefixes, which should be forwarded to the JWT/Authentication service: - `/sfu/get` - `/healthz` @@ -161,7 +161,7 @@ By default, all routes should be forwarded to Livekit with the exception of the proxy_buffering off; } - # for livekit + # for LiveKit location / { proxy_pass http://127.0.0.1:7880$request_uri; proxy_set_header X-Forwarded-For $remote_addr; @@ -205,7 +205,7 @@ Start up the services using your usual method - for example `docker compose up - ### Using LiveKit's built in TURN server -Livekit includes a built in TURN server which can be used in place of an external option. This TURN server will only work with Livekit, so you can't use it for legacy Matrix calling or anything else. +LiveKit includes a built in TURN server which can be used in place of an external option. This TURN server will only work with LiveKit, so you can't use it for legacy Matrix calling or anything else. If you don't want to set up a separate TURN server, you can enable this with the following changes: @@ -237,9 +237,9 @@ max-port=65535 To improve LiveKit's reliability, you can configure it to use your coturn server. -Generate a long random secret for LiveKit, and add it to your coturn config under the `static-auth-secret` option. You can add as many secrets as you want - so set a different one for each thing using your TURN server. +Generate a long random secret for LiveKit, and add it to your coturn config under the `static-auth-secret` option. You can add as many secrets as you want, so set a different one for each thing using your TURN server. -Then configure livekit, making sure to replace `COTURN_SECRET` with the ones you generated: +Then configure LiveKit, making sure to replace `COTURN_SECRET` with the ones you generated: ```yaml # livekit.yaml @@ -261,14 +261,14 @@ rtc: ## Testing -To test that Livekit is successfully integrated with Continuwuity, you will need to replicate its [Token Exchange Flow](https://github.com/element-hq/lk-jwt-service?tab=readme-ov-file#%EF%B8%8F-how-it-works--token-exchange-flow). First, request an OpenID token from your Matrix server: +To test that LiveKit is successfully integrated with Continuwuity, you will need to replicate its [Token Exchange Flow](https://github.com/element-hq/lk-jwt-service?tab=readme-ov-file#%EF%B8%8F-how-it-works--token-exchange-flow). First, request an OpenID token from your Matrix server: ```bash curl -X POST -H "Authorization: Bearer " \ https://matrix.example.com/_matrix/client/v3/user/@user:example.com/openid/request_token ``` -Your `` can be found in your client device, or via [this website](https://timedout.uk/mxtoken.html). The step above will respond with an `access_token` for use with the lk-jwt-service. +Your `` can be found in your client's settings, or via [this website](https://timedout.uk/mxtoken.html). The step above will respond with an `access_token` for use with the lk-jwt-service. Next, create a `payload.json` file with the following content: @@ -303,20 +303,20 @@ You can then send this payload to the lk-jwt-service with: curl -X POST -d @payload.json https://livekit.example.com/get_token ``` -The JWT service will respond with a `jwt` token. Use this token to test at the [LiveKit Connection Tester](https://livekit.io/connection-test) - if everything works there, then you have set up Livekit successfully! +The JWT service will respond with a `jwt` token. Use this token to test at the [LiveKit Connection Tester](https://livekit.io/connection-test) - if everything works there, then you have set up LiveKit successfully! ## Related Documentation Guides: - [Element Call self-hosting documentation](https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md) -- [Community guide with overview of Livekit's mechanisms](https://tomfos.tr/matrix/livekit/) +- [Community guide with overview of LiveKit's mechanisms](https://tomfos.tr/matrix/livekit/) - [Community guide using systemd](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) Specifications: - [MatrixRTC proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4143) -- [Livekit proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4195) +- [LiveKit proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4195) Source codes: From 2f1d4ecdbc9ebc010c989142b67b4f8479a9f2b1 Mon Sep 17 00:00:00 2001 From: stratself Date: Sun, 22 Feb 2026 22:18:39 +0000 Subject: [PATCH 8/8] docs: add caveat for deployment with non-federated instances --- docs/calls/livekit.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index b4b762d14..e9fb18d59 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -305,6 +305,10 @@ curl -X POST -d @payload.json https://livekit.example.com/get_token The JWT service will respond with a `jwt` token. Use this token to test at the [LiveKit Connection Tester](https://livekit.io/connection-test) - if everything works there, then you have set up LiveKit successfully! +## Caveats + +When deploying on servers with disabled federation (`enable_registration = false`), Livekit will fail as it can't fetch the required [OpenID endpoint](https://spec.matrix.org/v1.17/server-server-api/#get_matrixfederationv1openiduserinfo) via federation paths. You can find a workaround for this limitation [here](https://forgejo.ellis.link/continuwuation/continuwuity/issues/1440). + ## Related Documentation Guides: @@ -323,5 +327,3 @@ Source codes: - [Element Call](https://github.com/element-hq/element-call) - [lk-jwt-service](https://github.com/element-hq/lk-jwt-service) - [LiveKit server](https://github.com/livekit/livekit) - -