AliRTCEngine interface

Creates an AliRTCEngineInterface instance.

func CreateAliRTCEngine(eventHandler EngineEventHandlerInterface, lowPort, highPort int, logPath, coreServicePath string, h5mode bool, extra string) AliRTCEngineInterface

Parameters

Returns An AliRTCEngineInterface instance.

Releases resources held by the AliRTCEngineInterface instance.

Release() error

Retrieves the event handler.

GetEventHandler() EngineEventHandlerInterface

Returns: The event handler instance.

This syntactic sugar method joins a channel without requiring nonce and timestamp parameters, simplifying compatibility with third-party SDKs.

JoinChannel(token, channelId, userId, userName string, config *JoinChannelConfig) int

Parameters

Returns A return value of 0 indicates the method call succeeded. Any non-zero value indicates failure.

Leaves a channel.

LeaveChannel() int

Returns

Checks if the camera track is published.

IsLocalVideoStreamPublished() bool

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

Checks if publishing the local screen track is enabled.

IsLocalScreenPublishEnabled() bool

return value
true if publishing is enabled; false otherwise.

Checks if publishing the local audio track is allowed.

IsLocalAudioStreamPublished() bool

Returns: true if publishing is allowed; false otherwise.

Checks if simulcast publishing for the camera track is enabled.

IsDualStreamPublished() bool

Returns true if enabled; false otherwise.

Enables the external video source.

SetExternalVideoSource(enable bool, sourceType VideoSource, renderMode RenderMode) int

Once enabled, use the PushExternalVideoFrame method to push video data.

Parameters

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

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

PushExternalVideoFrame(frame *VideoDataSample, sourceType VideoSource) int

Input video frames can be in multiple formats, such as YUV and RGB.

Parameters

Returns A return value of 0 indicates a successful call. Any other value indicates a failed call. If the method returns ERR_AUDIO_BUFFER_FULL, adjust the sending rate.

Enables or disables publishing from an external audio source.

SetExternalAudioSource(enable bool, sampleRate, channelsPerFrame int) int

Call SetExternalAudioPublishVolume to set the publish volume.

Parameters

Returns A return value of 0 indicates success, while any other value indicates failure.

Pushes external audio data for streaming.

PushExternalAudioFrameRawData(audioSamples []byte, sampleLength int, timestamp int64) int

Parameters

Returns A return value of 0 indicates success; any other value indicates failure. If ERR_AUDIO_BUFFER_FULL is returned, retry the operation after a delay equal to the audio data's duration.

Sets the audio profile.

SetAudioProfile(audioProfile AudioQualityMode, audioScene AudioSceneMode) int

Parameters

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

Sets the publishing volume of the external audio input.

SetExternalAudioPublishVolume(volume int) int

Parameters

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

Gets the volume for mixing external audio into the published stream.

GetExternalAudioPublishVolume() int

Returns
The mixing volume.

Sends Supplemental Enhancement Information (SEI) containing small amounts of application data. The maximum length is 4,096 bytes.

SendMediaExtensionMsg(message []byte, length, repeatCount, delay int, isKeyFrame bool) int

Parameters

Returns 0 on success. Any other value indicates failure.

Enables or disables publishing the secondary video stream.

PublishLocalDualStream(enabled bool) int

The secondary video stream is published only if the primary video stream is also being published. Before enabling the secondary video stream, call the PublishLocalVideoStream method to publish the primary video stream. By default, the SDK does not publish the secondary video stream. You can call this method before joining a channel to change this default setting. This setting takes effect when you start publishing the primary video stream.

Parameters

Returns

Enables or disables publishing the local video stream from the camera.

PublishLocalVideoStream(enabled bool) int

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

Parameters

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

Enables or disables publishing the local audio stream.

PublishLocalAudioStream(enabled bool) int

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

Parameters

Returns A return value of 0 indicates the method call succeeded; any other value indicates it failed.

Starts publishing the screen share stream.

PublishScreenShareStream(enabled bool) int

Parameters

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

Subscribes to or unsubscribes from the audio stream of a specified remote user. You must join a channel before calling this method.

SubscribeRemoteAudioStream(uid string, sub bool) int

Parameters

Returns A return value of 0 indicates success; any other value indicates failure.

Subscribes to or unsubscribes from the video stream of a specified remote user. You must call this method during a call. Calling it before joining a channel has no effect.

