All Products
Search
Document Center

Features and usage

Last Updated: Aug 05, 2020

ApsaraVideo Player SDK for Windows provides the following features:

  • Play a single video
  • Download
  • Caching

This topic describes these features.

I. Playback

To use ApsaraVideo Player SDK for Windows to play a video, perform the following steps:

  1. Create a player. 2. Set listeners. 3. Set the playback source. 4. Prepare the player. 5. Start playback. 6. Set operations for playback control. 7. Release the player.

1. Create a player

  1. using namespace alivc_player;
  2. AliPlayer* mPlayerPtr = AliPlayer::CreatePlayer();

If a video is downloaded in the secure download mode, namely, it is encrypted and transcoded by Alibaba Cloud, you must configure a security file encryptedApp.dat for encryption verification to play the video. For information about how to configure this file, see Obtain the security file.

  1. InitPrivateService(fileContentBuffer, fileLength);

2. Set a player listener

ApsaraVideo Player SDK for Windows provides multiple callbacks, such as onPlayerEvent and onError. To use these callbacks, create a class to inherit IAVPListener and implement the pure virtual functions of the class.

  1. mPlayerPtr->setListener(new AVPListenerImpl);

3. Set the playback source and prepare the player

Four playback sources are supported: AVPVidStsSource, AVPVidAuthSource, AVPVidMpsSource, and AVPUrlSource. You can use AVPUrlSource for URL-based playback, and use AVPVidStsSource, AVPVidAuthSource, and AVPVidMpsSource for video ID (VID)-based playback. We recommend that you use AVPVidAuthSource for ApsaraVideo VOD. AVPVidMpsSource is available for ApsaraVideo Media Processing only.The following code uses AVPVidStsSource as an example:

  1. AVPVidStsSource vidSource;
  2. vidSource.initWithVid(VID,
  3. "accessKeyId",
  4. "accessKeySecret",
  5. "Security token",
  6. "Access region",
  7. nullptr);
  8. mPlayerPtr->setSource(vidSource);
  9. mPlayerPtr->prepare();

4. Set the UI view

  1. mPlayerPtr->setView((void *)The HWND handle of the UI view);

5. Set playback control

When the player is prepared, a notification of the AVPEventPrepareDone event is returned to the callback URL. Then, you can start the playback and set playback control.You can create playback control buttons and associate the click events with the corresponding playback control methods to implement playback interaction. The basic control features include play, stop, pause, and seek. The seek feature is valid only for video-on-demand (VOD) playback. If you pause a live stream, the current position of the live stream is saved. You can use the resume feature to go back to where you left off. You can use the following sample code to set playback control:

  1. // Start the playback.
  2. mPlayerPtr->start();
  3. // Pause the playback.
  4. mPlayerPtr->pause();
  5. // Stop the playback.
  6. mPlayerPtr->stop();
  7. // Seek to the video image at the specified time point. The seek feature supports both precise and imprecise modes. Imprecise seek directs the video to the nearest next keyframe. Precise seek directs the video to the specified time point, but is slower than imprecise seek.
  8. mPlayerPtr->seekToTime(int64_t time_in_ms, mode);
  9. // Reset the player.
  10. mPlayerPtr->reset();
  11. // Destroy the player.
  12. mPlayerPtr->destroy();

6. Set multi-bitrate switching

ApsaraVideo Player SDK for Windows supports playing an HTTP Live Streaming (HLS) Encryption-based video in different bitrates. After the player is prepared by using the prepare method, you can call the getMediaInfo method to obtain the value of the TrackInfo parameter, which indicates the bitrate information.

  1. AVPMediaInfo mediaInfo = mPlayerPtr->getMediaInfo();
  2. for (int i = 0; i < mediaInfo.trackCount; i++) {
  3. AVPTrackInfo *trackInfo = mediaInfo.tracks[i];
  4. }

