:Advanced features

To enable audio-only playback, you can disable video playback. You must configure PlayerConfig before you call the prepare method.

AVPConfig *config = mPlayerPtr->getConfig();
config->mDisableVideo = true;
mPlayerPtr->setConfig(config);

ApsaraVideo Player SDK for Windows supports adaptive bitrate streaming for HTTP Live Streaming (HLS) and Dynamic Adaptive Streaming over HTTP (DASH) video streams. After the prepare method is successfully called, you can call getMediaInfo to obtain information about each stream, which is returned as TrackInfo. Sample code:

AVPMediaInfo info = mPlayerPtr->getMediaInfo();
for (int i = 0; i < info.trackCount; i++) {
     AVPTrackInfo *track = info.tracks[i];
}

During playback, you can call the selectTrack method of the player to switch the stream bitrate. If you set the value to SELECT_AVPTRACK_TYPE_VIDEO_AUTO, adaptive bitrate streaming is enabled. Sample code:

// Switch the bitrate.
mPlayerPtr->selectTrack(trackIndex);
// Switch to the adaptive bitrate.
mPlayerPtr->selectTrack(SELECT_AVPTRACK_TYPE_VIDEO_AUTO);

The result of the switch is returned in the onTrackChanged listener callback. Sample code:

void AlivcLivePlayerMainDlg::onTrackChanged(AliPlayer *player, AVPTrackInfo *info)
{
    if (info->trackType == AVPTRACK_TYPE_VIDEO) {
        // video changed
    }
    // etc
}

You can call the snapShot method of the ApsaraVideo Player SDK for Windows to capture a snapshot of the current video. The snapshot is returned in ARGB32 format through the onSnapshotImageBuffer callback. Sample code:

// Capture a snapshot of the current video frame.
mPlayerPtr->snapshot();
// Callback for snapshot capture.
void AlivcLivePlayerMainDlg::onSnapshotImageBuffer(AliPlayer *player, int width, int height, unsigned char *pARGBBuffer)
{
    QString savePath = "save path";
    QImage snapshot(pARGBBuffer, width, height, QImage::Format_ARGB32);
    snapshot.save(savePath);
}

After you configure the preview feature, call the setPreviewTime method of the VidPlayerConfigGenerator interface to set the preview duration for the player. When you set a preview duration and play a video using the SDK, the server returns only the content for the preview period instead of the full video content. The following sample code shows an example of playback using VidSts:

VidPlayerConfigGenerator playConfigGen;
playConfigGen.setPreviewTime(10);
AVPVidStsSource vidSource;
vidSource.initWithVid("Video ID",
                        "accessKeyId",
                        "accessKeySecret",
                        "Security token",
                        "Region",
                        playConfigGen.generatePlayerConfig());
mPlayerPtr->setSource(vidSource);

ApsaraVideo Player SDK for Windows supports setting a Referer. You can use the Referer with blacklists and whitelists in the console to control access privileges. Use the AVPConfig interface to set the request Referer. Sample code:

// Obtain the configurations.
AVPConfig *pConfig = mPlayerPtr->getConfig();
// Set the Referer.
pConfig->referer = referer;
....// Other settings.
// Set the configurations for the player.
mPlayerPtr->setConfig(pConfig);

ApsaraVideo Player SDK for Windows provides AVPConfig to set the request User-Agent (UA). After you set the UA, the player includes the UA information in its requests. Sample code:

// Obtain the configurations.
AVPConfig *pConfig = mPlayerPtr->getConfig();
// Set the User-Agent.
pConfig->userAgent = userAgent;
....// Other settings.
// Set the configurations for the player.
mPlayerPtr->setConfig(pConfig);

ApsaraVideo Player SDK for Windows supports setting the network timeout period and the number of retries. You can use the AVPConfig interface to configure these settings. Sample code:

// Obtain the configurations.
AVPConfig *pConfig = mPlayerPtr->getConfig();
// Set the network timeout period in milliseconds.
pConfig->networkTimeout = 5000;
// Set the number of retries upon a timeout. The retry interval is the value of networkTimeout. If you set networkRetryCount to 0, no retry is performed. The retry policy is determined by the app. Default value: 2.
pConfig->networkRetryCount = 2;
....// Other settings.
// Set the configurations for the player.
mPlayerPtr->setConfig(pConfig);

