Zencoder Encoding Settings: Watermarks

Product(s)
Zencoder
Role(s)
API Developer
Topic(s)
Encoding Settings
Images
API(s)
Zencoder API

This topic contains details for encoding settings related to watermarks.

watermarks

watermarks:Array or Hash

API Versions: V1, V2

Parent: outputs

Valid Values: An array or hash of watermark settings

Compatible Job Types: All

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 GIF, JPEG, BMP, or PNG format.

Watermarks that extend beyond the edges of the video will not be applied. A warning will be raised on the output if this occurs.

Note: When using the VP6 codec there are some additional limitations. You may only apply one watermark to the video (if passed multiple watermarks only the first will be used). Additionally, watermark scaling is not supported and the watermark image must be a PNG file.

{
  "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: V1, V2

Parent: outputs / watermarks

Valid Values: A valid URL to an image file.

Compatible Job Types: All

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 GIF, 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 Integer

API Versions: V1, V2

Parent: outputs / watermarks

Default: -10

Compatible Job Types: All

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 Integer

API Versions: V1, V2

Parent: outputs / watermarks

Default: -10

Compatible Job Types: All

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: V1, V2

Parent: outputs / watermarks

Default: Scale to height, or original image width.

Valid Values: A positive number or a percentage

Compatible Job Types: All

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: V1, V2

Parent: outputs / watermarks

Default: Scale to width, or original image height.

Valid Values: A positive number or a percentage

Compatible Job Types: All

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: V1, V2

Parent: outputs / watermarks

Default: content

Valid Values: content or frame

Compatible Job Types: All

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: V1, V2

Parent: outputs / watermarks

Default: 1.0

Valid Values: 0.0 to 1.0

Compatible Job Types: All

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