During playback, you can call the selectTrack method to switch the bitrate.

  1. int trackIndex = trackInfo->trackIndex;
  2. mPlayerPtr->selectTrack(trackIndex);

You can call the onTrackChanged callback of the IAVPListener operation to view the bitrate switching result.

7. Set autoplay

ApsaraVideo Player SDK for Windows supports autoplay. Set autoplay before you call the prepare method.

  1. mPlayerPtr->setAutoPlay(true);

After you set autoplay, the player automatically starts playback once it is prepared. In this case, the AVPEventAutoPlayStart callback instead of the AVPEventPrepareDone callback is fired when the player is prepared.

  1. void onPlayerEvent(AliPlayer *player, AVPEventType eventType)
  2. {
  3. if (eventType == AVPEventPrepareDone) {
  4. // The player is prepared.
  5. }
  6. else if (eventType == AVPEventAutoPlayStart) {
  7. // The player automatically starts playback.
  8. }
  9. }

8. Set loop playback

ApsaraVideo Player SDK for Windows supports loop playback. Call the setLoop method to enable the loop playback feature. The player plays a video all over again after it plays the video completely. The callback for the start of loop playback is fired by the AVPEventLoopingStart callback.

  1. mPlayerPtr->setLoop(true);

9. Set video image rotation, scaling, and mirroring

ApsaraVideo Player SDK for Windows provides multiple operations for you to precisely control the video image, such as rotation, scaling, and mirroring.

  1. // Set the mirroring mode: horizontal mirroring, vertical mirroring, and no mirroring.
  2. mPlayerPtr->setMirrorMode(AVP_MIRRORMODE_HORIZONTAL);
  3. // Set the rotation angel: 0°, 90°, 180°, and 270°.
  4. mPlayerPtr->setRotateMode(AVP_ROTATE_0);
  5. // Set the scaling mode: aspect ratio-based padding, aspect ratio-based fitting, and stretching.
  6. mPlayerPtr->setScalingMode(AVP_SCALINGMODE_SCALEASPECTFILL);

The following table describes values of the rotateMode parameter.

Value Description
AVP_ROTATE_0 Indicates that the rotation angle is 0°, in the clockwise direction.
AVP_ROTATE_90 Indicates that the rotation angle is 90°, in the clockwise direction.
AVP_ROTATE_180 Indicates that the rotation angle is 180°, in the clockwise direction.
AVP_ROTATE_270 Indicates that the rotation angle is 270°, in the clockwise direction.

The following table describes values of the scalingMode parameter.

Value Description
AVP_SCALINGMODE_SCALEASPECTFIT Indicates that the video image is scaled down into the UI view without changing the aspect ratio. This prevents image distortion.
AVP_SCALINGMODE_SCALEASPECTFILL Indicates that the video image is scaled out to fill the UI view without changing the aspect ratio. This prevents image distortion.
AVP_SCALINGMODE_SCALETOFILL Indicates that the video image is stretched to fill the UI view. This may cause image distortion if the video image and the UI view do not match in the aspect ratio.

The following table describes values of the mirrorMode parameter.

Value Description
AVP_MIRRORMODE_NONE Indicates that mirroring is disabled.
AVP_MIRRORMODE_HORIZONTAL Indicates horizontal mirroring.
AVP_MIRRORMODE_VERTICAL Indicates vertical mirroring.

10. Set the mute mode and volume control

ApsaraVideo Player SDK for Windows provides the feature of volume control. You can call the setMute method to set the mute mode for the player, and call the setVolume method to set the player volume. The volume range is 0 to 200%.

  1. mPlayerPtr->setMute(true);
  2. mPlayerPtr->setVolume(1.0f);

11. Set the playback speed

ApsaraVideo Player SDK for Windows allows you to set the playback speed. You can call the setRate method to change the playback speed from 0.5x to 2x. The audio pitch remains unchanged at different speeds.

  1. mPlayerPtr->setRate(1.5);

12. Enable or disable hard decoding

