AliRTCLinuxEngine API

Creates and returns an AliRTCEngineInterface instance.

def CreateAliRTCEngine(eventHandler:EngineEventHandlerInterface, lowPort:int, highPort:int, \
                       logPath:str, coreServicePath:str, h5mode:bool, extra:str) -> AliRTCEngineInterface

Parameters

Returns an AliRTCEngineInterface instance.

Destroys the AliRTCEngineInterface instance.

def Release() -> None

Gets the event handler.

def GetEventHandler() -> EngineEventHandlerInterface

Return value: The event handler.

Joins a channel without requiring a nonce or timestamp. This method simplifies integration and improves compatibility with SDKs from other vendors.

def JoinChannel(token:str, channelId:str, userId:str, userName:str, config:JoinChannelConfig) -> int

Parameters

Returns 0 on success; a negative value on failure.

Leaves the channel.

def LeaveChannel() -> int

Returns
0 if the method call succeeds, or a non-zero value if it fails.

Checks if the camera track is published.

def IsLocalVideoStreamPublished() -> bool

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

Checks whether publishing the screen track is enabled.

def IsLocalScreenPublishEnabled() -> bool

Returns
true if publishing is enabled; false otherwise.

Checks if the local audio stream can be published.

def IsLocalAudioStreamPublished() -> bool

Returnstrue if publishing is allowed; false otherwise.

Checks whether simulcast publishing for the camera track is enabled.

def IsDualStreamPublished() -> bool

Returns
Returns true if enabled, or false otherwise.

Enables the external video source.

def SetExternalVideoSource(enable:bool, sourceType:VideoSource, renderMode:RenderMode) -> int

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

Parameters

Returns

Pushes an external video frame. Resolutions of 2K or higher are not supported.

def PushExternalVideoFrame(frame:VideoDataSample, sourceType:VideoSource) -> int

The video frame supports various formats, such as YUV and RGB.

Parameters

Returns Returns 0 on success, or a non-zero value on failure. If the return value is ERR_AUDIO_BUFFER_FULL, you can adjust the sending rate.

Enables or disables publishing from an external audio source.

def SetExternalAudioSource(enable:bool, sampleRate:int, channelsPerFrame:int) -> int

Call SetExternalAudioPublishVolume to set the publishing volume for the external audio source.

Parameters

Returns

Pushes raw external audio data to a stream.

def PushExternalAudioFrameRawData(audioSamples:bytes, sampleLength:int, timestamp:int) -> int

Parameters

Returns
Returns 0 on success or a non-zero value on failure. A return value of ERR_AUDIO_BUFFER_FULL means the audio buffer is full; retry after the data sending interval.

Sets the audio quality and scene.

def SetAudioProfile(audioProfile:AudioQualityMode, audioScene:AudioSceneMode) -> int

Parameters

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

Sets the volume of the external audio input for publishing.

def SetExternalAudioPublishVolume(volume:int) -> int

Parameters

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

Gets the publishing volume of the mixed external audio.

def GetExternalAudioPublishVolume() -> int

Returns
The publishing volume.

Sends a media extension message (SEI) to embed small amounts of application-specific data into the video stream. The maximum message size is 4,096 bytes.

def SendMediaExtensionMsg(message:bytes, length:int, repeatCount:int, delay:int, isKeyFrame:bool) -> int

Parameters

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

Enables or disables publishing the secondary video stream.

def PublishLocalDualStream(enabled:bool) -> int

The secondary video stream is published only if the main video stream is published. Before enabling the secondary video stream, call the PublishLocalVideoStream method to publish the main video stream. By default, the SDK does not publish the secondary video stream. You can call this method before you join a channel to change the default setting. The setting takes effect when you publish the video stream.

Parameters

Returns

Publishes or unpublishes the local video stream.

def PublishLocalVideoStream(enabled:bool) -> int

By default, the SDK publishes the video stream. You can call this method before joining a channel to change the default setting. The change takes effect when you join the channel.

Parameters

Return value

Enables or disables publishing the local audio stream.

def PublishLocalAudioStream(enabled:bool) -> int

By default, the SDK publishes the local audio stream. You can call this method before joining a channel to change the default setting. This setting takes effect after you join the channel.

Parameters

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

Starts publishing the screen share stream.

def PublishScreenShareStream(enabled:bool) -> int

Parameters

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

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

def SubscribeRemoteAudioStream(uid:str, sub:bool) -> int

Parameters

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

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

def SubscribeRemoteVideoStream(uid:str, videoTrack:VideoTrack, sub:bool) -> int:

Parameters

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

Sets the video encoder configuration for the camera stream.

def SetVideoEncoderConfiguration(config:AliEngineVideoEncoderConfiguration) -> int

This method sets the video parameters for the camera stream, such as resolution, frame rate, bitrate, and video orientation. All parameters have valid ranges. If you specify values outside these ranges, the SDK automatically adjusts them. You can call this method either before or after joining a channel. If you only need to set the video encoder configuration once per session, it is recommended to call this method before joining.

