Image and text watermarks for videos

Video watermarking adds identifying information to videos, such as company logos, TV station icons, user nicknames, or user IDs, to highlight your brand, protect your copyright, and increase product recognition. Java SDK examples are provided for adding, modifying, deleting, and querying image or text watermarks.

Usage notes

All examples in this topic use an AccessKey pair to initialize a client instance.
For request and response parameter details, visit Alibaba Cloud OpenAPI Explorer and open the API Documentations tab.
For SDK examples of other API operations, visit Alibaba Cloud OpenAPI Explorer. On the Parameters tab, specify the parameters and initiate the call. Then select the SDK version and language on the SDK Sample Code tab to view and download the code.
The examples in this topic use SDK V1.0. For V2.0 examples, select the correct SDK version in OpenAPI Explorer.

Initialize a client

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

Add a watermark

Call the AddWatermark operation to add a watermark. For more information, see the following example.

OpenAPI Portal: or AddWatermark.

Note

For more information about the parameters for obtaining an upload URL and credentials, see CreateUploadAttachedMedia.
For more information about the parameters for uploading a watermark file to Object Storage Service (OSS), see Upload OSS objects.

The following code provides an example:

import com.aliyuncs.auth.AlibabaCloudCredentials;
import com.aliyuncs.auth.EnvironmentVariableCredentialsProvider;
import com.aliyuncs.vod.model.v20170321.AddWatermarkRequest;
import com.aliyuncs.vod.model.v20170321.AddWatermarkResponse;

/** 
 * Read the AccessKey information.
 */
public static DefaultAcsClient initVodClient() throws ClientException {
    // The region where 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 Resource Access Management (RAM) user to call API operations or perform routine O&M.
    // Do not hard-code the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources in your account may be compromised.
    // This example shows how to obtain the AccessKey pair from environment variables to authenticate API requests. Before you run the example, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
    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;
    }

/**
 * The function to add watermark configuration information.
 */
public static AddWatermarkResponse addWatermark(DefaultAcsClient client) throws Exception {
    AddWatermarkRequest request = new AddWatermarkRequest();
    // The name of the watermark.
    request.setName("addwatermark");
    // The OSS URL of the watermark file. Example: http://example.oss-cn-shanghai.aliyuncs.com/watermark/test-****.png.
    String fileUrl = "<your watermarkFile URL>";
    // For an image watermark, you must specify the OSS URL of the image file. The watermark file must be in the same region as the video. For example, if the video is in the China (Shanghai) region, the watermark file must also be stored in the China (Shanghai) region.
    request.setFileUrl(fileUrl);
    // The watermark configuration data.
    JSONObject watermarkConfig = null;
    // The position configuration data for the image watermark.
    watermarkConfig = buildImageWatermarkConfig();

    // The position configuration data for the text watermark.
    //watermarkConfig = buildTextWatermarkConfig();
    request.setWatermarkConfig(watermarkConfig.toJSONString());

    // Text watermark: Text. Image watermark: Image.
    request.setType("Image");
    return client.getAcsResponse(request);
}


/**
 * The following code provides an example.
 * @param args
 * @throws ClientException
 */
public static void main(String[] args) throws ClientException {
    DefaultAcsClient client = initVodClient();
    AddWatermarkResponse response = new AddWatermarkResponse();
    try {
        // Add watermark information.
        response = addWatermark(client);
        // The watermark ID.
        System.out.println("WatermarkId = " + response.getWatermarkInfo().getWatermarkId());
        // The position and effect configuration data of the watermark.
        System.out.println("WatermarkConfig = " + response.getWatermarkInfo().getWatermarkConfig());
        // The FileUrl of the watermark file. This field is empty for text watermarks.
        System.out.println("FileUrl = " + response.getWatermarkInfo().getFileUrl());
    } catch (Exception e) {
        System.out.println("ErrorMessage = " + e.getLocalizedMessage());
    }
    System.out.println("RequestId = " + response.getRequestId());
}

/**
 * Build the configuration data for the image watermark. Modify the parameter values as needed.
 * @return
 */
public static JSONObject buildImageWatermarkConfig() {
    JSONObject watermarkConfig = new JSONObject();
    // The horizontal offset of the watermark.
    watermarkConfig.put("Dx", "8");
    // The vertical offset of the watermark.
    watermarkConfig.put("Dy", "8");
    // The width of the watermark.
    watermarkConfig.put("Width", "55");
    // The height of the watermark.
    watermarkConfig.put("Height", "55");
    // The relative position of the watermark. Valid values: TopLeft, TopRight, BottomLeft, and BottomRight.
    watermarkConfig.put("ReferPos", "BottomRight");
    // The timeline for displaying the watermark. You can specify the start time and end time.
    JSONObject timeline = new JSONObject();
    // The start time for displaying the watermark.
    timeline.put("Start", "2");
    // The end time for displaying the watermark.
    timeline.put("Duration", "ToEND");
    watermarkConfig.put("Timeline", timeline);
    return watermarkConfig;
}

/**
 * Build the configuration data for the text watermark. Modify the parameter values as needed.
 * @return
 */
public static JSONObject buildTextWatermarkConfig() {
    JSONObject watermarkConfig = new JSONObject();
    // The content of the text watermark.
    watermarkConfig.put("Content", "testwatermark");
    // The font name of the text watermark.
    watermarkConfig.put("FontName", "SimSun");
    // The font size of the text watermark.
    watermarkConfig.put("FontSize", 25);
    // The font color of the text watermark. You can also specify an RGB color value, such as #000000.
    watermarkConfig.put("FontColor", "Black");
    // The transparency of the text watermark.
    watermarkConfig.put("FontAlpha", "0.2");
    // The outline color of the text watermark. You can also specify an RGB color value, such as #ffffff.
    watermarkConfig.put("BorderColor", "White");
    // The outline width of the text watermark.
    watermarkConfig.put("BorderWidth", 1);
    // The offset of the text watermark from the top of the video.
    watermarkConfig.put("Top", 20);
    // The offset of the text watermark from the left of the video.
    watermarkConfig.put("Left", 15);
    return watermarkConfig;
}

