All Products
Search
Document Center

C/C++ Upload SDK

Last Updated: Aug 13, 2019

SDK introduction

Overview

ApsaraVideo for VOD is built based on OSS. After you activate ApsaraVideo for VOD, ApsaraVideo for VOD automatically allocates a dedicated bucket for you. The bucket stores various media files, including the video, audio, and image mezzanine files as well as the transcoded files, snapshots, and thumbnails. The bucket also serves as the CDN’s origin for ApsaraVideo for VOD. You can use the upload SDKs of ApsaraVideo for VOD to quickly upload media files. For more information about supported file formats, see Supported file formats for upload.

Features

C/C++ upload SDK has the following features.

Main features

  1. Supports uploading various media files, including videos, audio files, images, and attached media assets (such as watermark and subtitle files), to ApsaraVideo for VOD.
  2. Supports uploading local media files to ApsaraVideo for VOD. By default, multipart upload is used. The maximum size of a single file that can be uploaded is 48.8 TB. Resumable upload is not currently supported.
  3. Supports uploading online media files stored on the Internet to ApsaraVideo for VOD. The maximum size of a single file that can be uploaded is 5 GB. An online media file is downloaded to a local temporary directory before being uploaded. Resumable upload is not currently supported.
  4. Supports uploading M3U8 videos and provides a method for parsing the .m3u8 playlist to obtain the URL list of parts. You can also specify the URLs of parts.

Other features

  1. Provides an upload progress bar and supports the default and custom progress callbacks.
  2. Supports specifying the region of the ECS instance on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet to accelerate the upload speed and save the public network traffic.
  3. Supports specifying the ApsaraVideo for VOD center and storage region to facilitate upload in regions outside China.
  4. Supports setting the metadata (such as the title), StorageLocation, UserData, and transcoding templates for the upload.

SDK installation

Environment requirements

  • In ApsaraVideo for VOD, C/C++ upload SDK runs in the same environment as C/C++ server SDK. For more information about environment preparation, SDK installation, and initialization, see C/C++ SDK.

Install the SDK

On the SDK download page, click the download address for C/C++ upload SDK and download it. Install C/C++ upload SDK by following the instructions for installing C/C++ SDK.

Upgrade the SDK

If certain new APIs or new features of existing APIs are unavailable in the current SDK, upgrade the SDK to the latest version.Download the latest version of C/C++ upload SDK. Extract files and save them by replacing existing ones.

After decompression, the ChangeLog.txt file generated in the aliyun-c-sdk-vod directory provides version history. You can obtain the version number and release date of the current SDK in the first line.

How to use the SDK

SDK structure

Auxiliary files

  • ChangeLog.txt: provides version history. You can obtain the version number and release date of the current SDK in the first line.

Header files

  • upload.h
    • A function header file used for upload. The file contains basic upload structures, upload parameters, and upload methods.

Basic structures

  • CreateUploadVideoRequest

    • The request class for uploading videos. For more information about its fields, see CreateUploadVideo.
  • CreateUploadImageRequest

    • The request class for uploading images. For more information about its fields, see CreateUploadImage.
  • CreateUploadAttachedMediaRequest

    • The request class for uploading attached media assets. For more information about its fields, see CreateUploadAttachedMedia.
  • UploadOptions

    • The upload parameter structure. It contains the following parameters:
      • void (*uploadProgressCallback) (int64_t, int64_t): customizes the callback for upload progress. If you do not set this parameter, the default callback is used. If you set this parameter to Null, no callback for upload progress will be fired.
      • ecsRegionId: specifies the region of the ECS instance (if any) on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet.
      • multipartUploadLimit: specifies the threshold of the file size exceeding which multipart upload starts, in bytes. The default value is 10 MB. This parameter is valid only for uploading videos.
      • multipartUploadOnceSize: specifies the size of each part in multipart upload, in bytes. The default value is 10 MB. This parameter is valid only for uploading videos.
      • tmpDir: specifies a local temporary directory for storing the downloaded online files. This parameter is valid only for uploading online files.