Parameters

Sets the video encoder configuration for the screen sharing stream.

def SetScreenShareEncoderConfiguration(config:AliEngineScreenShareEncoderConfiguration) -> int

This method sets the video encoder configuration for the screen sharing stream, including resolution, frame rate, bitrate, and video orientation. All parameters have valid ranges. If you set a parameter outside its valid range, the SDK automatically adjusts it. You can call this method either before or after you join a meeting. If you only need to configure screen sharing once per session, call this method before joining.

Parameters

Sets the video stream type to subscribe to for a remote user, either the high stream or the low stream.

def SetRemoteVideoStreamType(uid:str, streamType:AliEngineVideoStreamType) -> int

By default, the publisher does not publish the low stream. The subscriber can choose to subscribe to the high stream or low stream only after the publisher enables dual-stream mode by calling PublishLocalDualStream(true). Otherwise, the subscriber can subscribe only to the high stream.

Parameters

Returns

Stops or resumes sending the local video stream.

def MuteLocalCamera(mute:bool) -> int

Parameters

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

Stops or resumes sending local audio data.

def MuteLocalMic(mute:bool) -> int

Parameters

Returns

Sets the user role.

def SetClientRole(clientRole:AliEngineClientRole) -> int

You can call this method before or after joining a channel, but only in the AliRtcChannelProfileCommunication channel mode. If the call is successful, the SDK triggers the OnUpdateRoleNotify callback. To switch from an interactive role to a live role, you must first stop publishing your stream. Otherwise, the call fails. In the AliRtcChannelProfileInteractiveLive channel mode, the default user role is AliRtcClientRoleLive.

Parameters

Return value

Sets the default video stream type for remote subscriptions.

def SetRemoteDefaultVideoStreamType(streamType:AliEngineVideoStreamType) -> int

Parameters

Returns

For users in audience mode, when all streamers in the room stop streaming, the SDK immediately triggers the OnError callback with the error code ERR_NO_PEOPLE.

def LeaveOnceNoStreamer(enable:bool) -> None

This feature is designed for content moderation scenarios.

Parameters

After joining a channel, if no one else joins within the specified period, the SDK triggers the OnError callback with the ERR_NO_PEOPLE error code.

def SetPeriodForCheckPeople(seconds:int) -> None

If a timeout occurs, the attempt to join the channel fails, and the OnJoinChannelResult callback returns -1. This feature is for moderation scenarios. By default, the maximum duration for this check is 5 seconds.

Parameters

Applies a custom configuration using a JSON string, such as enabling or disabling the dataChannel.

def SetParameter(params:str) -> int

Parameters

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

Generates a token locally for channel authentication. This token is required to call the JoinChannel method, enabling you to bypass an appserver.

def GenerateToken(authInfo:AuthInfo, appkey:str) -> None

The generated token is used as a parameter for joining a channel.

Parameters

Sends data through the data channel.

def SendDataChannelMessage(ctrlMsg:AliEngineDataChannelMsg) -> int

Usage limits

• Anchors can send and receive messages, while the audience can only receive messages.

• Call the setParameter method to enable the custom message channel.

• The following limits apply to sending data:

  • Maximum bitrate: 30 Kbps.

  • The data channel supports a maximum of 60 data packets per second, with each packet limited to 1 KB.

Parameters

Returns

Notifies the application layer when the engine encounters an error.

def OnError(self, error_code:ERROR_CODE) -> None

Parameters

Notifies the business layer when the engine reports a warning.

def OnWarning(self, warning_code:WARNING_CODE) -> None

Parameters

Reports the result of joining a channel.

def OnJoinChannelResult(self, result:int, channel:str, userId:str) -> None

This callback is triggered when the application calls the JoinChannel method. It indicates whether the user successfully joined the channel.

Parameters

Triggered when you receive a message from a remote user through the data channel.

def OnDataChannelMsg(self, uid:str, msg:AliEngineDataChannelMsg) -> None

Parameters

Reports the result of leaving a channel.

def OnLeaveChannelResult(self, result:int) -> None

When your application calls the LeaveChannel method, the SDK triggers this callback to report the result. If you destroy the SDK instance immediately after calling LeaveChannel, you will not receive this callback.

Parameters

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

def OnRemoteUserOnLineNotify(self, uid:str) -> None

The SDK triggers this callback in the following scenarios:

In interactive mode, this callback behaves as follows:

1. Hosts receive this callback when other hosts join the channel.

2. Audience members receive this callback when hosts join the channel.

3. Hosts do not receive this callback when audience members join the channel.

Parameters

Triggered when a remote user leaves the channel in communication mode, or when a host leaves the channel in interactive mode.

def OnRemoteUserOffLineNotify(self, uid:str) -> None

