Watermarks are an effective way to protect the copyright of your video content. Atomile supports adding visible watermarks to videos to help prevent unauthorized use. The platform supports four types of watermarks:

1. Image Watermarks: Add static images with adaptive scaling that adjusts proportionally when the video resolution changes
2. Video Watermarks: Add video clips as overlays, ideal for animated logos or advertisements
3. Text Watermarks: Add text captions or copyright notices
4. Dynamic Watermarks: Create watermarks that change position at specified intervals or timestamps

Atomile supports watermarking for many video formats and codecs, including MP4, FLV, M3U8, TS, MKV, MOV, WMV, AVI, VP8, VP9, RealVideo, Windows Media Video, H.265, H.264, H.263, MPEG, and more.

How to Use

Structure your fops command in the request body as follows:

<op>/<Format>
    /wmImage2/<value>
    /wmGravity/<value>
    /wmauto/<value>
    /wmWidth/<value>
    /wmHeight/<value>
    /wmDissolve/<value>
    /wmdx/<value>
    /wmdy/<value>
    /wmInterval/<value>
    /multiConvertTime/<value>
    /wmText/<value>
    /wmFont/<value>
    /wmFontColor/<value>
    /wmFontSize/<value>
    /wmFontDissolve/<value>
    /wmFontBorderWidth/<value>
    /wmFontBorderColor/<value>
    /wmTextGravity/<value>
    /wmtextdx/<value>
    /wmtextdy/<value>
    /wmTextInterval/<value>
    /wmFontBold/<value>
|saveas/<Urlsafe_Base64_Encode(bucket:filekey)>

Common Parameters

Parameter	Required	Description
op	Yes	Operation type. Use avthumb for watermarking operations.
format	Yes	Target output format, such as flv, mp4, or m3u8.
saveas	Yes	Output location as a URL-safe Base64-encoded string in the format Urlsafe_Base64_Encode(bucket:savedfilename).

Image and Video Watermark Parameters

Parameter	Required	Description
wmImage2	No	The image or video to use as the watermark. Format: URL-safe Base64-encoded <bucket>:<path> Example: test:1.jpg → dGVzdDoxLmpwZw== Multiple watermarks: Separate values with commas. Example: Urlsafe_Base64_Encode(test:1.jpg),Urlsafe_Base64_Encode(test:2.jpg) Tip: For video watermarks, shorter clips work best to maintain synchronization with the main video.
wmGravity	No	Watermark position. See the wmGravity Parameters table below. Tip: For branding, BOTTOM_RIGHT is commonly used because it is less intrusive to the viewing experience.
wmauto	No	Adaptive scaling of watermarks: • 1 - Scale the watermark proportionally as the video resolution changes • 0 (default) - Keep the original watermark size Example: If the original video is 1200x600 with a 40x40 watermark, and it is transcoded to 300x200, the watermark scales to 10x10 when wmauto/1 is used. Tip: Enable wmauto/1 when videos may be viewed on different device sizes.
wmWidth	No	Watermark width in pixels or as a percentage: • Fixed value: wmWidth/40 means 40 pixels wide • Percentage: wmWidth/50% means half of the video width • Value ≤ 0: Width is adjusted based on the aspect ratio Tip: Using percentages instead of fixed pixel values helps maintain proper scaling across different video resolutions.
wmHeight	No	Watermark height in pixels or as a percentage: • Fixed value: wmHeight/60 means 60 pixels high • Percentage: wmHeight/20% means one-fifth of the video height • Value ≤ 0: Height is adjusted based on the aspect ratio If both wmWidth and wmHeight are ≤ 0, the original watermark size is used. Tip: For logo watermarks, 10% to 15% of the video height usually provides good visibility without being too obtrusive.
wmDissolve	No	Watermark transparency, from 1 to 100: • 100 - Fully opaque (default) • 1 - Almost transparent • Out-of-range values are adjusted automatically Tip: Values between 70 and 85 usually provide good visibility while minimizing distraction.
wmdx	No	Horizontal offset relative to the wmGravity position: • Positive value: Move right • Negative value: Move left Must be used with wmGravity, with the same number of parameter values. Tip: Small offsets of 10 to 20 pixels from the edges often improve appearance and reduce the chance of cropping on some displays.
wmdy	No	Vertical offset relative to the wmGravity position: • Positive value: Move up • Negative value: Move down Must be used with wmGravity, with the same number of parameter values. Tip: As with wmdx, small vertical offsets can improve watermark placement and visibility.
wmInterval	No	Time interval in seconds between watermark position changes. Tip: For dynamic watermarks intended to discourage unauthorized screen recording, intervals of 15 to 30 seconds usually work well.
multiConvertTime	No	Specific timestamps for watermark changes, separated by commas. Example: 5,10,20 changes the watermark at 5, 10, and 20 seconds. Cannot be used together with wmInterval. Tip: Aligning watermark changes with scene transitions can make movement less distracting.

