Real-Time Audio and Video
  • Platform
  • Framework / Engine
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • WeChat Mini Program

Implement basic real-time audio and video features

Update Time:2021-08-25 15:02

This guide describes how to implement basic real-time audio and video features with the ZEGO Express SDK.

1 Introduction

This guide describes how to implement basic real-time audio and video features with the ZEGO Express SDK.

Basic concepts:

  • ZEGO Express SDK: The real-time audio and video SDK developed by ZEGO to help you quickly build high-quality, low-latency, and smooth real-time audio and video communications into your apps across different platforms, with support for massive concurrency.

  • Stream publishing: The process of the client app capturing and transmitting audio and video streams to the ZEGO Real-Time Audio and Video Cloud.

  • Stream playing: The process of the client app receiving and playing audio and video streams from the ZEGO Real-Time Audio and Video Cloud.

  • Room: Room refers to the audio and video space service provided by ZEGO, which is used to organize user groups. Users in the same room can send and receive real-time audio, video and messages to each other.

    1. Users need to log in to a room before they can push or play streams.
    2. Users can only receive relevant messages in their room (user entry and exit, audio and video stream changes, etc.).

For more basic concepts, please refer to Glossary.

2 Prerequisites

Before you begin, make sure you complete the following steps:

  1. Create a project in ZEGO Admin Console, and get the AppID and AppSign of your project. For more details, see ZEGO Admin Console-Project management.
  2. Integrate the ZEGO Express SDK into your project. For more details, see Quick starts-Integration.

3 Implementation steps

The following diagram shows the basic process of User A playing a stream published by User B:

/Pics/Common/ZegoExpressEngine/implementation_overall.png

The following diagram shows the API call sequence of the stream publishing and playing process:

/Pics/QuickStart/quickstart_uml_en_detail.png

The following sections explain each step of this process in more detail.

3.1 Create a ZegoExpressEngine instance

1. Optional: Create the UI

Add UI elements

Before creating a ZegoExpressEngine instance, we recommend you add the following UI elements to implement basic real-time audio and video features:

  • A view for local preview
  • A view for remote video
  • An End button
layout

2. Create a ZegoExpressEngine instance

To create a singleton instance of the ZegoExpressEngine class, call the createEngine method with the AppID and AppSign of your project.

To receive callbacks, implement an event handler object that conforms to the IZegoEventHandler protocol, and then pass the implemented event handler object to the createEngine method as the eventHandler parameter. Alternatively, you can pass null to the createEngine method as the eventHandler parameter for now, and then call the method setEventHandler to set up the event handler after creating the engine.

  • The AppID you get from the ZEGO Admin Console is by default for use in the testing environment. When you initialize the SDK in the development and testing phase, you need to configure the SDK to use the testing environment. Otherwise, the initialization will fail. Before your project goes live, you need to contact ZEGO sales for setting up the production environment in advance.
  • If you set the isTestEnv parameter to true, the SDK uses the testing environment. If you set it to false, the SDK uses the production environment.
/** Define a ZegoExpressEngine object */
ZegoExpressEngine engine;

/** Use the AppID and AppSign assigned by ZEGO when you create your project in the ZEGO Admin Console. */
long appID = ;  /** AppID format: 123456789L */
String appSign = ;  /** AppSign format: "0123456789012345678901234567890123456789012345678901234567890123"(64 characters)*/

/** Create a ZegoExpressEngine instance with your AppID and AppSign, and initialize it to use the testing environment and the settings for the general scenario. */
engine = ZegoExpressEngine.createEngine(appID, appSign, true, ZegoScenario.GENERAL, getApplication(), null);  

3.2 Log in to a room

1. Log in

To log in to a room, do the following:

  1. Create a ZegoUser with a unique user ID.
  2. Call the loginRoom method with the following parameters:
    • A unique room ID as the roomID parameter
    • The ZegoUser object created in the previous step as the user parameter
  • Each roomID must be globally unique within the scope of the AppID.
  • Each userID must be globally unique within the scope of the AppID. We recommend you set the userID to a meaningful value. You can associate userID with the account system of your application.
  • When you creating a ZegoUser object, the constructor method (public ZegoUser(String userID) ) sets the userName property to the same value of the userID parameter you pass to the constructor method. The userID and userName properties cannot be null. Otherwise, the room login will fail.
/** create a user */
ZegoUser user = new ZegoUser("user1");

/** log in to a room */
engine.loginRoom("room1", user);    

2. Listen for and handle the event callbacks related to room users and streams

To listen for and handle various events that may happen after logging in to a room, you can implement the corresponding event callback methods of the event handler as needed. The following are some common event callbacks related to room users and streams:

  • onRoomStateUpdate: Callback for updates on current user's room connection status. When the current user's room connection status changes (for example, when the current user is disconnected from the room or login authentication fails), the SDK sends out the event notification through this callback.

  • onRoomUserUpdate: Callback for updates on the status of other users in the room. When other users join or leave the room, the SDK sends out the event notification through this callback.

  • onRoomStreamUpdate: Callback for updates on the status of the streams in the room. When new streams are published to the room or existing streams in the room stop, the SDK sends out the event notification through this callback.
  • To receive the onRoomUserUpdate callback, you must set the isUserStatusNotify property of the room configuration parameter ZegoRoomConfig to true when you call the loginRoom method to log in to a room.
  • To play streams published by other users in the room: you can listen for the onRoomStreamUpdate callback, and when there is a stream added, call the startPlayingStream method to start receiving and playing the newly added stream.
