AliRTCLinuxEngine API

Creates an AliRTCEngineInterface instance.

AliRTCEngineInterface * CreateAliRTCEngine(EngineEventHandlerInterface * eventHandler, int lowPort, int highPort,  const char * logPath, const char * coreServicePath, bool h5mode=false, const char * extra="");

Parameters

Returns A pointer to an AliRTCEngineInterface instance.

Destroys the AliRTCEngineInterface instance.

virtual void Release() = 0;

Retrieves the event handler.

virtual EngineEventHandlerInterface * GetEventHandler() = 0;

Returns A pointer to the registered event handler.

Joins a channel.

virtual int JoinChannel(const AuthInfo &authInfo, const JoinChannelConfig &config) = 0;

Parameters

Returns A return value of 0 indicates success; a non-zero value indicates an error.

Joins a channel.

virtual int JoinChannel(const char *token, const char *channelId, const char *userId, const char *userName, const JoinChannelConfig &config) = 0;

Parameters

Returns

Leaves the channel.

virtual int LeaveChannel() = 0;

Returns 0 if successful, and a non-zero value otherwise.

Checks if the local camera track is published.

virtual bool IsLocalVideoStreamPublished() = 0;

Returns true if the local camera track is published; false otherwise.

Checks whether publishing the screen track is enabled.

virtual bool IsLocalScreenPublishEnabled() = 0;

Returns true if publishing is enabled; false otherwise.

Checks whether the local audio track is published.

virtual bool IsLocalAudioStreamPublished() = 0;

Returns

Checks whether simulcast is enabled for publishing the camera track.

virtual bool IsDualStreamPublished() = 0;

Returns
true if enabled; false otherwise.

Enables or disables the external video source.

virtual int SetExternalVideoSource(bool enable, VideoSource sourceType, RenderMode renderMode = RenderModeFill) = 0;

After enabling the external video source, call PushExternalVideoFrame to push video data.

Parameters

Returns Returns 0 on success, or an error code on failure.

Pushes an external video frame. This method does not support 2K or higher resolution video.

virtual int PushExternalVideoFrame(VideoDataSample *frame, VideoSource sourceType) = 0;

Parameters

Returns Returns 0 on success or an error code on failure. If this method returns ERR_AUDIO_BUFFER_FULL, adjust the send rate.

Enables or disables stream publishing from an external audio source.

virtual int SetExternalAudioSource(bool enable, unsigned int sampleRate,  unsigned int channelsPerFrame) = 0;

Parameters

Returns 0 on success; a non-zero value indicates failure.

Pushes raw external audio data for streaming.

virtual int PushExternalAudioFrameRawData(const void* audioSamples, unsigned int sampleLength, long long timestamp) = 0;

Parameters

Returns Returns 0 on success, or a non-zero value on failure. If the return value is ERR_AUDIO_BUFFER_FULL, the audio buffer is full, and you should retry the operation after a delay equal to the duration of the audio data you tried to push.

Sets the audio profile.

virtual int SetAudioProfile(AudioQualityMode audioProfile, AudioSceneMode audioScene) = 0;

Parameters

Returns 0 indicates success, while a non-zero value indicates failure.

Sets the publishing volume of the external audio.

virtual int SetExternalAudioPublishVolume(int volume) = 0;

Parameters

Returns Returns 0 on success. Any other value indicates failure.

Gets the mixing volume of the external audio for publishing.

virtual int GetExternalAudioPublishVolume() = 0;

Returns
The mixing volume.

Sends Supplemental Enhancement Information (SEI) for small-scale data transfer, with the message limited to 4,096 bytes.

virtual int SendMediaExtensionMsg(const char* message, size_t length, int repeatCount, uint32_t delay, bool isKeyFrame) = 0;

Parameters

Returns Returns 0 on success and a non-zero value on failure.

Enables or disables publishing the dual stream.

virtual int PublishLocalDualStream(bool enabled) = 0;

The dual stream is published only if the main video stream is also published. Before enabling the dual stream, you must first enable video stream publishing by calling the PublishLocalVideoStream method. By default, the SDK does not publish the dual stream. You can call this method before joining a channel to change the default setting. This setting takes effect when you start publishing the video stream.

Parameters

Returns Returns 0 on success and a non-zero value on failure.

Sets whether to publish the local video stream from the camera.

virtual int PublishLocalVideoStream(bool enabled) = 0;

By default, the SDK publishes the local video stream. You can call this API before joining a channel to change the default setting. The new setting applies after you join the channel.

Parameters

Return value 0 indicates success; any other value indicates failure.

Enables or disables publishing the local audio stream.

virtual int PublishLocalAudioStream(bool enabled) = 0;

By default, the SDK publishes the audio stream. To change this setting, call this method before joining a channel. The change takes effect when you join the channel.

Parameters

Returns 0 indicates success. Any other value indicates failure.

Starts or stops publishing the screen share stream.

virtual int PublishScreenShareStream(bool enabled) = 0;

Parameters

