This document describes how to integrate the Alibaba Real-Time Communication (ARTC) software development kit (SDK) into your Windows and Linux projects. You can use it to quickly build a simple, real-time audio and video application for scenarios such as interactive streaming and video calls.
Feature overview
Before you start, it helps to understand these key concepts:
ARTC SDK: The ARTC SDK helps you quickly add real-time audio and video features to your applications.
GRTN (Global Real-time Transport Network): An Alibaba Cloud network that provides ultra-low latency, high-quality, secure, and reliable audio and video communication services.
Channel: A virtual room where all users who join the same channel can interact in real time with audio and video.
Streamer: A user who can publish audio and video streams in a channel and subscribe to streams published by other streamers.
Viewer: A user who can subscribe to audio and video streams in a channel but cannot publish them.
The basic flow for real-time audio and video interaction is as follows:
Set the channel scenario and join the channel:
Video call scenario: All users are streamers. They can publish and subscribe to streams.
Interactive streaming scenario: Assign the streamer role to users who need to publish streams in the channel. Assign the viewer role to users who only need to subscribe to streams.
After joining the channel, users have different publishing and subscribing behaviors based on their roles:
All users in the channel can receive audio and video streams.
Streamers can publish audio and video streams in the channel.
If viewers need to publish a stream, they must switch their role to streamer.
Create application
Obtain the AppID and AppKey for your real-time communication application. For more information, see Create an application.
Server integration
Integrate the authentication code provided by Alibaba Cloud into your server environment. For more information, see Token-based authentication.
Provide an API on your server for your client application to call.
Feature implementation
Windows
Prerequisites
Visual Studio 2015 or later.
Windows 7 or later.
Integrate SDK
Download the SDK and obtain the latest ARTC SDK package.
Decompress the package and copy the files in the directory to your project.
Configure project properties:
In the Solution Explorer window, right-click the project and select Properties in the menu.
Add include directories: Select Configuration Properties > C/C++ > General, and add the header file path to Additional Include Directories.
Add library directories: In the Properties window, select Configuration Properties > Linker > General, and add the path of the library files (.lib) to Additional Library Directories, such as
.../x64/Release.Specify link library files: In the Properties window, select Configuration Properties > Linker > Input, and add the name of the library file to be linked "AliRTCSdk.lib" to Additional Dependencies.
Implementation steps
1. Initialize the RTC engine and register callbacks
When the SDK encounters an exception, it first tries to recover using its internal retry mechanism. For errors that the SDK cannot resolve automatically, it notifies your application through callback APIs.
Cause of exception |
Callback and parameters |
Solution |
Description |
Authentication failed |
The `result` in the `onJoinChannelResult` callback returns `AliRtcErrJoinBadToken`. |
When this error occurs, the app must check if the token is correct. |
If authentication fails when a user actively calls an API, the system returns an authentication failure error message in the API's callback. |
Authentication is about to expire |
onWillAuthInfoExpire |
When this exception occurs, the app must get the latest authentication information and then call `refreshAuthInfo` to refresh it. |
Authentication expiration errors occur in two situations: when a user calls an API or during program execution. Therefore, the error feedback is sent through an API callback or a separate error callback. |
Authentication expired |
onAuthInfoExpired |
When this exception occurs, the app must rejoin the channel. |
Authentication expiration errors occur in two situations: when a user calls an API or during program execution. Therefore, the error feedback is sent through an API callback or a separate error callback. |
Network connectivity exception |
The `onConnectionStatusChange` callback returns `AliRtcConnectionStatusFailed`. |
When this exception occurs, the app must rejoin the channel. |
The SDK can automatically recover from network disconnections for a certain period. However, if the disconnection time exceeds the preset threshold, a timeout is triggered and the connection is lost. The app should then check the network status and guide the user to rejoin the channel. |
Kicked offline |
onBye |
|
The RTC service lets an administrator actively remove participants. |
Local device exception |
onLocalDeviceException |
When this exception occurs, the app must check for permissions and if the device hardware is working correctly. |
The RTC service supports device detection and exception diagnosis. When a local device exception occurs, the RTC service notifies the client through a callback. If the SDK cannot resolve the issue, the app must intervene to check if the device is working correctly. |
class AliEngineEventListenerImpl : public AliEngineEventListener {
public:
AliEngineEventListenerImpl(AliEngine* engine, HWND hWnd) {
mAliRtcEngine = engine;
mHWnd = hWnd;
};
virtual AliEngineEventListenerImpl() {};
virtual void OnConnectionStatusChange(int status, int reason) override {
if (status == AliEngineConnectionFailed) {
/* TODO: Handle this. We recommend that you notify the customer. This is reported only after the SDK has tried all internal recovery policies and failed. */
} else {
/* TODO: Optional. Add business logic, usually for data statistics or UI changes. */
}
};
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg) override {
/* TODO: Handle this. We recommend that you notify the customer. This is reported only after the SDK has tried all internal recovery policies and failed. */
};
virtual void OnJoinChannelResult(int result, const char *channel, const char *userId, int elapsed) override {
/* TODO: Optional. Add business logic, usually for data statistics or UI changes. */
};
virtual void OnLeaveChannelResult(int result, AliEngineStats stats) override {
};
virtual void OnAuthInfoWillExpire() override {
/* TODO: Handle this. The business logic should trigger re-acquisition of the authentication information for the current channel and user, then call refreshAuthInfo. */
};
virtual void OnBye(int code) override {
/* TODO: We recommend that you handle this according to your business scenario. */
};
virtual void OnRemoteUserOnLineNotify(const char *uid, int elapsed) override {
};
virtual void OnRemoteUserOffLineNotify(const char *uid, AliEngineUserOfflineReason reason) override {
};
virtual void OnRemoteTrackAvailableNotify(const char *uid,
AliEngineAudioTrack audioTrack,
AliEngineVideoTrack videoTrack) {
AliEngineVideoCanvas remote_canvas;
if (videoTrack == AliEngineVideoTrackCamera
|| videoTrack == AliEngineVideoTrackBoth) {
RECT rect;
::GetWindowRect(mHWnd, &rect);
remote_canvas.displayView = remoteView;
remote_canvas.renderMode = AliEngineRenderModeAuto;
mAliRtcEngine->SetRemoteViewConfig(remote_canvas,uid,AliEngineVideoTrackCamera);
} else {
mAliRtcEngine->SetRemoteViewConfig(remote_canvas, uid, AliEngineVideoTrackCamera);
}
}
private:
AliEngine* mAliRtcEngine = nullptr;
/* Windows window handle */
HWND mHWnd;
};
private:
void createEngine() {
mAliRtcEngine = AliRtcEngine.Create("");
mLisenter = new AliEngineEventListenerImpl(mAliRtcEngine, mHWnd);
mAliRtcEngine->SetEngineEventListener(mLisenter);
}2. Set parameters before joining a channel
In interactive mode, a user with the streamer role automatically publishes the local audio and video stream and subscribes to streams from other streamers by default.
In interactive mode, a user with the viewer role does not publish the local audio and video stream but subscribes to streams from other streamers by default.
The SDK uses automatic publishing and subscribing by default. You can also disable this mode.
private:
void initEngineBeforeJoin() {
/* Optional: Set parameters before joining the channel. */
mAliRtcEngine->SetChannelProfile(AliEngineInteractiveLive);
mAliRtcEngine->SetClientRole(AliEngineClientRoleInteractive);
/* Set audio properties. */
mAliRtcEngine->SetAudioProfile(AliEngineBasicQualityMode, AliEngineSceneMusicMode);
/* Optional: Camera preview. The stream will be published even if this is not set. */
AliEngineVideoCanvas canvas;
/* Windows window handle */
canvas.view = mHWnd;
mAliRtcEngine.setLocalViewConfig(canvas, AliEngineVideoTrackCamera);
}3. Join a channel
After a user joins the channel, streams are published and subscribed based on the parameters that were set before joining.
The SDK automatically publishes and subscribes to streams by default to reduce the number of API calls from the client.
initEngineBeforeJoin();
mAliRtcEngine->joinChannel("Your authentication information", null, null, "testUserName");4. Switch roles
When a user switches from the streamer role to the viewer role (often called "going off-mic"), the SDK stops publishing the local audio and video stream. Subscribed streams are not affected.
When a user switches from the viewer role to the streamer role (often called "going on-mic"), the SDK starts publishing the local audio and video stream. Subscribed streams are not affected.
/* TODO: Set the role based on your business logic. */
/* Set the role to interactive (streamer role). */
mAliRtcEngine->SetClientRole(AliEngineClientRoleInteractive);
/* Set the role to live (viewer role). */
mAliRtcEngine->SetClientRole(AliEngineClientRoleLive);5. Leave the channel
mAliRtcEngine->LeaveChannel();6. Destroy the engine
mAliRtcEngine->Destroy();
mAliRtcEngine = nullptr;Demonstration
References
Linux
Prerequisites
Implementation steps
1. Initialize the RTC engine and register callbacks
2. Set parameters before joining a channel
In interactive mode, a user with the streamer role automatically publishes the local audio and video stream and subscribes to streams from other streamers by default.
In interactive mode, a user with the viewer role does not publish the local audio and video stream but subscribes to streams from other streamers by default.
The SDK uses automatic publishing and subscribing by default. You can also disable this mode.
Set parameters before joining for Java
Set parameters before joining for Python
3. Joining a meeting
After a user joins the channel, streams are published and subscribed based on the parameters that were set before joining.
The SDK automatically publishes and subscribes to streams by default to reduce the number of API calls from the client.
4. Switch roles
When a user switches from the streamer role to the viewer role (often called "going off-mic"), the SDK stops publishing the local audio and video stream. Subscribed streams are not affected.
When a user switches from the viewer role to the streamer role (often called "going on-mic"), the SDK starts publishing the local audio and video stream. Subscribed streams are not affected.