Aureal Watermark Documentation

Overview & Architecture

Aureal Watermark is an acoustic spread-spectrum watermark engine written in pure, zero-dependency JavaScript and Node.js. It embeds an invisible recipient ID into master audio recordings. Use the documented tests to evaluate detection after the transformations in your workflow.

CLI Quick Start

Get up and running in seconds. You can generate synthetic speech-like material for testing, embed unique tracking IDs, and verify audio files directly from the command line.

# 1. Synthesize 30 seconds of speech-like audio (no sample file needed)
node bin/auralwatermark.js gen test.wav --seconds 30 --rate 44100

# 2. Embed a 32-bit recipient tracking ID with your secret salt
node bin/auralwatermark.js embed test.wav marked.wav --id 1234567 --key my-secret

# 3. Verify watermark with matched filter detection
node bin/auralwatermark.js detect marked.wav --id 1234567 --key my-secret
# Outputs: detected: YES / confidence: 1.000 / ber: 0.0% / band hit: high/mid

# 4. Blind Detection: Extract embedded ID without providing expected ID
node bin/auralwatermark.js detect unknown.wav --key my-secret --json

CLI Options Reference

gen <output.wav>

Generates harmonic speech-like test audio with envelope modulation to benchmark embedding and detection without external audio files.

embed <in.wav> <out.wav> --id <uint32>

Embeds an imperceptible watermark into an existing uncompressed PCM audio file.

detect <in.wav> [--id <uint32>] [--key <s>]

Scans an audio stream for watermarks. Operates in targeted verification mode (when --id is passed) or blind extraction mode.

Web Audio & Browser DSP

Aureal provides a browser-native verifier (src/browser/aural-watermark-verify.js) that decodes and validates audio directly inside modern web browsers using standard Web Audio APIs.

import { verifyAudioBuffer } from "./src/browser/aural-watermark-verify.js";

// 1. Decode any web-supported format (MP3, AAC, FLAC, WAV, OGG)
const audioContext = new AudioContext();
const response = await fetch("/streamed_audio.mp3");
const arrayBuffer = await response.arrayBuffer();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

// 2. Perform offline sub-second matched filter analysis
const result = verifyAudioBuffer(audioBuffer, 1234567, "my-secret-key");

if (result.detected) {
  console.log(`Watermark Validated! Confidence: ${result.confidence * 100}%`);
  console.log(`Recovered Payload ID: ${result.recoveredPayloadId}`);
} else {
  console.log("No valid watermark detected in audio stream.");
}

Node.js API Reference

Integrate directly into backend audio pipelines, streaming servers, and distribution platforms:

import { embedWatermark, detectWatermark } from "aureal-watermark";
import { readWavFile, writeWavFile } from "aureal-watermark/src/wav.js";

// Read master recording
const wav = await readWavFile("master.wav");
const fmt = { sampleRate: wav.sampleRate, channels: wav.channels };

// Embed tracking signature
const watermarkedPcm = embedWatermark(wav.samples, fmt, {
  payloadId: 987654,
  key: process.env.WATERMARK_SALT,
  strength: 0.5,
  band: "dual"
});

// Write tagged WAV file
await writeWavFile("preview_watermarked.wav", watermarkedPcm, { ...fmt, bitDepth: 16 });

// Verify watermark
const verification = detectWatermark(watermarkedPcm, fmt, {
  payloadId: 987654,
  key: process.env.WATERMARK_SALT,
  band: "auto"
});

console.log(verification);
// { detected: true, confidence: 1.0, ber: 0.0, zScore: 14.2, frameCount: 30 }

Supported Formats & PCM

The core engine reads and writes uncompressed PCM WAV data, including 16-bit and 24-bit integer samples, mono through multichannel layouts, WAVE_FORMAT_EXTENSIBLE headers, and chunk padding. Compressed input is decoded first: the browser tools accept MP3, AAC, M4A, OGG, and FLAC through the Web Audio API before embedding or scanning.

Human Auditory System (HAS) Masking

Conventional audio watermarking methods rely on simple metadata tags or naive ultrasonic chirps (> 20 kHz). However, consumer audio encoders (MP3, AAC, Opus) immediately filter out high frequencies and strip ID3 headers during transcoding.

Aureal solves this by embedding directly into the audible frequency spectrum, strictly constrained below the biological inaudibility envelope of human hearing:

Direct Sequence Spread Spectrum (DSSS)

Rather than placing watermark energy in a few concentrated frequencies, Aureal uses an orthogonal pseudo-random noise sequence to spread the 32-bit payload across thousands of frequency bins:

