mirror of
https://github.com/vector-im/element-call.git
synced 2026-10-16 23:45:50 +00:00
Timo K.
d0a2ff12f1
The session speaks MatrixRTC and sees media through MediaBackend in sdk/src/backend/api.ts. Everything LiveKit lives in sdk/src/backend/livekit/, the only place in the SDK that imports livekit-client; the import boundary rule now enforces that outside sdk/src/backend/ the LiveKit packages appear in type imports only. The seam sits above the connection manager: one connection per transport url is the LiveKit multi-SFU strategy, not a MatrixRTC concept, so a cascading SFU or full mesh replaces the folder, not the session. A backend prepares the local transport the session discovered (the token exchange and the delegation probe, reported as canDelegateDelayedLeave), hands the delayed leave over per delay id, gives the local member one publish switch plus publish/unpublish, builds a remote member's media from its membership and registers that membership's transport for as long as the member lives, and reports its connections for the transport registry, which keys on the raw transport serialised with sorted keys. The backend's context carries no Matrix client (a backend picks what it calls in its own options), no membership list, and no js-sdk session: media keys arrive as a stream replayed on subscribe, and MatrixKeyProvider subscribes to it. The MatrixRTC mode no longer reaches LiveKit; it becomes a tokenEndpoint choice made where the default backend is built. Two behaviour changes ride along. Publishing is one boolean, joined and homeserver reachable, where before a sync hiccup after leave() resumed the upstream of tracks that were meant to stay silent. And ResolvedConnection keeps one ResolvedTransport object per fetch, so a state change no longer reads as a change of what was fetched. MatrixRTCClientOptions gains backend?: MediaBackendFactory, defaulting to createLivekitBackend built from the client options. authenticateWithTransport takes tokenEndpoint instead of matrixRTCMode.
77 lines
2.4 KiB
Markdown
77 lines
2.4 KiB
Markdown
# MatrixRTC SDK (EXPERIMENTAL)
|
|
|
|
`@element-hq/matrixrtc-sdk` is the call model under Element Call, on its own:
|
|
MatrixRTC memberships and transports, media connections, publishing, E2EE keys and
|
|
the media of every member, as observables. It has no UI. Element Call's own
|
|
`CallViewModel` is meant to become one consumer of it. The design is in
|
|
[`SdkArchitecture.md`](./SdkArchitecture.md), the migration from the view model
|
|
in [`SdkMigration.md`](./SdkMigration.md). Media goes through one media backend
|
|
behind `MediaBackend`; LiveKit, under `src/backend/livekit/`, is the only one
|
|
today and the only place that imports `livekit-client`.
|
|
|
|
**Status:** first implementation. `createMatrixRTCClient` joins the session, connects to
|
|
the transport, publishes the local media and exposes every member's media; the
|
|
development harness and its e2e tests in `playwright/sdk` drive it, and Element
|
|
Call's own `CallViewModel` is built on it. It depends on nothing in Element Call's
|
|
`src/`.
|
|
|
|
## Using it
|
|
|
|
```ts
|
|
import {
|
|
constant,
|
|
createMatrixRTCClient,
|
|
E2eeType,
|
|
MatrixRTCMode,
|
|
ObservableScope,
|
|
} from "@element-hq/matrixrtc-sdk";
|
|
|
|
const scope = new ObservableScope();
|
|
const rtcClient = createMatrixRTCClient(
|
|
scope,
|
|
client, // a matrix-js-sdk MatrixClient, logged in and syncing
|
|
room, // the matrix-js-sdk Room, from client.getRoom() once the join has synced
|
|
{
|
|
publish: [{ source: "microphone" }, { source: "camera" }],
|
|
audioOutputDeviceId$: constant(undefined),
|
|
},
|
|
{
|
|
encryptionSystem: { kind: E2eeType.PER_PARTICIPANT },
|
|
matrixRTCMode: MatrixRTCMode.Compatibility,
|
|
},
|
|
);
|
|
rtcClient.join();
|
|
|
|
rtcClient.remoteMembers$.subscribe((members) => {
|
|
// each member has displayName$, media$ and more; a media track is rendered
|
|
// by handing it a <video> or <audio> element: track.attach(element)
|
|
});
|
|
|
|
// later
|
|
rtcClient.leave();
|
|
scope.end();
|
|
```
|
|
|
|
[`dev/main.ts`](./dev/main.ts) is this example as a working page.
|
|
|
|
## Development
|
|
|
|
Everything runs from the repository root. This directory is a pnpm project of its
|
|
own only so that a host can install it as a git dependency (see
|
|
`pnpm-workspace.yaml`).
|
|
|
|
```sh
|
|
pnpm dev:sdk # the harness, https://localhost:3002
|
|
pnpm build:sdk # dist/matrixrtc-sdk.js and dist/types
|
|
pnpm test:playwright playwright/sdk # needs `pnpm backend`
|
|
```
|
|
|
|
## Installing
|
|
|
|
```sh
|
|
pnpm add github:element-hq/element-call#<ref>&path:/sdk
|
|
```
|
|
|
|
The host supplies `matrix-js-sdk`, `livekit-client` and `rxjs`; the build leaves
|
|
them external.
|