Traceless Watermark for Node.js

@traceless-watermark/node 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 Node.js worker thread using the CPU implementation. This package does not support WebGPU acceleration.

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

Requirements

• Node 22 or later.

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

Usage

import { readFile, writeFile } from "node:fs/promises";
import { TracelessWatermark } from "@traceless-watermark/node";

...

const watermark = new TracelessWatermark();
const watermarkText = "Example watermark";
const imageBytes = await readFile("input.png");

const encodeResult = await watermark.encodeText(imageBytes, watermarkText);

if (encodeResult.success) {
  await writeFile("watermarked.png", encodeResult.value);

  const decodeResult = await watermark.decodeText(
    encodeResult.value,
    Buffer.byteLength(watermarkText, "utf8"),
  );

  if (decodeResult.success) {
    console.log(decodeResult.value.payload);
  }
} 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/node";

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

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

Choose the CPU or reference implementation when performing watermarks.

WatermarkExecutionMode.Cpu
WatermarkExecutionMode.Gpu
WatermarkExecutionMode.Reference

Cpu uses WASM when available, then falls back to the TypeScript implementation. Reference always uses the TypeScript implementation. The shared API defaults to Gpu, but Node.js has no WebGPU backend and falls back to CPU execution; the example above selects Cpu explicitly.

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

This package does not support GPU execution in Node.js. The shared TracelessWatermark.warmUp() API reports WarmUpResult.GpuUnavailable; no GPU buffer reservation is needed.

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

• Node.js Buffer inputs are supported because Buffer extends Uint8Array.
• 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.