Burn in a personalized watermark into your 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": "lynda-7",
"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
}
]
}
Watermarks can be configured to meet your needs. For more information on available template or on how to customize the settings, see the Settings docs.
Watermark Using A Template
Using predefined 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 -H "Authorization: Bearer [[app:authentication_token]]" -H "Content-Type: application/json" -d '{
"key":"https://myvideos.com/myvideo.mp4",
"containers": [
"m3u8",
"mp4"
],
"settingsTemplateMapping": {
"id": "74fc00c8-847d-4631-94a4-f4ac7d1e4748",
"mappings": {
"name": "My User",
"email" : "[email protected]",
"time" : "12:13:11 am"
}
}
}' "https://safestream-api.shiftplatform.io/1.0/watermark"
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. See the ingest docs for those details.
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": "lynda-7",
"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 ASCII 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 Response
SafeStream supports several integration scenarios:
-
- Use SafeStream's default video player
-
- Use your own video player
-
- 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",
"iframe": "<iframe width='1280' height='720' src='></iframe>",
"m3u8": "http://api.safestream.com/..."
},
"href": "https://safestream-api.shiftplatform.io/0.1/watermark/..."
}
| Field | Description |
|---|---|
| status | Either PENDING or READY. |
| iframe | This iframe can be embedded on the page immediately after it is returned. Using the iFrame means all playback responsibility is delegated to the iframe and the turn-key SafeStream player. As a developer, you don't have to take any further action using this approach. |
| m3u8 | The m3u8 field is only returned when the status if set to READY and can be used immediately in your own player implementation. |
| href | This field is return immediately and includes the link to a long-poll URL that can be used to check the progress without additional authentication parameters. The long-poll url is signed and will expire shortly after the watermark job returns READY. Using this field is helpful when integration SafeStream with your own video player. |
| href -> container | The href inside the container is a direct link to the player page. This is useful when constructing your own iframe to add to the page. |
1. Use SafeStream's Default Player
The most straight forward integration with SafeStream is to use the default video player that is returned in the form of an iframe. Using this approach, the developer just has to submit the watermark request and place the iframe on the page. The player will display a loading animation while the watermark process in completing and will start playback automatically once the file is available.
<iframe width='1280' height='720' frameBorder='0' src='http://safestream-api.shiftplatform.io/public/player?sourceUrl=http%3A%2F%2Fsafestream-api.shiftplatform.io%2F0.1%2Fwatermark%2Ff60528b6-d408-4522-8695-914fd4def33a%2F2d95aa637b78ea0c24305eeec4f210a3ada27d7f%2Fvideo.m3u8%3Fexpiration%3D1452808936812%26signature%3D8369f474a6cddb73c44a833bc47eda25967a91f6171a01d4ef8f9b954cc0f416'></iframe>
2. Integrate With Your Video Player
If integration into your existing video player is desired, SafeStream returns a long-poll URL in the "href" field that can be used to periodically check for the status of the watermark job. Once done, the response object is similar to that of the watermark request (without the href longpoll url). The returned m3u8 link for HLS playback can now be passed to your video player.
The following example uses the href field that was returned from the watermark request and checks the url every 3 seconds to see if the file is ready for playback.
var pollUrl = [the href poll url];
function checkwatermark(){
var settings = {
"async": true,
"crossDomain": true,
"url": pollUrl,
"method": "GET",
"headers": {
"content-type": "application/json",
}
}
$.ajax(settings).done(function (response) {
var res = JSON.parse(response);
if(res.status === "READY"){
// tell your player to use res.container.m3u8
} else {
// Call again in a few seconds
setInterval(checkwatermark(), 3000);
});
}
3. Integrate with DRM
Contact us for integration scenarios with your preferred DRM vendor.
POST /WATERMARK belongs in the middle tier
We strongly recommend that the POST /watermark request is implemented in your middle tier and NOT in the front end of your application. This endpoint requires your credentials and sending those via JavaScript could weaken the security of your viewing system.
Subsequent requests, such as the longpolling url are signed requests and can therefore be used in your front end code.