All Products
Search
Document Center

ApsaraVideo VOD:Media processing

Last Updated:Aug 22, 2023

This topic provides examples on how to use the API operations of the media processing module. The API operations are encapsulated in ApsaraVideo VOD SDK for Java. You can call the API operations to submit transcoding and snapshot jobs, query snapshot data, and preprocess videos in the production studio.

Usage notes

  • In this example, an AccessKey pair is used to initialize a client instance.

  • For more information about the request and response parameters of this operation, visit OpenAPI Explorer. You can click API Documentation in the top navigation bar to view information related to the API operation.

  • This topic provides sample code only for some complex API operations. To obtain sample code for other API operations, perform the following operations: Visit Alibaba Cloud OpenAPI Explorer. In the left-side navigation pane, find the API operation whose sample code you want to obtain and specify the required parameters on the Parameters tab. Then, click Initiate Call. On the SDK Sample Code tab, select the language to view and download the sample code.

Initialize a client

Before you use the SDK, initialize a client. For more information, see Initialization.

Submit a transcoding job

You can call the SubmitTranscodeJobs operation to submit a transcoding job.

Note

Click SubmitTranscodeJobs to learn more about this API operation.

Sample code:

import com.aliyuncs.auth.AlibabaCloudCredentials;
import com.aliyuncs.auth.EnvironmentVariableCredentialsProvider;
import com.aliyuncs.vod.model.v20170321.SubmitTranscodeJobsRequest;
import com.aliyuncs.vod.model.v20170321.SubmitTranscodeJobsResponse;
import com.aliyuncs.vod.model.v20170321.GenerateKMSDataKeyRequest;
import com.aliyuncs.vod.model.v20170321.GenerateKMSDataKeyResponse;

/** 
 * Obtain the AccessKey information.
 */
