Introduction
Watermarks are images added to video, often to indicate its origin or ownership. When you specify a watermark, the image will be embedded into that output. Like the video input, the location of the watermark is specified through a url
that Zencoder can access.
Zencoder allows you to position and size the watermark through the following settings:
Setting | Description |
---|---|
x |
The horizontal position of the watermark expressed as a number of pixels, a percentage of the video width, or as centered . If x is a positive number or percentage it will be measured from the left edge of the video to the left edge of the image. If x has a negative value, it will be measured from the right edge of the video to the right edge of the image. Default: -10 |
y |
The vertical position of the watermark expressed as a number of pixels, a percentage of the video width, or as centered . If y is a positive number or percentage it will be measured from the top edge of the video to the top edge of the image. If y has a negative value, it will be measured from the bottom edge of the video to the bottom edge of the image. Default: -10 |
width |
The width of the watermark expressed as a number of pixels or a percentage of the video width. Default: actual width of the image. |
height |
The height of the watermark expressed as a number of pixels or a percentage of the video height. Default: actual height of the image. |
Notes
- All settings above may be entered as strings or numbers if they have pixel values.
- If you use
width
orheight
the image will be stretched or squeezed, reducing the image quality. - If you must resize the image, specify either the
width
orheight
, but not both. In that case the other dimension will be scaled accordingly while maintaining the aspect ratio. - The watermark must be sized and positioned in such a way that it will fit entirely with the frame-size of the output it is assigned to. If it does not, Zencoder will return an error.
- There is also an
origin
which allows you to make all measurements with reference to the video frame size rather than the content size, if the two are different - but that is rare.
The diagram below illustrates how the x
and y
settings work.
Sample
The sample below was watermarked with the following settings:
{
"input": "https://support.brightcove.com/test-assets/videos/oystercatcher.mp4",
"outputs": [
{
"watermarks": {
"url": "https://support.brightcove.com/test-assets/images/watermark.png",
"x": "centered",
"y": "centered"
}
}
]
}
watermarks
watermarks:Array or Hash
API Versions: V2
Parent: outputs OR dynamic_profile_options
Valid Values: An array or hash of watermark settings
Compatible Job Types: VOD
Description:
You can add one or more watermarks to an output video using our watermarking API. Zencoder supports up to 4 watermark files per output in JPEG, BMP, or PNG format.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": [
{
"url": "s3://bucket/watermark_file.png",
"x": 20,
"y": "-10%",
"width": 32,
"height": 24
}
]
}
]
}
url
url:String
API Versions: V2
Parent: outputs / watermarks
Valid Values: A valid URL to an image file.
Compatible Job Types: VOD
Example:
- https://s3.amazonaws.com/bucket/img.png
- ftp://user:pass@example.com/path/to/watermark.jpg
Description:
The URL of a remote image file to use as a watermark. Use the input URL syntax. Supports S3, GCS, Cloud Files, HTTP/S, FTP, and SFTP, with or without authentication.
Zencoder supports watermark files in JPEG, BMP, or PNG format.
For transparent watermarks, use PNGs with alpha or index transparency.
Supported PNG Formats
- 8-bit RGB
- 8-bit RGB+Alpha
- 8-bit Grayscale
- 8-bit Indexed
- 8-bit Indexed+Transparency
- 16-bit RGB
- 16-bit Grayscale
Unsupported PNG Formats
- 8-bit Grayscale+Alpha
- 16-bit Grayscale+Alpha
- 16-bit RGB+Alpha
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"url": "https://s3.amazonaws.com/bucket/img.png"
}
}
]
}
x
x:String or Number
API Versions: V2
Parent: outputs / watermarks
Default: -10
Compatible Job Types: VOD
Example:
- -0
- 320
- centered
Description:
Where to place the watermark within the video, on the x axis (left/right). Can be a number of pixels (e.g. 100 or -20), a percent of the video width (e.g. 25% or -5%), or 'centered' to align the watermark to the center of the video. Use a positive number to place relative to the left side of the video, and a negative number to place relative to the right side of the video. Use "-0" (as a string) to lock to the right side.
By default, position is based on the visible content area, not including any padding. Use origin to set watermark position based on the full output.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"x": 320
}
}
]
}
y
y:String or Number
API Versions: V2
Parent: outputs / watermarks
Default: -10
Compatible Job Types: VOD
Example:
- -0
- 320
- centered
Description:
Where to place the watermark within the video, on the y axis (top/bottom). Can be a number of pixels (e.g. 100 or -20), a percent of the video width (e.g. 25% or -5%), or 'centered' to align the watermark to the center of the video. Use a positive number to place relative to the top side of the video, and a negative number to place relative to the bottom side of the video. Use "-0" (as a string) to lock to the bottom.
By default, position is based on the visible content area, not including any padding. Use origin to set watermark position based on the full output.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"y": 320
}
}
]
}
width
width:Number or String
API Versions: V2
Parent: outputs / watermarks
Default: Scale to height, or original image width.
Valid Values: A positive number or a percentage
Compatible Job Types: VOD
Description:
The width of the watermark, expressed as a number of pixels (e.g. 64) or as a percent of the video width (e.g. 10%). If height is provided, but not width, the watermark image will be scaled proportionately.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"width": 100
}
}
]
}
See Also: height
height
height:Number or String
API Versions: V2
Parent: outputs / watermarks
Default: Scale to width, or original image height.
Valid Values: A positive number or a percentage
Compatible Job Types: VOD
Description:
The height of the watermark, expressed as a number of pixels (e.g. 64) or as a percent of the video height (e.g. 10%). If width is provided, but not height, the watermark image will be scaled proportionately.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"height": 100
}
}
]
}
See Also: width
origin
origin:String
API Versions: V2
Parent: outputs / watermarks
Default: content
Valid Values: content or frame
Compatible Job Types: VOD
Example: frame
Description:
The part of the video to base the watermark's positioning on. This only affects jobs where aspect_mode is 'pad'.
- 'frame' bases the placement on the full resolution of the output, including any padding.
- 'content' bases the placement on the visible content area, not including padding.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"origin": "content"
}
}
]
}
See Also: x, y, and aspect_mode
opacity
opacity:Float
API Versions: V2
Parent: outputs / watermarks
Default: 1.0
Valid Values: 0.0 to 1.0
Compatible Job Types: VOD
Example: 0.5
Description:
Make the watermark transparent by setting an opacity value between 0.0 (transparent) and 1.0 (opaque).
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"watermarks": {
"opacity": 0.5
}
}
]
}
See Also: url