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

The Nexguard module jswbw2-min.js is distributed with the player SDK.  If QuickMark is required the module must be included in the HTML file before the SDK file opy-sdk-js-all.js:

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

Theotvplayer 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 further errors may be encountered.

Pull mode example configuration

The QuickMark watermarking feature is enabled by the inclusion of the QuickMark configuration in the OTVToolkit configuration. The configuration options are provided by the application.

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 not suitable, 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 of the watermark.  A full description of such implementation is beyond the scope of this document.

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 which 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 called 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 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 of the parameters after initial configuration and to get the QuickMark version.

• getVersion() {returns string}
  This method gets the version of the QuickMark library.
  Return: the version string.
• setApiKey(apiKey)
  This method set the optional API key of the QuickMark surface server.
  Parameter: apiKey - the QuickMark service API Key.
• setTenant(tenant)
  This method set the optional tenant in the service URL.
  Parameter: tenant  - the tenant string.
• setToken(token)
  This method set 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 set 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