Use the features of Push SDK for Windows - - Alibaba Cloud Documentation Center

This topic describes how to use Push SDK for Windows and the classes and methods in the SDK. This topic also provides examples on how to use the features provided by Push SDK for Windows. By reading this topic, you can better understand how to use the SDK for live streaming.

Features

Adopts H.264 for video encoding and Opus and Advanced Audio Coding (AAC) for audio encoding.
Adopts H.265 for video encoding and Opus and AAC for audio encoding.
Supports custom configurations for features such as bitrate control, resolution, and display mode.
Supports various camera operations.
Allows you to stream screen recordings.
Supports external audio and video inputs in different formats such as YUV and pulse-code modulation (PCM).
Supports mixing of multiple streams.
Supports ingest of audio-only and video-only streams and stream ingest in the background.
Supports background music and allows you to manage background music.
Supports automatic reconnection and error handling.
Supports the audio 3A algorithm.
Allows you to switch between the software and hardware encoding modes for video files. This improves the stability of the encoding module.

Procedure

Perform the following steps:

Configure stream ingest parameters
Ingest streams

Use the features

Configure stream ingest parameters

You can use the AlivcLivePushConfig class to configure stream ingest parameters. Each parameter has a default value. For basic stream ingest, we recommend that you use the default values of the parameters.

AlivcLivePushConfig config;

Ingest a stream (from the camera)

AlivcLivePusher is the core class of Push SDK for Windows. This class provides parameters for initialization, stream ingest callbacks, camera preview, and stream ingest management. You can also use this class to modify parameters during stream ingest.

Initialize the AlivcLivePusher class.
After you configure stream ingest parameters, call the init method to initialize the class. Sample code:
```
AlivcLivePushConfig config;
pusher->init(config);
```
Register stream ingest callbacks.
The following stream ingest callbacks are supported:
- Info: the callbacks that are used for notifications and status detection.
- Error: the callbacks that are returned when errors occur.
- Network: the callbacks that are related to network.
When an event occurs, the corresponding callback is triggered to notify you of the event. Sample code:
```
pusher->setLivePushErrorListener(errorListener);
pusher->setLivePushInfoListener(errorListener);
pusher->setLivePushNetworkListener(errorListener);
```
Start preview.
You can start preview after you initialize the livePusher object and configure callbacks. Sample code:
```
pusher->startPreview(view, width, height);
```
Start stream ingest.
```
pusher->startPush(url);
```

Common control operations for stream ingest

Push SDK for Windows allows you to control stream ingest. For example, you can start, stop, restart, pause, and resume stream ingest, stop preview, and destroy stream ingest instances. You can add buttons to perform these operations.

pusher->stopPush();

Ingest a stream (from a shared screen)

You can stream a screen recording, which is from a shared screen. To do so, you need to obtain the list of shared sources and then specify a shared source for stream ingest. Specific steps:

Obtain the list of shared sources.
```
pusher->getScreenShareSourceInfo();
```
Start ingest of a shared source.
```
pusher->startScreenShareByDesktopId(desktopId);
```
Note
- desktopId indicates the ID of the desktop. You can query the ID by calling the GetScreenShareSourceInfo method.

Configure bitrate control

You can use the following method to configure bitrate control:

Configure the initialization parameter enableBitrateControl to enable bitrate control.
```
config.enableBitrateControl = true;
```
Note
If you enable this feature, the bitrate is automatically adjusted between the specified target bitrate and minimum bitrate. If you disable this feature, the bitrate is fixed at the initial value. In this case, stuttering may occur when the network is unstable. Proceed with caution before you disable this feature. (We recommend that you enable this feature.)
Specify custom bitrate parameters.
The parameters include mInitialVideoBitrate, mMinVideoBitrate, and mTargetVideoBitrate, which indicate the initial bitrate, minimum bitrate, and target bitrate, respectively.
```
config.mTargetVideoBitrate = 1400; // Set the target bitrate to 1,400 Kbit/s.
config.mMinVideoBitrate = 600; // Set the minimum bitrate to 600 Kbit/s.
config.mInitialVideoBitrate = 1000; // Set the initial bitrate to 1,000 Kbit/s.
```
The following table describes the recommended values of these parameters:
Resolution
mInitialVideoBitrate
mMinVideoBitrate
mTargetVideoBitrate
360p
600
300
1000
480p
800
300
1200
540p
1000
600
1400
720p
1500
600
2000
1080p
1800
1200
2500
Resolution
mInitialVideoBitrate
mMinVideoBitrate
mTargetVideoBitrate
360p
400
200
600
480p
600
300
800
540p
800
300
1000
720p
1000
300
1200
1080p
1500
1200
2200
Note
If you do not configure the mInitialVideoBitrate, mMinVideoBitrate, and mTargetVideoBitrate parameters, Push SDK automatically specifies an appropriate camera bitrate based on the resolution.

Ingest an image

Push SDK for Windows allows you to ingest images when your app is switched to the background or the bitrate is low. This improves user experience.

When your app is switched to the background, video stream ingest is paused. In this case, only audio streams are ingested. You can also specify an image that you want to ingest. For example, you can ingest an image in which a message such as The streamer will be back soon. is displayed to notify the viewers.

