Watermark a Video

Watermark Expiration Overview

Expiration:

• This does not affect the expiration on AWS signed urls returned from the POST /watermark endpoint.
• This only applies to the specified watermarked video.
• Expiration must be set on the initial watermark request made for a video with specified watermark settings.
• Once a video has been watermarked with specified watermark settings, the expiration property cannot be updated.
• Changing the watermark settings even in the slightest way will create a new watermark for a video, which would allow you to set a new expiration.
  Example: If you are using a template to watermark videos, you could change the shadowOpacity from .33 -> .34 and that would allow you to set the expiration on the new watermarked video.

Watermarking Overview

Once a video has been ingested, you can request a watermark for the video using this endpoint. At it's simplest you just need the ID or KEY of the video and the text that you'd like you have as your watermark. SafeStream will locate the video that you've already ingested and it will apply the watermark to the file.

{
    "key": "my-internal-id",
    "settings": [
           {
        "content": "Kai Pradel",
        "fontColor": "FFFFFF",
        "y": 0.02,
        "x": 0.02,
        "fontOpacity": 0.5,
        "fontSize": 0.04,
        "align": "LEFT",
        "verticalAlign": "TOP",
        "shadowColor": "000000",
        "shadowOffsetX": 0.08,
        "shadowOffsetY": 0.08,
        "shadowOpacity": 0.33
      },
      {
        "content": "ACME Studios",
        "fontColor": "FFFFFF",
        "y": 0.02,
        "x": 0.98,
        "fontOpacity": 0.5,
        "fontSize": 0.04,
        "align": "RIGHT",
        "verticalAlign": "TOP",
        "shadowColor": "000000",
        "shadowOffsetX": 0.08,
        "shadowOffsetY": 0.08,
        "shadowOpacity": 0.33,
        "animation": {
					"toX": -0.3,
					"startTime": 8,
					"endTime": 16
	  		}
      }
    ]
}

Watermark Using A Template

Using predefined template watermark templates simplifies the watermark request by referencing an existing template and providing the the placeholder data.

A template can contain a placeholder variable such as [%name%] or [%email%] which is then passed into the watermark request along with the template id.

curl -X "POST" "https://s2-api.safestream.com/2.0/watermark" \
     -H "Content-Type: application/json" \
     -H "x-api-key: [[app:apiKey]]" \
     -H "x-api-client-id: [[app:apiClientId]]" \
     -d '{
    "key":"my-internal-id",
    "settingsTemplateMapping": {
        "id": "my-template-id",
        "mappings": {
            "name": "My User",
            "email" : "[email protected]",
            "time" : "12:13:11 am"
        }
    }
}'

To learn more about creating templates, see Creating a Template

Embedding a Forensic Watermark

In addition to adding a visual watermark, you can also embed an invisible watermark. Doing this requires that the video was initially ingested with "enableForensic" set to true.

The request payload for embedding a forensic watermark is much simpler than for visual watermarking. Rather than specifying display properties, the settings for a forensic watermark only need the bits that should be embedded into the video. Here's an example request body for a forensic watermark:

{
    "key": "my-internal-id",
    "settings": [
      {
        "type":"FORENSIC",
        "content": "DIg="
      }
    ]
}

First, notice that we've added the "type" property to the request. This is an optional field that allows us to override the default type, TEXT, and set it to FORENSIC. Without this change this video would be visually watermarked with the string "DIg=" rather than embedding a forensic watermark.

Second, notice the content, it's a 16 bit base64 encoded payload that we'll ebbed invisibly in the video.

The forensic payload for each watermark should be unique to the user who is watching the video.

🚧

Minimum Video Duration

Embedding forensic watermarks is not supported on videos with a duration less than 5 minutes.

Understanding the Watermarking Response

SafeStream supports several integration scenarios:

• 1. Use SafeStream's default video player
• 2. Use your own video player
• 3. Implement SafeStream with your own DRM client.

The watermark post call returns all the data needed to support all three scenarios. Let's take a look at what the response object means:

{
  "status": "READY",
  "containers": {
    "href": "http://linktotheplayerpage",
    "m3u8": "http://api.safestream.com/..."
  },
  "href": "https://s2-api.safestream.com/2.0/watermark/..."
}

1. Using SafeStream's Default Player

The most straight forward integration with SafeStream is to use the default video player which is returned in the containers.href property of the watermarking response. Using this approach, the developer just has to submit the watermark request and place the href in a iframe on the page.

<iframe width='1280' height='720' frameBorder='0' src='<containers.href from watermarking response>'></iframe>

2. Integrate With Your Video Player

If you'd like to integrate with your own player or another third party player, you can use the containers.m3u8 URL in the watermarking response.

3. Integrate with DRM

Contact us for integration scenarios with your preferred DRM vendor.

❗️

Creating watermarks should be done server side

We strongly recommend that you do not create watermarks directly from the browser. Instead you should request watermarks server side. This endpoint requires your credentials and sending those via JavaScript could weaken the security of your viewing system.
However, ALL URL's returned in the watermarking response are intended to be used directly in the browser.