Watermarking

Transform supports most of the commercially available watermarking technologies including Nielsen, Nagra (Nexguard) and Kantar (Civolution). Watermarking technologies apply a unique identifier to the video or audio streams within a media container. Watermark identifiers are used for two main purposes:

program identification for audience measurement (e.g. Nielsen).
forensic identification for content piracy (e.g. Nexguard).

Nielsen Linear

Nielsen linear pre-rendering watermarks content that will be broadcast at a future data and time. This process allows a broadcaster to prepare and distribute VOD versions of the content prior to the broadcast.

Use the NielsenLinearWatermark property to pre-render a composition. For example the following composition watermarks the output for broadcast on December 25 2021 at 8PM PST.

---
input:
  container:
  - name: input1
    video:
    - name: v1
    audio:
    - name: a1
output:
  container:
  - name: media
    type: 'op1a'
    video:
    - name: v1
    audio:
    - name: a1
      properties:
        NielsenLinearWatermark:
          Id: 8adf032252f21defa22d36f100904c7f
          Start: 2021-12-25T20:00:00-08:00
          Duration: 3600
          Verify: true
          Output: watermark
  - name: watermark
    properties:
      Kind: data

Watermark Properties

Property	Type	Description
Id	string	Identifies the watermark to be applied to the content. See the Watermarking Service for details.
Start	string	An ISO8601 string representing the local broadcast start date and time, for example: `2021-12-25T20:00:00-08:00`
Duration	integer	The scheduled broadcast duration in seconds. If not specified the preprocessor will use the input content duration.
Verify	boolean	If `true` the watermarks are decoded and verified.
Output	string	Identifies the output container representing the watermark data. This is a ZIP file containing the watermark metadata and log files.

Watermarking Service

Telestream Cloud provides a utility service that manages watermark information for each of the supported watermarking technologies. For Nielsen linear watermarks the service provides the following:

Stores the information associated with a watermark (name, source identifier, check digits, etc.) and assigns a unique watermark ID.
Reserves a broadcast date, time and duration for a specific watermark ID. This prevents multiple users from watermarking different content for the same broadcast time slot.

Creating a Watermark

For example the following command creates a new watermark:

curl --request POST 'https://api.cloud.telestream.net/watermarking/v1.0/nielsen/watermarks' \
--header 'X-Api-Key: tcs_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "Linear",
  "name": "Test",
  "sid": 7001,
  "sid_check_digits": "YG",
  "csid": "0x21233",
  "csid_check_digits": "IK"
}'

If the command is successful the response will contain the new watermark ID as shown below.

{
  "id": "8adf032252f21defa22d36f100904c7f",
  "type": "Linear",
  "name": "Test",
  "sid": 7001,
  "sid_check_digits": "YG",
  "csid": "0x21233",
  "csid_check_digits": "IK",
  "status": "Active",
  "created_at": "2021-03-01T17:58:51.914522476Z"
}

A Nielsen watermark has the following properties:

Property	Type	Description
`id`	string	Unique identifier assigned to the watermark (32 digit hex string).
`type`	enum	`VOD` `Linear`
`name`	string	User assigned watermark name.
`sid`	integer	Source identifier. A 16 bit value that uniquely identifies the content provider or distribution source.
`sid_check_digits`	string	2 character redundancy check for the SID value.
`csid`	string	CBET Source identifier. A 20 bit value that identifies the content provider or distribution source. This value is typically expressed as a 5 digit hex string where the first digit indicates the CBET layer (1 local, 2 network, 5 TV local).
`csid_check_digits`	string	2 character redundancy check for the CSID value.

Reserving a Broadcast Date

Use the following command to reserve a broadcast date for a specific watermark ID. The request includes the start date and time of the broadcast and the duration of the program in seconds.

curl --request POST 'https://api.cloud.telestream.net/watermarking/v1.0/nielsen/watermarks/8adf032252f21defa22d36f100904c7f/linear_reservations' \
--header 'X-Api-Key: tcs_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "start": "2021-12-25T20:00:00-08:00",
  "duration": 3600
}'

If the entire broadcast time span is available a unique token for the reservation is returned.

{
  "watermark_id": "8adf032252f21defa22d36f100904c7f",
  "start": "2021-12-25T20:00:00-08:00",
  "duration": 3600,
  "token": "4b59b4d6302ab6dea2eb775042a64310",
  "sid": 7001,
  "sid_check_digits": "YG",
  "csid": "0x21233",
  "csid_check_digits": "IK",
  "status": "Active",
  "created_at": "2021-03-01T17:58:51.914522476Z"
}

Revoking a Reservation

The reservation should be revoked if application of the watermark fails or the broadcast time (and therefore the watermark) changes. Use the following command to revoke a reservation identified by the specified token:

curl --request POST 'https://api.cloud.telestream.net/watermarking/v1.0/nielsen/watermarks/linear_reservations/revoke/4b59b4d6302ab6dea2eb775042a64310' \
--header 'X-Api-Key: tcs_YOUR_API_KEY' \
--header 'Content-Type: application/json' \