Merge pull request #4194 from element-hq/toger5/rtc-mode-documentation

Add docs about currently used matrixRTC mode

.github/workflows/publish-embedded-packages.yaml

@@ -9,7 +9,7 @@ on:
       - opened
       - labeled
   push:
-    branches: [livekit]
+    branches: [main]
 
 jobs:
   versioning:

.github/workflows/sync-labels.yml

@@ -4,12 +4,12 @@ on:
 
   push:
     branches:
-      - livekit
+      - main
     paths:
       - .github/labels.yml
       - .github/workflows/sync-labels.yml
 
-permissions: {} # We use ELEMENT_BOT_TOKEN instead
+permissions: {} # We use LABEL_SYNC_GITHUB_TOKEN instead
 
 jobs:
   sync-labels:
@@ -20,4 +20,4 @@ jobs:
       DELETE: true
       WET: true
     secrets:
-      ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }}
+      ELEMENT_BOT_TOKEN: ${{ secrets.LABEL_SYNC_GITHUB_TOKEN }}

.github/workflows/test.yaml

@@ -2,7 +2,7 @@ name: Test
 on:
   pull_request: {}
   push:
-    branches: [livekit]
+    branches: [main]
 jobs:
   vitest:
     name: Run unit tests

.github/workflows/translations-upload.yaml

@@ -2,7 +2,7 @@ name: Upload translation files to Localazy
 on:
   push:
     branches:
-      - livekit
+      - main
     paths-ignore:
       - ".github/**"
 

.github/workflows/zizmor.yml

@@ -2,7 +2,7 @@ name: GitHub Actions Security Analysis with zizmor 🌈
 
 on:
   push:
-    branches: ["livekit", "full-mesh"]
+    branches: ["main", "full-mesh"]
   pull_request: {}
 
 permissions: {}

docker-compose-playwright.yml

@@ -13,7 +13,7 @@ services:
       - ./backend/playwright_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z
   element-web:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/element-web:develop@sha256:073e6a49baeac1fb0595593098328ee50589acec7f793bfed12e182c9857080d
+    image: ghcr.io/element-hq/element-web:develop@sha256:ee5b90cbc65f3c2f9f98629944f5712555df4ccf443597b886f70c69246f063b
   element-web-1:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/element-web:develop@sha256:073e6a49baeac1fb0595593098328ee50589acec7f793bfed12e182c9857080d
+    image: ghcr.io/element-hq/element-web:develop@sha256:ee5b90cbc65f3c2f9f98629944f5712555df4ccf443597b886f70c69246f063b

docs/README.md

@@ -5,5 +5,6 @@ This folder contains documentation for setup, usage, and development of Element
 - [Embedded vs standalone mode](./embedded_standalone.md)
 - [Url format and parameters](./url_params.md)
 - [Global JS controls](./controls.md)
+- [MatrixRTC modes](./matrix_rtc_modes.md)
 - [Self-Hosting](./self_hosting.md)
 - [Developing with linked packages](./linking.md)

docs/matrix_rtc_modes.md

