Upload files using the Android SDK - ApsaraVideo VOD - Alibaba Cloud Documentation Center

This topic describes how to use the Android software development kit (SDK) to upload local media files to ApsaraVideo VOD storage.

Prerequisites

Your Android device runs Android 4.0 or later.
Supported versions: Android 4.0 (API 14) and later.

Limits

The Android SDK supports uploading only audio and video files. It does not support uploading auxiliary media assets.

Integrate the SDK

1. Install the Android SDK

Add the Android SDK dependency to the app/build.gradle file of your project.

dependencies {
    implementation 'com.aliyun.video.android:upload:1.6.9'
}

Add the Alibaba Cloud Maven repository URL to the build.gradle file in the root directory.

allprojects {
    repositories {
        maven { url "https://maven.aliyun.com/nexus/content/repositories/releases" }
    }
}

2. Install the OSS Android SDK

The VOD upload SDK for Android depends on the OSS SDK. Therefore, you must also install the OSS Android SDK. For more information, see Install the OSS Android SDK. Add the dependency to your Gradle project.

Basic settings

1. Obtain credentials

First, you must understand the overall process for client-side uploads. Then, you can deploy the required authorization service based on your chosen authorization method:

If you use an upload URL and credential, obtain the upload URL and credential from your authorization service.
If you use a Security Token Service (STS) token, obtain the STS token from your authorization service.

2. Initialize the upload instance

Initialize the upload instance using either an upload URL and credential or an STS token.

Upload URL and credential (Recommended)

Declare the initialization callback for the upload instance (VODUploadClient).
```
uploader = new VODUploadClientImpl(getApplicationContext());
```

Initialize the upload instance (VODUploadClient).

Note

To use an upload URL and credential, call the init method to initialize the instance.
In the onUploadStarted callback, which is triggered after the upload starts, call the setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress) method to set the upload URL and credential.
When you upload audio or video files, the onUploadTokenExpired callback is triggered if the upload URL and credential expire. In this case, you must call the resumeWithAuth(uploadAuth) method and set a new upload credential to continue the upload.

Expand to view the code

// Create a VODUploadClient object.
final VODUploadClient uploader = new VODUploadClientImpl(getApplicationContext());
// Set up the callback.
VODUploadCallback callback = new VODUploadCallback(){
    @Override
    public void onUploadSucceed(UploadFileInfo info) {
        OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
    }

    @Override
    public void onUploadFailed(UploadFileInfo info, String code, String message) {
        OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
    }

    @Override
    public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
        OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
    }

    @Override
    public void onUploadTokenExpired() {
        OSSLog.logError("onExpired ------------- ");
        // Refresh the upload credential by calling the RefreshUploadVideo operation.
        uploadAuth = "Set this to the value of the refreshed credential.";
        uploader.resumeWithAuth(uploadAuth);
    }

    @Override
    public void onUploadRetry(String code, String message) {
        OSSLog.logError("onUploadRetry ------------- ");
    }

    @Override
    public void onUploadRetryResume() {
        OSSLog.logError("onUploadRetryResume ------------- ");
    }

    @Override
    public void onUploadStarted(UploadFileInfo uploadFileInfo) {
        OSSLog.logError("onUploadStarted ------------- ");
        // uploadAuth and uploadAddress are the upload credential and URL.
        uploader.setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress);
    }
};
// Initialize the upload.
uploader.init(callback);

STS token

Declare the initialization callback for the upload instance (VODUploadClient).
```
uploader = new VODUploadClientImpl(getApplicationContext());
```

Initialize the upload instance (VODUploadClient).

Note

To use an STS token, call the init(accessKeyId, accessKeySecret, secretToken, expireTime, callback) method to initialize the instance.
The secretToken initialization parameter is the temporary STS token that you requested.
If the temporary STS token expires, the OnUploadTokenExpired callback is triggered. In this case, you must call the resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime) method and set a new STS token to continue the upload.

Expand to view the code

// Create a VODUploadClient object.
uploader = new VODUploadClientImpl(getApplicationContext());
// Set up the callback.
VODUploadCallback callback = new VODUploadCallback() {
            public void onUploadSucceed(UploadFileInfo info) {
                OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
            }
            public void onUploadFailed(UploadFileInfo info, String code, String message) {
                OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
            }
            public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
                OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
                    }
                }
            }
            public void onUploadTokenExpired() {
                OSSLog.logError("onExpired ------------- ");
                    // After you obtain a new STS token, call resumeWithToken.
                    uploader.resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime);
            }
            public void onUploadRetry(String code, String message) {
                OSSLog.logError("onUploadRetry ------------- ");
            }
            public void onUploadRetryResume() {
                OSSLog.logError("onUploadRetryResume ------------- ");
            }
            public void onUploadStarted(UploadFileInfo uploadFileInfo) {
                OSSLog.logError("onUploadStarted ------------- ");
            }
        };
