QuickMark forensic watermarking

The Nexguard library forensic watermarking tool QuickMark embeds a unique, invisible serial number onto video/audio content.

QuickMark watermarking can work in different modes:

• In pull mode, the player will acquire the watermark from the configured server as necessary.

• In push mode, the customer application will acquire the watermark and provide it to the player for display.

The QuickmarkInterface class abstracts the NexGuard-QuickMark library functionality that provides watermarking technology to the SDK.

Integrating the QuickMark service

Download the opy-sdk-js-5.19.x-quickmark.zip file; see Downloading the SDK.

Include the Nexguard jswbw2-min.js module in the HTML file before the opy-sdk-js-all.js SDK file:

<!-- Quickmark module -->
<script src="jswbw2-min.js"></script>
<!-- player SDK -->
<script src="opy-sdk-js-all.js"></script>

Replace opy-sdk-js-all.js with opy-sdk-js-all-no-ui.js when using the Reduced Size SDK.

The otvplayer instantiates and operates the QuickMark service. The calling application provides the compulsory and optional configuration elements via the player options before otvplayer setup.

If the QuickMark service is enabled using player options, but the Nexguard module is not included, the error callback will be called with error code -1 (Nexguard module is not loaded), and other errors may be encountered.

Pull mode example configuration

The QuickMark watermarking feature is enabled by including the QuickMark configuration in the OTVToolkit configuration. The application provides configuration options.

let playerInstance = otvplayer(
    plugins: {
        otvtoolkit: {
			quickmark: {
			quickmarkConfig: {
				token: "400000000",
				tenant: "TEST_TENANT",
				apikey: "<Contact NAGRA for your key>",
				service: "<Contact NAGRA for your URL>",
				secret: "<Contact NAGRA for your secret>"
				},
				message: quickmarkMessageCallback,
				error: quickmarkErrorCallback
			}
		}
	}
});

// The player must be told when to start acquiring the watermark
playerInstance.on("playing", () => {
	playerInstance.otvtoolkit().quickmarkInterface.start();
});
playerInstance.on("ended", () => {
	playerInstance.otvtoolkit().quickmarkInterface.stop();
});
playerInstance.on("pause", () => {
	playerInstance.otvtoolkit().quickmarkInterface.stop();
});

On successful loading of the QuickMark service, QuickMark sends a jswbw <version> initialized message.

In pull mode, the following configuration items are mandatory:

• token 

• url (or service and tenant)

• secret or tlValidation

The following configuration items are optional:

• apiKey 

• message 

• error 

Push mode example configuration

Push mode can be used in architectures where the normal mechanisms for watermark acquisition are unsuitable, for example, where an API gateway is used.  Here the application is responsible not only for watermark acquisition but for the implementation of a timeline depending on the expiry.  A full description of such implementation is beyond the scope of this document. 

Push mode is not supported in the Reduced Size SDK.

let playerInstance = otvplayer(
    plugins: {
        otvtoolkit: {
			quickmark: {
				message: onQuickmarkMessage,
				error: onQuickmarkError,
				quickmarkConfig: {
					secret: "<Contact NAGRA for your secret>",
				}
			}
		}
	}
});

...

// When the watermark is acquired, pass it to the player
playerInstance.otvtoolkit().quickmarkInterface.update(watermark);

In push mode, the following configuration items are mandatory:

• secret or tlValidation

The following configuration items are optional:

• message 

• error 

The following configuration items should not be provided in push mode:

• url

• service

• tenant

• token

• apiKey

Watermark authentication

The watermark data is authenticated using a signature. By default, this signature is calculated using HMA SHA-1, and a secret must be provided in the configuration, as shown above. A deployment can use a mechanism other than HMAC SHA-1. In this case, a validation callback function  tValidation must be provided in the configuration instead of the secret. The tValidation callback will accept the watermark data as a single Uint8Array parameter and return the calculated signature as a Uint8Array.

QuickMark server URL

A QuickMark server has the form https://www.your_service_url.com/your_tenant_id/qm/v2/surfaces.  This may be specified using the url configuration, or for compatibility with an older version, the service and tenant configurations as shown above.

The quickmarkInterface API

The QuickMark API is accessed via the player instance.  i.e. player.otvtoolkit().quickmarkInterface 

const quickmark = player.otvtoolkit().quickmarkInterface;
quickmark.setURL("https:\\www.your_service_url.comyour_tenant_idqm\v2surfaces");
console.log("The QuickMark version is: " + quickmark.getVersion());

Disabling QuickMark

Remove QuickMark configuration in the OTVToolkit configuration and reinitialise the otvplayer  object.

Starting and stopping the service (pull mode)

• start()
  This method starts the fetching of the QuickMark Surface.

• stop()
  This method stops the fetching of the QuickMark Surface.

Applying the QuickMark watermark (push mode)

• update(watermark) 
  Passes watermark data as a Uint8Array  to the player for display.

Other methods

An API is provided to dynamically change some parameters after initial configuration and get the QuickMark version.

• getVersion() {returns string}
  This method gets the version of the QuickMark library.
  Return: the version string.

• setApiKey(apiKey)
  This method sets the optional API key of the QuickMark surface server.
  Parameter: apiKey - the QuickMark service API Key.

• setTenant(tenant)
  This method sets the optional tenant in the service URL.
  Parameter: tenant  - the tenant string.

• setToken(token)
  This method sets the token embedded in the QuickMark surface.
  Parameter: token  - the token string

• setURL(URL)
  This method sets the service URL of the QuickMark server.
  Parameter: URL  - a string representing the URL of the QuickMark server

Callbacks

To subscribe to information messages, two callback functions must be defined and set up either at player initialisation time via the configuration options or by the QuickmarkInterface API methods. The callback prototypes are:

• message(message)
  A string that contains message information.

• error(id, message)
id  is the error identifier, message  is the error string.

• tlValidation(tlBuffer) 
  Calculate the signature of the given Uint8Array , and return as a Uint8Array 

To set them via the API:

• setMessageCallback(messageCallback)
  This method sets the callback to receive QuickMark messages.
  Parameter: messageCallback  - the message function callback

• setErrorCallback(errorCallback)
  This method sets the callback to receive QuickMark errors.
  Parameter: errorCallback  - the error function callback

• setTlValidationCallback(tlValidationCallback) 
  This method sets the callback to calculate the watermark signature.
  Parameter: tlValidationCallback - the validation function callback.

Error messages

These are the errors QuickMark may report