@@ -0,0 +1,60 @@
+# MatrixRTC modes
+
+Element Call is in the middle of a transition of how a call session is
+represented and how participants pick an SFU:
+
+- **Membership events**: from room _state_ events
+  (`org.matrix.msc3401.call.member`) to _sticky_ events
+  ([MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354)),
+  which are a much better fit for the short lived, per-device nature of call
+  memberships.
+- **SFU selection**: from "everyone connects to the SFU of the oldest member" to
+  **multi SFU**, where each participant uses its own homeserver's SFU and the
+  SFUs interconnect.
+
+Not every homeserver supports sticky events yet. Multi SFU is supported on all current (August 2026)
+element call clients. The three MatrixRTC modes are the steps of that transition,
+so a deployment can pick the newest one its homeserver and its user base can
+handle.
+
+## The modes
+
+| Mode            | Membership events | SFU selection | JWT endpoint                 |
+| --------------- | ----------------- | ------------- | ---------------------------- |
+| `legacy`        | state events      | oldest member | legacy                       |
+| `compatibility` | state events      | multi SFU     | legacy                       |
+| `matrix_2_0`    | sticky events     | multi SFU     | Matrix 2.0 (hashed identity) |
+
+**`legacy`** — the lowest common denominator. Use it if calls need to work with
+Element Call clients older than v0.17.0, which cannot handle multi SFU calls. (unused)
+
+**`compatibility`** — multi SFU, but still state events. Use it when all Element
+Call clients are v0.17.0 or later but the homeserver does not support sticky
+events. This is the default. (default)
+
+**`matrix_2_0`** — the target state. Requires a homeserver that advertises
+MSC4354 and all clients on v0.17.0 or later. The local membership requests its
+token from the Matrix 2.0 JWT endpoint of the
+[MatrixRTC Authorization Service](https://github.com/element-hq/lk-jwt-service)
+and identifies the room by a hashed identity instead of a `livekit_alias`.
+(Remote memberships always try the new endpoint first and fall back to the
+legacy one, so remote participants can be on either.)
+
+## Selecting a mode
+
+Users can choose a mode under **Settings → Developer → MatrixRTC mode**. The
+Matrix 2.0 option is disabled if the homeserver does not support sticky events.
+
+A deployment can pin the mode for all its clients in `config.json`, which
+disables the Developer Settings choice:
+
+```json
+{
+  "matrix_rtc_mode": "compatibility"
+}
+```
+
+Valid values are `legacy`, `compatibility` and `matrix_2_0`; an invalid value is
+ignored (with a warning) and the user's choice applies. Pinning `matrix_2_0` on a
+homeserver without sticky event support makes joining fail with a "sticky events
+required" error.

docs/self_hosting.md

@@ -16,7 +16,7 @@
 The following [MSCs](https://github.com/matrix-org/matrix-spec-proposals) are
 required for Element Call to work properly:
 
-- **[MSC3266](https://github.com/deepbluev7/matrix-doc/blob/room-summaries/proposals/3266-room-summary.md):
+- **[MSC3266](https://github.com/deepbluev7/matrix-doc/blob/room-summaries/proposals/3266-room-summary.md)
   Room Summary API**: In Standalone mode Element Call is able to join rooms
   over federation using knocking. In this context MSC3266 is required as it
   allows to request a room summary of rooms you are not joined. The summary
@@ -29,19 +29,26 @@ required for Element Call to work properly:
   signalling. If disabled it is very likely that you end up with stuck calls in
   Matrix rooms.
 
+- **[MSC4519](https://github.com/matrix-org/matrix-spec-proposals/blob/travis/msc/voip-transports-registry/proposals/4519-rtc-transports-registry.md)
+  MatrixRTC Transports Registry**: Defines an endpoint that clients can use to
+  query the available MatrixRTC transports (i.e. find your LiveKit SFU).
+
 - **[MSC4222](https://github.com/matrix-org/matrix-spec-proposals/blob/erikj/sync_v2_state_after/proposals/4222-sync-v2-state-after.md)
   Adding `state_after` to sync v2**: Allow clients to opt-in to a change of the
   sync v2 API that allows them to correctly track the state of the room. This is
   required by Element Call to track room state reliably.
 
 If you're using [Synapse](https://github.com/element-hq/synapse/) as your
-homeserver, you'll need to additionally add the following config items to
-`homeserver.yaml` to comply with Element Call:
+homeserver, you can configure these features by adding the following entries to
+`homeserver.yaml`:
 
 ```yaml
 experimental_features:
   # MSC3266: Room summary API. Used for knocking over federation
   msc3266_enabled: true
+  # MSC4143: MatrixRTC. For historical reasons this flag enables the transports
+  # endpoint defined in MSC4519.
+  msc4143_enabled: true
   # MSC4222 needed for syncv2 state_after. This allow clients to
   # correctly track the state of the room.
   msc4222_enabled: true
@@ -61,6 +68,15 @@ rc_delayed_event_mgmt:
   # Currently the heart-beat is every 5 seconds which translates into a rate of 0.2Hz
   per_second: 1
   burst_count: 20
+
+matrix_rtc:
+  transports:
+    # The transport you specify will be made available to clients over the
+    # /_matrix/client/unstable/org.matrix.msc4143/rtc/transports endpoint as
+    # defined in MSC4519.
+    - type: livekit
+      # Replace this with the actual URL of your MatrixRTC Authorization Service
+      livekit_service_url: https://matrix-rtc.example.com/livekit/jwt
 ```
 
 As a prerequisite for the
@@ -187,23 +203,6 @@ backend mxrtc_auth_backend
 
 ```
 
-#### MatrixRTC transport announcement
-
-Enable the unstable feature flag `msc4143_enabled`, and update the
-[`matrix_rtc` section](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#matrix_rtc)
-of your Synapse config file:
-
-```yaml
-matrix_rtc:
-  transports:
-    - type: livekit
-      livekit_service_url: https://matrix-rtc.example.com/livekit/jwt
-```
-
-The transport you specify will be made available to clients over the
-`/_matrix/client/unstable/org.matrix.msc4143/rtc/transports` endpoint as defined
-in [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143).
-
 ## Building Element Call
 
 > [!NOTE]  

src/components/CallFooter.stories.tsx

@@ -127,6 +127,7 @@ export const Default: Story = {
     showFooter: true,
     hideControls: false,
     asOverlay: false,
+    showModals: true,
     sharingScreen: false,
     audioOutputSwitcher: undefined,
     reactionIdentifier: undefined,

src/components/CallFooter.tsx

@@ -77,6 +77,7 @@ export interface FooterState {
   /** The footer should be used as an overlay.
    * (Over the Call Grid) This saves spaces on small screens. */
   asOverlay: boolean;
+  showModals: boolean;
 
   buttonSize: "md" | "lg";
   showLogo: boolean;
@@ -121,6 +122,7 @@ export const CallFooter: FC<FooterProps> = ({
   const asOverlay = useBehavior(vm.asOverlay$);
   const showFooter = useBehavior(vm.showFooter$);
   const hideControls = useBehavior(vm.hideControls$);
+  const showModals = useBehavior(vm.showModals$);
   const layoutSwitchVm = useBehavior(vm.layoutSwitchVm$);
   const openSettings = useBehavior(vm.openSettings$);
   const audioEnabled = useBehavior(vm.audioEnabled$);
@@ -235,7 +237,8 @@ export const CallFooter: FC<FooterProps> = ({
     );
   }
 
-  if (reactionIdentifier && reactionData) {
+  // Reaction button contains a pretty large menu, so treat it like a modal
+  if (reactionIdentifier && reactionData && showModals) {
     buttons.push(
       <ReactionToggleButton
         size={buttonSize}

src/components/CallFooterViewModel.test.ts

@@ -49,6 +49,7 @@ function buildMinimalCallViewModel(layout: Layout): CallViewModel {
     reactions$: constant({}),
     tileStoreGeneration$: constant(0),
     showFooter$: constant(true),
+    showModals$: constant(true),
     settingsOpen$: constant(false),
     setSettingsOpen$: constant(() => {}),
   } as unknown as CallViewModel;

src/components/CallFooterViewModel.tsx

@@ -161,6 +161,7 @@ export function createCallFooterViewModel(
     // candidat to move into the FooterViewModel
     showFooter$: callModel.showFooter$,
     hideControls$: constant(!showControls),
+    showModals$: callModel.showModals$,
     asOverlay$: callModel.edgeToEdge$,
     buttonSize$: scope.behavior(
       isPip$.pipe(map<boolean, "md" | "lg">((pip) => (pip ? "md" : "lg"))),
@@ -168,12 +169,12 @@ export function createCallFooterViewModel(
 
     openSettings$: scope.behavior(
       combineLatest([
-        isPip$,
+        callModel.showModals$,
         callModel.showHeader$,
         callModel.setSettingsOpen$,
       ]).pipe(
-        map(([isPip, showHeader, setSettingsOpen]) =>
-          !isPip && headerStyle !== HeaderStyle.AppBar && showControls
+        map(([showModals, showHeader, setSettingsOpen]) =>
+          showModals && headerStyle !== HeaderStyle.AppBar && showControls
             ? (): void => setSettingsOpen(true)
             : undefined,
         ),
@@ -239,6 +240,7 @@ export function createLobbyFooterViewModel(
       showLogo,
       hideControls: false,
       asOverlay: false,
+      showModals: true,
       buttonSize: "lg",
       openSettings,
       hangup,

src/config/ConfigOptions.ts

@@ -179,7 +179,8 @@ export interface ConfigOptions {
   /**
    * Pins the {@link MatrixRTCMode} for all clients on this deployment,
    * overriding any per-user choice from the Developer Settings. If unset,
-   * the user's Developer Settings choice (or its default of `Legacy`) wins.
+   * the user's Developer Settings choice (or its default of `Compatibility`)
+   * wins.
    */
   matrix_rtc_mode?: MatrixRTCMode;
 

src/room/InCallView.tsx

@@ -261,6 +261,7 @@ export const InCallView: FC<InCallViewProps> = ({
   const overflowing = useBehavior(vm.overflowing$);
   const showNameTags = useBehavior(vm.showNameTags$);
   const showHeader = useBehavior(vm.showHeader$);
+  const showModals = useBehavior(vm.showModals$);
   const settingsOpen = useBehavior(vm.settingsOpen$);
   const setSettingsOpen = useBehavior(vm.setSettingsOpen$);
   const earpieceMode = useBehavior(vm.earpieceMode$);
@@ -622,7 +623,7 @@ export const InCallView: FC<InCallViewProps> = ({
       {earpieceOverlay}
       <ReactionsOverlay vm={vm} />
       {footer}
-      {layout.type !== "pip" && (
+      {showModals && (
         <>
           <RageshakeRequestModal {...rageshakeRequestModalProps} />
           <SettingsModal

src/room/VideoPreview.module.css

@@ -22,6 +22,9 @@ Please see LICENSE in the repository root for full details.
   height: 100%;
   object-fit: cover;
   background-color: var(--video-tile-background);
+  /* In FF if you add a transform: scale/translate/matrix filter on an element,
+  it'll ignore the parents' border-radius, so force back the radius to avoid UI glitch*/
+  border-radius: inherit;
 }
 
 video.mirror {

src/state/CallViewModel/CallViewModel.ts

@@ -366,6 +366,11 @@ export interface CallViewModel {
    */
   overflowing$: Behavior<boolean>;
 
+  /**
+   * Whether modals such as settings and reactions should be accessible at all.
+   */
+  showModals$: Behavior<boolean>;
+
   settingsOpen$: Behavior<boolean>;
   setSettingsOpen$: Behavior<(open: boolean) => void>;
 
@@ -1450,6 +1455,11 @@ export function createCallViewModel$(
       map((naturallyShowFooter) => naturallyShowFooter && showFooterUrlParams),
     ),
   );
+
+  const showModals$ = scope.behavior(
+    windowMode$.pipe(map((mode) => mode !== "pip")),
+  );
+
   const settingsOpen$ = new BehaviorSubject(false);
   const setSettingsOpen$ = constant((open: boolean) => {
     settingsOpen$.next(open);
@@ -1826,6 +1836,7 @@ export function createCallViewModel$(
     showNameTags$,
     showHeader$: showHeader$,
     showFooter$: showFooter$,
+    showModals$,
     settingsOpen$: settingsOpen$,
     setSettingsOpen$: setSettingsOpen$,
     edgeToEdge$,