ApsaraVideo VOD:Secure download

Overview

ApsaraVideo VOD supports video download to mobile devices for offline playback. The normal download and secure download modes are supported. The following content describes the differences between the two modes:

• Secure download (recommended): Videos that are downloaded in this mode are encrypted by Alibaba Cloud. You must use key files to decrypt the videos before you play them. Videos can be played only using ApsaraVideo Player.

• Normal download: Videos that are downloaded in this mode are not encrypted by Alibaba Cloud and can be copied and played using any player. Exercise caution when you use the normal download mode.

Secure download ensures that videos that you download are encrypted. You can play the encrypted videos only using the app that you specified when you generate the key file in the ApsaraVideo VOD console. Compared with the normal download mode, the secure download mode is more reliable and suitable to protect the copyright of downloaded videos. In most cases, we recommend that you use the secure download mode.

Limits

• To use the secure download feature, you must integrate ApsaraVideo Player SDK.

• ApsaraVideo Player SDK supports secure download based on only VidSts and VidAuth.

• Videos that are downloaded using the secure download mode are encrypted on the local device and can be played only based on playback URLs in ApsaraVideo Player SDK on the app that you specified.

Prerequisites

• The download feature is enabled and Download Mode is set to Secure Download in the ApsaraVideo VOD console. For more information, see Configure download settings.

• ApsaraVideo Player SDK is integrated. For more information, see Quick integration of ApsaraVideo Player for Android or Quick integration of ApsaraVideo Player for iOS.

• The video is encrypted using Alibaba Cloud proprietary cryptography or HLS encryption.

Key Android implementation

Secure download settings

1. Configure the key file for encryption verification.

   Configure the key file generated in the ApsaraVideo VOD console in ApsaraVideo Player SDK. The key file is used to encrypt and decrypt videos for download and playback. For more information about how to generate a key file, see Secure download.

   Note

   Make sure that the information in the key file matches the app information that you specified. Otherwise, video download fails.

   We recommend that you configure the security file in your application only once. Sample code:

   PrivateService.initService(getApplicationContext(),  "The path in which the encryptedApp.dat file is stored"); // We recommend that you store the encryptedApp.dat file on your mobile phone and set this parameter to the path in which the file is stored.

2. Create and set a video downloader.

   Use the AliDownloaderFactory class to create a download object. Sample code:

   AliMediaDownloader mAliDownloader = null;
   ......
   // Create a download object.
   mAliDownloader = AliDownloaderFactory.create(getApplicationContext());
   // Set the path for storing downloaded files.
   mAliDownloader.setSaveDir("The storage path");

3. Configure listeners.

   The download object provides multiple listeners. Sample code:

   Show code

   mAliDownloader.setOnPreparedListener(new AliMediaDownloader.OnPreparedListener() {
      @Override
      public void onPrepared(MediaInfo mediaInfo) {
          // Listen for the preparation of the content to be downloaded.
      }
   });
   mAliDownloader.setOnProgressListener(new AliMediaDownloader.OnProgressListener() {
      @Override
      public void onDownloadingProgress(int percent) {
          // Listen for the percentage of the download progress.
      }
      @Override
      public void onProcessingProgress(int percent) {
          // Listen for the percentage of the processing progress.
      }
   });
   mAliDownloader.setOnErrorListener(new AliMediaDownloader.OnErrorListener() {
      @Override
      public void onError(ErrorInfo errorInfo) {
          // Listen for download errors.
      }
   });
   mAliDownloader.setOnCompletionListener(new AliMediaDownloader.OnCompletionListener() {
      @Override
      public void onCompletion() {
          // Listen for a successful download.
      }
   });

