Watermarks Settings

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:

Position/Sizing 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 or height the image will be stretched or squeezed, reducing the image quality.
If you must resize the image, specify either the width or height. In that case, the other dimension will be scaled accordingly while maintaining the aspect ratio. The watermark image will be stretched relative to the video aspect ratio if both are specified.
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": [
      {
        //Single watermark
        "watermark":{
          "url": "s3://bucket/watermark_file.png",
          "x": -10,
          "y": -10,
          "width": "12.5%",
          "height": "12.5%"
        },
        //Multiple watermarks
        "watermarks": [
          {
            "url": "s3://bucket/watermark_file.png",
            "x": 20
          }, {
            "url": "s3://bucket/watermark_file.png",
            "x": -20
          }
        ]
      }
    ]
  }

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
        }
      }
    ]
  }

See Also: y and origin

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
        }
      }
    ]
  }

See Also: x and origin

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