Upload methods

  • uploadLocalVideo: a method for uploading local videos.
  • uploadWebVideo: a method for uploading online videos.
  • uploadLocalImage: a method for uploading local images.
  • uploadWebImage: a method for uploading online images.
  • uploadLocalAttachedMedia: a method for uploading local attached media assets.
  • uploadWebAttachedMedia: a method for uploading online attached media assets.
  • uploadLocalM3u8: a method for uploading local M3U8 videos.
  • uploadWebM3u8: a method for uploading online M3U8 videos.

samples directory

  • UploadVideo.cpp: provides the sample code for uploading videos.
  • UploadImage.cpp: provides the sample code for uploading images.
  • UploadAttachedMedia.cpp: provides the sample code for uploading attached media assets.

Example

The following section provides the sample code for uploading local videos and online videos:

  1. void testCallback(int64_t consumed_bytes, int64_t total_bytes)
  2. {
  3. printf("total :%ld, %ld\n", consumed_bytes, total_bytes);
  4. }
  5. // Tests the upload of a local video.
  6. VodApiResponse testUploadLocalVideo(VodCredential authInfo) {
  7. CreateUploadVideoRequest request;
  8. request.fileName = "testLocal.mp4";
  9. request.title = "testUploadLocalVideo";
  10. request.cateId = "1";
  11. request.coverURL = "http://xxxx.jpg";
  12. request.tags = "test1,test2";
  13. request.templateGroupId = "6ae347b0140181ad371d197ebe289326";
  14. requests.torageLocation. = "outin-xx.oss-cn-beijing.aliyuncs.com";
  15. Json::Value userData;
  16. Json::Value callbackUrl;
  17. callbackUrl["CallbackURL"] = "https://demo.sample.com/ProcessMessageCallback";
  18. userData["MessageCallback"] = callbackUrl;
  19. Json::Value extend;
  20. extend["localId"] = "xxx";
  21. extend["test"] = "www";
  22. userData["Extend"] = extend;
  23. request.userData = userData.toStyledString();
  24. UploadOptions uploadOptions;
  25. // Specifies the region of the ECS instance (if any) on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet.
  26. //uploadOptions.ecsRegionId = "cn-shanghai";
  27. // Customizes the callback for upload progress. If you do not set this parameter, the default callback is used. If you set this parameter to Null, no callback for upload progress will be fired.
  28. //uploadOptions.uploadProgressCallback = testCallback;
  29. //uploadOptions.multipartUploadLimit = 20*1024*1024;// Specifies the threshold of the file size exceeding which multipart upload starts.
  30. //uploadOptions.multipartUploadOnceSize = 10*1024*1024;// Specifies the size of each part in multipart upload.
  31. VodApiResponse result = uploadLocalVideo(authInfo, request, "./test.mp4", uploadOptions);
  32. return result;
  33. }
  34. // Tests the upload of an online video.
  35. VodApiResponse testUploadWebVideo(VodCredential authInfo) {
  36. CreateUploadVideoRequest request;
  37. request.fileName = "testWeb.mp4";
  38. request.title = "testUploadWebVideo";
  39. UploadOptions uploadOptions;
  40. // Specifies the region of the ECS instance (if any) on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet.
  41. //uploadOptions.ecsRegionId = "cn-shanghai";
  42. // Customizes the callback for upload progress. If you do not set this parameter, the default callback is used. If you set this parameter to Null, no callback for upload progress will be fired.
  43. //uploadOptions.uploadProgressCallback = testCallback;
  44. //uploadOptions.multipartUploadLimit = 20*1024*1024;// Specifies the threshold of the file size exceeding which multipart upload starts.
  45. //uploadOptions.multipartUploadOnceSize = 10*1024*1024;// Specifies the size of each part in multipart upload.
  46. // Specifies a local temporary directory for storing the downloaded online files. The default value is /tmp/.
  47. //uploadOptions.tmpDir = "/tmp/";
  48. VodApiResponse result = uploadWebVideo(authInfo, request, "<Your Download Url>", uploadOptions);
  49. return result;
  50. }
  51. // Tests the upload of a local M3U8 video.
  52. VodApiResponse testUploadLocalM3u8(VodCredential authInfo) {
  53. CreateUploadVideoRequest request;
  54. request.fileName = "testLocal.m3u8";
  55. request.title = "testUploadLocalM3u8";
  56. list<string> tsList;
  57. // Note: If you do not specify the URLs of parts, the file is parsed automatically.
  58. //tsList.push_back("/tmp/1.ts");
  59. UploadOptions uploadOptions;
  60. VodApiResponse result = uploadLocalM3u8(authInfo, request, "./test.m3u8", tsList, uploadOptions);
  61. return result;
  62. }
  63. // Tests the upload of an online M3U8 video.
  64. VodApiResponse testUploadWebM3u8(VodCredential authInfo) {
  65. CreateUploadVideoRequest request;
  66. request.fileName = "testWeb.m3u8";
  67. request.title = "testUploadWebM3u8";
  68. list<string> tsList;
  69. // Note: If you do not specify the URLs of parts, the file is parsed automatically.
  70. //tsList.push_back("<Ts1 Download Url>");
  71. //tsList.push_back("<Ts2 Download Url>");
  72. UploadOptions uploadOptions;
  73. VodApiResponse result = uploadWebM3u8(authInfo, request, "<Your M3u8 Download Url>", tsList, uploadOptions);
  74. return result;
  75. }
  76. #### Runs the test code. ####
  77. VodCredential initVodClient(std::string accessKeyId, std::string accessKeySecret) {
  78. VodCredential authInfo;
  79. authInfo.accessKeyId = accessKeyId;
  80. authInfo.accessKeySecret = accessKeySecret;
  81. authInfo.regionId = "cn-shanghai";
  82. return authInfo;
  83. }
  84. int main(int argc, char * argv[]) {
  85. VodCredential authInfo = initVodClient("<Your AccessKeyId>", "<Your AccessKeySecret>");
  86. VodApiResponse response;
  87. response = testUploadLocalVideo(authInfo);
  88. //response = testUploadWebVideo(authInfo);
  89. //response = testUploadLocalM3u8(authInfo);
  90. //response = testUploadWebM3u8(authInfo);
  91. printf("httpCode: %d, result: %s\n", response.httpCode, response.result.c_str());
  92. }

