Multi-Person Video Call

2024-01-04

Introduction

This document shows how to use the ZEGO Express SDK to construct a multi-person video call scenario, that is, to implement multi-to-multi real-time audio and video interaction. Users can conduct real-time video calls with other users in the room and publish and play streams with each other. This scenario can be used for multi-person real-time video chat, video conferences, etc.

Prerequisites

Before applying the multi-person video call scenario, ensure that:

A project has been created in the ZEGOCLOUD Console, and valid AppID and AppSign have been obtained. For details, please refer to Console - Project Information.
ZEGO Express SDK has been integrated into the project, and basic audio and video streaming functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation Process.

Download Sample Source Code

Please refer to Download Sample Source Code to obtain the source code.

For related source code, please check the files in the "ZegoExpressExample/Examples/Scenes/VideoForMultipleUsers" directory.

Usage Steps

This section will introduce how to use the ZEGO Express SDK to implement multi-person video calls.

The flow chart of multi-person video calls is as follows:

The API call sequence diagram is as follows:

Note

ZEGO Express SDK can support multi-person video calls. The above sequence diagram uses real-time video calls between 2 room members as an example. It is recommended that developers refer to the above process to design their own multi-person real-time video call scenarios.

1 Create engine

Define the SDK engine object, call the createEngine interface, pass the applied AppID and AppSign into the parameters "appID" and "appSign", and create the engine singleton object.

If you need to register a callback handler, you can pass an object that implements IZegoEventHandler into the parameter "eventHandler". If you do not need to register a callback handler, you can pass "null" into the parameter "eventHandler". After creating the engine, if you still need to register a callback, you can set the callback handler by calling the setEventHandler interface.

// Define SDK engine object
IZegoExpressEngine *engine;

ZegoEngineProfile profile;
// AppID and AppSign are assigned to each App by ZEGO; for security reasons, it is recommended to store AppSign in the App's business backend and obtain it from the backend when needed
profile.appID = appID;
profile.appSign = appSign;
profile.scenario = ZegoScenario::ZEGO_SCENARIO_DEFAULT;
// Create engine instance
engine = ZegoExpressSDK::createEngine(profile, nullptr);

// Define SDK engine object
IZegoExpressEngine *engine;

ZegoEngineProfile profile;
// AppID and AppSign are assigned to each App by ZEGO; for security reasons, it is recommended to store AppSign in the App's business backend and obtain it from the backend when needed
profile.appID = appID;
profile.appSign = appSign;
profile.scenario = ZegoScenario::ZEGO_SCENARIO_DEFAULT;
// Create engine instance
engine = ZegoExpressSDK::createEngine(profile, nullptr);

2 Enable room user change notifications

Developers need to set "isUserStatusNotify" in ZegoRoomConfig to "true" when each user logs in to the room to receive callback notifications for other users entering and leaving the room.

ZegoRoomConfig RoomConfig;
RoomConfig.isUserStatusNotify = true;
// Login room
engine->loginRoom(roomID, user, RoomConfig);

ZegoRoomConfig RoomConfig;
RoomConfig.isUserStatusNotify = true;
// Login room
engine->loginRoom(roomID, user, RoomConfig);

3 Set event notification callbacks

To implement the multi-person video call feature, you need to listen to the addition and deletion of users and streams in the room and make corresponding handling. You can set related callbacks through setEventHandler.

Listen to user changes in the room

Register the onRoomUserUpdate callback to listen to user changes in the room. The addition and deletion of users who have logged in to the room will trigger this callback.

The "updateType" parameter in the callback indicates the type of user change in the room. The values of this parameter are as follows:

User Change Type	Enumeration Value	Description
User Addition	ZEGO_UPDATE_TYPE_ADD	Users increase in the room, "userList" is the list of newly added users.
User Deletion	ZEGO_UPDATE_TYPE_DELETE	Users decrease in the room, "userList" is the list of deleted users.

When a user logs in to the room for the first time, if there are other users in the room, the newly logged-in user will receive the added user list through this callback, that is, the callback with "updateType" as "ZEGO_UPDATE_TYPE_ADD", and this user list is the users already existing in the room.

Warning

Only when status notification is allowed when logging in to the room via loginRoom , that is, when "isUserStatusNotify" in ZegoRoomConfig is set to "true" (default is "false"), can you listen to the onRoomUserUpdate callback.
When the number of people in the room exceeds 500, this callback will become invalid.

class MyEventHandler : public IZegoEventHandler
{
    void onRoomUserUpdate(const std::string &roomID, ZegoUpdateType updateType, const std::vector<ZegoUser> &userList){
        // Update UI or perform other operations here
    }
};
auto eventHandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventHandler)

class MyEventHandler : public IZegoEventHandler
{
    void onRoomUserUpdate(const std::string &roomID, ZegoUpdateType updateType, const std::vector<ZegoUser> &userList){
        // Update UI or perform other operations here
    }
};
auto eventHandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventHandler)

Listen to stream changes in the room

To listen to stream changes in the room, you need to register the onRoomStreamUpdate callback. When other users in the room add or delete streams, this callback will be triggered to notify the changed stream list.

The "updateType" parameter in the callback indicates the type of stream change in the room. The values of this parameter are as follows:

Stream Change Type	Enumeration Value	Description
Stream Addition	ZEGO_UPDATE_TYPE_ADD	Streams increase in the room, "streamList" is the list of newly added streams.
Stream Deletion	ZEGO_UPDATE_TYPE_DELETE	Streams decrease in the room, "streamList" is the list of deleted streams.

When a user logs in to the room for the first time, if there are other users publishing streams in the room, a stream addition list will be received, that is, the callback with "updateType" as "ZEGO_UPDATE_TYPE_ADD".

class MyEventHandler : public IZegoEventHandler
{
    void onRoomStreamUpdate(const std::string& currentRoomID, ZegoUpdateType updateType, const std::vector<ZegoStream>& streamList, const std::string& extendData){
        // Update UI or perform other operations here
    }
};
auto eventHandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventHandler)

class MyEventHandler : public IZegoEventHandler
{
    void onRoomStreamUpdate(const std::string& currentRoomID, ZegoUpdateType updateType, const std::vector<ZegoStream>& streamList, const std::string& extendData){
        // Update UI or perform other operations here
    }
};
auto eventHandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventHandler)

4 Start publishing/playing streams

Please refer to Quick Start - Implementation Process to complete the operations related to "publishing streams" and "playing streams" in sequence.

5 Stop video call

During the call, if users in the room need to end the call, please refer to Quick Start - Implementation Process to complete the related operations in sequence.