Skip to content

DoveRunner Distributor Watermarking Guide

DoveRunner Distributor Watermarking is a watermarking solution to track the illegally leaked content when a video content is distributed through multiple channels.

DoveRunner Distributor Watermarking inserts the channel information to the original video in the form of an invisible watermark, and can detect the watermark information from the leaked video as well as a single video frame captured using any device such as a mobile camera. It also provides an option to insert an additional Visible Watermark.

There is a CLI (Command Line Interface) tool used for the watermark embedding in DoveRunner DWM as follows.

  • DWM PreEmbedder: Used to embed the watermark for the distribution channel into Mezzanine or MP4 format files.

It can be easily integrated for secure content distribution in pre-release workflows.

This document is based on DWM PreEmbedder version 3.6.1.

DoveRunner DWM application workflow is as shown below.

DoveRunner DWM Workflow

  1. Input the original video along with the information of the distribution channels into DWM PreEmbedder.
  2. DoveRunner DWM server issues a unique DWM ID for each channel through API integration with the DWM PreEmbedder.
  3. DWM PreEmbedder creates videos with unique watermarks as many as the number of channels to be distributed.
  4. Deliver the corresponding DWM video to each distribution channel.
  5. In the event of a content leak, post the content on downloadable link and register it on DoveRunner Console for detection service.
  6. DoveRunner service extracts the watermark in the leaked copy and delivers the channel information (Distributor ID) to the customer.

DoveRunner DWM supports the below specifications.

ItemSpecificationRemarks
Content TypeSupports video contents only
Format and codecMP4(H.264, H.265, VP9), MOV(ProRes, XDCAM), MXF(XDCAM)
Supported ResolutionUp to 4K/UHD resolution
Dynamic RangeSDR (Standard Dynamic Range), HDR (High Dynamic Range) supported
Number of DWM IDDepending on DoveRunner DWM service plan
Minimum Video LengthNeed at least 30 seconds of recorded video to detect watermarkCannot support source video shorter than 30 seconds
Video Quality for DetectionNeed 480p 1Mbps or higher video quality for detection.720p video is recommended.
Single Frame DetectionIf there is only single frame captured of watermarked content then original frame required for detectionNon-blind detection technique

This video is a tutorial for applying DoveRunner Distributor Watermarking to contents.

For DWM embedding and detection, you firstly need to register recipients who will receive watermarked content. The number of recipient vary depending on the DoveRunner DWM service plan. You can register up to 1,000 recipients in the Startup plan, and more than 1,000 recipients in higher plans. A serial number for each recipient is given as a DWM ID in the order of registration.

The recipient name must be unique and can only contain English letters (uppercase and lowercase), decimal numbers, hyphens (-), underscores (_), and periods (.). No other special characters such as @, #, $, % etc supported. However, the system treats recipient names in a case-insensitive manner. This means that if you register Test, you cannot register variations like TEST or test as separate recipient names. Similarly, when using a DWM ID, regardless of the case used in the request (e.g., test), the system will utilize the DWM ID associated with the originally registered recipient name (e.g., Test).

To register DWM recipients, select the DWM recipient item in the Distributor Watermarking menu of DoveRunner Console. You can register a recipient by entering the name and description on the screen after clicking the Register button. (Click the + button when registering multiple items)

When inserting a watermark through DWM PreEmbedder, you may enter the name of the recipient in the job information, then the recipient’s DWM ID (serial number) is inserted as watermark data in the output video.

DoveRunner DWM PreEmbedder is a Linux CLI (Command Line Interface) based DWM embedding tool. It receives the original video and DWM ID information and outputs the DWM video with the corresponding ID.

When using the DWM PreEmbedder executable file alone, the customer must directly manage the DWM ID and distribution channel information without the use of DoveRunner server. For server integration, DWM embedding should be performed through a Python script distributed along with the core executable file.

You can request DoveRunner DWM PreEmbedder after subscribing to DoveRunner Distributor Watermarking service, and is composed as follows:

  • DwmEmbedder: It is an executable file which is a core module executed by the Python script below. It inserts a unique watermark (DWM ID) in the original video for each distribution target channel. Please don’t directly execute this file for watermark embedding as it would lead to detection failure.

  • DwmPreEmbedder.py: This is a Python script in charge of communication between DwmEmbedder and the DoveRunner server. DWM embedding should be done only through this script and not the above core module.

  • dwm_info.json: This is a file to input embedding job information such as the original video and output file to insert the DWM ID, and information of recipients.

  • Library files: In the lib folder, there are various libraries used by the DWM Embedder.

  • demokey.dat: This is a demo version key file used for DWM embedding in a trial account. In addition to the invisible watermark (DWM ID), Visible Watermarks (‘DRWM DEMO’ string and DoveRunner logo image) will be added in the video preprocessed with the demo key.