ApsaraVideo Player SDK for Windows supports H.264 and H.265 hard decoding. You can call the enableHardwareDecoder method to enable or disable hard decoding. By default, the hard decoding feature is enabled. If the hard decoding failed to be initialized, it is switched to soft decoding to ensure normal playback.

  1. mPlayerPtr->enableHardwareDecoder(true);

13. Set the referer

ApsaraVideo Player SDK for Windows provides the AVPConfig class for you to set the request referer. You can set referers in the blacklist or whitelist in the ApsaraVideo VOD console to implement access control. You can use the following sample code to set a referer:

  1. // Obtain player parameters.
  2. AVPConfig *pConfig = mPlayerPtr->getConfig();
  3. // Set the referer.
  4. pConfig->referer = referer;
  5. .... // Set other parameters.
  6. // Specify the settings for the player.
  7. mPlayerPtr->setConfig(pConfig);

14. Specify UserAgent

ApsaraVideo Player SDK for Windows provides the AVPConfig class for you to specify the request UserAgent. After you specify UserAgent, the player contains the UserAgent information in its requests. You can use the following sample code to specify UserAgent:

  1. // Obtain player parameters.
  2. AVPConfig *pConfig = mPlayerPtr->getConfig();
  3. // Set UserAgent.
  4. pConfig->userAgent = userAgent;
  5. .... // Set other parameters.
  6. // Specify the settings for the player.
  7. mPlayerPtr->setConfig(pConfig);

15. Specify the network timeout period and retry times

You can use the AVPConfig class to set the network timeout period and retry times, as shown in the following sample code:

  1. // Obtain player parameters.
  2. AVPConfig *pConfig = mPlayerPtr->getConfig();
  3. // Specify the network timeout period, in milliseconds.
  4. pConfig->networkTimeout = 5000;
  5. // Specify retry times upon a network timeout. The networkTimeout parameter indicates the retry interval. The networkRetryCount parameter indicates the retry times. A value of 0 indicates that the player does not retry playback upon a network timeout. The application determines the retry times. The default value is 2.
  6. pConfig->networkRetryCount = 2;
  7. .... // Set other parameters.
  8. // Specify the settings for the player.
  9. mPlayerPtr->setConfig(pConfig);
  • If you set the networkRetryCount parameter to a value other than 0, the player retries playback when the player starts loading data due to a network error. The number of retry times equals the value of the networkRetryCount parameter. The retry interval equals the value of the networkTimeout parameter.
  • If the player is still loading data when the retry times exceed the maximum limit, the onError callback is fired. You can call the AVPErrorModel.code method to obtain the error code: ERROR_LOADING_TIMEOUT.
  • If you set the networkRetryCount parameter to 0, the onPlayerEvent callback is fired when the network connection times out. You can call the eventWithString method to obtain the information code: EVENT_PLAYER_NETWORK_RETRY. To resolve the issue, call the reload method to reload data or take other operations as required.

16. Control the buffer and delay

Buffer control is important for a player. You can significantly shorten the startup loading time and improve playback smoothness with proper configuration. ApsaraVideo Player SDK for Windows provides the AVPConfig class for you to control the buffer and delay.

  1. // Obtain player parameters.
  2. AVPConfig *pConfig = mPlayerPtr->getConfig();
  3. // Set the maximum delay. This parameter is valid only for live streaming. If the delay time exceeds the maximum limit, the player synchronizes frames to reduce the delay under the set limit.
  4. pConfig->maxDelayTime = 5000;
  5. // Set the maximum buffer duration, in milliseconds. This parameter indicates the maximum video length that can be loaded by the player.
  6. pConfig->maxBufferDuration = 50000;
  7. // Set the peak buffer duration, in milliseconds. The player starts loading data when the network connection is poor. This parameter indicates the buffer duration beyond which the player stops loading in this case.
  8. pConfig->highBufferDuration = 3000;
  9. // Set the startup loading duration, in milliseconds. The smaller this value, the shorter the startup loading time is, and the sooner the player starts loading after the start of playback.
  10. pConfig->startBufferDuration = 500;
  11. // Set other parameters.
  12. // Specify the settings for the player.
  13. mPlayerPtr->setConfig(pConfig);