4. Prepare the download source.

   You can call the prepare method to prepare a download source. VidSts and VidAuth sources are supported. Sample code:

   • VidSts

     // Create the VidSts download source.
     VidSts aliyunVidSts = new VidSts();
     aliyunVidSts.setVid("Vid");// The ID of the video. 
     aliyunVidSts.setAccessKeyId("<yourAccessKeyId>");// The AccessKey ID that is generated when the temporary STS token is issued. To generate the AccessKey ID, call the AssumeRole operation in STS. 
     aliyunVidSts.setAccessKeySecret"<yourAccessKeySecret>");// The AccessKey secret that is generated when the temporary STS token is issued. To generate the AccessKey secret, call the AssumeRole operation in STS. 
     aliyunVidSts.setSecurityToken("<yourSecurityToken>");// The STS token. To obtain the STS token, call the AssumeRole operation in STS. 
     aliyunVidSts.setRegion("Access region");// The region in which ApsaraVideo VOD is activated. Default value: cn-shanghai. 
      // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
      // If you have not enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console, you do not need to integrate the following code.
      VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
      vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
      aliyunVidSts.setPlayerConfig(config);
             
     
     // Prepare the download source.
     mAliDownloader.prepare(aliyunVidSts)

   • VidAuth

     // Create the VidAuth download source.
     VidAuth vidAuth = new VidAuth();
     vidAuth.setVid("Video ID"); // The video ID. 
     vidAuth.setPlayAuth("<yourPlayAuth>");// The playback credential, which is generated by calling GetVideoPlayAuth. 
     vidAuth.setRegion("Access region"); // This parameter is deprecated in ApsaraVideo Player SDK V5.5.5.0 or later. If you use ApsaraVideo Player SDK V5.5.5.0 or later, the player automatically parses the region information. If you use ApsaraVideo Player SDK V5.5.5.0 or earlier, this parameter is required. Specify the ID of the region in which ApsaraVideo VOD is activated for this parameter. Default value: cn-shanghai. 
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
     VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
     vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     vidAuth.setPlayerConfig(config);
     // Prepare the download source.
     mAliDownloader.prepare(vidAuth);

   Note

   • The output file and the input file are in the same format and cannot be changed.

   • If you enable parameter pass-through for HLS encryption in the ApsaraVideo VOD console, the default parameter is MtsHIsUriToken. For more information, see Parameter pass-through for HLS encryption. Then, set the MtsHIsUriToken value to the ApsaraVideo VOD source by following the preceding code.

5. Select the content to be downloaded from the prepared download source.

   After the download source is prepared, the OnPreparedListener callback is fired. The value of the TrackInfo parameter indicates the information about video tracks such as video definitions. Select a track to download. Sample code:

   public void onPrepared(MediaInfo mediaInfo) {
       // Prepare the content to be downloaded.
       List<TrackInfo> trackInfos = mediaInfo.getTrackInfos();
       // Download the information about tracks, such as the first track.
       mAliDownloader.selectItem(trackInfos.get(0).getIndex());
       // Start the download.
       mAliDownloader.start();
   }

6. (Optional) Update the download source.

   VidSts or VidAuth sources may expire before the download. Therefore, we recommend that you update the download source before you start the download. Sample code:

   // Update the download source.
   mAliDownloader.updateSource(VidSts);
   // Start the download.
   mAliDownloader.start();

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

   After the download succeeds, call the release method to release the download object. You can release the download object after the onCompletion or onError callback is invoked. Sample code:

   mAliDownloader.stop();
   mAliDownloader.release();

8. Optional. Delete a downloaded file.

   You can delete a downloaded file during the download or after the download is complete. Sample code:

   // Delete the file by using the download object.
   mAliDownloader.deleteFile();
   // Delete the file by using the static method. If 0 is returned, the file is deleted.
   AliDownloaderFactory.deleteFile("The path of the downloaded file","Video ID","Video format","The index of the downloaded video");

Play downloaded videos

Videos that are downloaded can be played only based on playback URLs in ApsaraVideo Player SDK. To play a downloaded video, perform the following steps:

1. Obtain the absolute path of the downloaded video file.

   String path = mAliDownloader.getFilePath();

2. Set UrlSource to the absolute path of the downloaded video file to play the video.

    UrlSource urlSource = new UrlSource();
           urlSource.setUri("Playback URL");// Specify the absolute path of the downloaded video file. 
           aliPlayer.setDataSource(urlSource);

Key iOS implementation

Secure download settings

1. Configure the key file for encryption verification.

   Configure the key file generated in the ApsaraVideo VOD console in ApsaraVideo Player SDK. The key file is used to encrypt and decrypt videos for download and playback. For more information about how to generate a key file, see Secure download.

   Note

   Make sure that the information in the key file matches the app information that you specified. Otherwise, video download fails.

   We recommend that you configure the security file in your application only once. Sample code:

   NSString *encrptyFilePath = [[NSBundle mainBundle] pathForResource:@"encryptedApp" ofType:@"dat"];
   [AliPrivateService initKey:encrptyFilePath];

2. Create and set a video downloader.

   Sample code:

   AliMediaDownloader *downloader = [[AliMediaDownloader alloc] init];
   [downloader setSaveDirectory:self.downLoadPath];
   [downloader setDelegate:self];