// Initialize the upload. When the temporary credential expires, update it using resumeWithToken in the onUploadTokenExpired event. Resumable upload is enabled by default.
uploader.init(accessKeyId, accessKeySecret, secretToken, expireTime, callback);

3. Set the upload status callback class

Set the VODUploadCallback object. This object is the callback class for upload statuses. You must set the following callback methods:

Expand to view the code

/**
 Callback for a successful upload.
 @param info The information about the uploaded file.
 */
void onUploadSucceed(UploadFileInfo info);
/**
 Callback for a failed upload.
 @param info The information about the uploaded file.
 @param code The error code.
 @param message The error message.
 */
 void onUploadFailed(UploadFileInfo info, String code, String message);
/**
 Callback for the upload progress.
 @param fileInfo The information about the uploaded file.
 @param uploadedSize The size of the uploaded part.
 @param totalSize The total size of the file.
 */
 void onUploadProgress(UploadFileInfo fileInfo, long uploadedSize, long totalSize);
/**
 Callback for an expired upload URL and credential.
 If you use an upload URL and credential, you must call the resumeWithAuth method to continue the upload.
 If you use an STS token, you must call the resumeWithToken method to continue the upload.
 */
 void onUploadTokenExpired();
/**
 Callback for an upload retry.
 */
 void onUploadRetry(String code, String message);
/**
 Callback for resuming the upload after a retry.
 */
 void onUploadRetryResume ();
/**
 Callback for the start of an upload.
 If you use an upload URL and credential, you must call the setUploadAuthAndAddress:uploadAuth:uploadAddress: method to set the upload URL and credential.
 @param fileInfo The information about the uploaded file.
 */
  void onUploadStarted(UploadFileInfo fileInfo);

4. Construct the upload request function

Audio and video file parameters

Construct an upload request function to add audio and video files to the upload list.

String filePath = "File path";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("Title" + index);
vodInfo.setDesc("Description." + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);

Image file parameters

Construct an upload request function to add image files to the upload list.

String filePath = "Image file path";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("Title" + index);
vodInfo.setDesc("Description." + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);

vodInfo description

// The title.
String title;
// The tags.
List tags;
// The description.
String desc;
// The category.
idInteger cateId;
// The thumbnail URL. This must be a complete URL that starts with https://.
String coverUrl;

Note

After you add a file, the SDK encapsulates the file to be uploaded into an UploadFileInfo object. The structure is as follows:

// The local path of the file.
String filePath;
// The endpoint.
String endpoint;
// The bucket.
String bucket;
// The object.
String object;
// The VodInfo object.
VodInfo vodInfo;

5. Start the upload

Call the start() method to start the upload.
```
void start();
```
After this method is called, the onUploadStarted callback is triggered. If you are uploading the file using an upload URL and credential, you must set the upload URL and credential in this callback method. The following sample code provides an example:
```
void setUploadAuthAndAddress(UploadFileInfo uploadFileInfo, String uploadAuth, String uploadAddress)
```
After the file upload starts, the onUploadProgress callback syncs the upload progress.
After the file is uploaded, the onUploadSucceed callback returns the upload result. The result contains the videoId and imageUrl properties.

Result

After a video is uploaded, a videoId is returned. You can use the videoId to obtain a playback URL. For more information, see Obtain playback credentials.
After an image is uploaded, an imageUrl is returned. If you enable URL signing, the imageUrl expires after a specific period. For more information, see URL signing.

Advanced features

Upload acceleration

The VODUploadClient instance lets you enable upload acceleration.

To upload large files (at the GB or TB level) or perform cross-region uploads, such as uploading a video from the Chinese mainland to a storage address in the Singapore storage region, you can enable the Upload Acceleration feature. For more information, see how to enable it. After you enable the feature, you must add the corresponding key-value pair to the UserData string in the vodInfo configuration of an upload instance. The UserData string is passed as a JSON string. For example:

vodInfo.setUserData("{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}");

Parameter description