You need the following environment to run the DWM PreEmbedder.

Hardware

Software

  • Ubuntu 18.04, 20.04, 22.04, or 24.04
    • Support for Ubuntu 18.04 will end in October 2025.
    • Support for Ubuntu 20.04 will end in April 2026.
  • NVIDIA CUDA Toolkit 11.1 or later (NVIDIA hardware acceleration)
  • Dependencies

It requires CUDA Toolkit 11.1 or above. You can also install the latest version if there are no compatibility issues with your other programs. If you need to install other CUDA Toolkit version, please refer latest download or archive. This document guides the minimum version that satisfies the requirements.

  • Installing on Ubuntu 18.04 / 20.04

    $ distribution=$(. /etc/os-release;echo $ID$VERSION_ID|tr -d '.')
    $ wget https://developer.download.nvidia.com/compute/cuda/repos/${distribution}/x86_64/cuda-${distribution}.pin
    $ sudo mv cuda-${distribution}.pin /etc/apt/preferences.d/cuda-repository-pin-600
    $ wget https://developer.download.nvidia.com/compute/cuda/11.1.1/local_installers/cuda-repo-${distribution}-11-1-local_11.1.1-455.32.00-1_amd64.deb
    $ sudo dpkg -i cuda-repo-${distribution}-11-1-local_11.1.1-455.32.00-1_amd64.deb
    $ sudo apt-key add /var/cuda-repo-${distribution}-11-1-local/7fa2af80.pub
    $ sudo apt-get update
    $ sudo apt-get -y install cuda
    $ rm cuda-repo-${distribution}-11-1-local_11.1.1-455.32.00-1_amd64.deb
    $ sudo reboot
  • Installing on Ubuntu 22.04 / 24.04

    Terminal window
    $ dist_ver=$(. /etc/os-release;echo $VERSION_ID|tr -d '.')
    $ cuda_ver=$(case "$dist_ver" in 2204) echo 11-7 ;; 2404) echo 12-5 ;; esac)
    $ keyring=cuda-keyring_1.1-1_all.deb
    $ wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu${dist_ver}/x86_64/${keyring}
    $ sudo dpkg -i ${keyring} && rm ${keyring}
    $ sudo apt-get update
    $ sudo apt-get -y install cuda-${cuda_ver}
    $ sudo reboot
  • Installing on AWS Linux2

    • Please refer to this link
  • Verification

    $ nvidia-smi
  • References

  • Ubuntu 18.04

    $ sudo apt update
    $ sudo apt install -y \
    libva-drm2 \
    libvdpau1 \
    libmediainfo0v5 \
    libpng16-16
    $ sudo apt install -y python3 python3-pip
    $ python3 -m pip install requests
  • Ubuntu 20.04, 22.04, 24.04

    Terminal window
    $ sudo apt update
    $ sudo apt install -y \
    libnuma1 \
    libva-drm2 \
    libvdpau1 \
    libmediainfo0v5 \
    libpng16-16
    $ sudo apt install -y python3 python3-pip
    $ python3 -m pip install requests

After unpacking the DWM PreEmbedder distribution in the execution environment prepared through the above installation process, check if there are related files (core executable, Python script, dwm_info.json, key file, etc.) in the bin folder. After that, you can insert the DWM ID into the original video by running DWM PreEmbedder with the steps below.

In order to communicate with DoveRunner DWM server, a credential file should be created with Site ID, Site Key, and Access Key information. Save these values as ~/.doverunner/credentials file in the following format.

site_id=YOUR_SITE_ID
site_key=YOUR_SITE_KEY
access_key=YOUR_ACCESS_KEY

The actual values to be entered in the credentials file can be checked on the Distributor Watermarking > DWM Settings screen after logging in to DoveRunner Console.

Update the dwm_info.json file, which is the DWM job information file, referring to the example and description below.

