Watermarks Settings

This topic contains details for encoding settings related to video watermarks.

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, 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.

Positioning Watermarks
Positioning Watermarks

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

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