Record Mixed Stream

Feature Overview

The Local Server Recording SDK supports mixing the audio/video streams of all users in a room into one view and then recording it. After integrating the SDK, you can start using its mixed-stream recording feature.

Prerequisites

• The ZEGOCLOUD Local Server Recording SDK has been integrated into your project. For details, see Quick Start - Integration.
• You have created a project in the ZEGOCLOUD Console and obtained a valid AppID. For details, see "Project Information" in Console - Project Management.

Steps

Set the callback listener

Before initialization, you need to inherit and implement ICallback, and set the callback listener.

• API prototype:

  ZEGO_API bool SetCallback(ICallback* pCB)

• Parameters:

  pCB: Pointer to the callback object.

• Note:

  Before initializing the SDK, you can call the following API as needed:

  SetLogDirAndSize sets the log file path and size

Initialize the SDK

Call the InitSDK API to initialize the SDK, and pass the obtained AppID into the parameter "uiAppID".

• API prototype:

  ZEGO_API bool InitSDK(unsigned int uiAppID)

  ZEGO_API bool InitSDK(unsigned int uiAppID)

• Parameters:

  uiAppID: The numeric ID issued by ZEGO, the unique identifier of each developer.

• Asynchronous callback interface:

  class ICallback
  {
  public:
      virtual void OnInitSDK(int errorCode) {}
  }

  class ICallback
  {
  public:
      virtual void OnInitSDK(int errorCode) {}
  }

  errorCode == 0 indicates that the initialization succeeded.

Set the token

Before logging in to a room, call the SetToken API to pass the Token into the SDK.

For how to obtain the Token, see Authenticate with Token.

• API prototype:

  ZEGO_API void SetToken(const char *pszToken, const char *pszRoomID);

  ZEGO_API void SetToken(const char *pszToken, const char *pszRoomID);

• Parameters:

  pszToken: The authentication Token. pszRoomID: Room ID, required.

Log in to the room

You need to log in to the room before recording.

• API prototype:

  ZEGO_API bool LoginRoom(const char* pszRoomID)

  ZEGO_API bool LoginRoom(const char* pszRoomID)

• Parameters:

  pszRoomID: Room ID, the ID of the room that is publishing streams.

• Asynchronous callback interface:

  class ICallback
  {
  public:
      virtual void OnLoginRoom(int errorCode, const char *pszRoomID) = 0;
  }

  class ICallback
  {
  public:
      virtual void OnLoginRoom(int errorCode, const char *pszRoomID) = 0;
  }

Start recording

1. This API must be called after the initialization succeeds.
2. It is recommended to start recording based on the added stream information after logging in to the room and receiving the OnStreamUpdate stream information update callback.
3. Before starting recording, you can call GetMaxRecordCount to get the maximum number of streams the SDK supports recording simultaneously, and handle the number of concurrently recorded streams based on its value.

• API prototype:

  ZEGO_API bool StartRecordMixStream(ZegoMixStreamRecordConfig *pConfig,
                                   const char *pszRoomID = nullptr)

  ZEGO_API bool StartRecordMixStream(ZegoMixStreamRecordConfig *pConfig,
                                   const char *pszRoomID = nullptr)

• Parameters:

  pConfig: The mixed-stream recording configuration. See ZegoMixStreamRecordConfig.

• Asynchronous callback interface:

  class ICallback
  {
  public:
      virtual void OnStreamRecordBegin(const char* pszStreamID, const char *pszPathAndName) = 0;
      virtual void OnMixStreamRecordUpdate(const char** ppszStreamID, int nStreamCount) = 0;
  }

  class ICallback
  {
  public:
      virtual void OnStreamRecordBegin(const char* pszStreamID, const char *pszPathAndName) = 0;
      virtual void OnMixStreamRecordUpdate(const char** ppszStreamID, int nStreamCount) = 0;
  }

  When recording starts successfully, the OnStreamRecordBegin callback is received, and when a stream with audio/video data is successfully pulled, the OnMixStreamRecordUpdate callback is received.

• Note:

  If you need to record single streams and the mixed stream at the same time, call EnableSingleAndMixRecordMode before starting recording to enable the mode of recording single streams and the mixed stream simultaneously; this mode consumes considerable system resources, and you can only start mixed-stream recording first and then start single-stream recording; stopping mixed-stream recording also stops all single-stream recordings at the same time. In this mode, the SDK has a limitation: mixed-stream recording mixes in all streams being recorded by single-stream recording. Even if a single stream being recorded is not set as an input stream of the mixed stream, as long as this single stream has audio, the audio will also be recorded by the mixed-stream recording.

Update the mixed-stream configuration

When you need to add input streams, when the original input streams change, or when the mixed-stream output configuration changes, reconstruct the mixed-stream configuration and call the API for updating the mixed-stream configuration.

• API prototype:

  ZEGO_API bool UpdateInputStreamConfig(ZegoStreamConfig *pInputStream, int nInputStreamCount,
                                      const char *pszRoomID = nullptr)

  ZEGO_API bool UpdateInputStreamConfig(ZegoStreamConfig *pInputStream, int nInputStreamCount,
                                      const char *pszRoomID = nullptr)

• Asynchronous callback interface:

  class ICallback
  {
  public:
      virtual void OnMixStreamRecordUpdate(const char** ppszStreamID, int nStreamCount) = 0;
  }

  class ICallback
  {
  public:
      virtual void OnMixStreamRecordUpdate(const char** ppszStreamID, int nStreamCount) = 0;
  }

  After the mixing succeeds, a callback containing the list of single-stream IDs participating in the mixed-stream recording is returned, which only includes the stream IDs whose data was successfully pulled. Note: This callback is triggered whenever the streams participating in the mixed-stream recording change, for example, when recording starts or a stream encounters an exception during recording.

Stop recording

• API prototype:

  ZEGO_API bool StopRecordMixStream(const char *pszRoomID = nullptr)

  ZEGO_API bool StopRecordMixStream(const char *pszRoomID = nullptr)

• Asynchronous callback interface:

  class ICallback
  {
  public:
      virtual void OnStreamRecordEnd(const char* pszStreamID, const char *pszPathAndName, RecordEndReason reason) = 0;
  }

  class ICallback
  {
  public:
      virtual void OnStreamRecordEnd(const char* pszStreamID, const char *pszPathAndName, RecordEndReason reason) = 0;
  }

• Note:

  It is recommended to do the following when recording is no longer needed:

  1. Call LogoutRoom to exit the room.
  2. Call LIVEROOM::SetCallback(nullptr); to remove the callback listener.
  3. Call UnInitSDK to uninitialize the SDK.

API Reference