Returns A return value of 0 indicates success. Any other value indicates failure.

Subscribes to or unsubscribes from the audio stream of a specified remote user. You must call this method after joining a channel.

virtual int SubscribeRemoteAudioStream(const char* uid, bool sub) = 0;

Parameters

Returns Returns 0 if the method call succeeds; otherwise, it returns an error code.

Subscribes to or unsubscribes from the video stream of a remote user. Call this method only after joining a channel.

virtual int SubscribeRemoteVideoStream(const char* uid, VideoTrack videoTrack, bool sub) = 0;

Parameters

Returns
Returns 0 on success, or an error code on failure.

Sets the video encoder configuration for the camera stream.

virtual void SetVideoEncoderConfiguration(const AliEngineVideoEncoderConfiguration& config) = 0;

This method sets the encoding parameters for the camera stream, such as resolution, frame rate, bitrate, and video orientation. If you specify a parameter outside its valid range, the SDK automatically adjusts it to the nearest valid value. You can call this method before or after joining a channel. If you only need to set the video encoder configuration once per session, call this method before joining the channel.

Parameters

Sets the video encoding properties for the screen stream.

virtual int SetScreenShareEncoderConfiguration(const AliEngineScreenShareEncoderConfiguration& config) = 0;

This method sets the video parameters for the screen stream, including resolution, frame rate, bitrate, and video orientation. All parameters have valid ranges. If a parameter is outside its valid range, the SDK automatically adjusts it to a compliant value. You can call this method before or after joining a conference. If you only need to set these properties once per conference, we recommend calling this method before joining.

Parameters

Specifies whether to subscribe to the high or low video stream from a remote user.

virtual int SetRemoteVideoStreamType(const char* uid, AliEngineVideoStreamType streamType) = 0;

By default, a publisher does not send a low stream. Subscribers can choose between the high and low streams only after the publisher enables dual-stream mode by calling PublishLocalDualStream(true). Otherwise, the subscriber can only receive the high stream.

Parameters

Returns 0 on success, or a non-zero value on failure.

Stops or resumes sending local video data.

virtual int MuteLocalCamera(bool mute) = 0;

Parameters

Returns 0 indicates success, and a non-zero value indicates failure.

Stops or resumes sending local audio data.

virtual int MuteLocalMic(bool mute) = 0;

Parameters

Returns 0 if the method call succeeds, or an error code if it fails.

Sets the user role.

virtual int SetClientRole(const AliEngineClientRole clientRole) = 0;

You can call this method only when the channel profile is AliRtcChannelProfileCommunication. This method can be called either before or after joining a channel. A successful call to this method triggers the OnUpdateRoleNotify callback. To switch the user role from Interactive to Live, you must first stop publishing the stream. Otherwise, the method call fails. When the channel profile is AliRtcChannelProfileInteractiveLive, the user role defaults to AliRtcClientRoleLive.

Parameters

Returns Returns 0 on success and a non-zero value on failure.

Sets the default video stream type to subscribe to.

virtual int SetRemoteDefaultVideoStreamType(const AliEngineVideoStreamType streamType) = 0;

Parameters

Returns 0 on success; any other value indicates failure.

In audience mode, if all streamers in a room stop publishing their streams, the OnError callback is immediately triggered with the ERR_NO_PEOPLE error code.

virtual int LeaveOnceNoStreamer(bool enable) = 0;

This feature is designed for moderation scenarios.

Parameters

Returns Returns 0 on success; any other value indicates failure.

Sets a waiting period after a user joins a meeting. If no other users are online during this period, the SDK triggers the OnError callback with the ERR_NO_PEOPLE error code.

virtual int SetPeriodForCheckPeople(int seconds) = 0;

Parameters

Returns A return value of 0 indicates that the method call succeeded. Any other value indicates failure.

Sets custom configuration using a JSON-formatted string. For example, this method lets you enable or disable the dataChannel.

virtual int SetParameter(const char* params) = 0;

Parameters

Returns 0 on success; a non-zero value on failure.

Generates the token required to join a channel locally, bypassing application server authentication.

virtual void GenerateToken(AuthInfo& authInfo, const char* appkey) {}

This method automatically determines which token type to generate. If the length of authInfo.token is less than 64, it generates a multi-parameter token. If the length is 64, it generates a single-parameter token.

Parameters

Sends data through the data channel.

virtual int SendDataChannelMessage(AliEngineDataChannelMsg ctrlMsg) = 0;

Limitations

• Hosts can send and receive messages, while viewers can only receive messages.

• You must call setParameter to enable the custom message channel.

• Data transmission has the following limits:

  • The maximum bitrate is 30 KB/s.

  • The data channel is limited to 60 data packets per second, with each packet up to 1 KB in size.

Parameters

Returns A return value of 0 indicates a successful method call; other values indicate a failure.

Sets the log level.

int SetLogLevel(const LogLevel logLevel, bool upload);

Parameters

Return value 0 indicates the method call was successful; any other value indicates failure.

Notifies the business layer when an error occurs in the engine.

