Product Updates | Contact Support | System Status
Page Contents

    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


    Page last updated on 11 Jun 2022