For more sample code, see the samples directory in the decompressed aliyun-c-sdk-vod directory.

FAQ

  • How can I upload media files to ApsaraVideo for VOD through the intranet?
    In the ApsaraVideo for VOD console, click Storage in the left-side navigation pane and view the storage region of your media assets. Deploy the upload script on the ECS instance in that region. After initializing the AliyunVodUploader class instance, call the setEcsRegionId method to set the region ID to that of the ECS region, such as cn-shanghai.

  • How can I obtain the upload progress?
    The uploadProgressCallback function pointer in the UploadOptions structure points to the callback address so that you can obtain the size of uploaded parts and total file size. You can override this method to customize the callback for upload progress.

  • Is the upload synchronous or asynchronous?
    C/C++ upload SDK supports synchronous upload only, which may block the corresponding process or thread. If you need asynchronous upload, we recommend that you use a separate thread to upload files.

  • Is resumable upload supported?
    Currently, C/C++ upload SDK does not support resumable upload. When you resume the upload of a video or an image, the downloaded parts of the video or image will be downloaded again. Resumable upload will be supported in the future.

  • How can I handle disconnections?
    First, check whether you can connect to the Internet. You can ping vod.cn-shanghai.aliyuncs.com to check whether you can connect to the ApsaraVideo for VOD server. If the connection fails, check your network settings, such as whether you have the permission to access the Internet.