virtual void OnError(ERROR_CODE error_code) {}

Parameter

Notifies the business layer when the engine reports a warning.

virtual void OnWarning(WARNING_CODE warning_code) {}

Parameters

Reports the result of a user's attempt to join a channel.

virtual void OnJoinChannelResult(int result, const char *channel, const char *userId) {
        fprintf(stdout, "[Client] On join channel result: %d\n", result);
    }

After the application calls JoinChannel, this callback reports whether the user successfully joined the channel.

Parameters

Called when the data channel receives a remote message.

virtual void OnDataChannelMsg(const char* uid, AliEngineDataChannelMsg& msg) {}

Parameters

Reports the result of leaving a channel.

virtual void OnLeaveChannelResult(int result) {}

When your application calls the LeaveChannel method, this callback is triggered to report the result of leaving the channel. This callback is not triggered if you call LeaveChannel and then immediately call Release on the SDK.

Parameters

Occurs when a remote user in communication mode or a host in interactive mode joins the channel.

virtual void OnRemoteUserOnLineNotify(const char * uid) {}

The SDK triggers this callback in the following scenarios:

Callback behavior in interactive mode: 1. Hosts receive this callback when other hosts join the channel. 2. Audience members receive this callback when a host joins the channel. 3. Hosts do not receive this callback when an audience member joins the channel.

Parameters

Occurs when a remote user in communication mode, or a broadcaster in interactive mode, leaves the channel.

virtual void OnRemoteUserOffLineNotify(const char * uid) {}

The SDK triggers this callback in the following scenarios.

This callback also triggers when a remote user in communication mode or a broadcaster in interactive mode disconnects due to a timeout, for instance, when their data is not received for an extended period.

Parameters

Occurs when the audio subscription state changes.

virtual void OnAudioSubscribeStateChanged(const char *uid, AliEngineSubscribeState oldState, AliEngineSubscribeState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Triggered when the subscription state of a camera stream changes.

virtual void OnVideoSubscribeStateChanged(const char *uid, AliEngineSubscribeState oldState, AliEngineSubscribeState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Triggered when the subscribed stream type changes.

virtual void OnSubscribeStreamTypeChanged(const char *uid, AliEngineVideoStreamType oldStreamType, AliEngineVideoStreamType newStreamType, int elapseSinceLastState, const char *channel) {}

Parameters

Triggered when the subscription state of the screen sharing stream changes.

virtual void OnScreenShareSubscribeStateChanged(const char *uid, AliEngineSubscribeState oldState, AliEngineSubscribeState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Triggered when the screen sharing publishing state changes.

virtual void OnScreenSharePublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Occurs when the dual stream publish state changes.

virtual void OnDualStreamPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Occurs when the video publishing state changes.

virtual void OnVideoPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Triggered when the audio publishing state changes.

virtual void OnAudioPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {}

Parameters

Provides the audio data of a single remote user before audio mixing.

virtual void OnSubscribeAudioFrame(const char* uid, const AudioFrame * frame) {}

This callback corresponds to the AliRTCSdk::Linux::AudioFormatPcmBeforMixing audio format.

Parameters

This callback is triggered for subscribed audio data.

virtual void OnSubscribeMixAudioFrame(const AudioFrame * frame) {}

Provides the mixed audio data from all remote users, ready for playback. The data format is AudioFormatMixedPcm.

Parameters

This callback provides the raw video data from a subscribed remote user.

virtual void OnRemoteVideoSample(const char* uid, const VideoFrame * frame) {}

Parameters

Reports the encoded video data received from a remote user before decoding.

virtual void OnRemoteVideoEncodedSample(const char* uid, const VideoFrame * frame) {}

Parameters

Occurs when a media extension message is received.

virtual void OnMediaExtensionMsgReceived(const char* userid, const char* message, size_t size) {}

When a user calls SendMediaExtensionMsg, other users in the channel receive the message through this callback.

Parameters

Reports the result of a snapshot operation.

virtual void OnSnapshotComplete(const char* userId, VideoTrack videoSource, void* buffer, int width, int height, bool success) {}

The SDK triggers this callback when a snapshot operation is complete.

Parameters

Reports the audio data of each remote user before mixing.

virtual void OnPlaybackAudioFrameBeforeMixing(const char *uid, AudioFrame *frame) {}

The SDK triggers this callback when the audio format for the subscription is set to AudioFormatPcmBeforeMixing.

Parameters

Occurs when the user role changes.

virtual void OnUpdateRoleNotify(const AliEngineClientRole oldRole, const AliEngineClientRole newRole) {}

This callback is triggered after a successful call to SetClientRole.

Parameters

Provides the AAC-transcoded audio data from each subscribed stream for custom audio archiving.

virtual void OnSubscribeAudioAac(const char* uid, const AudioFrame * frame) {}

Parameters

Outputs the mixed audio, transcoded to AAC, for custom audio archiving.

virtual void OnSubscribeMixedAudioAac(const AudioFrame * frame) {}

Parameters