Note: Ensure that the value of startBufferDuration is not greater than the value of highBufferDuration, and the value of highBufferDuration is not greater than the value of maxBufferDuration.

17. Set HTTP headers

ApsaraVideo Player SDK for Windows provides the AVPConfig class to set HTTP headers for the player, as shown in the following sample code:

  1. // Obtain player parameters.
  2. AVPConfig *pConfig = mPlayerPtr->getConfig();
  3. // Define a header.
  4. pConfig->headerCount = 1;
  5. pConfig->httpHeaders = new char *[pConfig->headerCount];
  6. // Set a host when you use Alibaba Cloud HTTPDNS.
  7. pConfig->httpHeaders[0] = strdup("Host:xxx.com");
  8. .... // Set other parameters.
  9. // Specify the settings for the player.
  10. mPlayerPtr->setConfig(pConfig);

18. Set snapshot capture

ApsaraVideo Player SDK for Windows provides the feature of snapshot capture. When you capture a snapshot, the player saves the source data in the ARGB32 format of the video image. You can call the onSnapshotImageBuffer method to obtain the source data. Note that a snapshot is a video image and does not contain the UI.

  1. // Take a snapshot of the current video image.
  2. mPlayerPtr->snapshot();
  3. // The callabck for snapshot capture.
  4. void AlivcLivePlayerMainDlg::onSnapshotImageBuffer(AliPlayer *player, int width, int height, unsigned char *pARGBBuffer)
  5. {
  6. QString savePath = "save path";
  7. QImage snapshot(pARGBBuffer, width, height, QImage::Format_ARGB32);
  8. snapshot.save(savePath);
  9. }

19. Set play-and-cache

ApsaraVideo Player SDK for Windows provides the feature of play-and-cache. This feature saves your traffic during loop playback. To enable play-and-cache, call the AVPCacheConfig method before the prepare method is called.

To play an encrypted video, configure a security file for encryption verification. For more information, see “1. Create a player”.

  1. AVPCacheConfig mCacheConfig;
  2. // Enable play-and-cache.
  3. mCacheConfig.enable = true;
  4. // Specify the maximum length of a single cached file. Files whose length exceeds the maximum value are not cached.
  5. mCacheConfig.maxDuration = 100;
  6. // Specify the maximum size of the cache directory. When the total size of cached files in the cache directory exceeds the maximum size, the system overwrites the earliest cached files.
  7. mCacheConfig.maxSizeMB = 200;
  8. // Specify the cache directory. Specify it as required by your application.
  9. mCacheConfig.path = strdup("please use your cache path here");
  10. // Specify the cache settings for the player.
  11. mPlayerPtr->setCacheConfig(&mCacheConfig);

You must call the setCacheConfig method to use cached files. Cached files are used in the following scenarios:

  • If you enable loop playback, the player automatically plays a video all over again by using the cached file after it plays the video completely.
  • After you cache a video and create a player to play the video, the new player plays the video by using the cached file.

Note: The player needs to use the VID to locate cached files for VID-based playback from online requests.

The player does not cache videos during playback in certain scenarios. The following points provide more information about the play-and-cache feature:

  1. When the player plays AVPUrlSource streams by using the HLS protocol based on the URL in an M3U8 playlist, the player does not cache the video during playback. For other supported formats of URL-based playback, the player caches videos during playback as configured.
  2. When the player plays a video based on the VID, the player caches the video during playback as configured.
  3. A video is cached when the player reads all video data. Caching may fail if the stop method or the onError method is called before data reading is complete.
  4. Seeking to a position inside the cached video does not affect the caching result, but seeking to a position outside the cached video may cause a caching failure.
  5. To cache an encrypted video, ensure that the application information matches the authentication information in the security file of the video. Otherwise, the video caching may fail.
  6. The onPlayerEvent callback returns the caching result EVENT_PLAYER_CACHE_SUCCESS or EVENT_PLAYER_CACHE_ERROR.