Name	Type	Description
Type	string	The type of upload acceleration to enable. Only `oss` is supported.
Domain	string	The acceleration endpoint of the user's bucket. The default protocol is HTTPS. Note Use an acceleration endpoint that is assigned after you enable the feature, such as vod-*******.oss-accelerate.aliyuncs.com.

Queue management

The VODUploadClient instance supports adding multiple files for sequential upload and provides the following methods to manage the upload queue:

Note

Although VODUploadClient supports uploading multiple files, you must configure each file separately if you use an upload credential and URL. To reduce code complexity, we recommend that you add only one file for each upload.

You can delete an upload file from the queue. If the file that you want to delete is being uploaded, the upload is canceled and the next file is automatically uploaded.
```
void deleteFile(int index)
```
You can clear the upload queue. If a file is being uploaded, the upload is canceled.
```
void clearFiles()
```
You can obtain the upload file queue.
```
List<UploadFileInfo> listFiles()
```
You can mark a file as canceled. The file remains in the upload list. If the file that you want to cancel is being uploaded, the upload is canceled and the next file is automatically uploaded.
```
cancelFile(int index)
```
You can resume the upload of a canceled file. The upload starts automatically.
```
resumeFile(int index)
```

Upload control

The VODUploadClient instance supports the following upload control methods:

You can stop the upload. If a file is being uploaded, the upload is canceled.
```
void stop();
```
Note
After you stop an upload, you can call resumeFile to resume the upload of the file, or clear the queue and add the file again to restart the upload.
You can pause the upload.
```
void pause();
```
You can resume the upload.
```
void resume();
```

Callback handling

The VODUploadClient instance supports the following callbacks:

Upload Failure
If an upload fails, the onUploadFailed callback is triggered. In this callback method, you can view the cause of the failure from the code and message parameters and display a notification on the page. For more information about error codes, see Error codes and OSS error codes.
Expired Upload URL And Credential
If an upload credential expires, the onUploadTokenExpired callback is triggered. In this callback, you can request a new upload credential from your app server and call the following method to continue the upload.
Note
You must set the new upload credential in the callback.
Upload Timeout
If an upload times out, the uploadRetry callback is triggered and the upload is automatically retried. In this callback method, you can display a notification on the page or call the cancel method to stop the upload. You can also set the maxRetryCount property to specify the maximum number of retries. If the upload can be continued after a timeout retry, the uploadRetryResume callback is triggered and the upload resumes.

Timeout handling

The VODUploadClient instance lets you set the maximum number of retries:

/**
 Configure the maximum number of retries for a timeout. The default value is INT_MAX.
 */
void setVodHttpClientConfig(VodHttpClientConfig var);

Multipart upload settings

The upload instance (VODUploadClient) lets you set a file size threshold for multipart upload using the partSize value. Files that are larger than this threshold are uploaded in parts.

/**
 The part size. The default value is 1,024 × 1,024 bytes. If a file is larger than the size specified by partSize, the file is uploaded in parts.
*/
void setPartSize(long partSize);

Specify a storage address

The VODUploadClient instance lets you specify a storage address for the uploaded file. If you do not specify a storage address, the file is uploaded to the default storage address. You must enable or configure the storage address in advance. For more information, see Storage.

/**
* Specify the storage address for the file. Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Asset Management > Storage Management to view the storage address.
*/
void setStorageLocation(String storageLocation);

Set transcoding

The VODUploadClient instance lets you set transcoding by specifying a transcoding template group ID.

/**
* Set the transcoding template group ID. Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing > Transcoding Template Groups to view the transcoding template group ID.
*/
void setTemplateGroupId(String templateGroupId);

The VODUploadClient instance lets you set a workflow by specifying a workflow ID.

/**
* Set the workflow ID. Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing > Workflows to view the workflow ID.
*/
void setWorkflowId(String workflowId);

Important

If you specify both a transcoding template group ID and a workflow ID, the workflow configuration takes precedence.

Resumable upload

The client-side upload SDK supports resumable uploads. You only need to make sure that the value of the following method is true.

/**
 * Specifies whether to record the upload progress for resumable uploads. The default value is YES. The upload SDK automatically implements resumable uploads only when this parameter is set to YES. If you set this parameter to NO, the resumable upload feature is disabled.
 */
void setRecordUploadProgressEnabled(boolean var1);

Set the VOD service region

The VODUploadClient instance lets you set the VOD service region.

/**
 The VOD region. The default value is "cn-shanghai".
 */
void setRegion(String var);