1
Fork 0
mirror of https://github.com/jech/galene.git synced 2024-11-14 04:35:57 +01:00
galene/README.FRONTEND

159 lines
5.9 KiB
Text
Raw Normal View History

2020-08-12 21:47:05 +02:00
# Writing a new frontend
2020-08-14 15:22:50 +02:00
The frontend is written in JavaScript and is split into two files:
2020-08-12 21:47:05 +02:00
2020-08-14 15:22:50 +02:00
- `protocol.js` contains the low-level functions that interact with the
server;
2020-12-06 19:43:17 +01:00
- `galene.js` contains the user interface.
2020-08-12 21:47:05 +02:00
2020-12-19 02:37:07 +01:00
A new frontend may either implement Galène's client-server protocol from
scratch, or it may use the functionality of `protocol.js`. This document
documents the latter approach.
2020-08-12 21:47:05 +02:00
## Data structures
The class `ServerConnection` encapsulates a connection to the server as
2020-12-19 02:37:07 +01:00
well as all the associated streams. Unless your frontend communicates
with multiple servers, it will probably create just a single instance of
this class.
2020-08-12 21:47:05 +02:00
2020-12-19 02:37:07 +01:00
The class `Stream` encapsulates a set of related audio and video tracks
(for example, an audio track from a microphone and a video track from
a webcam). A stream is said to go *up* when it carries data from the
client to the server, and *down* otherwise. Streams going up are created
by the client (your frontend), streams going down are created by the server.
2020-08-12 21:47:05 +02:00
## Connecting to the server
First, create a `ServerConnection` and set up all the callbacks:
2020-08-14 15:22:50 +02:00
```javascript
2020-08-12 21:47:05 +02:00
let sc = new ServerConnection()
serverConnection.onconnected = ...;
serverConnection.onclose = ...;
2020-08-14 15:22:50 +02:00
serverConnection.onusermessage = ...;
serverConnection.onjoined = ...;
2020-08-14 15:22:50 +02:00
serverConnection.onuser = ...;
2020-08-12 21:47:05 +02:00
serverConnection.onchat = ...;
serverConnection.onclearchat = ...;
2020-08-14 15:22:50 +02:00
serverConnection.ondownstream = ...;
2020-08-12 21:47:05 +02:00
```
The `onconnected` callback is called when we connect to the server. The
`onclose` callback is called when the socket is closed; you should use it
2020-12-19 02:37:07 +01:00
to close all your up streams (down streams will be closed by the server).
The `onusermessage` callback indicates an application-specific message,
either from another user or from the server; the field `kind` indicates
the kind of message.
Once you have joined a group (see below), the remaining callbacks may
trigger. The `onuser` callback is used to indicate that a user has joined
or left the current group. The `onchat` callback indicates that a chat
message has been posted to the group, and `onclearchat` indicates that the
chat history has been cleared. Finally, `ondownstream` is called when the
server pushes a stream to the client; see the section below about streams.
2020-08-14 15:22:50 +02:00
You may now connect to the server.
```javascript
2020-08-12 21:47:05 +02:00
serverConnection.connect(`wss://${location.host}/ws`);
```
2020-08-14 15:22:50 +02:00
You typically join a group and request media in the `onconnected` callback:
2020-08-14 15:22:50 +02:00
```javascript
2020-08-12 21:47:05 +02:00
serverConnection.onconnected = function() {
this.join(group, 'join', username, password);
2020-08-12 21:47:05 +02:00
this.request('everything');
}
```
2020-08-14 15:22:50 +02:00
You should not attempt to push a stream to the server until it has granted
you the `present` permission through the `onjoined` callback.
2020-08-14 15:22:50 +02:00
2020-08-12 21:47:05 +02:00
## Sending and receiving chat messages
2020-08-14 15:22:50 +02:00
Once you have joined a group, you send chat messages with the `chat`
2020-12-19 02:37:07 +01:00
method of the `ServerConnection` class. No permission is needed to do that.
2020-08-14 15:22:50 +02:00
```javascript
2020-12-19 02:37:07 +01:00
serverConnection.chat(username, '', id, 'Hi!');
2020-08-12 21:47:05 +02:00
```
2020-08-14 15:22:50 +02:00
2020-08-12 21:47:05 +02:00
You receive chat messages in the `onchat` callback. The server may
request that you clear your chat window, in that case the `onclearchat`
callback will trigger.
2020-12-19 02:37:07 +01:00
## Other messages
The `usermessage` method of the `ServerConnection` is similar to the
`chat` method, but it sends an application-specific message. Just like
chat messages, application-specific messages are not interpreted by the
server; unlike chat messages, they are not kept in the chat history.
The `useraction` method is used to ask the server to act on a remote user
(kick it, change its permissions, etc.); similarly, the `groupaction`
class requests an action to be performed on the current group. Most
actions require either the `Op` or the `Record` permission.
2020-08-12 21:47:05 +02:00
## Accepting incoming video streams
When the server pushes a stream to the client, the `ondownstream` callback
2020-08-14 15:22:50 +02:00
will trigger; you should set up the stream's callbacks here.
```javascript
serverConnection.ondownstream = function(stream) {
stream.onclose = ...;
stream.onerror = ...;
stream.ondowntrack = ...;
stream.onstatus = ...;
}
2020-08-12 21:47:05 +02:00
```
2020-08-14 15:22:50 +02:00
The `stream.labels` dictionary maps each track's id to one of `audio`,
`video` or `screenshare`. Since `stream.labels` is already available at
this point, you may set up an `audio` or `video` component straight away,
or you may choose to wait until the `ondowntrack` callback is called.
2020-08-12 21:47:05 +02:00
After a new stream is created, `ondowntrack` will be called whenever
a track is added. If the `MediaStream` passed to `ondowntrack` differs
from the one previously received, then the stream has been torn down and
recreated, and you must drop all previously received tracks; in practice,
it is enough to set the `srcObject` property of the video component to the
new stream.
2020-08-14 15:22:50 +02:00
The `onstatus` callback is invoked whenever the client library detects
a change in the status of the stream; states `connected` and `complete`
indicate a functioning stream; other states indicate that the stream is
not working right now but might recover in the future.
The `onclose` callback is called when the stream is destroyed by the
server.
2020-08-12 21:47:05 +02:00
## Pushing outgoing video streams
If you have the `present` permission, you may use the `newUpStream` method
2020-08-14 15:22:50 +02:00
to push a stream to the server. Given a `MediaStream` called `localStream`
(as obtained from `getUserMedia` or `getDisplayMedia`).
```javascript
let stream = serverConnection.newUpStream();
2020-08-12 21:47:05 +02:00
stream.onerror = ...;
stream.onabort = ...;
stream.onstatus = ...;
localStream.getTracks().forEach(t => {
c.labels[t.id] = t.kind;
c.pc.addTrack(t, c.stream);
});
```
2020-08-14 15:22:50 +02:00
See above for information about setting up the `labels` dictionary.
2020-08-12 21:47:05 +02:00
2020-08-14 15:22:50 +02:00
## Stream statistics
2020-08-12 21:47:05 +02:00
2020-12-19 02:37:07 +01:00
Some statistics about streams are made available by calling the
`setStatsInterval` method and setting the `onstats` callback. These
include the data rate for streams in the up direction, and the average
audio energy (the square of the volume) for streams in the down direction.
2020-08-12 21:47:05 +02:00
--- Juliusz Chroboczek <https://www.irif.fr/~jch/>