20. Set preview

ApsaraVideo Player SDK for Windows provides the preview feature. After you set the preview duration, the player plays the video clip for preview instead of the whole video.You can use ApsaraVideo VOD to set the preview feature. This feature supports VidSts and VidAuth sources. For more information, see Best practice of preview. After you enable the preview feature, you can call the setPreviewTime method in VidPlayerConfigGenerator to set the preview duration. The following code uses AVPVidStsSource as an example:

  1. VidPlayerConfigGenerator playConfigGen;
  2. playConfigGen.setPreviewTime(10);
  3. AVPVidStsSource vidSource;
  4. vidSource.initWithVid(VID,
  5. "accessKeyId",
  6. "accessKeySecret",
  7. "Security token",
  8. "Access region",
  9. playConfigGen.generatePlayerConfig());
  10. mPlayerPtr->setSource(vidSource);

II. Video download

ApsaraVideo Player SDK for Windows allows you to download videos from ApsaraVideo VOD by using the STS token and playAuth. ApsaraVideo VOD supports two download modes: secure download and normal download. You can set the download mode in the console.When you select the normal download mode, downloaded videos are not encrypted by Alibaba Cloud, even though the videos have been encrypted by ApsaraVideo VOD. That means you can use third-party players to play the downloaded videos.When you select the secure download mode, downloaded videos are encrypted by Alibaba Cloud, even though the videos have not been encrypted by ApsaraVideo VOD. That means you cannot use third-party players other than ApsaraVideo Player to play the downloaded videos.

To download a video, perform the following steps:

  1. Create and set a download object. 2. Set listeners. 3. Prepare the download source. 4. Select download tasks. 5. Update the download source information and start download. 6. Release the download object after the download succeeds or fails.

1. Create and set a download object

Create a download object. You can use the following sample code:

  1. mMediaDownloader = AliMediaDownloader::CreateMediaDownloader();
  2. mMediaDownloader->setListener(new AVDListenerImpl);
  3. mMediaDownloader->setSaveDirectory("saveDir");

ApsaraVideo Player SDK for Windows allows you to download videos encrypted by Alibaba Cloud. To ensure security, configure a security file encryptedApp.dat for encryption verification.

  1. InitPrivateService(fileContentBuffer, fileLength);

To download an encrypted video, ensure that the application information matches the authentication information in the security file of the video. Otherwise, the video download may fail.

2. Prepare the download source

Call the prepare method to prepare the download source. ApsaraVideo Player SDK for Windows supports two download sources: AVPVidStsSource and AVPVidAuthSource. The following code uses AVPVidStsSource as an example:

  1. AVPVidStsSource vidSource;
  2. vidSource.initWithVid(VID,
  3. "accessKeyId",
  4. "accessKeySecret",
  5. "Security token",
  6. "Access region",
  7. nullptr);
  8. mMediaDownloader->prepareWithVid(&vidSource);

3. Select download tasks

When the download source is prepared, the onPrepared callback is fired. Select a video track for download:

  1. void YourClass::onPrepared(AliMediaDownloader *downloader, AVPMediaInfo *mediaInfo) {
  2. AVPTrackInfo *track = mediaInfo->tracks[0];
  3. mMediaDownloader->selectTrack(track->trackIndex);
  4. }

4. Update the download source information and start download

After you select download tasks and download the track information, you can start the download. We recommend that you update the download source information before the download to prevent AVPVidStsSource or AVPVidAuthSource expiration.

  1. mMediaDownloader->updateWithVid(&vidSource);
  2. mMediaDownloader->start();

5. Release the download object after the download succeeds or fails

After the download succeeds, release the download object.

  1. delete mMediaDownloader;
  2. mMediaDownloader = nullptr;