This callback occurs in the following scenarios:

The SDK also triggers this callback when a user in communication mode or a host in interactive mode times out. A user times out if the SDK does not receive their data packets for an extended period.

Parameters

This callback notifies you when the state of a remote user's audio or video stream changes.

def OnRemoteTrackAvailableNotify(self, uid:str, audioTrack:AudioTrack, videoTrack:VideoTrack) -> None

The SDK triggers this callback in the following scenarios:

1. A remote user starts publishing an audio or video stream.

2. A remote user stops publishing an audio or video stream.

3. In interactive mode, an audience member calls SetClientRole to switch to the broadcaster role (AliEngineClientRoleInteractive) and starts publishing a stream.

The SDK triggers this callback only for users in communication mode and broadcasters in interactive mode.

Parameters

Fires when the audio subscription state changes.

def OnAudioSubscribeStateChanged(self, uid:str, oldState:AliEngineSubscribeState, newState:AliEngineSubscribeState,
                                     elapseSinceLastState:int, channel:str) -> None

Parameters

Triggered when the camera stream subscription state changes.

def OnVideoSubscribeStateChanged(self, uid:str, oldState:AliEngineSubscribeState, newState:AliEngineSubscribeState,
                                     elapseSinceLastState:int, channel:str) -> None

Parameters

Triggers when the subscribed stream type (main stream or substream) changes.

def OnSubscribeStreamTypeChanged(self, uid:str, oldStreamType:AliEngineVideoStreamType, newStreamType:AliEngineVideoStreamType,
                                     elapseSinceLastState:int, channel:str) -> None

Parameters

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

def OnScreenShareSubscribeStateChanged(self, uid:str, oldState:AliEngineSubscribeState, newState:AliEngineSubscribeState,
                                           elapseSinceLastState:int, channel:str) -> None

Parameters

Triggered when the screen share publishing state changes.

def OnScreenSharePublishStateChanged(self, oldState:AliEnginePublishState, newState:AliEnginePublishState,
                                         elapseSinceLastState:int, channel:str) -> None

Parameters

Triggers when the dual stream publish state changes.

def OnDualStreamPublishStateChanged(self, oldState:AliEnginePublishState, newState:AliEnginePublishState,
                                        elapseSinceLastState:int, channel:str) -> None

Parameters

Called when the video publishing state changes.

def OnVideoPublishStateChanged(self, oldState:AliEnginePublishState, newState:AliEnginePublishState,
                                   elapseSinceLastState:int, channel:str) -> None

Parameters

Triggers when the audio stream's publishing state changes.

def OnAudioPublishStateChanged(self, oldState:AliEnginePublishState, newState:AliEnginePublishState,
                                   elapseSinceLastState:int, channel:str) -> None

Parameters

Reports the audio data of each remote user before audio mixing.

def OnSubscribeAudioFrame(self, uid:str, frame:AudioFrame) -> None

This callback is triggered for each audio frame. For more information, see AliRTCSdk::Linux::AudioFormatPcmBeforMixing.

Parameters

Provides the mixed audio data from all subscribed remote users.

def OnSubscribeMixAudioFrame(self, frame:AudioFrame) -> None

This audio data is ready for local playback. For details, see AudioFrame: The audio frame class.

Parameters

Occurs when the SDK receives the raw video data of a subscribed remote user.

def OnRemoteVideoSample(self, uid:str, frame:VideoFrame) -> None

Parameters

Reports the encoded data from a subscribed remote video stream before decoding.

def OnRemoteVideoEncodedSample(self, uid:str, frame:VideoFrame) -> None

Parameters

Occurs when a media extension message is received.

def OnMediaExtensionMsgReceived(self, userid:str, message:bytes, size:int) -> None

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

Parameters

Occurs when the user role changes.

def OnUpdateRoleNotify(self, oldRole:AliEngineClientRole, newRole:AliEngineClientRole) -> None

The SDK triggers this callback after the role is successfully changed by calling SetClientRole.

Parameters

The SDK triggers this callback upon receiving an AAC-encoded audio frame from a subscribed remote user. You can use this callback to transcode individual audio streams to the AAC format for use cases such as custom audio archiving.

def OnSubscribeAudioAac(self, uid:str, frame:AudioFrame) -> None

Parameters

Occurs when an AAC-encoded mixed audio frame is received. This callback enables custom audio archiving by transcoding the mixed audio stream to the AAC format.

def OnSubscribeMixedAudioAac(self, frame:AudioFrame) -> None

Parameters

Called when the SDK audio buffer is full because audio data is being pushed too quickly or unevenly.

def OnPushAudioFrameBufferFull(self, isFull:bool) -> None

Parameters

This callback is triggered when the SDK's internal video buffer is full, which occurs when video data is pushed too quickly or unevenly.

def OnPushVideoFrameBufferFull(self, isFull:bool) -> None

Parameters