mirror of
https://github.com/vector-im/element-call.git
synced 2026-05-22 11:04:38 +00:00
Minor documentation fixes
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
This commit is contained in:
Johannes Marbach
@@ -12,7 +12,7 @@ A few aspects of Element Call's interface can be controlled through a global API
|
||||
|
||||
On mobile platforms (iOS, Android), web views do not reliably support selecting audio output devices such as the main speaker, earpiece, or headset. To address this limitation, the following functions allow the hosting application (e.g., Element Web, Element X) to manage audio devices via exposed JavaScript interfaces. These functions must be enabled using the URL parameter `controlledAudioDevices` to take effect.
|
||||
|
||||
- `controls.setAvailableAudioDevices(devices: { id: string, name: string, forEarpiece?: boolean, isEarpiece?: boolean isSpeaker?: boolean, isExternalHeadset?, boolean; }[]): void` Sets the list of available audio outputs. `forEarpiece` is used on iOS only.
|
||||
- `controls.setAvailableAudioDevices(devices: { id: string, name: string, forEarpiece?: boolean, isEarpiece?: boolean isSpeaker?: boolean, isExternalHeadset?: boolean }[]): void` Sets the list of available audio outputs. `forEarpiece` is used on iOS only.
|
||||
It flags the device that should be used if the user selects earpiece mode. This should be the main stereo loudspeaker of the device.
|
||||
- `controls.onAudioDeviceSelect: ((id: string) => void) | undefined` Callback called whenever the user or application selects a new audio output.
|
||||
- `controls.setAudioDevice(id: string): void` Sets the selected audio device in Element Call's menu. This should be used if the OS decides to automatically switch to Bluetooth, for example.
|
||||
|
||||
@@ -25,7 +25,7 @@ The basics are:
|
||||
|
||||
1. Add the appropriate platform dependency as given for a [release](https://github.com/element-hq/element-call/releases), or use the embedded tarball. e.g. `npm install @element-hq/element-call-embedded@0.9.0`
|
||||
2. Include the assets from the platform dependency in the build process. e.g. copy the assets during a [Webpack](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/webpack.config.js#L677-L682) build.
|
||||
3. Use the `index.html` entrypointof the imported assets when you are constructing the WebView or iframe. e.g. using a [relative path in a webapp](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/src/models/Call.ts#L680), or on the the Android [WebViewAssetLoader](https://github.com/element-hq/element-x-android/blob/fe5aab6588ecdcf9354a3bfbd9e97c1b31175a8f/features/call/impl/src/main/kotlin/io/element/android/features/call/impl/utils/DefaultCallWidgetProvider.kt#L20)
|
||||
3. Use the `index.html` entrypoint of the imported assets when you are constructing the WebView or iframe. e.g. using a [relative path in a webapp](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/src/models/Call.ts#L680), or on the the Android [WebViewAssetLoader](https://github.com/element-hq/element-x-android/blob/fe5aab6588ecdcf9354a3bfbd9e97c1b31175a8f/features/call/impl/src/main/kotlin/io/element/android/features/call/impl/utils/DefaultCallWidgetProvider.kt#L20)
|
||||
4. Set any of the [embedded-only URL parameters](./url_params.md#embedded-only-parameters) that you need.
|
||||
|
||||
## Widget vs standalone mode
|
||||
@@ -35,5 +35,5 @@ Element Call is developed using the [js-sdk](https://github.com/matrix-org/matri
|
||||
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 then Element Call will try to connect to the client via the widget postMessage API using the parameters provided in [Url Format and parameters
|
||||
Element Call detects that it is run as a widget if `widgetId` is defined in the url parameters. If `widgetId` is present then Element Call will try to connect to the client via the widget postMessage API using the parameters provided in [Url Format and parameters
|
||||
](./url_params.md).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
## Quickstart guide
|
||||
|
||||
run
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./scripts/setup-linking.sh
|
||||
@@ -50,7 +50,7 @@ before committing a change.
|
||||
To make this less of a foot gun we added a git hook.
|
||||
A `pre-commit` hook will check if linking is currently used. If it detects
|
||||
a `.pnpmfile.cjs` file it will abort the commit with an explanatory message.
|
||||
You will than need to run `pnpm links:off` and commit again.
|
||||
You will then need to run `pnpm links:off` and commit again.
|
||||
|
||||
To activate the hooks configure git with (when using the setup script (`./scripts/setup-linking.sh`) this is already done):
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ When the renovate bot creates a PR it runs `pnpm install --ignore-pnpmfile`. Thi
|
||||
This breaks builds that **don't** ignore the `.pnpmfile.cjs`-file. (CI that runs on the renovate PR)
|
||||
From here we have two possible paths:
|
||||
|
||||
- ignore `.pnpmfile.cjs` in all CI builds CI will also fail if we accidently add it locally.
|
||||
- ignore `.pnpmfile.cjs` in all CI builds (CI will also fail if we accidently add it locally).
|
||||
- fixup the `pnpm-lock.yaml` in the renovate PR to contain the correct `pnpmfileChecksum`.
|
||||
|
||||
Ignoring in all CI builds means that CI will always fail if we enable the linking system.
|
||||
@@ -22,9 +22,9 @@ Only if we remember setting it back/disbale linking (or let ourselves remember b
|
||||
#### Summary
|
||||
|
||||
- We will always run into conflicts with the `pnpmfileChecksum` because in renovate prs it will be empty (`--ignore-pnpmfile`)
|
||||
- To keep it simple we set `--ignore-pnpmfile` in all of ours CI to see issues immediately.
|
||||
- To keep it simple we set `--ignore-pnpmfile` in all of our CI builds to see issues immediately.
|
||||
- The only solution is to never have a `.pnpmfile.cjs` in the repository when pushing.
|
||||
- This way there will never be a commit with `pnpmfileChecksum` in the lockfile.
|
||||
- renovate (which uses `--ignore-pnpmfile` which we cannot disable) and other CI will work
|
||||
- renovate (which uses `--ignore-pnpmfile` which we cannot disable) and other CI will work.
|
||||
- We are able to use the linking system locally if we `cp` this file from the scripts folder into `./` on demand.
|
||||
- `pnpm links:on` and `pnpm links:off` + `./scripts/setup-linking.sh` will help us with this.
|
||||
|
||||
@@ -58,7 +58,7 @@ rc_message:
|
||||
|
||||
rc_delayed_event_mgmt:
|
||||
# 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
|
||||
# Currently the heart-beat is every 5 seconds which translates into a rate of 0.2Hz
|
||||
per_second: 1
|
||||
burst_count: 20
|
||||
```
|
||||
@@ -70,7 +70,7 @@ make sure that your Synapse server has either a `federation` or `openid`
|
||||
|
||||
### MatrixRTC Backend
|
||||
|
||||
In order to **guarantee smooth operation** of Element Call MatrixRTC backend is
|
||||
In order to **guarantee smooth operation** of Element Call, a MatrixRTC backend is
|
||||
required for each site deployment.
|
||||
|
||||
|
||||
@@ -190,8 +190,8 @@ backend mxrtc_auth_backend
|
||||
|
||||
> [!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 **Matrix site's
|
||||
> [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143),
|
||||
> the MatrixRTC backend(s) must be announced to the client via your **Matrix site's
|
||||
> `.well-known/matrix/client`** file (e.g.
|
||||
> `example.com/.well-known/matrix/client` matching the site deployment example
|
||||
> from above). The configuration is a list of Foci configs:
|
||||
@@ -222,7 +222,7 @@ Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization
|
||||
|
||||
> [!NOTE]
|
||||
> Most `org.matrix.msc4143.rtc_foci` configurations will only have one entry in
|
||||
> the array
|
||||
> the array.
|
||||
|
||||
## Building Element Call
|
||||
|
||||
@@ -291,7 +291,7 @@ 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
|
||||
in the Matrix federated network. The homeserver used can be set up 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
|
||||
|
||||
@@ -12,7 +12,7 @@ https://element_call.domain/room/#
|
||||
```
|
||||
|
||||
The URL is split into two sections. The `https://element_call.domain/room/#`
|
||||
contains the app and the intend that the link brings you into a specific room
|
||||
contains the app and the intent that the link brings you into a specific room
|
||||
(`https://call.element.io/#` would be the homepage). The fragment is used for
|
||||
query parameters to make sure they never get sent to the element_call.domain
|
||||
server. Here we have the actual Matrix room ID and the password which are used
|
||||
@@ -76,16 +76,16 @@ These parameters are relevant to both [widget](./embedded_standalone.md) and [st
|
||||
|
||||
These parameters are only supported in [widget](./embedded_standalone.md) mode.
|
||||
|
||||
| Name | Values | Required | Description |
|
||||
| --------------- | ----------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `baseUrl` | | Yes | The base URL of the homeserver to use for media lookups. |
|
||||
| `deviceId` | Matrix device ID | Yes | The Matrix device ID for the widget host. |
|
||||
| `parentUrl` | | Yes | The url used to send widget action postMessages. This should be the domain of the client or the webview the widget is hosted in. (in case the widget is not in an Iframe but in a dedicated webview we send the postMessages same WebView the widget lives in. Filtering is done in the widget so it ignores the messages it receives from itself) |
|
||||
| `posthogUserId` | Posthog user identifier | No | This replaces the `analyticsID` parameter |
|
||||
| `preload` | `true` or `false` | No, defaults to `false` | Pauses app before joining a call until an `io.element.join` widget action is seen, allowing preloading. |
|
||||
| `returnToLobby` | `true` or `false` | No, defaults to `false` | Displays the lobby in widget mode after leaving a call; shows a blank page if set to `false`. Useful for video rooms. |
|
||||
| `userId` | [Matrix User Identifier](https://spec.matrix.org/v1.12/appendices/#user-identifiers) | Yes | The Matrix user ID. |
|
||||
| `widgetId` | [MSC2774](https://github.com/matrix-org/matrix-spec-proposals/pull/2774) format widget ID | Yes | The id used by the widget. The presence of this parameter implies that element call will not connect to a homeserver directly and instead tries to establish postMessage communication via the `parentUrl`. |
|
||||
| Name | Values | Required | Description |
|
||||
| --------------- | ----------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `baseUrl` | | Yes | The base URL of the homeserver to use for media lookups. |
|
||||
| `deviceId` | Matrix device ID | Yes | The Matrix device ID for the widget host. |
|
||||
| `parentUrl` | | Yes | The url used to send widget action postMessages. This should be the domain of the client or the webview the widget is hosted in. (In case the widget is not in an Iframe but in a dedicated webview, we send the postMessages in the same WebView the widget lives in. Filtering is done in the widget so it ignores the messages it receives from itself.) |
|
||||
| `posthogUserId` | Posthog user identifier | No | This replaces the `analyticsID` parameter |
|
||||
| `preload` | `true` or `false` | No, defaults to `false` | Pauses app before joining a call until an `io.element.join` widget action is seen, allowing preloading. |
|
||||
| `returnToLobby` | `true` or `false` | No, defaults to `false` | Displays the lobby in widget mode after leaving a call; shows a blank page if set to `false`. Useful for video rooms. |
|
||||
| `userId` | [Matrix User Identifier](https://spec.matrix.org/v1.12/appendices/#user-identifiers) | Yes | The Matrix user ID. |
|
||||
| `widgetId` | [MSC2774](https://github.com/matrix-org/matrix-spec-proposals/pull/2774) format widget ID | Yes | The id used by the widget. The presence of this parameter implies that element call will not connect to a homeserver directly and instead tries to establish postMessage communication via the `parentUrl`. |
|
||||
|
||||
### Embedded-only parameters
|
||||
|
||||
|
||||
Reference in New Issue
Block a user