{
"account_id": "your_account_id",
"content_id":"contentid_test",
"input": "input.mp4",
"output": "output.mp4",
"visible_watermark": {
"type": "none",
"image": {
"filename": "watermark.png"
},
"alpha": 0.3,
"position": [
{ "x": 200, "y": 100},
{ "x": 300, "y": 200}
],
"timing": {
"interval": "00:05:00",
"disappear": "00:01:00"
}
},
"recipients": [
"recipient 1",
"recipient 2",
"recipient 3"
]
}
  • account_id: Your DoveRunner Account ID shown on the console.
  • content_id: Unique ID for the original contents.
  • input: The source file name to embed the DWM ID.
  • output: The target file name to save the DWM-embedded result file.
    • Distribution information (recipient name, DWM ID) is appended after the file name.
  • visible_watermark: “visible” watermark to the output file. (optional)
    • In addition to the invisible DWM ID information, an image watermark can be displayed on the video.
    • You may omit this keyword and its subitems if you don’t want to add Visible Watermark.
    • For detailed options that can be entered, please refer to the separate description below.
  • recipients: list of recipients.
    • Enter the name of recipient who will receive the DWM applied video.
    • Only recipient names registered in DoveRunner Console in advance can be entered.

The DWM job details mentioned above are sent to the DWM server API using a Python script. Consequently, the server returns the DWM IDs, which are then incorporated into the output video as an invisible watermark through the core module.

During the DWM trial, the demo key file (demokey.dat) included with the distribution is used instead of the commercial version key file. In this case, run it by adding the --demo parameter along with the dwm_info.json file name as follows.

$ python3 DwmPreEmbedder.py dwm_info.json --demo

After subscribing to the DWM commercial plan, request the commercial key file (dwmkey.dat) via HelpDesk and copy it to the bin directory, that is, to the same location as DwmPreEmbedder.py. The commercial version runs without the --demo parameter as follows:

$ python3 DwmPreEmbedder.py dwm_info.json

Visible Watermark configuration (optional)

Section titled “Visible Watermark configuration (optional)”

By default, DWM PreEmbedder invisibly embeds a unique DWM ID for each distribution channel into the video. If you want to add a Visible Watermark to the video, you can set the following options in the visible_watermark item of the dwm_info.json file. A single visible watermark can be integrated. You are limited to using just one image file, and only one watermark can be presented simultaneously.

KeyTypeMandatoryDescriptionExample
typeStringYType of Visible Watermark. “image” to embed image watermark as follow settings, “none” to do not embed any Visible Watermark.”type”: “image”
imageStringYOptions for image type watermark. Not used for text type watermark.
filenameStringYFile path of watermark image.”image_file”: ”~/watermark.png”
alphaFloatNOpacity of Visible Watermark. It allows 1.0 (opaque) ~ 0.01 (transparent). (default: 1)“alpha”: 0.5
positionObject arrayNOptions for watermark positioning. If multiple values are set, the values cycle according to the interval.
x, yIntegerNX, Y position of the watermark (default: 0,0)[{"x": 200, "y": 100}]
timingObjectNOptions for showing/hiding watermark periodically (watermark interval)
intervalStringNPeriod to display a watermark in the format of ‘HH:MM:SS’ (default: unlimited, no repetition)When it is “00:05:00”, it is displayed every 5 minutes and then disappears after the value of disappear.
disappearStringNTime until disappearance after displayed in the format of ‘HH:MM:SS’When it is “00:01:00”, the watermark disappears after 1 minute after every interval.

The image size is up to 5% of the screen resolution. If the image size exceeds 5% of the screen resolution, it will not be automatically resized and embedding will fail. If the video resolution is 1920x1080 px, 300x300 px (4.34%) and 500x200 px (4.82%) images can be embedded, but 400x300 px (5.79%) and 1000x110 px (5.3%) images cannot be embedded.

The image must be fully positioned within the screen without any portion being cut off. If any part of the image is truncated due to the position setting, it will be automatically adjusted to fit inside the screen boundaries.

For instance, if you configure “interval”: “00:05:00”, “disappear”: “00:01:00”, the watermark will appear and disappear in a cyclic pattern every 5 minutes. This means it will display for 1 minute and then remain hidden for 4 minutes.

If “disappear” is set without “interval”, the watermark will vanish after a single display and won’t reappear. Essentially, it can be shown only once for a specified duration. Additionally, the Visible Watermark cannot simultaneously appear in two locations. Instead, a new location is determined by the “interval” before the watermark vanishes as per the “disappear” setting, causing the existing watermark to disappear. In such cases, the value of “disappear” is disregarded, even if set to 0.

You can review the DWM embedding information transmitted to the server in the DoveRunner console.

In the Distributor Watermarking > DWM packaging history screen, you can inquire the recipient information entered in the dwm_info.json.