Text Watermark Parameters

Parameter	Required	Description
wmText	No	Text watermark content, URL-safe Base64-encoded. Multiple text values: Separate with commas. Example: Urlsafe_Base64_Encode(text1),Urlsafe_Base64_Encode(text2) Important: For Simplified Chinese, use UTF-8 encoding to avoid display issues. Tip: Keep text watermarks short and clear, such as a company name, website, or copyright notice.
wmFont	No	Font used for the text watermark, URL-safe Base64-encoded. Allowed characters: letters, numbers, spaces, and hyphens. Multiple fonts: Separate with commas before encoding. Format: Urlsafe_Base64_Encode(Font1,Font2,…) Tip: See the Supported Watermark Fonts table for the full list. Sans-serif fonts usually provide better readability.
wmFontColor	No	Text color in RGB format, URL-safe Base64-encoded. Format: 0xrrggbb or &Hrrggbb (prefix optional) Multiple colors: Separate with commas before encoding. Format: Urlsafe_Base64_Encode(Color1,Color2,…) Tip: White (0xFFFFFF) or light yellow (0xFFFF00) often provides good visibility on dark backgrounds. Adding a contrasting border improves readability.
wmFontSize	No	Font size in pixels or as a percentage: • Pixel value: Absolute height, range 5 to 2160 • Percentage: Relative to video height, range >0% to 100% • Default: 6% Tip: For most videos, 5% to 8% of the video height provides good readability without overwhelming the content.
wmFontDissolve	No	Text transparency, from 1 to 100: • 100 - Fully opaque (default) • 1 - Almost transparent • Out-of-range values are adjusted automatically Tip: As with image watermarks, values between 70 and 85 often work well.
wmFontBorderWidth	No	Text outline width: • Value ≤ 0 - No outline (default) • Value > 0 - Outline thickness in pixels Tip: A 1- to 2-pixel outline can greatly improve readability, especially on complex backgrounds.
wmFontBorderColor	No	Text outline color, URL-safe Base64-encoded. Format: Same as wmFontColor Default: 0x000000 (black) Tip: For white text, a black outline usually gives the best readability across varied backgrounds.
wmTextGravity	No	Text position, using the same values as wmGravity. For dynamic text watermarks, separate multiple positions with commas. Tip: Text watermarks are often most effective near the bottom of the frame, where they are less likely to block important visual content.
wmtextdx	No	Horizontal offset for text relative to the wmTextGravity position. Uses the same rules as wmdx. Tip: Offsetting text slightly from the edge, such as 10 to 20 pixels, can help prevent it from being cut off on some displays.
wmtextdy	No	Vertical offset for text relative to the wmTextGravity position. Uses the same rules as wmdy. Tip: When placing text at the bottom of the frame, a small positive offset helps keep it from touching the edge.
wmTextInterval	No	Time interval in seconds between text watermark position changes. Must be greater than or equal to 1. Tip: For moving copyright notices, intervals of 20 to 30 seconds are usually less distracting than frequent movement.
wmFontBold	No	Bold text formatting: • 1 - Bold • 0 - Normal (default) Tip: Bold text is often easier to read at smaller sizes or on complex backgrounds.

Watermark Position Parameters (wmGravity)

Parameter	Description
TOP_LEFT	Upper-left corner
TOP_CENTER	Center of the top edge
TOP_RIGHT	Upper-right corner
CENTER_LEFT	Center of the left edge
CENTER	Exact center of the frame
CENTER_RIGHT	Center of the right edge
BOTTOM_LEFT	Bottom-left corner
BOTTOM_CENTER	Center of the bottom edge
BOTTOM_RIGHT	Bottom-right corner

Examples

Example 1: Dynamic Image Watermark

This example adds an image watermark to test.mp4 with the following behavior:

• Watermark image: watermark.jpg from the vod-test001 bucket
• Initially positioned in the top-left corner
• After 5 seconds, moves to the top-right corner with a 20-pixel shift to the left
• After another 5 seconds, returns to the top-left corner
• Watermark size: 20% of the video dimensions

Pseudocode:

curl -v -X POST \
  -d "bucket=Urlsafe_Base64_Encode(vod-test001)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(avthumb/mp4/wmImage2/Urlsafe_Base64_Encode(vod-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-test001:test_watermark.mp4))&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Actual Request:

curl -v -X POST \
  -d "bucket=dm9kLXdjcy10ZXN0MDAx&key=dGVzdC5tcDQ=&fops=YXZ0aHVtYi9tcDQvd21JbWFnZTIvZG05a0xYZGpjeTEwWlhOME1EQXhPbmRoZEdWeWJXRnlheTVxY0djPS93bUdyYXZpdHkvVE9QX0xFRlQsVE9QX1JJR0hUL3dtSW50ZXJ2YWwvNS93bWR4LzAsLTIwL3dtZHkvMCwwL3dtV2lkdGgvMjAlL3dtSGVpZ2h0LzIwJXxzYXZlYXMvZG05a0xYZGpjeTEwWlhOME1EQXhPblJsYzNSZmQyRjBaWEp0WVhKckxtMXdOQT09&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Example 2: Video Watermark

This example adds a video watermark to test.mp4:

• Watermark video: watermark.mp4 from the vod-test001 bucket
• Positioned in the top-left corner
• Size: 20% of the main video dimensions

Pseudocode:

curl -v -X POST \
  -d "bucket=Urlsafe_Base64_Encode(vod-test001)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(avthumb/mp4/wmImage2/Urlsafe_Base64_Encode(vod-test001:watermark.mp4)/wmGravity/TOP_LEFT/wmWidth/20%/wmHeight/20%|saveas/Urlsafe_Base64_Encode(vod-test001:test_video.mp4))&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Actual Request:

curl -v -X POST \
  -d "bucket=dm9kLXdjcy10ZXN0MDAx&key=dGVzdC5tcDQ=&fops=YXZ0aHVtYi9tcDQvd21JbWFnZTIvZG05a0xYZGpjeTEwWlhOME1EQXhPbmRoZEdWeWJXRnlheTV0Y0RRPS93bUdyYXZpdHkvVE9QX0xFRlQvd21XaWR0aC8yMCUvd21IZWlnaHQvMjAlfHNhdmVhcy9kbTlrTFhkamN5MTBaWE4wTURBeE9uUmxjM1JmZG1sa1pXOHViWEEw&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Example 3: Text Watermark

This example adds a text watermark to test.mp4:

• Watermark text: Atomile
• Font: Arial Unicode MS
• Positioned in the top-left corner

Pseudocode:

curl -v -X POST \
  -d "bucket=Urlsafe_Base64_Encode(vod-test001)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(avthumb/mp4/wmText/Urlsafe_Base64_Encode(Atomile)/wmFont/Urlsafe_Base64_Encode(Arial Unicode MS)/wmTextGravity/TOP_LEFT|saveas/Urlsafe_Base64_Encode(vod-test001:test_file.mp4))&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Actual Request:

curl -v -X POST \
  -d "bucket=dm9kLXdjcy10ZXN0MDAx&key=dGVzdC5tcDQ=&fops=YXZ0aHVtYi9tcDQvd21UZXh0L0ppTjROMFkxTVRzbUkzZzFRa0pHT3lZamVEYzVSREU3SmlONE5qSTRNRHNnSmlONE56QkNPVHNtSTNnMk5FRkVPeVlqZURVeVFUQTdKaU40T1RBeFJqcz0vd21Gb250L1FYSnBZV3dnVlc1cFkyOWtaU0JOVXc9PS93bVRleHRHcmF2aXR5L1RPUF9MRUZUfHNhdmVhcy9kbTlrTFhkamN5MTBaWE4wTURBeE9uUmxjM1JmWm1sc1pTNXRjRFE9&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

Supported Watermark Fonts

Font Family	Font Variations
Noto Sans CJK SC	Noto Sans CJK SC Regular Noto Sans CJK SC Black Noto Sans CJK SC Bold Noto Sans CJK SC DemiLight Noto Sans CJK SC Light Noto Sans CJK SC Medium Noto Sans CJK SC Thin
Noto Sans Mono CJK SC	Noto Sans Mono CJK SC Regular Noto Sans Mono CJK SC Bold
Noto Serif CJK SC	Noto Serif CJK SC Noto Serif CJK SC Black Noto Serif CJK SC ExtraLight Noto Serif CJK SC Light Noto Serif CJK SC Medium Noto Serif CJK SC SemiBold
Roboto	Roboto Roboto Condensed Roboto Condensed Light Roboto Black Roboto Light Roboto Medium Roboto Thin