1 Feature Intro
1.1 Brief Introduction
Watermarking is a lightweight copyright protection method. CDNetworks’ VOD platform supports adding image, video, and text watermarks at specified locations, as well as dynamic watermarks.
(1) Image watermark: Supports adaptive scaling, that is, adjusting the size of the watermark image according to the maximum proportion of the video resolution.
(2) Video watermark: Generally used to insert advertising videos into the source video without affecting the video playback.
(3) Text watermark: Does not support adaptive scaling.
(4) Dynamic watermark: The watermark supports changing the position according to a certain time interval or specified time.
1.2 Applicable Product Lines
• Media Acceleration VOD
1.3 Application Scenarios
(1) Implementing lightweight copyright protection.
(2) Adding advertising videos as watermarks to increase revenue.
2 Feature Details
Video watermarking supports common video/audio formats and codecs of source files, such as:
(1) Video formats: MP4, FLV, M3U8, TS, MKV, MOV, WMV, AVI, VP8, VP9, RealVideo, Windows Media Video, etc.;
(2) Audio formats: AAC, AC-3, MP1, MP2, MP3, PCM, RealAudio, Windows Media Audio (WMA), OGG, etc.;
(3) Codecs: H.265, H.264, H.263, MPEG, etc.
When you upload video files, you can configure the parameters for adding watermark operations, use the functions of video transcoding, transmuxing and other audio and video operations simultaneously, by just one API command.
2.1 Basic principles
Customer uploads the instructions to add a watermark by calling the cloud storage API interface, and object storage then issue the instructions to the cloud transcoding module.
After receiving the instruction, cloud transcode module will pull the specified file from the cloud storage and performs the operation according to the customer’s requirements.
After the operation is completed, the file is uploaded to the specified directory of the cloud storage for preservation, while the cloud storage callbacks the target video file address to notify the customer.
3 Instruction for Use
3.1 Request specification
The request parameters are organized in the following format and submitted as the request content.
bucket=<Urlsafe_Base64_Encoded_Bucket>&key=<Urlsafe_Base64_Encoded_Key>&fops=<Urlsafe_Base64_Encoded_Fops>¬ifyURL=<Urlsafe_Base64_Encoded_PersistentNotifyUrl>&force=&separate=
Table 1 Description of request parameters
| Parameters |
Required |
Description |
| bucket |
Yes |
Space
name, i.e., the space where the original file is located. |
| key |
Yes |
File name, i.e., the name of the original
file. |
| fops |
Yes |
Video
watermarking parameters table; supports requesting multiple operations at the
same time, and the parameter list is separated by ';', i.e.,
fops=Urlsafe_Base64_Encode(operation1;operation2;...) |
| notifyURL |
No |
Notify
the receiving URL of processing results, the notification data details the
processed content information, such as code rate, duration, etc. Please refer
to the notification data content description. |
| force |
No |
Whether
to force the execution of data processing. The following values are
supported:： |
| (1) 0: If the specified data processing result exists, returns
that the file already exists without processing to avoid wasting resources
with duplicate processing. |
| (2) 1: Force the execution of data processing and overwrite the
existing file; |
| The default value is 0. |
| separate |
No |
Whether
the processing result is notified separately. The following values are
supported:： |
| (1) 0: Notify the notifyURL after all transcoding instructions
are executed at one time. |
| (2) 1: Notify the notifyURL after each transcoding instruction
is executed. |
| The
default value is 0. |
|
After filling the parameters with the following format, and filling the fops parameter with its URL-safe Base64 encoded value.
/
/wmImage2/<Urlsafe_Base64_Encode(:)>
/wmGravity/
/wmauto/
/wmWidth/,…
/wmHeight/,…
/wmDissolve/,…
/wmdx/,…
/wmdy/,…
/wmInterval/
/multiConvertTime/,…
/wmText/<Urlsafe_Base64_Encode(),<Urlsafe_Base64_Encode()…
/wmFont/<Urlsafe_Base64_Encode(,…)>
/wmFontColor/<Urlsafe_Base64_Encode(,…)>
/wmFontSize/,…
/wmFontDissolve/,…
/wmFontBorderWidth/,…
/wmFontBorderColor/<Urlsafe_Base64_Encode(,…)>
/wmTextGravity/,…
/wmtextdx/,…
/wmtextdy/,…
/wmTextInterval/,…
/wmFontBold/,…
|saveas/<Urlsafe_Base64_Encode(bucket:filekey)>
Table 2 Video watermarking parameters table
|
Parameters
|
Required
|
Description
|
|
<op>
|
Yes
|
avthumb
(operation type - audio and video processing)
|
|
<format>
|
Yes
|
Target
output format, supporting mp4, flv, m3u8, etc.
|
|
|saveas/<bucket:filekey>
|
No
|
Save
as a specified file, where the parameter should be filled in as
"space:filename" after URL-safe Base64 encoded value.
|
|
Image
watermark, video watermark parameters
|
|
/wmImage2/<Urlsafe_Base64_Encode(<bucket1>
:<key1> ,<bucket2> :<key2> ...)>
|
No
|
A
list of image and video watermarks, separated by commas and need to be
URL-safe Base64 encoded value.
|
|
/wmGravity/<Gravity1>
,<Gravity2> …
|
No
|
Watermark
position, see "Table 3 - Video Offset Parameters".
|
|
/wmauto/<wmauto>
|
No
|
Adaptive
scaling of image and video watermarks based on changes in video transcoding
resolution. If set to 1, the image & video watermark will be scaled
adaptively if the transcoding involves a resolution operation; otherwise, it
will be the original image & video watermark size.
For
example: if the original video resolution is 1200x600, the watermark size is
40x40, and the output resolution is set to 300x200, the final watermark size
will be 10x10.
|
|
/wmWidth/<WmWidth1>
,<WmWidth2> ...
|
No
|
Image
and video watermark width, which can be in pixels or percentage. Percentages
represent the percentage of the watermark image's size relative to the output
video's screen size. For example: wmWidth=50%&wmHeight=20% means that the
watermark width is half of the output screen, and the height is 1/5 of the
output screen. wmWidth=40&wmHeight=60 means that the watermark size is
40x60 in pixels. Special note: when wmWidth or wmHeight is 0 or less than 0,
it means adaptive; when both wmWidth and wmHeight are 0 or negative, it means
that the resolution setting function is not enabled for this watermark.
|
|
/wmHeight/<WmHeight1>
,<WmHeight2> ...
|
No
|
Image
and video watermark resolution height, which can be in pixels or percentage.
See the wmWidth parameter for examples and explanations.
|
|
/wmDissolve/<alpha1>
,<alpha2> ...
|
No
|
Image
and video watermark transparency, which supports transformation and is a
numeric type. The range is [0,100], where 100 is opaque and 0 is completely
transparent. When a value outside of this range is specified, it is
automatically limited to this range. For example, -4 becomes 0 and 120
becomes 100. The default value is 100.
|
|
/wmdx/<dx1> ,<dx2> …
|
No
|
Used
to make horizontal adjustments to the position of video/image watermarks
based on the offset list. When the value is positive, the watermark will be
shifted to the right, and vice versa for negative values. When using this parameter,
wmGravity is required and the number of parameters should match with
wmGravity.
|
|
/wmdy/<dy1>
,<dy2> …
|
|
Used
to make vertical adjustments to the position of video/image watermarks based
on the offset list. When the value is positive, the watermark will offset
downwards, otherwise it will be offset upwards. When using this parameter,
wmGravity is required and the number of parameters should match with
wmGravity.
|
|
/wmInterval/<wmInterval>
|
No
|
The
interval at which watermark transformations occur, in seconds.
|
|
/multiConvertTime/<ConvertTime1>
,<ConvertTime2> ...
|
No
|
A
list of video file times at which watermark transformations begin, separated
by commas, and in seconds. Note: wmInterval cannot be used together with
wmStartTime.
|
|
Text
watermark parameters
|
|
/wmText/Urlsafe_Base64_Encode(<Text1>),Encode(<Text2>)...
|
No
|
A
list of text strings. If variations are needed, unlike image/video
watermarks, each string of text must be URL-safe Base64 encoded and then
connected with commas (considering that text contains commas). Chinese
characters need to be encoded in UTF-8, otherwise, they may display as
garbled characters.
|
|
/wmFont/<Urlsafe_Base64_Encode(<Font1>,<Font2>...)>
|
No
|
The
font name of the text watermark. If variations are needed, the font name
should be connected with commas and then URL-safe Base64 encoded. The font
name can only contain numbers, uppercase and lowercase letters, spaces, and
hyphens "-".
|
|
/wmFontColor/<Urlsafe_Base64_Encode(<Color1>,<Color2>...)>
|
No
|
The
font color of the text watermark, if support for transformation is required,
the font color is first connected by a comma and then URL-safe Base64
encoded. Each color item is a string in the format of 0xrrggb or &Hrrggbb
(case-insensitive), which represents the RGB components of the color, and the
0x or &H prefix can be omitted. The color format needs to be correct. The
default value is 0xffffff, which is white.
|
|
/wmFontSize/<size1>,<size2>...
|
No
|
Font
size for text watermark, supports variable. Integer type, a percent sign can
be added after the integer. There are two forms: pixel and percentage. When a
percent sign follows the number, it refers to the percentage of the font
height relative to the output image height. Otherwise, it represents an
absolute pixel size. For example, 10 represents a font height of 10 pixels,
while 10% represents a font height of 10% of the output image height. When
expressed in pixels, the value needs to be within the range [5, 2160]. When
expressed in percentage, the value needs to be within the range (0, 100%].
Default value: 6%.
|
|
/wmFontDissolve/<alpha1>,<alpha2>...
|
No
|
Transparency
of text watermark, supports variable, numerical type. Range is [0, 100]. 100
means opaque, 0 means fully transparent. If the value is beyond this range,
it will not report an error and will be automatically limited to this range.
For example, -4 becomes 0, and 120 becomes 100. Default value: 100.
|
|
/wmFontBorderWidth/<w1>,<w2>...
|
No
|
Font
stroke for text watermark, supports variable, integer type. Less than or
equal to 0 means no stroke, otherwise it represents stroke. Default value: 0.
|
|
/wmFontBorderColor/<Urlsafe_Base64_Encode(<Color1>,<Color2>...)>
|
No
|
Font
stroke color for text watermark, if support for transformation is required,
the font stroke color is first connected by a comma and then URL-safe Base64
encoded. The format is the same as wmFontColor. The default value is
0x000000, which is black.
|
|
/wmTextGravity/<gravity1>,<gravity2>...
|
No
|
The
position of the text watermark, a string type, case-insensitive. If support
for position transformation is required, the preset position is separated by
commas. The format is the same as wmGravity. It must be one of the nine
preset values. The default value is top_right.
|
|
/wmtextdx/<dx1>,<dx2>...
|
No
|
The
horizontal offset based on the preset position of the text watermark, which
supports transformation, is an integer type. The format and meaning are
similar to wmdx. The default value is 0.
|
|
/wmtextdy/<dy1>,<dy2>...
|
No
|
The
vertical offset based on the preset position of the text watermark, which
supports transformation, is an integer type. The format and meaning are
similar to wmdy. The default value is 0.
|
|
/wmTextInterval/<interval1>,<interval2>...
|
No
|
The
time interval for switching the text watermark, which supports
transformation, is in seconds and is a numeric type. The format and meaning
are similar to wmInterval. It needs to be greater than or equal to 1.
|
|
/wmFontBold/<b1>,<b2>...
|
No
|
Whether
the font of the text watermark is bold, which supports transformation, is an
integer type. 0 means that the text does not use bold. Non-zero means that
bold is used. The default value is 0.
|
|
Table 3 Video offset parameters
|
Parameters
|
Description
|
|
TOP_LEFT
|
The
top left corner is the origin of the coordinates. The x-axis goes from left
to right, and the y-axis goes from top to bottom, which is also the default
value.
|
|
TOP_CENTER
|
The
top center position is the origin of the coordinates. The x-axis goes from
left to right, and the y-axis goes from top to bottom.
|
|
TOP_RIGHT
|
The
top right corner is the origin of the coordinates. The x-axis goes from right
to left, and the y-axis goes from top to bottom.
|
|
CENTER_LEFT
|
The
center of the left edge is the origin of the coordinates. The x-axis goes
from left to right, and the y-axis goes from top to bottom.
|
|
CENTER
|
The
center position is the origin of the coordinates. The x-axis goes from left
to right, and the y-axis goes from top to bottom
|
|
CENTER_RIGHT
|
The
center of the right edge is the origin of the coordinates. The x-axis goes
from right to left, and the y-axis goes from top to bottom.
|
|
BOTTOM_LEFT
|
The
bottom left corner is the origin of the coordinates. The x-axis goes from
left to right, and the y-axis goes from bottom to top.
|
|
BOTTOM_CENTER
|
The
center of the bottom edge is the origin of the coordinates. The x-axis goes
from left to right, and the y-axis goes from bottom to top.
|
|
BOTTOM_RIGHT
|
The
bottom right corner is the origin of the coordinates. The x-axis goes from
right to left, and the y-axis goes from bottom to top
|
|
If the request is successful, a Json string is returned with the following content：
{ "persistentId":
}
If the request fails, a Json string is returned with the following content：
{
"code": "",
"message": ""
}
3.2 Response Description
Table 4 Description of response parameters
|
Field Name
|
Required
|
Description
|
|
persistentId
|
Yes
|
Process ID for the
upload preprocessing or triggered persistent processing.
|
|
code
|
Yes
|
HTTP response code,
refer to HTTP response status code <return code>.
|
|
message
|
Yes
|
Error message for
failed processing.
|
|
### 3.3 Example of use
#### 3.3.1 Add Image Watermark
Add an image watermark to the video "test.mp4" under the "vod-wcs-test001" bucket in the top left corner of the screen. The watermark image is named "watermark.jpg" under the same "vod-wcs-test001" bucket and dynamically changes every 5 seconds. The effect is as follows:
(1) At the beginning, the video watermark is placed in the top left corner of the screen.
(2) After 5 seconds, it changes to the top right corner of the screen, shifted 20 pixels to the left.
(3) After another 5 seconds, it changes back to the top left corner of the screen... and so on.
Save the processed video file under the "vod-wcs-test001" bucket and name it "test_watermark.mp4".
curl -v -X POST –d "bucket=Urlsafe_Base64_Encode(vod-wcs-test001)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(avthumb/mp4/wmImage2/Urlsafe_Base64_Encode(vod-wcs-test001:watermark.jpg) /wmGravity/TOP_LEFT,TOP_RIGHT/wmInterval/5/wmdx/0,-20/wmdy/0,0/wmWidth/20%/wmHeight/20%|saveas/Urlsafe_Base64_Encode(vod-wcs-test001:test_watermark.mp4))&force=1&separate=1" –H "Authorization:mgrAuthorization_A:mgrAuthorization_B" --url "http://mgrDomain/fops"
After encryption:
curl -v -X POST -d"bucket=dm9kLXdjcy10ZXN0MDAx&key=dGVzdC5tcDQ=&fops=YXZ0aHVtYi9tcDQvd21JbWFnZTIvZG05a0xYZGpjeTEwWlhOME1EQXhPbmRoZEdWeWJXRnlheTVxY0djPS93bUdyYXZpdHkvVE9QX0xFRlQsVE9QX1JJR0hUL3dtSW50ZXJ2YWwvNS93bWR4LzAsLTIwL3dtZHkvMCwwL3dtV2lkdGgvMjAlL3dtSGVpZ2h0LzIwJXxzYXZlYXMvZG05a0xYZGpjeTEwWlhOME1EQXhPblJsYzNSZmQyRjBaWEp0WVhKckxtMXdOQT09&force=1&separate=1" -H “Authorization:mgrAuthorization_A:mgrAuthorization_B” --url “http://mgrDomain/fops”
Where:
(1) mgrAuthorization_A:mgrAuthorization_B: Management credentials generated by the management credential generation tool using AK (Access Key), SK (Security Key), Path, Path, Body. AK and SK can be obtained from “Console-Account Management-API Information Management-AccessKey Management”. Path is /fops and Body is the request content.
(2) mgrDomain: Management domain name, which can be obtained from "Console-Object Storage-Buckets ".
3.3.2 Add Video Watermark
Add a dynamic video watermark at the top left corner of the test.mp4 video under the vod-wcs-test001 space. The watermark video is named watermark.mp4 and is located under the vod-wcs-test001 space. The watermark video occupies 1/5 of the main video. The processed video file is stored in the vod-wcs-test001 space and named test_video.mp4.
curl -v -X POST –d “bucket=Urlsafe_Base64_Encode(vod-wcs-test001)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(avthumb/mp4/wmImage2/Urlsafe_Base64_Encode(vod-wcs-test001:watermark.mp4)/wmGravity/TOP_LEFT/wmWidth/20%/wmHeight/20%|saveas/Urlsafe_Base64_Encode(vod-wcs-test001:test_video.mp4))&force=1&separate=1” –H “Authorization:mgrAuthorization_A:mgrAuthorization_B” --url “http://mgrDomain/fops”
After encryption：
curl -v -X POST -d"bucket=dm9kLXdjcy10ZXN0MDAx&key=dGVzdC5tcDQ=&fops=YXZ0aHVtYi9tcDQvd21UZXh0L0ppTjROMFkxTVRzbUkzZzFRa0pHT3lZamVEYzVSREU3SmlONE5qSTRNRHNnSmlONE56QkNPVHNtSTNnMk5FRkVPeVlqZURVeVFUQTdKaU40T1RBeFJqcz0vd21Gb250L1FYSnBZV3dnVlc1cFkyOWtaU0JOVXc9PS93bVRleHRHcmF2aXR5L1RPUF9MRUZUfHNhdmVhcy9kbTlrTFhkamN5MTBaWE4wTURBeE9uUmxjM1JmWm1sc1pTNXRjRFE9&force=1&separate=1" -H “Authorization:mgrAuthorization_A:mgrAuthorization_B” --url “http://mgrDomain/fops”
For parameter explanations, please refer to 4.3.1 Add Image Watermark.
4 Notices
(1) The watermark function can only operate on video files stored in cloud storage, so both MA VOD and cloud storage service must be enabled.
(2) Video watermarking is a value-added service and requires a separate fee to use.