Modify a watermark

Call the UpdateWatermark operation to modify a watermark. For more information, see the following example.

OpenAPI Portal: | UpdateWatermark.

The following code provides an example:

import com.aliyuncs.auth.AlibabaCloudCredentials;
import com.aliyuncs.auth.EnvironmentVariableCredentialsProvider;
import com.aliyuncs.vod.model.v20170321.UpdateWatermarkRequest;
import com.aliyuncs.vod.model.v20170321.UpdateWatermarkResponse;

/** 
 * Read the AccessKey information.
 */
public static DefaultAcsClient initVodClient() throws ClientException {
    // The region where 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 Resource Access Management (RAM) user to call API operations or perform routine O&M.
    // Do not hard-code the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources in your account may be compromised.
    // This example shows how to obtain the AccessKey pair from environment variables to authenticate API requests. Before you run the example, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
    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;
    }

/**
 * The function to modify watermark configuration information.
 * Note: You cannot modify the file URL of an image watermark. To use a different image, create a new watermark.
 */
public static UpdateWatermarkResponse updateWatermark(DefaultAcsClient client) throws Exception {
    UpdateWatermarkRequest request = new UpdateWatermarkRequest();
    request.setName("updatewatermark");
    // The ID of the watermark whose configuration information you want to update.
    request.setWatermarkId("421ddddd4f6e734a526fd2****");
    // The watermark configuration data.
    JSONObject watermarkConfig = null;
    // The position configuration data for the image watermark.
    //watermarkConfig = buildImageWatermarkConfig();
    // The position configuration data for the text watermark.
    watermarkConfig = buildTextWatermarkConfig();
    request.setWatermarkConfig(watermarkConfig.toJSONString());
    return client.getAcsResponse(request);
}

/**
 * The following code provides an example.
 */
public static void main(String[] args) {
    DefaultAcsClient client = initVodClient();
    UpdateWatermarkResponse response = new UpdateWatermarkResponse();
    try {
        response = updateWatermark(client);
        // The watermark ID.
        System.out.println("WatermarkId = " + response.getWatermarkInfo().getWatermarkId());
        // The position and effect configuration data of the watermark.
        System.out.println("WatermarkConfig = " + response.getWatermarkInfo().getWatermarkConfig());
        // The FileUrl of the watermark file. This field is empty for text watermarks.
        System.out.println("FileUrl = " + response.getWatermarkInfo().getFileUrl());
    } catch (Exception e) {
        System.out.println("ErrorMessage = " + e.getLocalizedMessage());
    }
    System.out.println("RequestId = " + response.getRequestId());
}

/**
 * Build the configuration data for the image watermark. Modify the parameter values as needed.
 * @return
 */
public static JSONObject buildImageWatermarkConfig() {
    JSONObject watermarkConfig = new JSONObject();
    // The horizontal offset of the watermark.
    watermarkConfig.put("Dx", "10");
    // The vertical offset of the watermark.
    watermarkConfig.put("Dy", "10");
    // The width of the watermark.
    watermarkConfig.put("Width", "66");
    // The height of the watermark.
    watermarkConfig.put("Height", "66");
    // The relative position of the watermark. Valid values: TopLeft, TopRight, BottomLeft, and BottomRight.
    watermarkConfig.put("ReferPos", "BottomLeft");
    // The timeline for displaying the watermark. You can specify the start time and end time.
    JSONObject timeline = new JSONObject();
    // The start time for displaying the watermark.
    timeline.put("Start", "2");
    // The end time for displaying the watermark.
    timeline.put("Duration", "ToEND");
    watermarkConfig.put("Timeline", timeline);
    return watermarkConfig;
}

/**
 * Build the configuration data for the text watermark. Modify the parameter values as needed.
 * @return
 */
public static JSONObject buildTextWatermarkConfig() {
    JSONObject watermarkConfig = new JSONObject();
    // The content of the text watermark.
    watermarkConfig.put("Content", "testwatermark");
    // The font name of the text watermark.
    watermarkConfig.put("FontName", "SimSun");
    // The font size of the text watermark.
    watermarkConfig.put("FontSize", 40);
    // The font color of the text watermark. You can also specify an RGB color value, such as #000000.
    watermarkConfig.put("FontColor", "Black");
    // The transparency of the text watermark.
    watermarkConfig.put("FontAlpha", "0.2");
    // The outline color of the text watermark. You can also specify an RGB color value, such as #ffffff.
    watermarkConfig.put("BorderColor", "White");
    // The outline width of the text watermark.
    watermarkConfig.put("BorderWidth", 2);
    // The offset of the text watermark from the top of the video.
    watermarkConfig.put("Top", 20);
    // The offset of the text watermark from the left of the video.
    watermarkConfig.put("Left", 15);
    return watermarkConfig;
}

Delete a watermark

Call the DeleteWatermark operation to delete a watermark.

OpenAPI Portal: / DeleteWatermark.

Query a list of watermarks

Call the ListWatermark operation to query watermarks.

OpenAPI Portal: ListWatermark.

Query a single watermark

Call the GetWatermark operation to query a single watermark.

OpenAPI Portal: GetWatermark.

Set a default watermark

Call the SetDefaultWatermark operation to set a default watermark.

OpenAPI Portal: SetDefaultWatermark.

References

Image and text watermarks for videos: Provides details about the image and text watermark feature of ApsaraVideo VOD, including its working mechanism, scenarios, and examples.