diff --git a/.github/workflows/blocked.yaml b/.github/workflows/blocked.yaml new file mode 100644 index 00000000..d6e592cb --- /dev/null +++ b/.github/workflows/blocked.yaml @@ -0,0 +1,17 @@ +name: Prevent blocked +on: + pull_request: + types: [opened, labeled, unlabeled] +jobs: + prevent-blocked: + name: Prevent blocked + runs-on: ubuntu-latest + permissions: + pull-requests: read + steps: + - name: Add notice + uses: actions/github-script@v7 + if: contains(github.event.pull_request.labels.*.name, 'X-Blocked') + with: + script: | + core.setFailed("PR has been labeled with X-Blocked; it cannot be merged."); diff --git a/.github/workflows/build-and-publish-docker.yaml b/.github/workflows/build-and-publish-docker.yaml index 20a291ff..2fb361ad 100644 --- a/.github/workflows/build-and-publish-docker.yaml +++ b/.github/workflows/build-and-publish-docker.yaml @@ -30,7 +30,7 @@ jobs: with: github-token: ${{ secrets.GITHUB_TOKEN }} run-id: ${{ inputs.artifact_run_id }} - name: build-output + name: build-output-full path: dist - name: Log in to container registry diff --git a/.github/workflows/build-element-call.yaml b/.github/workflows/build-element-call.yaml index a41605c3..14c39b6a 100644 --- a/.github/workflows/build-element-call.yaml +++ b/.github/workflows/build-element-call.yaml @@ -5,6 +5,10 @@ on: vite_app_version: required: true type: string + package: + type: string # This would ideally be a `choice` type, but that isn't supported yet + description: The package type to be built. Must be one of 'full' or 'embedded' + required: true secrets: SENTRY_ORG: required: true @@ -31,8 +35,20 @@ jobs: node-version-file: ".node-version" - name: Install dependencies run: "yarn install --frozen-lockfile" - - name: Build - run: "yarn run build" + - name: Build full version + if: ${{ inputs.package == 'full' }} + run: "yarn run build:full" + env: + SENTRY_ORG: ${{ secrets.SENTRY_ORG }} + SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }} + SENTRY_URL: ${{ secrets.SENTRY_URL }} + SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + VITE_APP_VERSION: ${{ inputs.vite_app_version }} + NODE_OPTIONS: "--max-old-space-size=4096" + - name: Build embedded + if: ${{ inputs.package == 'embedded' }} + run: "yarn run build:embedded" env: SENTRY_ORG: ${{ secrets.SENTRY_ORG }} SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }} @@ -44,7 +60,7 @@ jobs: - name: Upload Artifact uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4 with: - name: build-output + name: build-output-${{ inputs.package }} path: dist # We'll only use this in a triggered job, then we're done with it retention-days: 1 diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 891a73b8..06f1e853 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -16,9 +16,11 @@ on: - ".github/CODEOWNERS" - "docs/**" jobs: - build_element_call: + build_full_element_call: + # Use the full package vite build uses: ./.github/workflows/build-element-call.yaml with: + package: full vite_app_version: ${{ github.event.release.tag_name || github.sha }} secrets: SENTRY_ORG: ${{ secrets.SENTRY_ORG }} @@ -29,7 +31,7 @@ jobs: deploy_develop: # Deploy livekit branch to call.element.dev after build completes if: github.ref == 'refs/heads/livekit' - needs: build_element_call + needs: build_full_element_call runs-on: ubuntu-latest steps: - name: Deploy to call.element.dev @@ -50,7 +52,7 @@ jobs: docker_for_develop: # Build docker and publish docker for livekit branch after build completes if: github.ref == 'refs/heads/livekit' - needs: build_element_call + needs: build_full_element_call permissions: contents: write packages: write @@ -61,3 +63,15 @@ jobs: type=sha,format=short,event=branch type=raw,value=latest-ci type=raw,value=latest-ci_{{date 'X' }} + build_embedded_element_call: + # Use the embedded package vite build + uses: ./.github/workflows/build-element-call.yaml + with: + package: embedded + vite_app_version: ${{ github.event.release.tag_name || github.sha }} + secrets: + SENTRY_ORG: ${{ secrets.SENTRY_ORG }} + SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }} + SENTRY_URL: ${{ secrets.SENTRY_URL }} + SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/deploy-to-netlify.yaml b/.github/workflows/deploy-to-netlify.yaml index 6d825e3c..e865432c 100644 --- a/.github/workflows/deploy-to-netlify.yaml +++ b/.github/workflows/deploy-to-netlify.yaml @@ -50,7 +50,7 @@ jobs: with: github-token: ${{ secrets.ELEMENT_BOT_TOKEN }} run-id: ${{ inputs.artifact_run_id }} - name: build-output + name: build-output-full path: webapp - name: Add redirects file diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index 2a446d11..4c4ed43c 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -13,6 +13,7 @@ jobs: if: ${{ github.event_name == 'release' }} uses: ./.github/workflows/build-element-call.yaml with: + package: full vite_app_version: ${{ github.event.release.tag_name || github.sha }} secrets: SENTRY_ORG: ${{ secrets.SENTRY_ORG }} @@ -38,7 +39,7 @@ jobs: with: github-token: ${{ secrets.GITHUB_TOKEN }} run-id: ${{ github.event.workflow_run.id || github.run_id }} - name: build-output + name: build-output-full path: dist - name: Create Tarball env: diff --git a/.gitignore b/.gitignore index 8d306b2c..7b2cd2c2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ node_modules dist dist-ssr *.local +*.bkp .idea/ public/config.json backend/synapse_tmp/* diff --git a/README.md b/README.md index b2db171d..acadb9c0 100644 --- a/README.md +++ b/README.md @@ -2,122 +2,101 @@ [](https://matrix.to/#/#webrtc:matrix.org) [](https://localazy.com/p/element-call) +[](LICENSE-AGPL-3.0) -Group calls with WebRTC that leverage [Matrix](https://matrix.org) and an -open-source WebRTC toolkit from [LiveKit](https://livekit.io/). +[🎬 Live Demo 🎬](https://call.element.io) -For prior version of the Element Call that relied solely on full-mesh logic, -check [`full-mesh`](https://github.com/element-hq/element-call/tree/full-mesh) -branch. +The world's first 🌐 decentralized and 🤝 federated video conferencing solution +powered by **the Matrix protocol**. + +## 📌 Overview + +**Element Call** is a native Matrix video conferencing application developed by +[Element](https://element.io/), designed for **secure**, **scalable**, +**privacy-respecting**, and **decentralized** video and voice calls over the +Matrix protocol. Built on **MatrixRTC** +([MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)), it +utilizes +**[MSC4195](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md)** +with **[LiveKit](https://livekit.io/)** as its backend.  -To try it out, visit our hosted version at -[call.element.io](https://call.element.io). You can also find the latest -development version continuously deployed to +You can find the latest development version continuously deployed to [call.element.dev](https://call.element.dev/). -## Host it yourself +> [!NOTE] +> For prior version of the Element Call that relied solely on full-mesh logic, +> check [`full-mesh`](https://github.com/element-hq/element-call/tree/full-mesh) +> branch. -Until prebuilt tarballs are available, you'll need to build Element Call from -source. First, clone and install the package: +## ✨ Key Features -```sh -git clone https://github.com/element-hq/element-call.git -cd element-call -yarn -yarn build -``` +✅ **Decentralized & Federated** – No central authority; works across Matrix +homeservers. +✅ **End-to-End Encrypted** – Secure and private calls. +✅ **Standalone & Widget Mode** – Use as an independent app or embed in Matrix +clients. +✅ **WebRTC-based** – No additional software required. +✅ **Scalable with LiveKit** – Supports large meetings via SFU +([MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md)). +✅ **Raise Hand** – Participants can signal when they want to speak, helping to +organize the flow of the meeting. +✅ **Emoji Reactions** – Users can react with emojis 👍️ 🎉 👏 🤘, adding +engagement and interactivity to the conversation. -If all went well, you can now find the build output under `dist` as a series of -static files. These can be hosted using any web server that can be configured -with custom routes (see below). +## 🚀 Deployment Options -You also need to add a configuration file which goes in `public/config.json` - -you can use the sample as a starting point: +Element Call can be packaged in two ways: -```sh -cp config/config.sample.json public/config.json -# edit public/config.json -``` +**Full Package** – Supports both **Standalone** and **Widget** mode. Hosted as +a static web page and accessed via a URL when used as a widget. -The sample needs editing to contain the homeserver and LiveKit backend that you -are using. +**Embedded Package** – 🚧 **Coming [Soon](https://github.com/element-hq/element-call/issues/2994):** Designed for **Widget mode** only. Bundled with a +messenger app for seamless integration. This is the recommended method for +embedding Element Call into a messenger app. -Because Element Call uses client-side routing, your server must be able to route -any requests to non-existing paths back to `/index.html`. For example, in Nginx -you can achieve this with the `try_files` directive: +### Standalone mode -```jsonc -server { - ... - location / { - ... - try_files $uri /$uri /index.html; - } -} -``` + -Element Call requires a homeserver with registration enabled without any 3pid or -token requirements, if you want it to be used by unregistered users. -Furthermore, it is not recommended to use it with an existing homeserver where -user accounts have joined normal rooms, as it may not be able to handle those -yet and it may behave unreliably. +In Standalone mode Element Call operates as an independent, full-featured video +conferencing web application, allowing users to join or host calls without +requiring a separate Matrix client. -Therefore, to use a self-hosted homeserver, this is recommended to be a new -server where any user account created has not joined any normal rooms anywhere -in the Matrix federated network. The homeserver used can be setup to disable -federation, so as to prevent spam registrations (if you keep registrations open) -and to ensure Element Call continues to work in case any user decides to log in -to their Element Call account using the standard Element app and joins normal -rooms that Element Call cannot handle. +### Widget mode embedded in Messenger Apps -## Configuration + -There are currently two different config files. `.env` holds variables that are -used at build time, while `public/config.json` holds variables that are used at -runtime. Documentation and default values for `public/config.json` can be found -in [ConfigOptions.ts](src/config/ConfigOptions.ts). +Element Call can be embedded as a widget inside apps like +[**Element Web**](https://github.com/element-hq/element-web) or **Element X +([iOS](https://github.com/element-hq/element-x-ios), +[Android](https://github.com/element-hq/element-x-android))**, bringing +**MatrixRTC** capabilities to messenger apps for seamless decentralized video +and voice calls within Matrix rooms. -If you're using [Synapse](https://github.com/element-hq/synapse/), you'll need -to additionally add the following to `homeserver.yaml` or Element Call won't -work: +> [!IMPORTANT] +> Embedded packaging is recommended for Element Call in widget mode! -```yaml -experimental_features: - # MSC3266: Room summary API. Used for knocking over federation - msc3266_enabled: true - # MSC4222 needed for syncv2 state_after. This allow clients to - # correctly track the state of the room. - msc4222_enabled: true +## 🛠️ Self-Hosting -# The maximum allowed duration by which sent events can be delayed, as -# per MSC4140. -max_event_delay_duration: 24h +For operating and deploying Element Call on your own server, refer to the +[**Self-Hosting Guide**](./docs/self-hosting.md). -rc_message: - # This needs to match at least the heart-beat frequency plus a bit of headroom - # Currently the heart-beat is every 5 seconds which translates into a rate of 0.2s - per_second: 0.5 - burst_count: 30 -``` +## 🧭 MatrixRTC Backend Discovery and Selection -MSC3266 allows to request a room summary of rooms you are not joined. The -summary contains the room join rules. We need that to decide if the user gets -prompted with the option to knock ("Request to join call"), a cannot join error or the -join view. +For proper Element Call operation each site deployment needs a MatrixRTC backend +setup as outlined in the [Self-Hosting](#self-hosting). A typical federated site +deployment for three different sites A, B and C is depicted below. -MSC4222 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. + -Element Call requires a Livekit SFU alongside a [Livekit JWT -service](https://github.com/element-hq/lk-jwt-service) to work. The url to the -Livekit JWT service can either be configured in the config of Element Call -(fallback/legacy configuration) or be configured by your homeserver via the -`.well-known/matrix/client`. This is the recommended method. +### Backend Discovery -The configuration is a list of Foci configs: +MatrixRTC backend (according to +[MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)) +is announced by the homeserver's `.well-known/matrix/client` file and discovered +via the `org.matrix.msc4143.rtc_foci` key, e.g.: ```json "org.matrix.msc4143.rtc_foci": [ @@ -125,25 +104,41 @@ The configuration is a list of Foci configs: "type": "livekit", "livekit_service_url": "https://someurl.com" }, - { - "type": "livekit", - "livekit_service_url": "https://livekit2.com" - }, - { - "type": "another_foci", - "props_for_another_foci": "val" - }, ] ``` -## Translation +where the format for MatrixRTC using LiveKit backend is defined in +[MSC4195](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md). +In the example above Matrix clients do discover a focus of type `livekit` which +points them to a Matrix LiveKit JWT Auth Service via `livekit_service_url`. + +### Backend Selection + +- Each call participant proposes their discovered MatrixRTC backend from + `org.matrix.msc4143.rtc_foci` in their `org.matrix.msc3401.call.member` state event. +- For **LiveKit** MatrixRTC backend + ([MSC4195](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md)), + the **first participant who joined the call** defines via the `foci_preferred` + key in their `org.matrix.msc3401.call.member` which actual MatrixRTC backend + will be used for this call. +- During the actual call join flow, the **LiveKit JWT Auth Service** provides + the client with the **LiveKit SFU WebSocket URL** and an **access JWT token** + in order to exchange media via WebRTC. + +The example below illustrates how backend selection works across **Matrix +federation**, using the setup from sites A, B, and C. It demonstrates backend +selection for **Matrix rooms 123 and 456**, which include users from different +homeservers. + + +## 🌍 Translation If you'd like to help translate Element Call, head over to [Localazy](https://localazy.com/p/element-call). You're also encouraged to join the [Element Translators](https://matrix.to/#/#translators:element.io) space to discuss and coordinate translation efforts. -## Development +## 🛠️ Development ### Frontend @@ -155,13 +150,15 @@ cd element-call yarn ``` -To use it, create a local config by, e.g., `cp ./config/config.devenv.json ./public/config.json` -and adapt it if necessary. The `config.devenv.json` config should work with the backend -development environment as outlined in the next section out of box. +To use it, create a local config by, e.g., +`cp ./config/config.devenv.json ./public/config.json` and adapt it if necessary. +The `config.devenv.json` config should work with the backend development +environment as outlined in the next section out of box. -(Be aware, that this `config.devenv.json` is exposing a deprecated fallback -LiveKit config key. If the homeserver advertises SFU backend via -`.well-known/matrix/client` this has precedence.) +> [!NOTE] +> Be aware, that this `config.devenv.json` is exposing a deprecated fallback +> LiveKit config key. If the homeserver advertises SFU backend via +> `.well-known/matrix/client` this has precedence. You're now ready to launch the development server: @@ -200,7 +197,8 @@ yarn backend To add a new translation key you can do these steps: -1. Add the new key entry to the code where the new key is used: `t("some_new_key")` +1. Add the new key entry to the code where the new key is used: + `t("some_new_key")` 1. Run `yarn i18n` to extract the new key and update the translation files. This will add a skeleton entry to the `locales/en/app.json` file: @@ -212,30 +210,38 @@ To add a new translation key you can do these steps: } ``` -1. Update the skeleton entry in the `locales/en/app.json` file with - the English translation: +1. Update the skeleton entry in the `locales/en/app.json` file with the English + translation: -```jsonc + ```jsonc { ... "some_new_key": "Some new key", ... } -``` + ``` -## Documentation +## 📖 Documentation Usage and other technical details about the project can be found here: [**Docs**](./docs/README.md) -## Copyright & License +## 📝 Copyright & License Copyright 2021-2025 New Vector Ltd -This software is dual-licensed by New Vector Ltd (Element). It can be used either: +This software is dual-licensed by New Vector Ltd (Element). It can be used +either: -(1) for free under the terms of the GNU Affero General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR +(1) for free under the terms of the GNU Affero General Public License (as +published by the Free Software Foundation, either version 3 of the License, or +(at your option) any later version); OR -(2) under the terms of a paid-for Element Commercial License agreement between you and Element (the terms of which may vary depending on what you and Element have agreed to). -Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licenses for the specific language governing permissions and limitations under the Licenses. +(2) under the terms of a paid-for Element Commercial License agreement between +you and Element (the terms of which may vary depending on what you and Element +have agreed to). Unless required by applicable law or agreed to in writing, +software distributed under the Licenses is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +Licenses for the specific language governing permissions and limitations under +the Licenses. diff --git a/docs/Federated_Setup.drawio.png b/docs/Federated_Setup.drawio.png new file mode 100644 index 00000000..6f0a4967 Binary files /dev/null and b/docs/Federated_Setup.drawio.png differ diff --git a/docs/MSC4195_setup.drawio.png b/docs/MSC4195_setup.drawio.png new file mode 100644 index 00000000..42b4d1aa Binary files /dev/null and b/docs/MSC4195_setup.drawio.png differ diff --git a/docs/README.md b/docs/README.md index 113b52c5..4866fe4b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,3 +5,4 @@ This folder contains documentation for Element Call setup and usage. - [Embedded vs standalone mode](./embedded-standalone.md) - [Url format and parameters](./url-params.md) - [Global JS controls](./controls.md) +- [Self-Hosting](./self-hosting.md) diff --git a/docs/SFU_selection.drawio.png b/docs/SFU_selection.drawio.png new file mode 100644 index 00000000..f2b5e8b0 Binary files /dev/null and b/docs/SFU_selection.drawio.png differ diff --git a/docs/element_call_standalone.drawio.png b/docs/element_call_standalone.drawio.png new file mode 100644 index 00000000..7667d77c Binary files /dev/null and b/docs/element_call_standalone.drawio.png differ diff --git a/docs/element_call_widget.drawio.png b/docs/element_call_widget.drawio.png new file mode 100644 index 00000000..97d5ace3 Binary files /dev/null and b/docs/element_call_widget.drawio.png differ diff --git a/docs/embedded-standalone.md b/docs/embedded-standalone.md index f798c346..328af811 100644 --- a/docs/embedded-standalone.md +++ b/docs/embedded-standalone.md @@ -2,7 +2,7 @@ Element call is developed using the js-sdk with matroska mode. This means the app can run either as a standalone app directly connected to a homeserver providing login interfaces or it can be used as a widget. -As a widget the app only uses the core calling (matrixRTC) parts. The rest (authentication, sending events, getting room state updates about calls) is done by the hosting client. +As a widget the app only uses the core calling (MatrixRTC) parts. The rest (authentication, sending events, getting room state updates about calls) is done by the hosting client. Element Call and the hosting client are connected via the widget api. Element call detects that it is run as a widget if a widgetId is defined in the url parameters. If `widgetId` is present element call will try to connect to the client via the widget postMessage api using the parameters provided in [Url Format and parameters diff --git a/docs/self-hosting.md b/docs/self-hosting.md new file mode 100644 index 00000000..26644ed6 --- /dev/null +++ b/docs/self-hosting.md @@ -0,0 +1,161 @@ +# Self-Hosting Element Call + +## Prerequisites + +> [!IMPORTANT] +> This section covers the requirements for deploying a **Matrix site** +> compatible with MatrixRTC, the foundation of Element Call. These requirements +> apply to both Standalone as well as Widget mode operation of Element Call. + +### A Matrix Homeserver + +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): + 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 + contains the room join rules. We need that information to decide if the user + gets prompted with the option to knock ("Request to join call"), a "cannot + join error" or "the join view". + +- **[MSC4140](https://github.com/matrix-org/matrix-spec-proposals/blob/toger5/expiring-events-keep-alive/proposals/4140-delayed-events-futures.md) + Delayed Events**: Delayed events are required for proper call participation + signalling. If disabled it is very likely that you end up with stuck calls in + Matrix rooms. + +- **[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: + +```yaml +experimental_features: + # MSC3266: Room summary API. Used for knocking over federation + msc3266_enabled: true + # MSC4222 needed for syncv2 state_after. This allow clients to + # correctly track the state of the room. + msc4222_enabled: true + +# The maximum allowed duration by which sent events can be delayed, as +# per MSC4140. +max_event_delay_duration: 24h + +rc_message: + # This needs to match at least the heart-beat frequency plus a bit of headroom + # Currently the heart-beat is every 5 seconds which translates into a rate of 0.2s + per_second: 0.5 + burst_count: 30 +``` + +### MatrixRTC Backend + +In order to **guarantee smooth operation** of Element Call MatrixRTC backend is +required for each site deployment. + + + +As depicted above, Element Call requires a +[Livekit SFU](https://github.com/livekit/livekit) alongside a +[Matrix Livekit JWT auth service](https://github.com/element-hq/lk-jwt-service) +to implement +[MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md). + +> [!IMPORTANT] +> As defined in +> [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143) +> MatrixRTC backend must be announced to the client via your **homeserver's +> `.well-known/matrix/client`**. The configuration is a list of Foci configs: + +```json +"org.matrix.msc4143.rtc_foci": [ + { + "type": "livekit", + "livekit_service_url": "https://someurl.com" + }, + { + "type": "livekit", + "livekit_service_url": "https://livekit2.com" + }, + { + "type": "another_foci", + "props_for_another_foci": "val" + }, +] +``` + +## Building Element Call + +> [!NOTE] +> This step is only required if you want to deploy Element Call in Standalone +> mode. + +Until prebuilt tarballs are available, you'll need to build Element Call from +source. First, clone and install the package: + +```sh +git clone https://github.com/element-hq/element-call.git +cd element-call +yarn +yarn build +``` + +If all went well, you can now find the build output under `dist` as a series of +static files. These can be hosted using any web server that can be configured +with custom routes (see below). + +You also need to add a configuration file which goes in `public/config.json` - +you can use the sample as a starting point: + +```sh +cp config/config.sample.json public/config.json +# edit public/config.json +``` + +The sample needs editing to contain the homeserver that you are using. + +Because Element Call uses client-side routing, your server must be able to route +any requests to non-existing paths back to `/index.html`. For example, in Nginx +you can achieve this with the `try_files` directive: + +```jsonc +server { + ... + location / { + ... + try_files $uri /$uri /index.html; + } +} +``` + +## Configuration + +There are currently two different config files. `.env` holds variables that are +used at build time, while `public/config.json` holds variables that are used at +runtime. Documentation and default values for `public/config.json` can be found +in [ConfigOptions.ts](src/config/ConfigOptions.ts). + +> [!CAUTION] +> Please note configuring MatrixRTC backend via `config.json` of +> Element Call is only available for developing and debug purposes. Relying on +> it might break Element Call going forward! + +## A Note on Standalone Mode of Element Call + +Element Call in Standalone mode requires a homeserver with registration enabled +without any 3pid or token requirements, if you want it to be used by +unregistered users. Furthermore, it is not recommended to use it with an +existing homeserver where user accounts have joined normal rooms, as it may not +be able to handle those yet and it may behave unreliably. + +Therefore, to use a self-hosted homeserver, this is recommended to be a new +server where any user account created has not joined any normal rooms anywhere +in the Matrix federated network. The homeserver used can be setup to disable +federation, so as to prevent spam registrations (if you keep registrations open) +and to ensure Element Call continues to work in case any user decides to log in +to their Element Call account using the standard Element app and joins normal +rooms that Element Call cannot handle. diff --git a/public/index.html b/index.html similarity index 70% rename from public/index.html rename to index.html index bf26d8ec..f17c73c0 100644 --- a/public/index.html +++ b/index.html @@ -2,34 +2,40 @@
+ + <% if (packageType === "full") { %> + <% } %> + -{t("error.generic_description")}
{t("error.open_elsewhere_description", {
brand: import.meta.env.VITE_PRODUCT_NAME || "Element Call",
diff --git a/src/UrlParams.test.ts b/src/UrlParams.test.ts
index 8e185abc..dce46754 100644
--- a/src/UrlParams.test.ts
+++ b/src/UrlParams.test.ts
@@ -110,8 +110,8 @@ describe("UrlParams", () => {
});
describe("returnToLobby", () => {
- it("is true in SPA mode", () => {
- expect(getUrlParams("?returnToLobby=false").returnToLobby).toBe(true);
+ it("is false in SPA mode", () => {
+ expect(getUrlParams("?returnToLobby=true").returnToLobby).toBe(false);
});
it("defaults to false in widget mode", () => {
diff --git a/src/UrlParams.ts b/src/UrlParams.ts
index 61b777c7..fda4a95f 100644
--- a/src/UrlParams.ts
+++ b/src/UrlParams.ts
@@ -264,7 +264,9 @@ export const getUrlParams = (
"skipLobby",
isWidget && intent === UserIntent.StartNewCall,
),
- returnToLobby: isWidget ? parser.getFlagParam("returnToLobby") : true,
+ // In SPA mode the user should always exit to the home screen when hanging
+ // up, rather than being sent back to the lobby
+ returnToLobby: isWidget ? parser.getFlagParam("returnToLobby") : false,
theme: parser.getParam("theme"),
viaServers: !isWidget ? parser.getParam("viaServers") : null,
homeserver: !isWidget ? parser.getParam("homeserver") : null,
diff --git a/src/config/Config.ts b/src/config/Config.ts
index d98bd9ec..b52acc46 100644
--- a/src/config/Config.ts
+++ b/src/config/Config.ts
@@ -13,6 +13,7 @@ import {
type ConfigOptions,
type ResolvedConfigOptions,
} from "./ConfigOptions";
+import { isFailure } from "../utils/fetch";
export class Config {
private static internalInstance: Config | undefined;
@@ -28,7 +29,20 @@ export class Config {
const internalInstance = new Config();
Config.internalInstance = internalInstance;
- Config.internalInstance.initPromise = downloadConfig("/config.json").then(
+ let fetchTarget: string;
+
+ if (
+ window.location.pathname.endsWith("/room/") ||
+ window.location.pathname.endsWith("/room")
+ ) {
+ // it looks like we are running in standalone mode so use the config at the root
+ fetchTarget = new URL("/config.json", window.location.href).href;
+ } else {
+ // otherwise we are probably running as a widget so use the config in the same directory
+ fetchTarget = "config.json";
+ }
+
+ Config.internalInstance.initPromise = downloadConfig(fetchTarget).then(
(config) => {
internalInstance.config = merge({}, DEFAULT_CONFIG, config);
},
@@ -70,18 +84,15 @@ export class Config {
private initPromise?: Promise
{error.localisedMessage ?? (
@@ -101,38 +104,16 @@ const ErrorPage: FC
@@ -199,6 +200,7 @@ export const RoomPage: FC = () => {
{groupCallState.error.messageBody}
diff --git a/src/settings/settings.ts b/src/settings/settings.ts
index 4ec0143f..ee43acc6 100644
--- a/src/settings/settings.ts
+++ b/src/settings/settings.ts
@@ -113,4 +113,8 @@ export const soundEffectVolumeSetting = new Setting = Promise<
@@ -49,7 +51,7 @@ export async function prefetchSounds(
const response = await fetch(
preferredFormat === "ogg" ? ogg : (mp3 ?? ogg),
);
- if (!response.ok) {
+ if (isFailure(response)) {
// If the sound doesn't load, it's not the end of the world. We won't play
// the sound when requested, but it's better than failing the whole application.
logger.warn(`Could not load sound ${name}, response was not okay`);
diff --git a/src/state/CallViewModel.ts b/src/state/CallViewModel.ts
index f634233e..ce104396 100644
--- a/src/state/CallViewModel.ts
+++ b/src/state/CallViewModel.ts
@@ -496,6 +496,10 @@ export class CallViewModel extends ViewModel {
}
return displaynameMap;
}),
+ // It turns out that doing the disambiguation above is rather expensive on Safari (10x slower
+ // than on Chrome/Firefox). This means it is important that we share() the result so that we
+ // don't do this work more times than we need to. This is achieve through the state() operator:
+ this.scope.state(),
);
/**
diff --git a/src/utils/displayname-integration.test.ts b/src/utils/displayname-integration.test.ts
new file mode 100644
index 00000000..8dd72d8c
--- /dev/null
+++ b/src/utils/displayname-integration.test.ts
@@ -0,0 +1,40 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+
+import { shouldDisambiguate } from "./displayname";
+import { alice } from "./test-fixtures";
+import { mockMatrixRoom } from "./test";
+
+// Ideally these tests would be in ./displayname.test.ts but I can't figure out how to
+// just spy on the removeHiddenChars() function without impacting the other tests.
+// So, these tests are in this separate test file.
+vi.mock("matrix-js-sdk/src/utils");
+
+describe("shouldDisambiguate", () => {
+ // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+ let jsUtils: typeof import("matrix-js-sdk/src/utils");
+
+ beforeAll(async () => {
+ jsUtils = await import("matrix-js-sdk/src/utils");
+ vi.spyOn(jsUtils, "removeHiddenChars").mockImplementation((str) => str);
+ });
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ test("should only call removeHiddenChars once for a single displayname", () => {
+ const room = mockMatrixRoom({});
+ shouldDisambiguate(alice, [], room);
+ expect(jsUtils.removeHiddenChars).toHaveBeenCalledTimes(1);
+ for (let i = 0; i < 10; i++) {
+ shouldDisambiguate(alice, [], room);
+ }
+ expect(jsUtils.removeHiddenChars).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/src/utils/displayname.ts b/src/utils/displayname.ts
index 32532506..0eac045d 100644
--- a/src/utils/displayname.ts
+++ b/src/utils/displayname.ts
@@ -7,12 +7,36 @@ Please see LICENSE in the repository root for full details.
import {
removeDirectionOverrideChars,
- removeHiddenChars,
+ removeHiddenChars as removeHiddenCharsUncached,
} from "matrix-js-sdk/src/utils";
import type { Room } from "matrix-js-sdk/src/matrix";
import type { CallMembership } from "matrix-js-sdk/src/matrixrtc";
+// Calling removeHiddenChars() can be slow on Safari, so we cache the results.
+// To illustrate a simple benchmark:
+// Chrome: 10,000 calls took 2.599ms
+// Safari: 10,000 calls took 242ms
+// See: https://github.com/element-hq/element-call/issues/3065
+
+const removeHiddenCharsCache = new Map