3. Configure listeners.

   The download object provides multiple listeners. Sample code:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       // The listener for the preparation of the content to be downloaded.
   }
   -(void)onError:(AliMediaDownloader *)downloader errorModel:(AVPErrorModel *)errorModel {
       // The listener for a download error.
   }
   -(void)onDownloadingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // The listener for the download progress in percentage.
   }
   -(void)onProcessingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // The listener for the processing progress in percentage.
   }
   -(void)onCompletion:(AliMediaDownloader *)downloader {
       // The listener for a successful download.
   }

4. Prepare the download source.

   You can call the prepare method to prepare a download source. AVPVidStsSource and AVPVidAuthSource are supported. Sample code:

   • VidSts

     // Create the VidSts download source.
     AVPVidStsSource* stsSource = [[AVPVidStsSource alloc] init];
     stsSource.region = @"Access region"; // The region in which ApsaraVideo VOD is activated. Default value: cn-shanghai. 
     stsSource.vid = @"Video ID"; // The ID of the video. 
     stsSource.securityToken = @"<Your security token>"; // The STS token. To generate an STS token, call the AssumeRole operation in STS. 
     stsSource.accessKeySecret = @"<Your AccessKey secret>"; // The AccessKey secret that is generated when the temporary STS token is issued. To generate the AccessKey secret, call the AssumeRole operation in STS. 
     stsSource.accessKeyId = @"<Your AccessKey ID>"; // The AccessKey ID that is generated when the temporary STS token is issued. To generate the AccessKey ID, call the AssumeRole operation in STS. 
     
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
     // If you have not enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console, you do not need to integrate the following code.
     VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
     [vp setHlsUriToken:yourMtsHlsUriToken];
     stsSource.playConfig = [vp generatePlayerConfig];
     // Prepare the download source.
     [downloader prepareWithVid:stsSource];

   • VidAuth

     // Add the VidAuth download source.
     AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
     authSource.vid = @"Video ID";// The ID of the video. 
     authSource.playAuth = @"<Your playback credential>"; // The playback credential. To obtain the playback credential, call the GetVideoPlayAuth operation in ApsaraVideo VOD. 
     authSource.region = @"Access region"; // This parameter is deprecated in Player SDK V5.5.5.0 or later. If you use Player SDK V5.5.5.0 or later, the player automatically parses the region information. If you use Player SDK V5.5.5.0 or earlier, this parameter is required. Specify the ID of the region in which ApsaraVideo VOD is activated for this parameter. Default value: cn-shanghai. 
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
     // If you have not enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console, you do not need to integrate the following code.
     VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
     [vp setHlsUriToken:yourMtsHlsUriToken];
     authSource.playConfig = [vp generatePlayerConfig];
     // Prepare the download source.
     [downloader prepareWithVid:authSource];

   Note

   If you enable parameter pass-through for HLS encryption in the ApsaraVideo VOD console, the default parameter is MtsHIsUriToken. For more information, see Parameter pass-through for HLS encryption. Then, set the MtsHIsUriToken value to the ApsaraVideo VOD source by following the preceding code.

5. Select the content that you want to download from the prepared download source.

   After the download source is prepared, a callback is invoked by the onPrepared method. The value of the TrackInfo parameter indicates the information about video tracks such as video definitions. Select a track to download. Sample code:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       NSArray<AVPTrackInfo*>* tracks = info.tracks;
       // In this example, download the content of the first track.
       [downloader selectTrack:[tracks objectAtIndex:0].trackIndex];
   }

6. Update the download source and start the download.

   VidSts or VidAuth may expire before the download. Therefore, we recommend that you update the download source before you start the download. Sample code:

   // Update the download source.
   [downloader updateWithVid:vidSource]
   // Start the download.
   [downloader start];

7. Release the downloader after the download succeeds or fails.

   After the download succeeds, call the destroy method to release the downloader.

   [self.downloader destroy];
   self.downloader = nil;

Play downloaded videos

Videos that are downloaded can be played only based on playback URLs in ApsaraVideo Player SDK. To play a downloaded video, perform the following steps:

1. Obtain the absolute path of the downloaded video file.

   Note

   We recommend that you generate the absolute path of a downloaded video file by performing the following steps: obtain the custom storage path and file name from downloadedFilePath, retrieve the sandbox directory, and then concatenate the custom storage path, file name, and sandbox directory.

   NSString *downloadedFilePath = downloader.downloadedFilePath;

2. Set UrlSource to the absolute path of the downloaded video file to play the video.

   AVPUrlSource *urlSource = [[AVPUrlSource alloc] 
   urlWithString:downloadedFilePath];
   [self.player setUrlSource:urlSource];