Video Watermarking
Overview
This page covers video-specific features of the DeepMark watermarking API: quality settings that control the robustness/visibility tradeoff, visual comparisons, and supported video formats.
For general API usage (authentication, submitting jobs, downloading results), see the API Key Guide.
Quality Settings
Quality settings let you control the tradeoff between watermark robustness (how well the watermark survives compression, cropping, re-encoding) and visual quality (how invisible the watermark is).
The system automatically selects optimal defaults based on the input video's resolution. You only need to override the parameters you want to change — everything else uses the defaults for your video's resolution tier.
How to pass quality settings
Include quality settings as additional form fields in the POST /client/embed request:
| Field | Description |
|---|---|
quality_mode | Speed/quality tradeoff: fast or precise (optional) |
embed_strength | Watermark strength, 1–10 (optional) |
dark_suppression | Dark region protection, 0.0–1.0 (optional) |
dark_threshold | Dark luminance threshold, 0–255 (optional) |
flat_area_retention | Minimum watermark in flat areas, 0.0–1.0 (optional) |
Example Request (with quality settings)
curl -sS -X POST "https://<your-deepmark-domain>/client/embed" \
-H "X-Client-Api-Key: <your-api-key>" \
-F "file=@/path/to/input.mp4" \
-F "watermark=10101010" \
-F "model=model-id" \
-F "quality_mode=precise" \
-F "embed_strength=4" \
-F "dark_suppression=0.8" \
-F "dark_threshold=80" \
-F "flat_area_retention=0.5"Each parameter has different defaults depending on which resolution tier the input video falls into:
| Tier | Video height | Typical resolutions |
|---|---|---|
| ≤480p | up to 480 pixels | 360p, 480p |
| 480–720p | 481 to 720 pixels | 540p, 720p |
| 720–1080p | 721 to 1080 pixels | 900p, 1080p |
| >1080p | above 1080 pixels | 1440p, 2160p (4K), 2880p (5K) |
Parameters
1. quality_mode
Controls the speed/quality tradeoff for perceptual masking — the process that adapts the watermark to the video content so it is less visible in areas where the human eye is sensitive.
| Value | Behavior |
|---|---|
fast | Perceptual masking runs at a low internal resolution. Fastest processing. Good visual quality for high-resolution inputs where pixel density provides natural cover. |
precise | Perceptual masking runs at the full input resolution. Slower processing. Best visual quality, especially important for low-resolution inputs where every pixel matters. |
Defaults
- ≤720p —
precise(cost is negligible at low resolutions) - >720p —
fast
2. embed_strength
Controls how strongly the watermark signal is blended into the video. This is the primary knob for the robustness vs. visibility tradeoff.
| Range | Effect |
|---|---|
| 1 | Minimum strength. Watermark is barely visible but fragile — may not survive heavy compression or re-encoding. |
| 5 (default) | Balanced. Watermark is imperceptible in most content and survives standard compression workflows. |
| 10 | Maximum strength. Watermark survives aggressive transformations but may produce visible artifacts. |
Range:1 to 10 (integer or decimal). Default: 5 for all resolutions.
3. dark_suppression
Controls how much the watermark is reduced in dark regions of the video. Dark areas have less perceptual headroom to hide the watermark, so without suppression, artifacts become visible as noise or banding in shadows.
| Range | Effect |
|---|---|
| 0.0 | Off. Watermark is applied at full strength everywhere, including dark regions. |
| 0.5 | Moderate. Watermark is reduced by half in regions below the dark threshold. |
| 1.0 | Full suppression. Watermark is completely removed in the darkest regions. |
Defaults by resolution tier
- ≤480p —
0.0 - 480–720p —
0.4 - 720–1080p —
0.6 - >1080p —
0.95
4. dark_threshold
Controls the luminance threshold below which a region is treated as dark for the purposes of dark_suppression. Higher values mean more of the image is considered dark and receives suppression.
| Range | Effect |
|---|---|
| 0 | Only pure black pixels are protected. |
| 40 | Pixels below ~16% brightness are protected. |
| 127 | Pixels below ~50% brightness are protected — roughly the darker half of the image. |
| 255 | The entire image is treated as dark (not recommended — effectively disables the watermark). |
Defaults by resolution tier
- ≤480p —
0 - 480–720p —
40 - 720–1080p —
60 - >1080p —
127
5. flat_area_retention
Controls the minimum watermark strength retained in smooth, flat areas of the video — regions with low texture like sky, walls, gradients, and solid backgrounds.
| Range | Effect |
|---|---|
| 0.0 | Watermark can be fully suppressed in flat areas. Best visual quality in gradient-heavy content, but watermark is very weak in those regions. |
| 0.4 (default) | Watermark is reduced to 40% strength in flat areas. Good balance between visual quality and robustness. |
| 1.0 | No reduction. Flat areas receive the same watermark strength as textured areas. Maximum robustness but artifacts may be visible in skies, walls, and gradients. |
Defaults by resolution tier
- ≤480p —
0.7 - 480–720p —
0.6 - 720–1080p —
0.4 - >1080p —
0.3
Defaults Summary
| Parameter | ≤480p | 480–720p | 720–1080p | >1080p |
|---|---|---|---|---|
quality_mode | precise | precise | fast | fast |
embed_strength | 5 | 5 | 5 | 5 |
dark_suppression | 0.0 | 0.4 | 0.6 | 0.95 |
dark_threshold | 0 | 40 | 60 | 127 |
flat_area_retention | 0.7 | 0.6 | 0.4 | 0.3 |
Visual Comparison
The following videos demonstrate why the system uses content-adaptive quality defaults. All examples use 1080p mountain-landscape source, which is a good worst case — it contains large skies (flat, gradient-heavy regions) and deep shadows on the mountain slopes (dark regions).
Original vs. Optimally Watermarked (1080p)
The watermarked video uses the 720–1080p production defaults:
| Parameter | Value |
|---|---|
quality_mode | fast |
embed_strength | 5 |
dark_suppression | 0.6 |
dark_threshold | 60 |
flat_area_retention | 0.4 |
Wrong Defaults vs. Optimal Defaults (1080p)
The left video forces ≤480p-tier quality parameters onto 1080p content. The right video uses the correct 720–1080p production defaults.
Watermark Delta Visualizations
The videos below visualize the watermark signal itself — what the system adds to each frame. Both are amplified 30× and rendered as white on black. Brighter pixels indicate stronger watermark energy.
Pre-Blend Delta (Intended Signal)
Post-Encode Delta (Actual Pixel Difference)
Video Format and Codec Support
Supported Resolutions
360p up to 5K (2880p).
Watermark Length
The video watermark payload supports up to 256 bits. If the provided watermark is shorter than 256 bits, it is automatically tiled (repeated) to fill the full capacity. Detection recovers the full 256-bit payload and folds it back to the original length via majority voting, which improves detection reliability.
Supported Codecs
- H.264 (AVC)
- H.265 (HEVC)
- AV1
Other codecs (VP8, VP9, etc.) are transcoded to AV1.
Supported Containers
- MP4
- MKV
- MOV
- WEBM
Other containers are not guaranteed to work and may require remuxing before upload.