Implementing Voice Call

Prerequisites

Before implementing basic real-time voice functionality, please ensure:

• The ZEGO Express SDK has been integrated in your project. For details, please refer to Quick Start - Integration.
• A project has been created in the ZEGOCLOUD Console and a valid AppID and Server address have been obtained.

Usage Steps

This section introduces how to use ZEGO Express SDK to implement basic real-time audio/video functionality. The API call sequence is shown below:

(Optional) Create User Interface

Add UI Elements

Before creating the engine, it is recommended for developers to add the following UI elements to facilitate the implementation of basic real-time voice call functionality.

• Local preview window
• Remote video window
• End button

Create Engine and Listen for Callbacks

1. Create Engine

Create a ZegoExpressEngine engine instance, pass the obtained AppID to the "appID" parameter, and pass the access server address to the "server" parameter.

// Project unique identifier AppID, Number type, please obtain from ZEGOCLOUD Console
let appID = ;
// Access server address Server, String type, please obtain from ZEGOCLOUD Console (refer to "Prerequisites" above for how to obtain)
let server = "";
// Initialize instance
const zg = new ZegoExpressEngine(appID, server);

// Project unique identifier AppID, Number type, please obtain from ZEGOCLOUD Console
let appID = ;
// Access server address Server, String type, please obtain from ZEGOCLOUD Console (refer to "Prerequisites" above for how to obtain)
let server = "";
// Initialize instance
const zg = new ZegoExpressEngine(appID, server);

2. Listen for Event Callbacks

The SDK provides notification callbacks such as room connection status, audio/video stream changes, user join/leave, etc. After creating the engine, you can register callbacks through the on method of the engine instance.

// Room status update callback
zg.on('roomStateChanged', (roomID, reason, errorCode, extendData) => {
    if (reason == 'LOGINING') {
        // Logging in
    } else if (reason == 'LOGINED') {
        // Login successful
        // Only when the room status is login successful or reconnection successful, publishing (startPublishingStream) and playing (startPlayingStream) can normally send/receive audio and video
        // Publish your audio/video stream to ZEGO audio/video cloud
    } else if (reason == 'LOGIN_FAILED') {
        // Login failed
    } else if (reason == 'RECONNECTING') {
        // Reconnecting
    } else if (reason == 'RECONNECTED') {
        // Reconnection successful
    } else if (reason == 'RECONNECT_FAILED') {
        // Reconnection failed
    } else if (reason == 'KICKOUT') {
        // Kicked out of the room
    } else if (reason == 'LOGOUT') {
        // Logout successful
    } else if (reason == 'LOGOUT_FAILED') {
        // Logout failed
    }
});

// User status update callback
zg.on('roomUserUpdate', (roomID, updateType, userList) => {
    console.warn(
        `roomUserUpdate: room ${roomID}, user ${updateType === 'ADD' ? 'added' : 'left'} `,
        JSON.stringify(userList),
    );
});

// Stream status update callback
zg.on('roomStreamUpdate', async (roomID, updateType, streamList, extendedData) => {
    if (updateType == 'ADD') {
        // Stream added, start playing
    } else if (updateType == 'DELETE') {
        // Stream deleted, stop playing
    }
});

// Room status update callback
zg.on('roomStateChanged', (roomID, reason, errorCode, extendData) => {
    if (reason == 'LOGINING') {
        // Logging in
    } else if (reason == 'LOGINED') {
        // Login successful
        // Only when the room status is login successful or reconnection successful, publishing (startPublishingStream) and playing (startPlayingStream) can normally send/receive audio and video
        // Publish your audio/video stream to ZEGO audio/video cloud
    } else if (reason == 'LOGIN_FAILED') {
        // Login failed
    } else if (reason == 'RECONNECTING') {
        // Reconnecting
    } else if (reason == 'RECONNECTED') {
        // Reconnection successful
    } else if (reason == 'RECONNECT_FAILED') {
        // Reconnection failed
    } else if (reason == 'KICKOUT') {
        // Kicked out of the room
    } else if (reason == 'LOGOUT') {
        // Logout successful
    } else if (reason == 'LOGOUT_FAILED') {
        // Logout failed
    }
});