Error CodeStatusCauseSolution
D0000Success--
D0001Undefined DwmEmbedder errorUndefined DwmEmbedder error occurs.Contact us with displayed message.
D0002Not enough memoryInsufficient system memory.Terminate unnecessary processes and retry again.
D0010User canceledInterrupted/canceled by user such ac Ctrl + C.-
D0030Access key mismatchedAccess key does not match key file.Set valid access key for key file.
D0031No key fileThe key file does not exist.Set valid key file name.
D0043Invalid output pathThe output path is not writable.Set writable output file path.
D0054Invalid input fileThe input file has no video track.Retry with input file which contains video track.
D0055Invalid input fileThe video length should be more than 30 sec.Retry with different file with length greater than 30sec.
D0137SIGKILL receivedSIGKILL recevied from user or system.-
D0200Encoder not foundThere is no valid video encoder.Reinstall valid video encoder.
D0201Decoder not foundThere is no valid video decoder.Reinstall valid video decoder.
D0220Restricted codecThe video codec is restricted or not supported.Check supported codecs.
D0301Invalid config fileThe config file is not valid JSON format.Check config file.
D0302No credential fileThe credential file does not exist.Set valid credential file name.
D0303Invalid credential fileThe credential file does not contain some mandatory data.Check credential file.
D0304Incorrect credential data lengthThe length of some data in the credential file is incorrect.Check credential data and length in file.
D0305No job fileThe job file does not exist.Set valid job file name.
D0306Invalid job fileThe job file is not valid JSON format.Check job file.
D0307Account id not setThe account id is mandatory but not set.Set account id by job file.
D0308Content id not setThe content id is mandatory but not set.Set content id by job file or command line.
D0309Input file not setThe input file is mandatory but not set.Set input filename by job file or command line.
D0310Output file not setThe output file is mandatory but not set.Set output filename by job file or command line.
D0311Recipients not setThe recipients are mandatory but not set.Set recipients by job file.
D0312No input fileThe input file does not exist.Set valid input filename.
D0313Invalid input/output typeThe input and output must be filenames with extension.Set valid input/output filenames with extension.
D0314Mismatched extensionsThe extensions of the input and output files do not match.Match input/output file extensions (container).
D0315Invalid output pathThe output path is invalid.Set valid and writable output path.
D0316Invalid visible watermarkThe visible watermark syntax is invalid.Set valid visible watermark syntax.
D0317No visible watermark fileThe visible watermark input file does not exist.Set valid visible watermark input filename.
D0321Invalid DWM-API Server stateSome DWM-API Server is called while it is not ready.If you have changed the script, restore it.
D0322Invalid request parameterSome DWM-API Server parameter is invalid.If you have changed the script, restore it.
D0323DWM-API Server failedDWM-API Server does not respond correctly.Contact us and retry later.
D0324Invalid response formatDWM-API Server response is invalid JSON or some mandatory data is absent.Contact us with error code and response message.
D0325DWM-API Server errorDWM-API Server responds an error code.Contact us with error code and response message.
D0326Wrong content id in responseDWM-API Server response contains wrong content id.Contact us with error code and response message.
D0331No DwmEmbedder executableThe DwmEmbedder executable does not found.Re-extract software package file.
D0332Invalid internal statusInvalid internal status.Contact us with displayed message. If you have changed the script, restore it.
D0401Undefined DwmPreEmbedder errorUndefined DwmPreEmbedder error occurs.Contact us with displayed message.
AxxxxDWM-API Server errorDWM-API Server responds an error code.Refer DWM-API Server guide at online docs.

If a video with DWM applied is leaked and distributed illegally, you can request the DoveRunner service to detect a watermark on the video that is suspected of being leaked. To request watermark detection, register the title and download link of the video on the DWM detection request page of the DoveRunner Console.

DWM detection analyzes each frame of the video to detect the original watermark pattern and decrypts the data with the secret key used at the time of insertion. If a DWM ID is found through the detection process, we find the distribution channel(recipient) information in our database and report it as the detection result.

If a single frame of the DWM applied video is illegally distributed even that can be detected using our detection service but for that the original non-watermarked video is required as it is based on non-blind technology.

sequenceDiagram
    participant A as Service site
    participant B as DoveRunner service
    A ->> B: Suspicious content
    Note right of B: Detect watermark
    B -->> B: Analyze video frames
    opt DWM ID detected
    Note right of B: DWM recipients DB
    B -->> B: Find the recipient data
    end
    B ->> A: Report detection result

Please contact us for detailed information on watermark detection such as monitoring service.

This product adds some code to FFmpeg libavformat (LGPL). Please contact us for more details.

Contact Us