diff --git a/README.md b/README.md index 6612d5e6..be17c56c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ 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 @@ -26,38 +25,36 @@ with **[LiveKit](https://livekit.io/)** as its backend. You can find the latest development version continuously deployed to [call.element.dev](https://call.element.dev/). -> [!NOTE] +> [!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. - +> check [`full-mesh`](https://github.com/element-hq/element-call/tree/full-mesh) +> branch. ## ✨ Key Features ✅ **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 +✅ **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 +✅ **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. - +engagement and interactivity to the conversation. ## 🚀 Deployment Options Element Call can be packaged in two ways: **Full Package** – Supports both **Standalone** and **Widget** mode. Hosted as - a static web page and accessed via a URL when used as a widget. +a static web page and accessed via a URL when used as a widget. **Embedded Package** – 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. +messenger app for seamless integration. This is the recommended method for +embedding Element Call into a messenger app. ### Standalone mode @@ -67,7 +64,6 @@ 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. - ### Widget mode embedded in Messenger Apps ![Element Call in Widget Mode](./docs/element_call_widget.drawio.png) @@ -82,13 +78,11 @@ and voice calls within Matrix rooms. > [!IMPORTANT] > Embedded packaging is recommended for Element Call in widget mode! - ## 🛠️ Self-Hosting For operating and deploying Element Call on your own server, refer to the [**Self-Hosting Guide**](./docs/self-hosting.md). - ## 🧭 MatrixRTC Backend Discovery and Selection For proper Element Call operation each site deployment needs a MatrixRTC backend @@ -103,14 +97,16 @@ 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": [ - { - "type": "livekit", - "livekit_service_url": "https://someurl.com" - }, - ] - ``` + +```json +"org.matrix.msc4143.rtc_foci": [ + { + "type": "livekit", + "livekit_service_url": "https://someurl.com" + }, +] +``` + 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 @@ -135,7 +131,6 @@ selection for **Matrix rooms 123 and 456**, which include users from different homeservers. ![Element Call SFU selection over Matrix federation](./docs/SFU_selection.drawio.png) - ## 🌍 Translation If you'd like to help translate Element Call, head over to @@ -143,7 +138,6 @@ If you'd like to help translate Element Call, head over to the [Element Translators](https://matrix.to/#/#translators:element.io) space to discuss and coordinate translation efforts. - ## 🛠️ Development ### Frontend @@ -161,10 +155,10 @@ To use it, create a local config by, e.g., The `config.devenv.json` config should work with the backend development environment as outlined in the next section out of box. -> [!NOTE] +> [!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. +> 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: @@ -199,7 +193,6 @@ yarn backend - ### Add a new translation key To add a new translation key you can do these steps: @@ -220,14 +213,13 @@ 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: - ```jsonc - { - ... - "some_new_key": "Some new key", - ... - } - ``` - + ```jsonc + { + ... + "some_new_key": "Some new key", + ... + } + ``` ## 📖 Documentation @@ -235,7 +227,6 @@ Usage and other technical details about the project can be found here: [**Docs**](./docs/README.md) - ## 📝 Copyright & License Copyright 2021-2025 New Vector Ltd @@ -253,4 +244,4 @@ 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. \ No newline at end of file +the Licenses. diff --git a/docs/self-hosting.md b/docs/self-hosting.md index 751ea530..26644ed6 100644 --- a/docs/self-hosting.md +++ b/docs/self-hosting.md @@ -12,28 +12,24 @@ 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". +- **[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) +- **[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) +- **[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: @@ -69,11 +65,12 @@ As depicted above, Element Call requires a to implement [MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md). -> [!IMPORTANT] +> [!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": [ { @@ -91,7 +88,6 @@ to implement ] ``` - ## Building Element Call > [!NOTE] @@ -136,7 +132,6 @@ server { } ``` - ## Configuration There are currently two different config files. `.env` holds variables that are @@ -144,12 +139,11 @@ 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] +> [!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 @@ -164,4 +158,4 @@ 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. \ No newline at end of file +rooms that Element Call cannot handle.