1
Fork 0
mirror of https://github.com/jech/galene.git synced 2024-11-22 08:35:57 +01:00

Improve documentation.

This commit is contained in:
Juliusz Chroboczek 2020-12-19 02:37:07 +01:00
parent a2f5bb82d1
commit 3afc3d06a0
2 changed files with 56 additions and 29 deletions

18
README
View file

@ -77,9 +77,25 @@ If you are using *runit*, use a script like the following:
#!/bin/sh #!/bin/sh
exec 2>&1 exec 2>&1
cd ~galene cd ~galene
ulimit -n 65536
exec setuidgid galene ./galene exec setuidgid galene ./galene
If you are using *systemd*, use `Type=simple` in your service file. If you are using *systemd*, something like this should do:
[Unit]
Description=Galene
After=network.target
[Service]
Type=simple
WorkingDirectory=/home/galene
User=galene
Group=galene
ExecStart=/home/galene/galene
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
# Locations # Locations

View file

@ -6,19 +6,22 @@ The frontend is written in JavaScript and is split into two files:
server; server;
- `galene.js` contains the user interface. - `galene.js` contains the user interface.
If you wish to develop your own frontend, I recommend using `protocol.js`, A new frontend may either implement Galène's client-server protocol from
which is likely to remain reasonably stable as the protocol evolves. This scratch, or it may use the functionality of `protocol.js`. This document
file can be processed with JSDoc or Typescript (a sample `tsconfig.json` documents the latter approach.
is provided), but is otherwise plain Javascript (ES6).
## Data structures ## Data structures
The class `ServerConnection` encapsulates a connection to the server as The class `ServerConnection` encapsulates a connection to the server as
well as all the associated streams. well as all the associated streams. Unless your frontend communicates
with multiple servers, it will probably create just a single instance of
this class.
The class `Stream` encapsulates a set of related audio and video tracks; The class `Stream` encapsulates a set of related audio and video tracks
your frontend will probably associate each stream with a `video` or (for example, an audio track from a microphone and a video track from
`audio` component. 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.
## Connecting to the server ## Connecting to the server
@ -38,16 +41,17 @@ serverConnection.ondownstream = ...;
The `onconnected` callback is called when we connect to the server. The 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 `onclose` callback is called when the socket is closed; you should use it
to close all your outgoing streams (incoming streams will be closed by the to close all your up streams (down streams will be closed by the server).
server). `onusermessage` indicates a message from the server that should The `onusermessage` callback indicates an application-specific message,
be displayed to the user. either from another user or from the server; the field `kind` indicates
the kind of message.
The other callbacks will only be called after you join a group. `onuser` Once you have joined a group (see below), the remaining callbacks may
is used to indicate that a user has joined or left the current group. trigger. The `onuser` callback is used to indicate that a user has joined
`onchat` indicates that a chat message has been posted to the group, and or left the current group. The `onchat` callback indicates that a chat
`onclearchat` indicates that the chat history has been cleared. Finally, message has been posted to the group, and `onclearchat` indicates that the
`ondownstream` is called when the server pushes a stream to the client; chat history has been cleared. Finally, `ondownstream` is called when the
see the section below about streams. server pushes a stream to the client; see the section below about streams.
You may now connect to the server. You may now connect to the server.
@ -67,25 +71,31 @@ serverConnection.onconnected = function() {
You should not attempt to push a stream to the server until it has granted You should not attempt to push a stream to the server until it has granted
you the `present` permission through the `onjoined` callback. you the `present` permission through the `onjoined` callback.
## Managing groups and users
The `groupaction` and `useraction` methods perform actions such as kicking
users or locking groups. Most actions require either the `Op` or the
`Record` permission.
## Sending and receiving chat messages ## Sending and receiving chat messages
Once you have joined a group, you send chat messages with the `chat` Once you have joined a group, you send chat messages with the `chat`
method. No permission is needed to do that. method of the `ServerConnection` class. No permission is needed to do that.
```javascript ```javascript
serverConnection.chat(username, '', 'Hi!'); serverConnection.chat(username, '', id, 'Hi!');
``` ```
You receive chat messages in the `onchat` callback. The server may You receive chat messages in the `onchat` callback. The server may
request that you clear your chat window, in that case the `onclearchat` request that you clear your chat window, in that case the `onclearchat`
callback will trigger. callback will trigger.
## 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.
## Accepting incoming video streams ## Accepting incoming video streams
When the server pushes a stream to the client, the `ondownstream` callback When the server pushes a stream to the client, the `ondownstream` callback
@ -145,8 +155,9 @@ See above for information about setting up the `labels` dictionary.
## Stream statistics ## Stream statistics
For outgoing streams only, the `setStatsInterval` and `onstats` callback Some statistics about streams are made available by calling the
can be used to determine the data rate in real time. This is currently `setStatsInterval` method and setting the `onstats` callback. These
not implemented for down streams. 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.
--- Juliusz Chroboczek <https://www.irif.fr/~jch/> --- Juliusz Chroboczek <https://www.irif.fr/~jch/>