openvidu-call 🔗
OpenVidu Call is the flagship videoconference app based on OpenVidu Components. It includes many of the capabilities offered by OpenVidu platform and brings a great number of basic and advanced features:
- Chat service
- Switch camera
- Screensharing
- Speech detection
- Automatic reconnection
- Virtual background
- Recording
- Broadcast
Moreover, OpenVidu Call contains an intelligent layout algorithm that adapts the video layout to the number of participants in the session. OpenVidu Call is installed by default when you deploy OpenVidu.
Visit its presentation page for more information.
Running the application 🔗
To run OpenVidu Call you need the three components started in OpenVidu application architecture: an OpenVidu deployment, your server application and your client application. In this order:
1. Run OpenVidu deployment 🔗
Using Docker Engine:
# WARNING: this container is not suitable for production deployments of OpenVidu
# Visit https://docs.openvidu.io/en/stable/deployment
docker run -p 4443:4443 --rm -e OPENVIDU_SECRET=MY_SECRET openvidu/openvidu-dev:2.28.0
2. Run your preferred server application 🔗
Let's run the server application. Choose one of the backends offered in OpenVidu Call:
You need Node and npm.
- Clone the repository
git clone https://github.com/OpenVidu/openvidu-call.git -b v2.28.0
- Install dependencies
cd openvidu-call-back
npm install
- Run the server application, which in this case is the OpenVidu Call backend. To configure this command you can check below section Configuration parameters for OpenVidu Call backend.
npm run dev:start
3. Run the client application 🔗
Install frontend dependencies in path openvidu-call/openvidu-call-front
:
npm install
Run the client application:
npx ng serve --open
Understanding the code 🔗
OpenVidu Call is the production ready videconference app included by default in any OpenVidu deployment. OpenVidu Call consists of:
openvidu-call-back 🔗
OpenVidu Call offers two different flavors of the same backend (Java and Node), so that you can choose the one that is most convenient for you. Both of them are fully functional applications using its corresponding SDK (openvidu-java-client or openvidu-node-client) and exposing the same REST API.
app.ts
: entrypoint of the server.config.ts
: contains the backend environment variables.AuthController.ts
: controller for login to the OpenVidu Session and do login/logout to the admin dashboard.SessionController.ts
: controller for requesting OpenVidu Tokens (see basic concepts).CallController.ts
: controller for requesting OpenVidu Call environment information.RecordingController.ts
: controller for recording features.BroadcastController.ts
: controller for broadcast features.OpenViduService.ts
: service using openvidu-node-client to communicate with the OpenVidu deployment.AuthService.ts
: service which includes the auth logic.
(Used by default with OpenVidu deployment)
See code here
Session control 🔗
The OpenVidu Call backend provides a basic authentication system to control the access to the OpenVidu Session. The authentication system is based on a single user with a fixed username and password. The default username and password are represented by variables CALL_USER
and CALL_SECRET
respectively.
You can check and change these values in the configuration parameters.
Note that the authentication system can be disabled by setting the variable
CALL_PRIVATE_ACCESS
toDISABLED
.
If you want to know more about what type of authentication you can use with OpenVidu, you can check the user authentication section.
Recording management 🔗
You can check the user authentication section for more information.
For OpenVidu Call backend exists two types of users:
-
Session creator user: user with full recording privileges. This user who create the session can start, stop and delete the recordings of the OpenVidu Call sessions plus all the privileges of the Normal user.
-
Normal user: user without recording privileges. This user who joins to the created session can only see the recordings available to the OpenVidu Call sessions as well as play, pause, stop and download the recording.
Note that the playback and download of the recordings is done by the OpenVidu Call frontend. Here the backend acts as a proxy between the frontend and the OpenVidu Server, which is the most optimal way to do it.
To identify who is able to have recording privileges, the OpenVidu Call backend implements a cookie-based session system.
It will generate and store (in-memory) a cookie with an unique ID
that will be used to identify the user.
This ID
will be generated when the session creator user (that is the first user connecting to the session) creates the session. The token will be sent to the frontend and will be used to identify the user in the backend.
Note that the recording features can be disabled by setting the variable
CALL_RECORDING
toDISABLED
.
Admin dashboard 🔗
In addition, the backend also provides two endpoints for login and logout to the admin dashboard. This dashboard allows you to see the recordings of the all OpenVidu Call sessions and manage them.
The authentication system for this dashboard is based on a single user with a fixed password. The default password is represented by variable CALL_ADMIN_SECRET
.
This admin dashboard will be public in http://localhost:4200/admin.
Broadcast management 🔗
The OpenVidu Call backend also provides broadcasting features. This feature allows to you stream any OpenVidu Call videoconference to Youtube, Twitch or any other broadcast platform that supports RTMP protocol (check the official documentation section here).
As identical to the recording features, the broadcast features are also based on a cookie-based session system and the session creator user is the only one who can start and stop the broadcast of the OpenVidu Call sessions.
Note that the broadcast features can be disabled by setting the variable
CALL_BROADCAST
toDISABLED
.
openvidu-call-front 🔗
A simple Angular app built with openvidu-angular library allowing us to develop a powerful videconference frontend. See code here.
services/guards/navigator-guard.service.ts
: service in charge of checking if the navigation to an specific route is allowed verifying the user authentication.services/call.service.ts
: service in charge of the OpenVidu Call environment information.services/auth.service.ts
: service in charge of the authentication process.services/rest.service.ts
: services for requesting OpenVidu Tokens to the application's backend.services/http-interceptor.service.ts
: service for adding the authentication token to the HTTP requests.components/home
: component with the home screen, where the user can define the session name and join it.components/call
: component with the videoconference screen.components/admin-dashboard
: component with the admin dashboard.
Let's focus on the CallComponent template. We can have a videoconference app with a few lines of code:
<ov-videoconference
[tokens]="tokens"
[recordingActivityRecordingsList]="recordingList"
[recordingActivityRecordingError]="recordingError"
[broadcastingActivityBroadcastingError]="broadcastingError"
[activitiesPanelRecordingActivity]="recordingEnabled"
[toolbarRecordingButton]="recordingEnabled"
[activitiesPanelBroadcastingActivity]="broadcastingEnabled"
[toolbarBroadcastingButton]="broadcastingEnabled"
(onToolbarLeaveButtonClicked)="onLeaveButtonClicked()"
(onToolbarStartRecordingClicked)="onStartRecordingClicked()"
(onActivitiesPanelStartRecordingClicked)="onStartRecordingClicked()"
(onToolbarStopRecordingClicked)="onStopRecordingClicked()"
(onActivitiesPanelStopRecordingClicked)="onStopRecordingClicked()"
(onActivitiesPanelDeleteRecordingClicked)="onDeleteRecordingClicked($event)"
(onActivitiesPanelStartBroadcastingClicked)="onStartBroadcastingClicked($event)"
(onActivitiesPanelStopBroadcastingClicked)="onStopBroadcastingClicked()"
(onToolbarStopBroadcastingClicked)="onStopBroadcastingClicked()"
(onNodeCrashed)="onNodeCrashed()"
>
</ov-videoconference>
You will need to request for OpenVidu Tokens to the backend and pass them to the ov-videoconference
component. You can also pass the recording list and the recording error to the component if the recording features are enabled.
You can see all the inputs offered by
VideoconferenceComponent
here
Once the tokens are passed to the component, the videoconference will be automatically created and the users will be able to join the session.
You also have the possibility to customize the application listening to the events emitted by the ov-videoconference
component.
For example, you can listen to the onToolbarLeaveButtonClicked
event to know when the user has clicked on the leave button and do something else.
You can see all the events offered by
VideoconferenceComponent
here.
Configuration parameters for OpenVidu Call backend 🔗
Parameter | Description | Default value |
---|---|---|
SERVER_PORT |
Number that indicates the port where http server will listen | 5000 |
OPENVIDU_URL |
The URL where OpenVidu Server will be reachable. | "http://localhost:4443" |
OPENVIDU_SECRET |
Secret used to connect to OpenVidu Server. | "MY_SECRET" |
CALL_PRIVATE_ACCESS |
Whether to enable the authentication feature or not. | "ENABLED" |
CALL_USER |
Username used for login to the OpenVidu Call session. This property has effect only if is CALL_PRIVATE_ACCESS='ENABLED' |
"admin" |
CALL_SECRET |
Secret used for login to the OpenVidu Call session. This property has effect only if is CALL_PRIVATE_ACCESS='ENABLED' |
Same as OPENVIDU_SECRET |
CALL_ADMIN_SECRET |
Secret used for login to the OpenVidu Call admin dashboard. | Same as OPENVIDU_SECRET |
CALL_RECORDING |
Whether to enable the recording features or not. | "ENABLED" |
CALL_BROADCAST |
Whether to enable the broadcast features or not. | "ENABLED" |
These configuration parameters can be set as environment variables. For example, to execute the application against an OpenVidu deployment with a domain name such us my.openvidu.deployment.com
that is configured with secret PASSWORD
:
$ npx cross-env OPENVIDU_URL=https://my.openvidu.deployment.com OPENVIDU_SECRET=PASSWORD nodemon src/app.ts
Backend REST API 🔗
1. Initialize a Session | |
---|---|
HTTP METHOD | POST |
URL | https://localhost:5000/sessions |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
REQUEST BODY | {"sessionId":"session_id", "nickname":"openvidu_name"} |
200 OK RETURN VALUE | A JSON object with the Connection tokens and recording information. For example: {"cameraToken": "wss://localhost:4443?sessionId=ses_JM9v0nfD1l&token=tok_MIYGGzuDQb8Xf1Qd", "screenToken": "wss://localhost:4443?sessionId=ses_JM2v0nfD1l&token=tok_MIYGGduDQb8Xf1Qd", "recordings": [], "recordingEnabled": true} |
2. List all recordings | |
---|---|
HTTP METHOD | GET |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/recordings |
200 OK RETURN VALUE | The list of all Recording objects associated to the session |
3. Start recording | |
---|---|
HTTP METHOD | POST |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/recordings/start |
REQUEST BODY | {"sessionId": "session_name"} |
200 OK RETURN VALUE | The Recording object |
4. Stop recording | |
---|---|
HTTP METHOD | POST |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/recordings/stop |
REQUEST BODY | {"sessionId": "session_name"} |
200 OK RETURN VALUE | The list of all Recording objects associated to the session |
5. Delete a recording | |
---|---|
HTTP METHOD | DELETE |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/recordings/delete/RECORDING_ID |
200 OK RETURN VALUE | The list of all Recording objects associated to the session |
6. Get a recording | |
---|---|
HTTP METHOD | GET |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/recordings/RECORDING_ID |
206 Partial Content RETURN VALUE | Byterange used to allow large files to be downloaded or requested progressively |
7. Start broadcast | |
---|---|
HTTP METHOD | POST |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/broadcasts/start |
REQUEST BODY | {"broadcastUrl": "your_broadcast_url" } |
200 OK RETURN VALUE | {"id": "broadcast_id", "status": "STARTED", "broadcastAvailable": true } |
8. Stop broadcast | |
---|---|
HTTP METHOD | DELETE |
HEADERS | Authorization: Basic EncodeBase64(CALL_USER:<CALL_SECRET>) . Only if is CALL_PRIVATE_ACCESS='ENABLED' |
URL | https://localhost:5000/broadcasts/stop |
200 OK RETURN VALUE | {"id": "broadcast_id", "status": "STOPPED", "broadcastAvailable": true } |
9. Call login | |
---|---|
HTTP METHOD | POST |
URL | https://localhost:5000/login |
REQUEST BODY | Username and password for doing login in OpenVidu session {"username":"user", "password": "xxx"} |
200 OK RETURN VALUE |
10. Admin login | |
---|---|
HTTP METHOD | POST |
URL | https://localhost:5000/admin/login |
REQUEST BODY | Password for doing login in Admin dashboard {"password": "xxx"} |
200 OK RETURN VALUE | A list of all Recording objects available in the entire OpenVidu deployment |
11. Admin logout | |
---|---|
HTTP METHOD | POST |
URL | https://localhost:5000/admin/logout |
How to build OpenVidu Call 🔗
Docker image 🔗
- Handle the NGINX certificates with a proxy
- Edit OpenVidu Call image to include the SSL certificate
The process to build a Docker image of OpenVidu call is really easy. Take into account that you need to use one Dockerfile or another depending on the server technology you choose (Node or Java).
- In directory
openvidu-call/.
, execute:
docker build -f docker/Dockerfile.node -t <your-tag-name> .
- After that, you can run the Docker container:
docker run -p <your-port>:5000 -e OPENVIDU_URL=<your-openvidu-url> -e OPENVIDU_SECRET=<your-secret> <your-image-name>
- Go to
http://localhost:your-port
to test the app
Configuration parameters when building OpenVidu Call Docker image 🔗
Parameter | Description | Default value |
---|---|---|
BASE_HREF |
URL prefix for application's path | / |
Packaged application 🔗
You can also build OpenVidu Call without Docker and serve it directly using Node or Java. Placed at openvidu-call/.
root path:
- Build OpenVidu Call frontend. Set as
BASE_HREF
the desired value depending on the path your application will be accessible:
cd openvidu-call-front
npm run prod:build BASE_HREF
- Build OpenVidu Call backend:
cd ../openvidu-call-back
npm run build
- You will find the app built in
dist
directory. You can use Node to launch it:
cd dist/
node openvidu-call-server.js