@dtelecom/livekit-client 1.12.24 → 1.12.26

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/README.md CHANGED
@@ -1,47 +1,86 @@
1
- # JavaScript/TypeScript client SDK
1
+ # dTelecom JavaScript/TypeScript client SDK
2
2
 
3
- ## Docs
3
+ `@dtelecom/livekit-client` connects a browser to dTelecom rooms: join, publish camera, microphone and screen, and receive other participants' tracks and data. It is dTelecom's build of the LiveKit client and works with dTelecom Cloud.
4
4
 
5
- Docs and guides at [https://docs.dtelecom.org](https://docs.dtelecom.org)
5
+ Your backend creates the participant token with the server SDK ([`@dtelecom/server-sdk-js`](https://github.com/dTelecom/server-sdk-js) or [`server-sdk-go`](https://github.com/dTelecom/server-sdk-go)); the browser only gets the token and the node URL. Never put the API key or secret in browser code.
6
6
 
7
7
  ## Installation
8
8
 
9
- ### Yarn
9
+ ```shell
10
+ npm install @dtelecom/livekit-client
11
+ ```
12
+
13
+ or
10
14
 
11
15
  ```shell
12
16
  yarn add @dtelecom/livekit-client
13
17
  ```
14
18
 
15
- ### NPM
19
+ ### Without a bundler
16
20
 
17
- ```shell
18
- npm install @dtelecom/livekit-client --save
21
+ The browser build registers a global named `LivekitClient` (from 1.12.25):
22
+
23
+ ```html
24
+ <script src="https://unpkg.com/@dtelecom/livekit-client@1.12.25/dist/livekit-client.umd.js"></script>
25
+ <script type="module">
26
+ const { Room, RoomEvent } = LivekitClient;
27
+ const { token, wsUrl } = await (await fetch('/api/token')).json();
28
+ const room = new Room();
29
+ await room.connect(wsUrl, token);
30
+ </script>
31
+ ```
32
+
33
+ Versions up to 1.12.24 register `window['@dtelecom/livekitClient']`; that name still works.
34
+
35
+ ## Getting a token
36
+
37
+ On your server, with dTelecom Cloud credentials (`DTELECOM_API_KEY`, `DTELECOM_API_SECRET`, `DTELECOM_CLOUD_URL`):
38
+
39
+ ```typescript
40
+ import { CloudClient } from '@dtelecom/server-sdk-js';
41
+
42
+ const cloud = new CloudClient();
43
+
44
+ // e.g. GET /api/token
45
+ const { token, wsUrl, sessionId, expiresAt } = await cloud.createToken({
46
+ room: 'my-room',
47
+ identity: userId, // unique in the room; a second connection with it replaces the first
48
+ name: userName,
49
+ clientIp: request.ip, // picks the node nearest to the user
50
+ });
51
+ // send { token, wsUrl } to the browser
19
52
  ```
20
53
 
54
+ A token lasts 6 hours by default (at most 24). For longer sessions your backend extends it with `cloud.extendToken(sessionId, '1h')` before `expiresAt`; a participant whose token expired without an extension is removed from the room about a minute later.
55
+
21
56
  ## Usage
22
57
 
23
- Examples below are in TypeScript, if using JS/CommonJS imports replace import with:
58
+ Examples below are in TypeScript. With CommonJS:
24
59
 
25
60
  ```javascript
26
- const livekit = require('@dtelecom/livekit-client');
27
-
28
- const room = new livekit.Room(...);
29
- await room.connect(...);
61
+ const { Room } = require('@dtelecom/livekit-client');
30
62
  ```
31
63
 
32
64
  ### Connecting to a room, publish video & audio
33
65
 
34
66
  ```typescript
35
67
  import {
68
+ DisconnectReason,
69
+ LocalParticipant,
70
+ LocalTrackPublication,
36
71
  Participant,
37
72
  RemoteParticipant,
38
73
  RemoteTrack,
39
74
  RemoteTrackPublication,
40
75
  Room,
41
76
  RoomEvent,
77
+ Track,
78
+ VideoPresets,
42
79
  } from '@dtelecom/livekit-client';
43
80
 
44
- // creates a new room with options
81
+ // token and wsUrl come from your backend (see "Getting a token")
82
+ const { token, wsUrl } = await (await fetch('/api/token')).json();
83
+
45
84
  const room = new Room({
46
85
  // automatically manage subscribed video quality
47
86
  adaptiveStream: true,
@@ -63,8 +102,8 @@ room
63
102
  .on(RoomEvent.Disconnected, handleDisconnect)
64
103
  .on(RoomEvent.LocalTrackUnpublished, handleLocalTrackUnpublished);
65
104
 
66
- // connect to room
67
- await room.connect('ws://localhost:7800', token);
105
+ // connect to the node your backend got with the token
106
+ await room.connect(wsUrl, token);
68
107
  console.log('connected to room', room.name);
69
108
 
70
109
  // publish local camera and mic tracks
@@ -91,27 +130,25 @@ function handleTrackUnsubscribed(
91
130
  track.detach();
92
131
  }
93
132
 
94
- function handleLocalTrackUnpublished(track: LocalTrackPublication, participant: LocalParticipant) {
133
+ function handleLocalTrackUnpublished(publication: LocalTrackPublication, participant: LocalParticipant) {
95
134
  // when local tracks are ended, update UI to remove them from rendering
96
- track.detach();
135
+ publication.track?.detach();
97
136
  }
98
137
 
99
138
  function handleActiveSpeakerChange(speakers: Participant[]) {
100
139
  // show UI indicators when participant is speaking
101
140
  }
102
141
 
103
- function handleDisconnect() {
104
- console.log('disconnected from room');
142
+ function handleDisconnect(reason?: DisconnectReason) {
143
+ // CLIENT_INITIATED: room.disconnect(); PARTICIPANT_REMOVED: removed by your backend or after
144
+ // the token expired; DUPLICATE_IDENTITY: the same identity joined elsewhere; ROOM_DELETED
145
+ console.log('disconnected from room', reason);
105
146
  }
106
147
  ```
107
148
 
108
- In order to connect to a room, you need to first create an access token.
109
-
110
- See [access token docs](https://docs.dtelecom.org/guides/access-tokens) for details
111
-
112
149
  ### Handling common track types
113
150
 
114
- While LiveKit is designed to be flexible, we've added a few shortcuts that makes working with common track types simple. For a user's camera, microphone, and screen share, you can enable them with the following `LocalParticipant` methods:
151
+ There are shortcuts that make working with common track types simple. For a user's camera, microphone, and screen share, you can enable them with the following `LocalParticipant` methods:
115
152
 
116
153
  ```typescript
117
154
  const p = room.localParticipant;