SubscribeRemoteVideoStream(uid string, videoTrack VideoTrack, sub bool) int

Parameters

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

Sets the video encoder configuration for the camera stream.

SetVideoEncoderConfiguration(config AliEngineVideoEncoderConfiguration) int

This method sets video parameters for the camera stream, such as resolution, frame rate, bitrate, and video orientation. 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 set the video encoder configuration once per meeting, call this method before joining the meeting.

Parameters

Sets the screen share encoder configuration.

SetScreenShareEncoderConfiguration(config AliEngineScreenShareEncoderConfiguration) int

Sets the video parameters for the screen share, such as 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 to a supported value. You can call this method either before or after you join a meeting. If you only need to set the encoder configuration once per meeting, call this method before you join the meeting.

Parameters

Sets the type of remote camera stream to receive: the high-resolution stream or the low-resolution stream.

SetRemoteVideoStreamType(uid string, streamType AliEngineVideoStreamType) int

By default, a publisher does not send the low-resolution stream. A subscriber can subscribe to either the high-resolution or low-resolution stream only after the publisher enables dual-stream mode by calling PublishLocalDualStream(true). Otherwise, the subscriber can only receive the high-resolution stream.

Parameters

Returns 0 indicates the method call succeeded. A non-zero value indicates the method call failed.

Mutes or unmutes the local video stream.

MuteLocalCamera(mute bool) int

Parameters

Return value A return value of 0 indicates a successful method call; any other value indicates failure.

Mutes or unmutes the local audio.

MuteLocalMic(mute bool) int

Parameters

Returns 0 on success; any other value indicates failure.

Sets the user role.

SetClientRole(clientRole AliEngineClientRole) int

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

Parameters

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

Sets the default video stream type for subscriptions.

SetRemoteDefaultVideoStreamType(streamType AliEngineVideoStreamType) int

Parameters

Return valuesA return value of 0 indicates success. Any other value indicates failure.

After you join a room in audience mode, the SDK triggers the OnError callback with the ERR_NO_PEOPLE error code if all streamers stop publishing.

LeaveOnceNoStreamer(enable bool) int

This feature is designed for moderation scenarios.

Parameters

After a user joins a channel, the SDK triggers the OnError callback with the ERR_NO_PEOPLE error code if no other users join within the specified period.

SetPeriodForCheckPeople(seconds int) int

Consequently, the join fails, and the OnJoinChannelResult callback returns -1. This feature is designed for moderation scenarios. By default, the maximum duration for checking an empty room is 5 seconds.

Parameters

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

SetParameter(params string) int

Parameters

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

Generates the token required by JoinChannel. This method allows you to generate the token locally, bypassing the app server for authentication.

GenerateToken(authInfo AuthInfo, appkey string) string

Use this token to authenticate a user when they join a channel.

Parameters

Sends data through the data channel.

SendDataChannelMessage(ctrlMsg AliEngineDataChannelMsg) int

Limitations

• Users with the host role can send and receive messages. Users with the audience role can only receive messages.

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

• The following limits apply to data transmission:

  • The maximum bitrate is 30 KB/s.

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

Parameters

Returns 0 indicates success. Any other value indicates failure.

Notifies your application when the engine encounters an error.

OnError(errorCode ErrorCode)

Parameters

Notifies the business layer of warnings from the engine.

OnWarning(warningCode WarningCode)

Parameter description

Reports the result of joining a channel.

OnJoinChannelResult(result int, channel, userId string)

After the application calls the JoinChannel method, the SDK triggers this callback to report the result of joining the channel.

Parameters

Occurs when a message is received from a remote user through the data channel.

OnDataChannelMsg(uid string, msg AliEngineDataChannelMsg)

Parameters

Reports the result of leaving a channel.

OnLeaveChannelResult(result int)

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

Parameters

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

OnRemoteUserOnLineNotify(uid string)

The SDK triggers this callback in the following scenarios:

1. In communication mode: The SDK triggers this callback when a remote user joins the channel. If other users are already in the channel when the local user joins, the SDK also triggers this callback for each existing user.

2. In interactive mode:

   1. The SDK triggers this callback when a remote user with the broadcaster role joins the channel. If other broadcasters are already in the channel when the local user joins, the SDK also triggers this callback for each existing broadcaster.

   2. The SDK triggers this callback when a remote user with the audience role calls SetClientRole to switch their role to broadcaster (AliEngineClientRoleInteractive).

