Traceless Watermark for Browsers

@traceless-watermark/browser is an image-processing library written in TypeScript for adding and extracting invisible watermarks.

This package uses the DWT-DCT-SVD implementation from ShieldMnt's Python invisible-watermark library and incorporates Reed-Solomon error correction.

Encoding and decoding happen in a Web Worker. WebGPU is used for GPU acceleration when available, with a CPU fallback.

Traceless Watermark also includes libraries for iOS, Android, and Python.

Requirements

• A browser with Web Workers and WebAssembly support.
• A WebGPU-capable browser for optional GPU acceleration.

This package works with JavaScript and TypeScript applications and ships as ES modules.

Usage

import { TracelessWatermark } from "@traceless-watermark/browser";

...

const watermark = new TracelessWatermark();
const watermarkText = "Example watermark";
const encodeResult = await watermark.encodeText(imageFile, watermarkText);

if (encodeResult.success) {
  const watermarkedImage = encodeResult.value;
  const decodeResult = await watermark.decodeText(
    watermarkedImage,
    new TextEncoder().encode(watermarkText).length,
  );

  if (decodeResult.success) {
    console.log(decodeResult.value.payload);
  } else {
    console.log("Decode failed:", decodeResult.error);
  }
} else {
  console.log("Encode failed:", encodeResult.error);
}

API

Traceless Watermark has the following methods used for encoding and decoding watermarks, and all move through a worker to avoid blocking the caller.

Text-based APIs:

encodeText(
  image: Uint8Array | ArrayBuffer | Blob | File,
  text: string,
): Promise<WatermarkResult<Uint8Array, WatermarkEncodeError>>

decodeText(
  image: Uint8Array | ArrayBuffer | Blob | File,
  byteCount: number,
): Promise<WatermarkResult<DecodedPayload<string>, WatermarkDecodeError>>

Byte-based APIs:

encodeBytes(
  image: Uint8Array | ArrayBuffer | Blob | File,
  payload: Uint8Array | readonly number[],
): Promise<WatermarkResult<Uint8Array, WatermarkEncodeError>>

decodeBytes(
  image: Uint8Array | ArrayBuffer | Blob | File,
  byteCount: number,
): Promise<WatermarkResult<DecodedPayload<Uint8Array>, WatermarkDecodeError>>

Encode methods return PNG bytes.

Decode success values contain a DecodedPayload. Use payload for the recovered text or bytes, and correctionUsage for the fraction of the Reed-Solomon correction budget used during recovery.

Options

Options can be set when creating the TracelessWatermark object.

import {
  TracelessWatermark,
  ChannelScales,
  WatermarkBlockSize,
  WatermarkErrorCorrectionLevel,
  WatermarkExecutionMode,
} from "@traceless-watermark/browser";

const watermark = new TracelessWatermark({
  scales: ChannelScales.defaultScales,
  blockSize: WatermarkBlockSize.Four,
  correctionLevel: WatermarkErrorCorrectionLevel.medium,
  executionMode: WatermarkExecutionMode.Gpu,
});

Channel Scales

The scale controls how strongly the watermark is written into each YUV channel.

Using more channels can improve decode reliability, but costs more work.

new ChannelScales(0, 36, 36) // Default values

Higher YUV color scale values improve watermark resilience at the cost of visual artifacting.

Execution Mode

Switch between CPU and GPU environments when performing watermarks.

WatermarkExecutionMode.Cpu
WatermarkExecutionMode.Gpu
WatermarkExecutionMode.Reference

Gpu uses WebGPU in supported browsers and is the default. When WebGPU is unavailable, it falls back to Cpu. Cpu uses WASM when available, then falls back to the TypeScript implementation. Reference always uses the TypeScript implementation.

Error Correction

Error correction levels are provided for better watermark survivability.

WatermarkErrorCorrectionLevel.none
WatermarkErrorCorrectionLevel.low
WatermarkErrorCorrectionLevel.medium
WatermarkErrorCorrectionLevel.quartile
WatermarkErrorCorrectionLevel.high
WatermarkErrorCorrectionLevel.custom(recoveryRate)

The levels mimic QR code error correction levels. The default is medium.

Block Size

Block size controls the squares used for embedding watermark bits.

WatermarkBlockSize.Four
WatermarkBlockSize.Eight

Four is the recommended default. Eight is available for tuning and experiments.

GPU Cold Starts

If you know the image dimensions and payload size in advance, reserve buffers during warmup to reduce GPU cold start latency.

import { TracelessWatermark } from "@traceless-watermark/browser";

const warmUpResult = await TracelessWatermark.warmUp({
  width: 1920,
  height: 1080,
  byteCount: new TextEncoder().encode("Example watermark").length,
});

The reservation uses the default medium correction level unless you supply correctionLevel.

warmUp returns WarmUpResult.Success, WarmUpResult.GpuUnavailable, or WarmUpResult.ReservationTooLarge.

Call TracelessWatermark.cleanUp() when the application is finished with the library to release the shared worker and its resources. This terminates the worker and rejects pending requests.

Image Notes

• Supported encoded image formats are PNG and JPEG; encode methods return PNG bytes.
• Accepted encoded image inputs are Uint8Array, ArrayBuffer, Blob, and File.
• Decode length is the original UTF-8 byte length.
• Resizing, cropping, rotating, taking screenshots, or heavy recompression damages the signal.
• Higher-resolution images increase watermark capacity, but require more processing time and memory.
• Transparent images are not supported due to alpha premultiplication.
• Encoded output file sizes are typically larger than the source images.
• Cross-platform compatibility may still encounter edge cases.
• Currently Traceless Watermark is meant to watermark one image at a time.

Decoding requires the original payload byte count and matching channel scales, block size, and error correction level.

Development

See the repository README for the overview of both JavaScript packages and PLATFORM_DETAILS.md for local setup, the example app, and testing instructions.

License

Apache-2.0. See LICENSE and THIRD_PARTY_NOTICES.md.