Go to file
2024-11-11 16:44:13 +01:00
.github Update GitHub Actions 2024-11-01 01:16:40 +00:00
.vscode Apply Prettier to the entire project 2022-12-09 14:34:25 -05:00
backend update README.md 2024-11-06 20:20:29 +01:00
config fix nginx config 2024-11-07 23:01:50 +01:00
docs Add a config option to disable the app prompt 2024-11-01 16:57:48 -04:00
public knock reject wording update (shorter/simpler) 2024-11-11 16:44:13 +01:00
scripts Fix my lazy regexing 2023-04-06 17:59:48 +01:00
src Skip lobby if when coming from waitForInvite state. 2024-11-11 15:49:31 +01:00
.dockerignore Add CI 2021-12-20 16:59:39 +00:00
.env.example Adopt the Compound color system 2023-08-28 17:14:40 -04:00
.eslintrc.cjs Add rxjs/recommend eslint rules (#2724) 2024-11-06 14:33:06 +00:00
.gitignore update gitignore to irgnore temp synapse state 2024-11-05 00:18:33 +01:00
.postcssrc.json Add automatic css prefixing 2021-10-14 17:41:59 -07:00
.prettierignore Add prettier support 2022-05-03 14:24:04 +01:00
.prettierrc.json Add prettier support 2022-05-03 14:24:04 +01:00
babel.config.cjs Fix tests 2023-06-30 18:46:10 -04:00
codecov.yaml Disable Codecov annotations 2024-10-18 16:39:02 -04:00
CONTRIBUTING.md Apply Prettier to the entire project 2022-12-09 14:34:25 -05:00
demo.jpg Add a demo screenshot to the README 2023-01-20 10:51:28 -05:00
dev-backend-docker-compose.yml Update dev-backend-docker-compose.yml 2024-11-07 19:16:55 +01:00
Dockerfile Upload source maps to sentry (#810) 2023-01-03 10:48:48 +00:00
i18next-parser.config.ts Fix i18next-parser.config.ts and re-sort app.json 2023-11-20 13:22:54 +00:00
knip.ts Perform dead code analysis with Knip (#2575) 2024-08-28 02:06:57 +02:00
LICENSE Update LICENCE file 2024-09-06 10:21:49 +02:00
localazy.json Add localazy.json and related automations 2023-11-20 13:35:24 +00:00
package.json Merge pull request #2744 from robintown/element-call-nov-preview 2024-11-09 08:31:35 -05:00
README.md Skip lobby if when coming from waitForInvite state. 2024-11-11 15:49:31 +01:00
renovate.json Hold back PostHog updates for now 2024-09-27 16:02:12 -04:00
tsconfig.json Update matrix-js-sdk 2024-09-03 16:18:34 -04:00
vite.config.js Update file headers copyright and change licence to AGPL-3.0-only 2024-09-06 10:22:13 +02:00
vitest.config.js Exclude test utilities from coverage report 2024-09-10 16:23:00 -04:00
yarn.lock Merge pull request #2744 from robintown/element-call-nov-preview 2024-11-09 08:31:35 -05:00

Element Call

Chat Localazy

Group calls with WebRTC that leverage Matrix and an open-source WebRTC toolkit from LiveKit.

For prior version of the Element Call that relied solely on full-mesh logic, check full-mesh branch.

A demo of Element Call with six people

To try it out, visit our hosted version at call.element.io. You can also find the latest development version continuously deployed to call.element.dev.

Host it yourself

Until prebuilt tarballs are available, you'll need to build Element Call from source. First, clone and install the package:

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 may also wish to add a configuration file (Element Call uses the domain it's hosted on as a Homeserver URL by default, but you can change this in the config file). This goes in public/config.json - you can use the sample as a starting point:

cp config/config.sample.json public/config.json
# edit public/config.json

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:

server {
    ...
    location / {
        ...
        try_files $uri /$uri /index.html;
    }
}

By default, the app expects you to have a Matrix homeserver (such as Synapse) installed locally and running on port 8008. If you wish to use a homeserver on a different URL or one that is hosted on a different server, you can add a config file as above, and include the homeserver URL that you'd like to use.

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.

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.

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.

If you're using Synapse, you'll need to additionally add the following to homeserver.yaml or Element Call won't work:

experimental_features:
    # MSC3266: Room summary API. Used for knocking over federation
    msc3266_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

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"), a cannot join error or the join view.

Element Call requires a Livekit SFU alongside a Livekit 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.

The configuration is a list of Foci configs:

"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"
    },
]

Translation

If you'd like to help translate Element Call, head over to Localazy. You're also encouraged to join the Element Translators space to discuss and coordinate translation efforts.

Development

Frontend

Element Call is built against matrix-js-sdk. To get started, clone, install, and link the package:

git clone https://github.com/matrix-org/matrix-js-sdk.git
cd matrix-js-sdk
yarn
yarn link

Next, we can set up this project:

git clone https://github.com/element-hq/element-call.git
cd element-call
yarn
yarn link matrix-js-sdk

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.)

You're now ready to launch the development server:

yarn dev

Backend

A docker compose file dev-backend-docker-compose.yml is provided to start the whole stack of components which is required for a local development environment:

  • Minimum Synapse Setup (servername: synapse.localhost)
  • LiveKit JWT Service (Note requires Federation API and hence a TLS reverse proxy)
  • Minimum TLS reverse proxy (servername: synapse.localhost) Note certificates are valid for at least 10 years from now
  • Minimum LiveKit SFU Setup using dev defaults for config
  • Redis db for completness

These use a test 'secret' published in this repository, so this must be used only for local development and never be exposed to the public Internet.

Run backend components:

yarn backend
# or  for podman-compose
# podman-compose -f dev-backend-docker-compose.yml up

Test Coverage

Add a new translation key

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")
  2. Run yarn i18n to extract the new key and update the translation files. This will add a skeleton entry to the public/locales/en-GB/app.json file:
    {
        ...
        "some_new_key": "",
        ...
    }
    
  3. Update the skeleton entry in the public/locales/en-GB/app.json file with the English translation:
   {
       ...
       "some_new_key": "Some new key",
       ...
   }

Documentation

Usage and other technical details about the project can be found here:

Docs