• The energy per frequency bin is tens of decibels lower than ambient acoustic noise.
• Recovery after lossy compression depends on the audio, codec, bitrate, and subsequent processing; test the formats used in your own delivery chain.
• A decoder with the matching key is required to recover the embedded payload in the current design.

Payload & Error Correction

Each watermark carries a 32-bit recipient ID plus a 16-bit CRC-16/CCITT-FALSE check, transmitted as 48 BPSK symbols. Every symbol is spread with its own key-derived pseudorandom chip sequence and repeated once per frame (~1 second) across the whole track; the detector folds all repetitions together, so detection confidence grows with track length.

Before CRC validation, the detector attempts reliability-ordered soft-decision correction: a 1-bit flip sweep followed by a 2-bit permutation sweep over the lowest-confidence symbols, repairing up to two flipped bits per codeword. Heavier damage after aggressive transcoding is reported as a failed detection rather than a false match. The CRC gate helps reject corrupted payloads; false-positive rates have not been characterized on a representative production corpus.

Watermark Detection Audit Reports

Aureal can export an audit report containing hashes of the analyzed file, watermark-detection metrics, and an HMAC-SHA256 integrity seal. These values can help document a particular scan but do not independently establish authorship, prove when the file existed, or provide a chain of custody.

File Hashes & Report Integrity Seal

For documentation purposes, the forensic engine hashes the evidence file with SHA-256 and SHA-512, captures low-level physical-layer DSP metrics (processing gain \(E_b/N_0\), bit error rate, Z-score significance), and can include an HMAC-SHA256 shared-secret integrity seal. HMAC is not a digital signature and does not establish chain of custody or authorship.

# Scan an audio file and export a hash-and-detection audit report
auralwatermark detect leak_screener.mp3 \
  --report forensic_proof.json \
  --report-txt forensic_certificate.txt \
  --key "studio-master-salt"

Sample Audit Report (Illustrative)

The following is an illustrative sample, not a certification of admissibility, authorship, or chain of custody:

==============================================================================
              AUREAL WATERMARK — SAMPLE AUDIT REPORT               
               Watermark Detection Metrics (Illustrative)                
==============================================================================
Date/Time (UTC) : 2026-09-14T12:00:00.000Z
Engine          : Aureal Watermark Forensic DSP Engine v0.2.5
Report Schema   : v1.0.0
------------------------------------------------------------------------------
1. TARGET EVIDENCE FILE
   Path         : unreleased_screener_leak.mp3 (Lossy 128 kbps Rip)
   Size         : 3,452,192 bytes
   SHA-256      : 7dafa0b0c58327ed539a87b78ead6c632007b9dff869849489bef82b2cb1c293
   SHA-512      : 82b16b5068978739e3fbb5d4e1a11a7bcb14100342f5b2f1...
------------------------------------------------------------------------------
2. FORENSIC VERIFICATION RESULT
   Result       : [WATERMARK ID MATCH]
   Detected     : YES
   Payload ID   : #928401 (Recipient: Zane Lowe / BBC Radio 1)
   Confidence   : 100.0%
   Bit Error Rate: 0.00% (0/48 bits)
   CRC Integrity: VALID (OK)
------------------------------------------------------------------------------
3. PHYSICAL-LAYER DSP METRICS
   Eb/N0        : +14.13 dB (Signal-to-Noise Processing Gain)
   SQNR         : +17.14 dB
   Z-Score      : 33.49 (Correlation Significance)
   Carrier Band : 8000 - 19500 Hz (Dual-Band DSSS Rake)
   Sync Method  : Preamble Cyclic Modulo Fold
------------------------------------------------------------------------------
4. INTEGRITY SEAL
   Algorithm    : HMAC-SHA256
   Seal Hash    : 9702c8625046347512fe23df534257be752512a650fd8ed072b6aa90d814356b
==============================================================================
Attribution: Illustrative sample output only; a watermark match does not independently prove ownership or legal attribution.
==============================================================================

Commercial Licensing & Enterprise SLAs

Aureal Watermark offers commercial production licenses and custom enterprise deployment models:

For complete licensing terms, procurement details, and enterprise SLAs, visit the Commercial Licensing & Pricing Page →

Local Processing & Deployment

The DSP embed/detect operations run locally: CLI processing uses the local machine and the web Studio processes audio in the browser. Optional license activation contacts Polar.sh. Hosting and any external assets may generate normal network traffic.

For air-gapped deployments, review the exact bundle, configuration, and license workflow you intend to use, and test it with network access disabled before processing sensitive audio.

Transcode Survival Tests

Watermark recovery depends on the source audio, carrier band, encoder settings, and any transformations applied to the copy. Use the Studio verifier to evaluate your own workflow rather than treating a single result as a universal guarantee.