openvidu-call 🔗

Check it on GitHub

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:

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.26.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.

  1. Clone the repository
git clone https://github.com/OpenVidu/openvidu-call.git -b v2.24.0
  1. Install dependencies
cd openvidu-call-back
npm install
  1. 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 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_SECRETrespectively.

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 to DISABLED.

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 🔗
This authentication and authorization recording system is very basic and limited. It will not be suitable for most production environments. We highly recommend IMPLEMENTING YOUR OWN USER MANAGEMENT SYSTEM with real persistence for a properly secured recording process.
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 to DISABLED.


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 to DISABLED.

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 🔗

OpenVidu Call container is designed to be served next to an OpenVidu deployment. To allow the use of this image out of an OpenVidu deployment, you have two options:

  1. Handle the NGINX certificates with a proxy
  2. 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).

  1. In directory openvidu-call/., execute:
docker build -f docker/Dockerfile.node -t <your-tag-name> .


  1. 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>
  1. 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:

  1. 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
  1. Build OpenVidu Call backend:
cd ../openvidu-call-back
npm run build
  1. You will find the app built in dist directory. You can use Node to launch it:
cd dist/
node openvidu-call-server.js