public static DefaultAcsClient initVodClient() throws ClientException {
    // Specify the region in which ApsaraVideo VOD is activated.
    String regionId = "cn-shanghai";  
    // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
    // We recommend that you do not save your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked. As a result, the security of all resources in your account is compromised. 
    // In this example, the system reads the AccessKey pair from environment variables to implement authentication for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
    DefaultProfile profile = DefaultProfile.getProfile(regionId, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    DefaultAcsClient client = new DefaultAcsClient(profile);
    return client;
    }

/**
 * Submit a transcoding job.
 */
public static SubmitTranscodeJobsResponse submitTranscodeJobs(DefaultAcsClient client) throws Exception {
    SubmitTranscodeJobsRequest request = new SubmitTranscodeJobsRequest();
    // Set the ID of the video that you want to transcode.
    request.setVideoId("34a6ca54f5c140eece85a289****");
    // Set the ID of the transcoding template.
    request.setTemplateGroupId("e8aa925a9798c630d30cd****");
    // Construct watermark parameters to be overridden. These parameters are required only if you want to override watermark-related information.
    JSONObject overrideParams = buildOverrideParams();
    // Configure the watermark parameters to be overridden. You can override only specific watermark parameters. These parameters are required only if you want to override watermark-related information.
    request.setOverrideParams(overrideParams.toJSONString());
    // Construct parameters that are required for HTTP Live Streaming (HLS) encryption. The parameters are required only for HLS encryption.
    JSONObject encryptConfig = buildEncryptConfig(client);
    // Configure the parameters for HLS encryption. The parameters are required only for HLS encryption.
    request.setEncryptConfig(encryptConfig.toJSONString());
    return client.getAcsResponse(request);
}


/**
 * Sample code
 */
public static void main(String[] args) throws ClientException {
    DefaultAcsClient client = initVodClient();
    SubmitTranscodeJobsResponse response = new SubmitTranscodeJobsResponse();
    try {
        response = submitTranscodeJobs(client);
        // The task ID.
        System.out.println("JobId = " + response.getTranscodeJobs().get(0).getJobId());
    } catch (Exception e) {
        System.out.println("ErrorMessage = " + e.getLocalizedMessage());
    }
    System.out.println("RequestId = " + response.getRequestId());
}

/**
 * Construct the parameters for HLS encryption.
 * @return
 * @throws ClientException
 */
public static JSONObject buildEncryptConfig(DefaultAcsClient client) throws ClientException {
    // Note: Specify the client of the ApsaraVideo VOD SDK. You can call the initVodClient method to initialize the client.
    GenerateKMSDataKeyResponse response = generateDataKey(client);
    JSONObject encryptConfig = new JSONObject();
    // The uniform resource identifier (URI) that is used to obtain the decryption key. To obtain the URI, concatenate the URL of the decryption service and the ciphertext key. The ciphertext key varies among videos.
    // You can specify a custom name for the Ciphertext parameter. The name used in this example is for reference only.
    encryptConfig.put("DecryptKeyUri", "http://example.aliyundoc.com/decrypt?" +
            "Ciphertext=" + response.getCiphertextBlob());
    // The type of the key service. Only KMS is supported.
    encryptConfig.put("KeyServiceType", "KMS");
    // The ciphertext key.
    encryptConfig.put("CipherText", response.getCiphertextBlob());
    return encryptConfig;
}

/**
 * 1. Construct watermark parameters to be overridden. You can override only the URL of an image watermark or the content of a text watermark. 
 * 2. Configure the watermark parameters to be overridden. Make sure that the ID of the watermark is associated with the ID of the transcoding template that you use. The ID of the transcoding template is specified by TranscodeTemplateId. 
 * 3. You can call an operation to add only a watermark whose ID is associated with the ID of the transcoding template that you use. 
 * Note: The watermark file and the video must be stored on the same origin server. 
 * @return
 */
public static JSONObject buildOverrideParams() {
    JSONObject overrideParams = new JSONObject();
    JSONArray watermarks = new JSONArray();
    // Override the URL of the image watermark.
    JSONObject watermark1 = new JSONObject();
    // The ID of the image watermark that you want to override. The ID must be associated with the transcoding template.
    watermark1.put("WatermarkId", "2ea587477c5a1bc8b57****");
    // The URL of the new watermark file that is stored in an Object Storage Service (OSS) bucket. The new image and the video must be stored on the same origin server.
    watermark1.put("FileUrl", "https:192.168.0.1/16");

    // Override the content of the text watermark.
    JSONObject watermark2 = new JSONObject();
    // The ID of the text watermark whose content you want to override. The ID must be associated with the transcoding template.
    watermark2.put("WatermarkId", "d297ba31ac5242d207****");
    // The new content of the text watermark.
    watermark2.put("Content", "User ID: 6****");
    watermarks.add(watermark2);
    overrideParams.put("Watermarks", watermarks);
    return overrideParams;
}

/**
 * Create a data key for encryption. The response contains the plaintext and ciphertext of the data key. You need to only pass the ciphertext to ApsaraVideo VOD.
 * @return
 * @throws ClientException
 */
public static GenerateKMSDataKeyResponse generateDataKey(DefaultAcsClient client) throws ClientException {
    GenerateKMSDataKeyRequest request = new GenerateKMSDataKeyRequest();
    return client.getAcsResponse(request);
}

Submit a snapshot job

You can call the SubmitSnapshotJob operation to submit a snapshot job.

Note

For more information about how to create a snapshot template, see AddVodTemplate.

Click SubmitSnapshotJob to learn more about this API operation.

Sample code:

import com.aliyuncs.auth.AlibabaCloudCredentials;
import com.aliyuncs.auth.EnvironmentVariableCredentialsProvider;
import com.aliyuncs.vod.model.v20170321.SubmitSnapshotJobRequest;
import com.aliyuncs.vod.model.v20170321.SubmitSnapshotJobResponse;

/** 
 * Obtain the AccessKey information.
 */
public static DefaultAcsClient initVodClient() throws ClientException {
    // Specify the region in which ApsaraVideo VOD is activated.
    String regionId = "cn-shanghai";  
    // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
    // We recommend that you do not save your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked. As a result, the security of all resources in your account is compromised. 
    // In this example, the system reads the AccessKey pair from environment variables to implement authentication for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
    DefaultProfile profile = DefaultProfile.getProfile(regionId, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    DefaultAcsClient client = new DefaultAcsClient(profile);
    return client;
    }

/**
 * Submit a snapshot job.
 */
public static SubmitSnapshotJobResponse submitSnapshotJob(DefaultAcsClient client) throws Exception {
    SubmitSnapshotJobRequest request = new SubmitSnapshotJobRequest();
    // The ID of the video from which you want to capture snapshots. We recommend that you specify SnapshotTemplateId.
    request.setVideoId("4d237a8270084849bf4207876181****");
    // The ID of the snapshot template.
    request.setSnapshotTemplateId("5d745e6b8baadf589e0702426cfc6****");

    // If you specify SnapshotTemplateId, the following parameters are skipped.
    request.setCount(50L);
    request.setSpecifiedOffsetTime(0L);
    request.setInterval(1L);
    request.setWidth("200");
    request.setHeight("200");
    JSONObject spriteSnapshotConfig = buildSnapshotTemplateConfig();
    request.setSpriteSnapshotConfig(spriteSnapshotConfig.toJSONString());
    return client.getAcsResponse(request);
}

/**
 * Construct the parameters for sprite snapshots.
 * @return
 */
public static JSONObject buildSnapshotTemplateConfig() {
    JSONObject spriteSnapshotConfig = new JSONObject();
    spriteSnapshotConfig.put("CellWidth", "120");
    spriteSnapshotConfig.put("CellHeight", "68");
    spriteSnapshotConfig.put("Columns", "3");
    spriteSnapshotConfig.put("Lines", "10");
    spriteSnapshotConfig.put("Padding", "20");
    spriteSnapshotConfig.put("Margin", "50");
    // Specify whether to retain the source image after an image sprite is generated.
    spriteSnapshotConfig.put("KeepCellPic", "keep");
    spriteSnapshotConfig.put("Color", "tomato");
    return spriteSnapshotConfig;
}

/**
 * Sample code
 */
public static void main(String[] args) throws ClientException {
    DefaultAcsClient client = initVodClient();
    SubmitSnapshotJobResponse response = new SubmitSnapshotJobResponse();
    try {
        response = submitSnapshotJob(client);
        // The task ID.
        System.out.println("JobId = " + response.getSnapshotJob().getJobId());
    } catch (Exception e) {
        System.out.println("ErrorMessage = " + e.getLocalizedMessage());
    }
    System.out.println("RequestId = " + response.getRequestId());
}

Query snapshot data

You can call the ListSnapshots operation to query snapshot data.

Click ListSnapshots to learn more about this API operation.

Preprocess videos in the production studio

You can call the SubmitPreprocessJobs operation to preprocess videos in the production studio.

Click SubmitPreprocessJobs to learn more about this API operation.