// User status update callback
zg.on('roomUserUpdate', (roomID, updateType, userList) => {
    console.warn(
        `roomUserUpdate: room ${roomID}, user ${updateType === 'ADD' ? 'added' : 'left'} `,
        JSON.stringify(userList),
    );
});

// Stream status update callback
zg.on('roomStreamUpdate', async (roomID, updateType, streamList, extendedData) => {
    if (updateType == 'ADD') {
        // Stream added, start playing
    } else if (updateType == 'DELETE') {
        // Stream deleted, stop playing
    }
});

(Optional) Check Compatibility

const result = await zg.checkSystemRequirements();
// The returned result is the compatibility check result. When webRTC is true, it means WebRTC is supported. For the meaning of other attributes, please refer to the interface API documentation.
console.log(result);
// {
//   webRTC: true,
//   customCapture: true,
//   camera: true,
//   microphone: true,
//   videoCodec: { H264: true, H265: false, VP8: true, VP9: true },
//   screenSharing: true,
//   errInfo: {}
// }

const result = await zg.checkSystemRequirements();
// The returned result is the compatibility check result. When webRTC is true, it means WebRTC is supported. For the meaning of other attributes, please refer to the interface API documentation.
console.log(result);
// {
//   webRTC: true,
//   customCapture: true,
//   camera: true,
//   microphone: true,
//   videoCodec: { H264: true, H265: false, VP8: true, VP9: true },
//   screenSharing: true,
//   errInfo: {}
// }

Log in to Room

1. Generate Token

Logging into the room requires a Token for identity verification. Developers can directly obtain temporary Tokens (valid for 24 hours) from the ZEGOCLOUD Console for use. For details, please refer to Console - Development Assistance.

2. Log in to Room

Call the loginRoom interface, pass in the room ID parameter "roomID", "token", and user parameter "user", to log into the room. If the room does not exist, calling this interface will create and log into this room.

// Log in to room, returns true if successful
// Setting userUpdate to true will enable listening for roomUserUpdate callbacks. By default, this listening is not enabled.
const result = await zg.loginRoom(roomID, token, { userID: userID, userName: userName}, {userUpdate: true});

// Log in to room, returns true if successful
// Setting userUpdate to true will enable listening for roomUserUpdate callbacks. By default, this listening is not enabled.
const result = await zg.loginRoom(roomID, token, { userID: userID, userName: userName}, {userUpdate: true});

3. Listen for Event Callbacks After Logging into Room

You can listen to the roomStateChanged callback to monitor your connection status with the room in real time. Only when the room status is connected successfully, can you perform operations such as publishing and playing streams. If logging into the room fails, please refer to Error Codes for operations.

Publish Stream

1. Create Stream

a. Before starting to publish, you need to create the local audio/video stream. Call the createZegoStream interface, which by default captures camera footage and microphone sound.

Through the localStream's playAudio interface, create a local media stream playback component to play audio to be published or already successfully published; you can also assign localStream.stream to the video element's srcObject property for playback.

// After calling the createZegoStream interface, you need to wait for the ZEGO server to return the ZegoLocalStream instance object before performing subsequent operations
const localStream = await zg.createZegoStream({camera :{audio:true,video:false}});
// Call the playAudio method on the localStream instance to play audio preview before or during publishing
localStream.playAudio();

// After calling the createZegoStream interface, you need to wait for the ZEGO server to return the ZegoLocalStream instance object before performing subsequent operations
const localStream = await zg.createZegoStream({camera :{audio:true,video:false}});
// Call the playAudio method on the localStream instance to play audio preview before or during publishing
localStream.playAudio();

b. (Optional) Set Audio Capture Parameters

c. (Optional) Render MediaStream on Page

2. Start Publishing Stream

Call the startPublishingStream interface, pass in the stream ID parameter "streamID" and the stream object "localStream" obtained from creating the stream, to send your audio/video stream to remote users.

// localStream is the MediaStream object obtained from creating the stream
zg.startPublishingStream(streamID, localStream)

// localStream is the MediaStream object obtained from creating the stream
zg.startPublishingStream(streamID, localStream)