engine.setEventHandler(new IZegoEventHandler() {

    /** Common event callbacks related to room users and streams. */

    /** Callback for updates on the current user's room connection status. */
    @Override
    public void onRoomStateUpdate(String roomID, ZegoRoomState state, int errorCode, JSONObject extendedData) {
        /** Implement the callback handling logic as needed. */
    }

    /** Callback for updates on the status of other users in the room. */
    @Override
    public void onRoomUserUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoUser> userList) {
        /** Implement the callback handling logic as needed. */
    }

    /** Callback for updates on the status of the streams in the room. */
    @Override
    public void onRoomStreamUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoStream> streamList, JSONObject extendedData){
        /** Implement the callback handling logic as needed. */
     }

});

3.3 Publish streams

1. Start publishing a stream

To start publishing a local audio or video stream to remote users, call the startPublishingStream method with the corresponding Stream ID passed to the streamID parameter.

streamID must be globally unique within the scope of the AppID. If different streams are published with the same streamID, the ones that are published after the first one will fail.

/** Start publishing a stream */
engine.startPublishingStream("stream1");

2. Optional: Start the local video preview

Start the local video preview

To start the local video preview, call the startPreview method with the view for rendering the local video passed to the canvas parameter.

You can use a SurfaceView, TextureView, or SurfaceTexture to render the video.

/**
 *  Set up a view for the local video preview and start the preview with SDK's default view mode (AspectFill).
 *  The following play_view is a SurfaceView, TextureView, or SurfaceTexture object on the UI.
 */
engine.startPreview(new ZegoCanvas(preview_view));

3. Listen for and handle the event callbacks related to stream publishing

To listen for and handle various events that may happen after stream publishing starts, you can implement the corresponding event callback methods of the event handler as needed. The following is a common event callback related to stream publishing:

  • onPublisherStateUpdate: Callback for updates on stream publishing status. After stream publishing starts, if the status changes, (for example, when the stream publishing is interrupted due to network issues and the SDK retries to start publishing the stream again), the SDK sends out the event notification through this callback.
engine.setEventHandler(new IZegoEventHandler() {
    /** Common event callbacks related to stream publishing. */

    /** Callback for updates on stream publishing status.   */
    @Override
    public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData){
        /** Implement the callback handling logic as needed. */
    }
});

3.4 Play streams

1. Start playing a stream

To start playing a remote audio or video stream, call the startPlayingStream method with the corresponding Stream ID passed to the streamID parameter and the view for rendering the video passed to the canvas parameter.

You can obtain the stream IDs of the streams published by other users in the room from the callback onRoomStreamUpdate.

You can use a SurfaceView, TextureView, or SurfaceTexture to render the video.

/**
 *  Start playing a remote stream with the SDK's default view mode (AspectFill).
 *  The play_view below is a SurfaceView/TextureView/SurfaceTexture object on UI.
 */
engine.startPlayingStream("stream1", new ZegoCanvas(play_view));

2. Listen for and handle the event callbacks related to stream playing

To listen for and handle various events that may happen after stream playing starts, you can implement the corresponding event callback methods of the event handler as needed. The following is a common event callback related to stream playing:

  • onPlayerStateUpdate: Callback for updates on stream playing status. After stream playing starts, if the status changes (for example, when the stream playing is interrupted due to network issues and the SDK retries to start playing the stream again), the SDK sends out the event notification through this callback.
engine.setEventHandler(new IZegoEventHandler() {
    /** Common event callbacks related to stream playing. */

    /** Callback for updates on stream playing status.  */
    @Override
    public void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData){
        /** Implement the callback handling logic as needed. */
    }
});

3.5 Test out real-time audio and video features

We recommend you run your project on a real device. If your app runs successfully, you should hear the sound and see the video captured locally from your device.

To test out the real-time audio and video features, visit the ZEGO Express Web Demo (only supported in the test environment), and enter the same AppID and RoomID to join the same room. If it runs successfully, you should be able to view the video from both the local side and the remote side, and hear the sound from both sides as well.

In audio-only scenarios, no video will be captured and displayed.

3.6 Stop publishing and playing streams

1. Stop publishing a stream

To stop publishing a local audio or video stream to remote users, call the stopPublishingStream method.

/** Stop publishing a stream */
engine.stopPublishingStream();

2. Stop the local video preview

If local video preview is started, call the stopPreview method to stop it as needed.

/** Stop local video preview */
engine.stopPreview();

3. Stop playing a stream

To stop playing a remote audio or video stream, call the stopPlayingStream method with the corresponding stream ID passed to the streamID parameter.

/** Stop playing a stream*/
engine.stopPlayingStream(streamID);

3.7 Log out of a room

To log out of a room, call the logoutRoom method with the corresponding room ID passed to the roomID parameter.

/** Log out of a room */
engine.logoutRoom("room1");

3.8 Destroy the ZegoExpressEngine instance

To destroy the ZegoExpressEngine instance and release the resources it occupies, call the destroyEngine method.

  • If you want to receive a callback to make sure the hardware resources are released, pass in the value callback when destroying the ZegoExpressEngine instance. This callback can only be used to send out a notification when the destruction of the engine is completed. You can't use this callback method to release engine-related resources.
  • If you don't want to receive any callbacks, pass null to destroyEngine instead.
/** Destroy the ZegoExpressEngine instance */
ZegoExpressEngine.destroyEngine(null);