@wtfalch/calls 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/livekit.mjs ADDED
@@ -0,0 +1,343 @@
1
+ import {
2
+ Room, RoomEvent, Track, LocalAudioTrack, LocalVideoTrack,
3
+ ExternalE2EEKeyProvider, isE2EESupported,
4
+ } from 'livekit-client';
5
+
6
+ // Per-sender E2EE key provider. One sender key per identity, keyed by index,
7
+ // installed through setSenderKey rather than the shared-passphrase path
8
+ // ExternalE2EEKeyProvider.setKey() offers -- the engine only ever hands this
9
+ // adapter a per-sender key set (browser.d.ts's connect() takes `keys`, never
10
+ // a shared `key`), so that path is the only one implemented here.
11
+ class SenderKeyProvider extends ExternalE2EEKeyProvider {
12
+ constructor(localIdentity) {
13
+ super();
14
+ this.localIdentity = localIdentity;
15
+ this.localKeyIndex = 0;
16
+ }
17
+
18
+ getOptions() {
19
+ return { ...super.getOptions(), sharedKey: false, keyringSize: 256, ratchetWindowSize: 0 };
20
+ }
21
+
22
+ getLatestManuallySetKeyIndex() {
23
+ return this.localKeyIndex;
24
+ }
25
+
26
+ async setSenderKey(key, participantIdentity, keyIndex) {
27
+ const bytes = Uint8Array.from(atob(key), (c) => c.charCodeAt(0));
28
+ const material = await crypto.subtle.importKey('raw', bytes, 'HKDF', false, ['deriveBits', 'deriveKey']);
29
+ this.onSetEncryptionKey(material, participantIdentity, keyIndex);
30
+ if (participantIdentity === this.localIdentity) this.localKeyIndex = keyIndex;
31
+ }
32
+ }
33
+
34
+ // Same shape check the engine's own MediaLifecycle.validateKeys() applies
35
+ // before it ever calls connect() -- repeated here because installKeys() and
36
+ // a direct (non-engine) caller reach this adapter without that guard.
37
+ function validateKeys(keys, localIdentity, requireLocal = true) {
38
+ if (!Array.isArray(keys) || !keys.length || typeof localIdentity !== 'string' || !localIdentity) throw new Error('media_authority_unavailable');
39
+ const identities = new Set();
40
+ let local = 0;
41
+ for (const entry of keys) {
42
+ if (!entry || typeof entry.identity !== 'string' || !entry.identity || identities.has(entry.identity) || !Number.isInteger(entry.index) || entry.index < 0 || entry.index > 255 || typeof entry.key !== 'string' || !/^[A-Za-z0-9+/]{43}=$/.test(entry.key)) throw new Error('media_authority_unavailable');
43
+ identities.add(entry.identity); if (entry.identity === localIdentity) local++;
44
+ }
45
+ if (requireLocal ? local !== 1 : local > 1) throw new Error('media_authority_unavailable');
46
+ }
47
+
48
+ // A participant's connectionQuality is already one of these exact strings
49
+ // (see ConnectionQuality in livekit-client's Participant.d.ts); this is a
50
+ // whitelist rather than a passthrough so an unrecognized value reads as
51
+ // 'unknown' instead of leaking an arbitrary string.
52
+ const QUALITY = { excellent: 'excellent', good: 'good', poor: 'poor', lost: 'lost', unknown: 'unknown' };
53
+
54
+ /** @wtfalch/calls/livekit -- a real LiveKit media adapter. It owns
55
+ * livekit-client, devices and tracks; the engine that injects it owns
56
+ * authority, keys and lifecycle. See packages/sdk/browser.d.ts for the
57
+ * contract this implements, and packages/sdk/README.md for how to wire it up.
58
+ */
59
+ export function createLiveKitAdapter({ worker, capture = {} } = {}) {
60
+ // Caller-owned, not this adapter's: it is never terminated here, so the
61
+ // same worker instance survives every leave()/connect() cycle the engine
62
+ // drives across a reconnect. See the Decisions in the shipping report for
63
+ // why (livekit-client's E2EEManager documents worker reuse across Room
64
+ // instances; dist/src/e2ee/E2eeManager.d.ts's dispose() comment).
65
+ if (!worker) throw new Error('livekit_adapter_worker_required');
66
+
67
+ let room, keyProvider, connectionCount = 0, keyMetadata = [];
68
+ const errors = [];
69
+ // Remote tracks this adapter is subscribed to, keyed by trackSid. Built
70
+ // from TrackSubscribed/TrackUnsubscribed; read by stats() only -- attach()
71
+ // reads live publications off the room directly, not this map.
72
+ const remoteTracks = new Map();
73
+ let localAudioTrack, localVideoTrack, screenTrack;
74
+ let onMediaChangeCb = () => {};
75
+ // Remembered per MediaDeviceKind ('audioinput' | 'videoinput' | 'audiooutput')
76
+ // so the next capture (mic/camera) or the next connect() (speaker) picks up
77
+ // what useDevice() last asked for.
78
+ const preferredDevice = {};
79
+
80
+ function audioConstraints() {
81
+ const deviceId = preferredDevice.audioinput;
82
+ return deviceId ? { deviceId: { exact: deviceId } } : true;
83
+ }
84
+ function videoConstraints() {
85
+ const deviceId = preferredDevice.videoinput;
86
+ return deviceId ? { deviceId: { exact: deviceId } } : true;
87
+ }
88
+
89
+ async function toggle(source, enabled) {
90
+ if (!room) throw new Error('media_authority_unavailable');
91
+ const track = room.localParticipant.getTrackPublication(source)?.track;
92
+ if (!track) return;
93
+ await (enabled ? track.unmute() : track.mute());
94
+ }
95
+
96
+ // The one stop path for a screen share, whether the application asked
97
+ // (unpublishScreen) or the browser's own "stop sharing" control ended the
98
+ // track (the 'ended' listener in publishScreen). Both funnel through here
99
+ // so only one of them ever finds a track left to unpublish.
100
+ async function releaseScreen() {
101
+ const track = screenTrack;
102
+ screenTrack = undefined;
103
+ if (!track) return;
104
+ if (room) await room.localParticipant.unpublishTrack(track, true);
105
+ else track.stop();
106
+ }
107
+
108
+ return {
109
+ // Answers the package's construction-time check: an environment that
110
+ // cannot encrypt media is refused before a call starts.
111
+ supported() { return isE2EESupported(); },
112
+
113
+ async connect({ url, token, keys, localIdentity, controlled = true, onUnsafe = () => {}, onMediaChange } = {}) {
114
+ if (!isE2EESupported()) throw new Error('e2ee_unavailable');
115
+ validateKeys(keys, localIdentity);
116
+ onMediaChangeCb = typeof onMediaChange === 'function' ? onMediaChange : () => {};
117
+ keyMetadata = keys.map(({ identity, index }) => ({ identity, index }));
118
+ keyProvider = new SenderKeyProvider(localIdentity);
119
+ // Install the local identity's key last: the same ordering the engine
120
+ // itself relies on elsewhere, so a partial install never leaves a peer
121
+ // key in place without the local one.
122
+ for (const entry of [...keys].sort((a, b) => (a.identity === localIdentity ? 1 : 0) - (b.identity === localIdentity ? 1 : 0))) await keyProvider.setSenderKey(entry.key, entry.identity, entry.index);
123
+ const activeRoom = new Room({
124
+ adaptiveStream: false, dynacast: false,
125
+ ...(controlled ? { reconnectPolicy: { nextRetryDelayInMs: () => null } } : {}),
126
+ e2ee: { keyProvider, worker },
127
+ publishDefaults: { videoCodec: 'vp8', simulcast: false },
128
+ ...(preferredDevice.audiooutput ? { audioOutput: { deviceId: preferredDevice.audiooutput } } : {}),
129
+ });
130
+ room = activeRoom;
131
+ // The worker outlives every Room, so a superseded Room's decrypt error can
132
+ // still arrive here. Only the live Room may end the call.
133
+ room.on(RoomEvent.EncryptionError, () => { if (room !== activeRoom) return; errors.push('encryption_error'); onUnsafe(); });
134
+ if (controlled) {
135
+ const unsafe = () => { if (room === activeRoom) onUnsafe(); };
136
+ room.on(RoomEvent.Reconnecting, unsafe);
137
+ room.on(RoomEvent.SignalReconnecting, unsafe);
138
+ room.on(RoomEvent.Disconnected, unsafe);
139
+ }
140
+ const notify = () => onMediaChangeCb();
141
+ // Remote audio plays without the application doing anything: attach it
142
+ // to a hidden element the moment it is subscribed. Video (camera,
143
+ // screen) gets no such default -- attach() is how a UI puts it somewhere.
144
+ room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
145
+ remoteTracks.set(publication.trackSid, { track, publication, participant });
146
+ if (track.kind === Track.Kind.Audio) {
147
+ const element = track.attach();
148
+ element.autoplay = true;
149
+ document.body.append(element);
150
+ element.play().catch(() => errors.push('autoplay_blocked'));
151
+ }
152
+ notify();
153
+ });
154
+ room.on(RoomEvent.TrackUnsubscribed, (track, publication) => {
155
+ for (const element of track.detach()) element.remove();
156
+ remoteTracks.delete(publication.trackSid);
157
+ notify();
158
+ });
159
+ for (const event of [
160
+ RoomEvent.TrackPublished, RoomEvent.TrackUnpublished,
161
+ RoomEvent.TrackMuted, RoomEvent.TrackUnmuted,
162
+ RoomEvent.LocalTrackPublished, RoomEvent.LocalTrackUnpublished,
163
+ RoomEvent.ActiveSpeakersChanged, RoomEvent.ConnectionQualityChanged,
164
+ RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected,
165
+ RoomEvent.MediaDevicesChanged,
166
+ ]) room.on(event, notify);
167
+ await activeRoom.setE2EEEnabled(true);
168
+ await activeRoom.connect(url, token, { autoSubscribe: true, maxRetries: 0, peerConnectionTimeout: 15000 });
169
+ connectionCount++;
170
+ return { state: activeRoom.state, encryption: activeRoom.isE2EEEnabled };
171
+ },
172
+
173
+ async installKeys(entries) {
174
+ if (!(keyProvider instanceof SenderKeyProvider) || !room) throw new Error('media_authority_unavailable');
175
+ validateKeys(entries, room.localParticipant.identity, false);
176
+ for (const entry of [...entries].sort((a, b) => (a.identity === room.localParticipant.identity ? 1 : 0) - (b.identity === room.localParticipant.identity ? 1 : 0))) await keyProvider.setSenderKey(entry.key, entry.identity, entry.index);
177
+ const next = new Map(keyMetadata.map((entry) => [entry.identity, entry]));
178
+ for (const { identity, index } of entries) next.set(identity, { identity, index });
179
+ keyMetadata = [...next.values()];
180
+ },
181
+
182
+ async publishAudio(authority = { canPublish: () => true }) {
183
+ if (!room) throw new Error('media_authority_unavailable');
184
+ if (!authority.canPublish()) throw new Error('media_authority_unavailable');
185
+ const mediaTrack = capture.audio
186
+ ? await capture.audio()
187
+ : (await navigator.mediaDevices.getUserMedia({ audio: audioConstraints() })).getAudioTracks()[0];
188
+ // authority can be lost while a permission prompt is pending; check
189
+ // again before this ever reaches the room.
190
+ if (!authority.canPublish()) { mediaTrack.stop(); throw new Error('media_authority_unavailable'); }
191
+ // userProvidedTrack=true: mute()/unmute() below then only flip
192
+ // mediaStreamTrack.enabled, never stop or reacquire the device.
193
+ localAudioTrack = new LocalAudioTrack(mediaTrack, undefined, true);
194
+ await room.localParticipant.publishTrack(localAudioTrack, { source: Track.Source.Microphone });
195
+ },
196
+
197
+ async publishVideo(authority = { canPublish: () => true }) {
198
+ if (!room) throw new Error('media_authority_unavailable');
199
+ if (!authority.canPublish()) throw new Error('media_authority_unavailable');
200
+ const mediaTrack = capture.video
201
+ ? await capture.video()
202
+ : (await navigator.mediaDevices.getUserMedia({ video: videoConstraints() })).getVideoTracks()[0];
203
+ if (!authority.canPublish()) { mediaTrack.stop(); throw new Error('media_authority_unavailable'); }
204
+ localVideoTrack = new LocalVideoTrack(mediaTrack, undefined, true);
205
+ await room.localParticipant.publishTrack(localVideoTrack, { source: Track.Source.Camera, simulcast: false, videoCodec: 'vp8' });
206
+ },
207
+
208
+ // Local capture toggles, not a publish/unpublish: mute() and unmute() on
209
+ // a userProvidedTrack (see publishAudio/publishVideo above) only flip
210
+ // mediaStreamTrack.enabled -- no renegotiation, no device reacquired.
211
+ async setMicrophoneEnabled(enabled) { await toggle(Track.Source.Microphone, enabled); },
212
+ async setCameraEnabled(enabled) { await toggle(Track.Source.Camera, enabled); },
213
+
214
+ async publishScreen(authority = { canPublish: () => true }, onEnded = () => {}) {
215
+ if (!room) throw new Error('media_authority_unavailable');
216
+ if (!authority.canPublish()) throw new Error('media_authority_unavailable');
217
+ const mediaTrack = capture.screen
218
+ ? await capture.screen()
219
+ : (await navigator.mediaDevices.getDisplayMedia({ video: true })).getVideoTracks()[0];
220
+ if (!authority.canPublish()) { mediaTrack.stop(); throw new Error('media_authority_unavailable'); }
221
+ const track = new LocalVideoTrack(mediaTrack, undefined, true);
222
+ // Registered synchronously, before any await below, so this listener
223
+ // is in place ahead of livekit-client's own (added asynchronously when
224
+ // the track's internal state is set up). The browser's own "stop
225
+ // sharing" control ends the track without asking this module; this is
226
+ // the listener that answers it, same as an explicit unpublishScreen().
227
+ // livekit-client also unpublishes an ended screen-share track by
228
+ // itself -- releaseScreen() clears `screenTrack` first, so that second
229
+ // unpublish finds nothing left to do and onEnded() fires exactly once.
230
+ mediaTrack.addEventListener('ended', async () => { if (screenTrack === track) { await releaseScreen(); onEnded(); } }, { once: true });
231
+ screenTrack = track;
232
+ await room.localParticipant.publishTrack(track, { source: Track.Source.ScreenShare, simulcast: false, videoCodec: 'vp8' });
233
+ },
234
+ async unpublishScreen() { await releaseScreen(); },
235
+
236
+ // Lists without asking for permission. Room.getLocalDevices() with no
237
+ // kind always opens the microphone and camera to learn their labels, so
238
+ // a device menu would start a capture. Before the call has a device,
239
+ // labels come back empty; after it, they are filled in.
240
+ async devices() {
241
+ const list = await navigator.mediaDevices.enumerateDevices();
242
+ return list.filter(({ kind }) => ['audioinput', 'videoinput', 'audiooutput'].includes(kind)).map(({ kind, deviceId, label }) => ({ kind, deviceId, label }));
243
+ },
244
+
245
+ async useDevice(kind, deviceId) {
246
+ preferredDevice[kind] = deviceId;
247
+ if (room) await room.switchActiveDevice(kind, deviceId);
248
+ },
249
+
250
+ // Synchronous, keyed by LiveKit identity, local participant included.
251
+ // Reads live off the room rather than tracking a parallel copy of its
252
+ // state, so there is nothing here that can drift from what the room says.
253
+ media() {
254
+ if (!room) return {};
255
+ const result = {};
256
+ for (const participant of [room.localParticipant, ...room.remoteParticipants.values()]) {
257
+ const mic = participant.getTrackPublication(Track.Source.Microphone);
258
+ const camera = participant.getTrackPublication(Track.Source.Camera);
259
+ const screen = participant.getTrackPublication(Track.Source.ScreenShare);
260
+ // Decision: a participant whose every publication is muted -- or who
261
+ // has published nothing at all -- still gets an entry, with every
262
+ // flag false. Nothing here distinguishes "never published" from
263
+ // "muted"; a UI that cares keeps its own memory of which is which.
264
+ result[participant.identity] = {
265
+ microphone: !!mic && !mic.isMuted,
266
+ camera: !!camera && !camera.isMuted,
267
+ screen: !!screen && !screen.isMuted,
268
+ speaking: participant.isSpeaking,
269
+ quality: QUALITY[participant.connectionQuality] ?? 'unknown',
270
+ };
271
+ }
272
+ return result;
273
+ },
274
+
275
+ // Decision: a source that is not yet published or not yet subscribed
276
+ // throws 'track_unavailable' rather than waiting or returning a no-op
277
+ // detach. A UI re-attaches once media() reports that source live -- the
278
+ // simplest contract that does not silently show a blank element.
279
+ attach(identity, source, element) {
280
+ const trackSource = source === 'camera' ? Track.Source.Camera : source === 'screen' ? Track.Source.ScreenShare : undefined;
281
+ if (!trackSource) throw Object.assign(new Error('track_unavailable'), { code: 'track_unavailable' });
282
+ const participant = room && (identity === room.localParticipant.identity ? room.localParticipant : room.remoteParticipants.get(identity));
283
+ const track = participant?.getTrackPublication(trackSource)?.track;
284
+ if (!track) throw Object.assign(new Error('track_unavailable'), { code: 'track_unavailable' });
285
+ track.attach(element);
286
+ return () => { track.detach(element); };
287
+ },
288
+
289
+ async stats() {
290
+ const tracks = [];
291
+ for (const { track, publication, participant } of remoteTracks.values()) {
292
+ const report = await track.getRTCStatsReport();
293
+ const inbound = [...(report?.values() ?? [])].find((s) => s.type === 'inbound-rtp');
294
+ tracks.push({
295
+ identity: participant.identity, trackSid: publication.trackSid, kind: track.kind,
296
+ source: publication.source, muted: publication.isMuted,
297
+ encrypted: publication.isEncrypted,
298
+ packetsReceived: inbound?.packetsReceived ?? 0,
299
+ framesDecoded: inbound?.framesDecoded ?? 0,
300
+ audioEnergy: inbound?.totalAudioEnergy ?? 0,
301
+ // The proof reads element.videoWidth; this adapter does not attach
302
+ // an element to every track by default (see attach() above), so
303
+ // width comes off the received MediaStreamTrack's own settings
304
+ // instead -- populated whether or not a UI has attached it yet.
305
+ width: track.mediaStreamTrack?.getSettings?.().width ?? 0,
306
+ });
307
+ }
308
+ return {
309
+ localTracks: [localAudioTrack, localVideoTrack].filter((t) => t && t.mediaStreamTrack.readyState === 'live').length,
310
+ screenTracks: screenTrack ? 1 : 0,
311
+ state: room?.state, encryption: room?.isE2EEEnabled, connectionCount,
312
+ keyMode: 'per-sender',
313
+ keys: keyMetadata.map(({ identity, index }) => ({ identity, index })),
314
+ tracks, errors: [...errors],
315
+ };
316
+ },
317
+
318
+ // Private SDK instrumentation for an adversarial test only. The product
319
+ // API must never expose this property. The token is held in memory,
320
+ // never logged.
321
+ retainedToken() { return room?.engine?.token ?? null; },
322
+
323
+ stopCapture() {
324
+ localAudioTrack?.stop(); localAudioTrack = undefined;
325
+ localVideoTrack?.stop(); localVideoTrack = undefined;
326
+ screenTrack?.stop(); screenTrack = undefined;
327
+ },
328
+
329
+ async leave() {
330
+ localAudioTrack?.stop(); localAudioTrack = undefined;
331
+ localVideoTrack?.stop(); localVideoTrack = undefined;
332
+ screenTrack?.stop(); screenTrack = undefined;
333
+ const previousRoom = room; room = undefined;
334
+ keyProvider = undefined;
335
+ // disconnect() keeps emitting while it tears down, and never drops its
336
+ // listeners, so a late TrackSubscribed could leave an <audio> behind.
337
+ previousRoom?.removeAllListeners();
338
+ await previousRoom?.disconnect();
339
+ for (const { track } of remoteTracks.values()) for (const element of track.detach()) element.remove();
340
+ remoteTracks.clear();
341
+ },
342
+ };
343
+ }
package/package.json ADDED
@@ -0,0 +1,64 @@
1
+ {
2
+ "name": "@wtfalch/calls",
3
+ "version": "0.1.0",
4
+ "description": "Framework-independent SDK for Agora calls: session control (admission, guest links, moderation) and a media-ready browser call handle.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/wtfalch/calls.git",
10
+ "directory": "packages/sdk"
11
+ },
12
+ "publishConfig": {
13
+ "access": "public"
14
+ },
15
+ "exports": {
16
+ ".": {
17
+ "types": "./index.d.ts",
18
+ "import": "./index.mjs"
19
+ },
20
+ "./browser": {
21
+ "types": "./browser.d.ts",
22
+ "import": "./browser.mjs"
23
+ },
24
+ "./livekit": {
25
+ "types": "./livekit.d.ts",
26
+ "import": "./livekit.mjs"
27
+ },
28
+ "./engine/*": {
29
+ "import": "./engine/*"
30
+ },
31
+ "./package.json": "./package.json"
32
+ },
33
+ "files": [
34
+ "index.mjs",
35
+ "index.d.ts",
36
+ "browser.mjs",
37
+ "browser.d.ts",
38
+ "livekit.mjs",
39
+ "livekit.d.ts",
40
+ "engine",
41
+ "LICENSE",
42
+ "README.md"
43
+ ],
44
+ "scripts": {
45
+ "test": "node --test test/*.test.mjs",
46
+ "prepack": "cp ../../LICENSE ."
47
+ },
48
+ "peerDependencies": {
49
+ "@matrix-org/matrix-sdk-crypto-wasm": "18.8.0",
50
+ "livekit-client": "2.22.3"
51
+ },
52
+ "peerDependenciesMeta": {
53
+ "livekit-client": {
54
+ "optional": true
55
+ }
56
+ },
57
+ "devDependencies": {
58
+ "@matrix-org/matrix-sdk-crypto-wasm": "18.8.0",
59
+ "livekit-client": "2.22.3"
60
+ },
61
+ "engines": {
62
+ "node": ">=24"
63
+ }
64
+ }