Callback behavior in interactive mode:

1. Broadcasters receive this callback when other broadcasters join the channel.

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

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

Parameters

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

OnRemoteUserOffLineNotify(uid string)

The SDK triggers this callback in the following scenarios:

1. In communication mode: When a remote user leaves the channel.

2. In interactive mode:

   1. When a remote user with the broadcaster role (AliEngineClientRoleInteractive) leaves the channel.

   2. When a remote broadcaster calls SetClientRole to switch their role to audience (AliEngineClientRoleLive).

For users in communication mode and for broadcasters in interactive mode, the SDK also triggers this callback when a remote user times out. A timeout occurs if the SDK does not receive data from the user for an extended period.

Parameters

Occurs when a remote user's audio or video track becomes available or unavailable.

OnRemoteTrackAvailableNotify(uid string, audioTrack AudioTrack, videoTrack VideoTrack)

This callback is triggered in the following scenarios:

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

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

3. In interactive mode, a user calls SetClientRole to switch to the broadcaster role (AliEngineClientRoleInteractive) and starts publishing a track.

This callback is triggered only for users in communication mode and for broadcasters in interactive mode.

Parameters

Fires when the audio subscription state changes.

OnAudioSubscribeStateChanged(uid string, oldState, newState AliEngineSubscribeState, elapseSinceLastState int, channel string)

Parameters

Occurs when the camera stream subscription state changes.

OnVideoSubscribeStateChanged(uid string, oldState, newState AliEngineSubscribeState, elapseSinceLastState int, channel string)

Parameters

Occurs when the subscribed stream type changes.

OnSubscribeStreamTypeChanged(uid string, oldStreamType, newStreamType AliEngineVideoStreamType, elapseSinceLastState int, channel string)

Parameters

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

OnScreenShareSubscribeStateChanged(uid string, oldState, newState AliEngineSubscribeState, elapseSinceLastState int, channel string)

Parameters

Triggered when the screen sharing publish state changes.

OnScreenSharePublishStateChanged(oldState, newState AliEnginePublishState, elapseSinceLastState int, channel string)

Parameters

Called when the publishing state of the secondary stream changes.

OnDualStreamPublishStateChanged(oldState, newState AliEnginePublishState, elapseSinceLastState int, channel string)

Parameters

Triggered when the video publish state changes.

OnVideoPublishStateChanged(oldState, newState AliEnginePublishState, elapseSinceLastState int, channel string)

Parameters

Indicates that the audio publish state has changed.

OnAudioPublishStateChanged(oldState, newState AliEnginePublishState, elapseSinceLastState int, channel string)

Parameters

Provides the raw audio data from each remote user before audio mixing.

OnSubscribeAudioFrame(uid string, frame AudioFrame)

The audio data in this callback is from a single remote user. For details, see AudioFormatPcmBeforMixing.

Parameters

This callback provides the mixed audio data that the local user has subscribed to.

OnSubscribeMixAudioFrame(frame AudioFrame)

This is the mixed audio from all remote users, ready for playback. For details, see AudioFormatMixedPcm.

Parameters

Provides the remote video data from a user you have subscribed to.

OnRemoteVideoSample(uid string, frame VideoFrame)

Parameters

Occurs when the SDK receives an encoded video sample from a subscribed remote user before decoding.

OnRemoteVideoEncodedSample(uid string, frame VideoFrame)

Parameters

Occurs when a media extension message is received.

OnMediaExtensionMsgReceived(userid string, message []byte, size int)

When a party calls SendMediaExtensionMsg, other parties receive the message through this callback.

Parameters

Occurs when the user role changes.

OnUpdateRoleNotify(oldRole, newRole AliEngineClientRole)

The SDK triggers this callback after you successfully call SetClientRole.

Parameters

A custom audio archiving callback that provides the AAC-transcoded audio data for each subscribed stream.

OnSubscribeAudioAac(uid string, frame AudioFrame)

Parameters

A callback for custom audio archiving that provides mixed audio data transcoded to the AAC format.

OnSubscribeMixedAudioAac(frame AudioFrame)

Parameters

The SDK triggers this callback when audio data is pushed too fast or unevenly, filling the audio buffer.

OnPushAudioFrameBufferFull(isFull bool)

Parameters

Triggered when the SDK's video buffer fills up because video data is pushed too fast or at a non-uniform rate.

OnPushVideoFrameBufferFull(isFull bool)

Parameters