Cache control is critical for a player. Proper configuration can speed up startup and reduce stuttering. ApsaraVideo Player SDK for Windows provides interfaces in AVPConfig to control the cache and latency. Sample code:

// Obtain the configurations.
AVPConfig *pConfig = mPlayerPtr->getConfig();
// The maximum latency. Note: This parameter is valid only for live streaming. If the latency is high, the SDK performs operations such as frame synchronization to keep the latency within this range.
pConfig->maxDelayTime = 5000;
// The maximum buffer duration in milliseconds. The player loads a maximum of the specified duration of data into the buffer at a time.
pConfig->maxBufferDuration = 50000;
// The high buffer watermark in milliseconds. When the player loads data due to poor network conditions, the loading state ends if the buffered data reaches this duration.
pConfig->highBufferDuration = 3000;
// The startup buffer duration in milliseconds. A smaller value indicates a faster startup. However, the player may enter the loading state soon after playback starts.
pConfig->startBufferDuration = 500;
// Other settings.
// Set the configurations for the player.
mPlayerPtr->setConfig(pConfig);

Using the AVPConfig parameter, you can add HTTP header parameters to requests from the player. Sample code:

// Obtain the configurations.
AVPConfig *pConfig = mPlayerPtr->getConfig();
// Set the header.
pConfig->headerCount = 1;
pConfig->httpHeaders = new char *[pConfig->headerCount];
// For example, if you use HTTPDNS, you must set the Host.
pConfig->httpHeaders[0] = strdup("Host:example.com");
....// Other settings.
// Set the configurations for the player.
mPlayerPtr->setConfig(pConfig);

ApsaraVideo Player SDK for Windows provides a local caching feature that lets you cache content during playback. This feature saves data traffic when users play a video repeatedly. To implement this feature, configure AVPCacheConfig for the player before you call the prepare method. Sample code:

AVPCacheConfig mCacheConfig;
// Enable the caching feature.
mCacheConfig.enable = true;
// The maximum duration of a single file that can be cached. Files that exceed this duration are not cached.
mCacheConfig.maxDuration = 100;
// The maximum size of the cache directory. If the size limit is exceeded, the oldest cached files are deleted.
mCacheConfig.maxSizeMB = 200;
// The path of the cache directory. Replace this with the desired path for your app.
mCacheConfig.path = strdup("please use your cache path here");
// Set the cache configurations for the player.
mPlayerPtr->setCacheConfig(&mCacheConfig);

If you have configured setCacheConfig, the cached file is used in the following situations after a video is successfully cached.

• If loop playback is enabled, the cached file is automatically used for playback starting from the second loop.

• If you create a new player to play the same resource after the video is successfully cached, the cached file is also automatically used.

  Important

  For VID-based playback, the player uses information such as the video ID (VID) from online requests to locate cached files. Therefore, the player can determine which cached file to use only after it receives information from network requests.

The cache-while-playing feature is subject to the following conditions:

• For playback using UrlSource, HLS (M3U8) streams are not cached. Other supported formats are cached according to the cache configuration.

• For playback using VidAuth or VidSts, videos are cached according to the cache configuration.

• Caching is considered successful only after the player reads all the data. If you call the stop method or an onError event occurs before the download is complete, the caching process fails.

• Seeking within the cached content does not affect the caching result. Seeking outside the cached content causes the caching process to fail.

• If the security file is inconsistent with the app information, the caching process fails.

• The caching result is returned in the onPlayerEvent callback. The callback includes EVENT_PLAYER_CACHE_SUCCESS and EVENT_PLAYER_CACHE_ERROR.

ApsaraVideo Player SDK for Windows provides a download feature for ApsaraVideo VOD videos. This feature allows users to cache videos locally for offline viewing with ApsaraVideo Player. Two download modes are available: normal download and secure download.

• Normal download

  Videos that are downloaded in normal download mode are not encrypted by Alibaba Cloud and can be played by third-party players.

• Secure download

  Videos that are downloaded in secure download mode are encrypted by Alibaba Cloud. You can only use ApsaraVideo Player to play these videos.