3. Listen for Event Callbacks After Publishing Stream

Based on actual application needs, listen for the event notifications you want to Follow after publishing, such as publishing status updates, publishing quality, etc.

• publisherStateUpdate: Publishing status update callback. After successfully calling the publishing interface, when the publishing status changes (such as publishing anomalies caused by network interruption, etc.), the SDK will notify through this callback while retrying publishing.
• publishQualityUpdate: Publishing quality callback. After successfully calling the publishing interface, periodically callbacks audio/video stream quality data (such as resolution, frame rate, bitrate, etc.).

zg.on('publisherStateUpdate', result => {
    // Publishing status update callback
    // ...
})

zg.on('publishQualityUpdate', (streamID, stats) => {
    // Publishing quality callback
    // ...
})

zg.on('publisherStateUpdate', result => {
    // Publishing status update callback
    // ...
})

zg.on('publishQualityUpdate', (streamID, stats) => {
    // Publishing quality callback
    // ...
})

Play Stream

1. Start Playing Stream

a. Call the startPlayingStream interface, and based on the passed stream ID parameter "streamID", play the remote audio/video footage that has been published to the ZEGO server.

The "streamID" published by remote users can be obtained from the roomStreamUpdate callback.

const remoteStream = await zg.startPlayingStream(streamID);

// remoteAudio is a local <video> or <audio> object
remoteAudio.srcObject = remoteStream;

const remoteStream = await zg.startPlayingStream(streamID);

// remoteAudio is a local <video> or <audio> object
remoteAudio.srcObject = remoteStream;

b. (Optional) Render MediaStream on Page

2. Listen for Event Callbacks After Playing Stream

Based on actual application needs, listen for the event notifications you want to Follow after playing, such as playing status changes, playing quality, etc.

• playerStateUpdate: Playing status update callback. After successfully calling the playing interface, when the playing status changes (such as playing anomalies caused by network interruption, etc.), the SDK will notify through this callback while retrying to play.
• playQualityUpdate: Playing quality callback. After successfully calling the playing interface, periodically callbacks audio/video stream quality data (such as resolution, frame rate, bitrate, etc.).

zg.on('playerStateUpdate', result => {
    // Playing status update callback
    // ...
})

zg.on('playQualityUpdate', (streamID,stats) => {
    // Playing quality callback
})

zg.on('playerStateUpdate', result => {
    // Playing status update callback
    // ...
})

zg.on('playQualityUpdate', (streamID,stats) => {
    // Playing quality callback
})

Experience Real-Time Audio/Video Functionality

Run the project on a real device. After successful execution, you can see the local video footage.

To facilitate testing, ZEGO provides a Web platform for debugging. On this page, enter the same AppID and RoomID, enter different UserIDs and corresponding Tokens, and you can join the same room to communicate with real device. When the audio/video call starts successfully, you can hear the remote audio and see the remote video footage.

Stop Audio/Video Call

1. Stop Publishing Stream

Call the stopPublishingStream interface to stop sending your audio/video stream to remote users.

zg.stopPublishingStream(streamID)

zg.stopPublishingStream(streamID)

2. Destroy Stream

Call the destroyStream interface to destroy the created stream data. After destroying the stream, developers need to destroy audio (stop capture) themselves.

// localStream is the ZegoLocalStream instance object obtained by calling the createZegoStream interface
zg.destroyStream(localStream)

// localStream is the ZegoLocalStream instance object obtained by calling the createZegoStream interface
zg.destroyStream(localStream)

3. Stop Playing Stream

Call the stopPlayingStream interface to stop playing the remote audio/video stream.

zg.stopPlayingStream(streamID)

zg.stopPlayingStream(streamID)

4. Log Out of Room

Call the logoutRoom interface to exit the room.

zg.logoutRoom(roomID)

zg.logoutRoom(roomID)

5. Destroy Engine

If users will no longer use audio/video functionality, they can call the destroyEngine interface to destroy the engine and release resources such as microphone, camera, memory, CPU, etc.

zg.destroyEngine()
zg = null

zg.destroyEngine()
zg = null