config.mPausePushImagePath = "The path of the specified image in the PNG format for stream ingest";// Specify the image for stream ingest when your app is switched to the background.

Listen to callbacks

Push SDK allows you to receive callbacks for stream ingest exceptions and errors. This way, you can handle the exceptions and errors accordingly. Push SDK for Windows provides the following types of callbacks.

Callback type	Class
Stream ingest callbacks	AlivcLivePushInfoListener
Network callbacks	AlivcLivePushNetworkListener
Error callbacks	AlivcLivePushErrorListener

Stream ingest callbacks

Stream ingest callbacks are used to notify the app of the SDK status, including the callback for preview start, the callback for rendering the first frame, the callback for sending the first frame of an audio or video stream, the callback for stream ingest start, and the callback for stream ingest stop.

onPushStarted and onFirstFramePushed: indicates that stream ingest is successful.
onPushStarted: indicates that the server is connected.
onFirstFramePushed: indicates that the first frame of the audio or video stream is sent.

Network callbacks

Network callbacks are used to notify the app of the network status and link status regarding the SDK.

onConnectFail: indicates that stream ingest fails. We recommend that you check whether the ingest URL is valid (for example, whether the URL contains invalid characters), whether there is an authentication issue, whether the upper limit on the number of concurrently ingested streams is exceeded, and whether the stream is in the blacklist. Make sure that the ingest URL is valid and available before you try to ingest the stream. The relevant error codes include 0x30020901 to 0x30020905 and 0x30010900 to 0x30010901.
onConnectionLost: indicates that the network is disconnected. After the network is disconnected, the SDK automatically attempts to reconnect to the network and fires the onReconnectStart callback. If the maximum allowed number of reconnection attempts (config.connectRetryCount) is reached but the network is still not recovered, the SDK fires the onReconnectError callback.
onNetworkPoor: indicates that the network speed is slow. If you receive this callback, the current network may not be able to fully support your ingested stream, even though the stream is not interrupted and can keep running. In this case, you can handle your own business logic, for example, notify the user on the user interface (UI) of the app.
onNetworkRecovery: indicates that the network is recovered.
onReconnectError: indicates that the network reconnection fails. We recommend that you check the current network and re-ingest the stream when the network recovers. In general, the SDK attempts to reconnect to the network when a network disconnection or a network switchover occurs. You can use the AlivcLivePushConfig class to set the reconnection timeout period and the maximum number of reconnection attempts allowed. After the SDK reconnects to the network, stream ingest is resumed. If a reconnection request times out or the number of reconnection attempts exceeds the upper limit, the SDK fails to reconnect to the network. In this case, the onReconnectError callback is fired. After the network connection is recovered, call reconnectAsyn to reconnect to the network. You must also reconnect the SDK to the player. If you use ApsaraVideo Player, we recommend that you perform a reconnection operation 5 seconds after you receive a timeout notification.
Note
- We recommend that you externally monitor the network connection.
- Use the server to handle communication failures between the streamer side and player. For example, when the streamer is disconnected, the server receives a callback of stream ingest interruption. The server pushes the callback message to the player. Then, the player handles the stream ingest interruption. The callback procedure for resuming stream ingest is the same.
- Stop the playback and then restart ApsaraVideo Player to reconnect the player to the server. To achieve this, call stop, then prepareToPlay. For more information about ApsaraVideo Player, see SDK overview and download.
onSendDataTimeout: indicates that a timeout occurs when the data is sent. We recommend that you check the current network and re-ingest the stream when the network recovers.
onPushURLAuthenticationOverdue: indicates that the signed ingest URL is about to expire. If URL signing is enabled, the ingest URL contains the auth_key field, which Alibaba Cloud regularly verifies. This callback is fired 1 minute before the ingest URL expires. After the callback is returned, you must specify a new ingest URL to ensure that stream ingest is not interrupted when the original URL expires.

Error callbacks

onSystemError: indicates a system device exception. You must destroy the engine and try again.
onSDKError: indicates an SDK error. You need to perform operations based on the error code:
- If the error code is 805438211, the device performance is poor and the frame rate for encoding and rendering is low. You need to prompt the streamer and stop time-consuming business logic, such as advanced retouching and animation, at the app layer.
- You need to pay special attention to the callbacks that are related to microphone and camera permissions. The 268455940 error code indicates that the app requires the permissions on the microphone. The 268455939 error code indicates that the app requires the permissions on the camera.
- For other error codes, no additional operations are required. All error codes are recorded in logs.

List of common classes

Class	Description
AlivcLivePushConfig	The class for stream ingest settings.
AlivcLivePusher	The class for stream ingest features.
AlivcLivePusherErrorListener	The class for error callbacks.
AlivcLivePusherNetworkListener	The class for network callbacks.
AlivcLivePusherInfoListener	The class for stream ingest callbacks.

API reference

API reference for Push SDK for Windows

Resolution	mInitialVideoBitrate	mMinVideoBitrate	mTargetVideoBitrate
360p	600	300	1000
480p	800	300	1200
540p	1000	600	1400
720p	1500	600	2000
1080p	1800	1200	2500