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

Publishing Streams

Update Time:2021-04-25 20:24

1 Introduction

When users participate in a call or a live broadcast, if they want their video to be visible to other participants, they need to stream their video to ZEGO's cloud servers so that other participants can play the streams from the cloud and view the video.

2 Procedures

Call the API startPublishingStream to start publishing a stream to ZEGO's live streaming cloud, and call the API stopPublishingStream to stop the stream publishing when needed. To handle the events related to stream publishing, please listen for and handle the corresponding event callbacks when setting up the event handler.

2.1 Start Publishing Streams

  • API Function Prototype
    /**
     * Start publishing a stream
     *
     * Call this API to publish a media stream to ZEGO's live streaming cloud. Users in the same room can pull the stream from ZEGO servers by specifying the streamID. 
     * Before publishing a stream, it is required to log in to a room by calling the API [loginRoom]. When a stream is published successfully, users in the same room can be notified of such events and obtain the streamID through the callback [onRoomStreamUpdate].
     * In the case of poor network quality, the stream publishing may get interrupted. The SDK will try to reconnect and restart the stream publishing automatically. Listen for the callback [onPublisherStateUpdate] to handle such events.
     * @param streamID: the stream ID, which is a string with a maximum length of 256 bytes and contains only numbers, letters, and special characters listed here: '~', '!', '@', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'. The streamID CANNOT contain any URL keywords, or the stream publishing will fail. The streamID must be globally unique within the scope of the AppID.
     */
    public void startPublishingStream(String streamID);
  • API Call Example
/** Start publishing a stream */
engine.startPublishingStream("stream1");

Notes: It is recommended to set up parameters for stream publishing and preview before staring to publish a stream.
ZEGO Express SDK has many stream publishing parameters, including video frame rate/bit rate/resolution, audio bit rate, phone orientation, beautification and filters, video mirroring, front/rear camera selection, etc. If not specified, default settings will apply.

2.2 Start/Stop Local Preview

If users want to start/stop viewing their own video, call the following APIs to set up the view of the preview, and start/stop the preview as needed.

Preview can be rendered to:SurfaceView/TextureView/SurfaceTexture

  • API Call Example
/**
 *  Set up the view for preview and start the preview with SDK's default view mode (AspectFill).
 *  The object preview_view below is the UI object for displaying the preview, which can be a SurfaceView, TextureView, or SurfaceTexture.
 */
engine.startPreview(new ZegoCanvas(preview_view));
/** Stop preivew */
engine.stopPreview();

2.3 Stop Publishing Streams

  • API Function Prototype
   /**
     * Stop publishing Streams
     *
     * Call this API to stop publishing the local media stream.
     * If the user is already publishing a stream, it is required to call this API to end the current publishing before starting to publish a new stream (with new streamID). 
     */
    public void stopPublishingStream();
  • API Call Example
/** stop publishing streams */
engine.stopPublishingStream();

Stream Publishing Error Codes

Listed below are the stream publishing related event callbacks that need to be handled in common scenarios.

  • API Call Example
engine.setEventHandler(new IZegoEventHandler() {
    //....
    /** listed below are common stream publishing related event callbacks */

    @Override
    public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData){
        /** When the status of the stream publisher changes, for example, when the streaming publishing gets interrupted due to network problems, the SDK will notify such events through this callback. */
        //....
    }
});

3 API Reference

Method Description
startPublishingStream Starts publishing a stream.
stopPublishingStream Stops publishing a stream.
startPreview Starts the local video preview.
stopPreview Stops the local video preview.
Callback Description
onPublisherStateUpdate The callback triggered when the status of stream publishing changes.
onPublisherQualityUpdate The callback triggered every 3 seconds to report the current stream publishing quality.

If users want to have two-way video communication with other participants in a call or live broadcast, they will also need to play the audio/video streams published by those participants. Use the next/previous buttons below or the side navigation bar on the left to navigate to the related documents.

  • Quick Start- Playing Streams