Spaces:
Running
Running
| title: LTMarX | |
| emoji: 🎬 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # LTMarX — Video Watermarking | |
| Imperceptible 32-bit watermarking for video. Embeds a payload into the luminance channel using DWT/DCT transform-domain quantization (DM-QIM) with BCH error correction. | |
| Survives re-encoding, rescaling, brightness/contrast/saturation adjustments, and cropping up to ~20%. | |
| All processing runs in the browser — no server round-trips needed. | |
| ## Quick Start | |
| ```bash | |
| npm install | |
| npm run dev # Web UI at localhost:5173 | |
| npm test # Run test suite | |
| ``` | |
| ## CLI | |
| ```bash | |
| npx tsx server/cli.ts embed -i input.mp4 -o output.mp4 --key SECRET --preset moderate --payload DEADBEEF | |
| npx tsx server/cli.ts detect -i output.mp4 --key SECRET | |
| npx tsx server/cli.ts presets | |
| ``` | |
| ## Docker | |
| ```bash | |
| docker build -t ltmarx . | |
| docker run -p 7860:7860 ltmarx | |
| ``` | |
| ## Architecture | |
| ``` | |
| core/ Pure TypeScript watermark engine (isomorphic, zero platform deps) | |
| ├── dwt.ts Haar DWT (forward/inverse, multi-level) | |
| ├── dct.ts 8×8 DCT with zigzag scan | |
| ├── dmqim.ts Dither-Modulated QIM (embed/extract with soft decisions) | |
| ├── bch.ts BCH(63,36,5) over GF(2^6), Berlekamp-Massey decoding | |
| ├── crc.ts CRC-4 integrity check | |
| ├── tiling.ts Periodic tile layout + autocorrelation-based grid recovery | |
| ├── masking.ts Perceptual masking (variance-adaptive quantization step) | |
| ├── keygen.ts Seeded PRNG for dithers and permutations | |
| ├── embedder.ts Y-plane → watermarked Y-plane | |
| ├── detector.ts Y-plane(s) → payload + confidence | |
| ├── presets.ts Named configurations (light → fortress) | |
| └── types.ts Shared types | |
| web/ Frontend (Vite + React + Tailwind) | |
| ├── src/ | |
| │ ├── App.tsx | |
| │ ├── components/ | |
| │ │ ├── EmbedPanel.tsx Upload, configure, embed, download | |
| │ │ ├── DetectPanel.tsx Upload, detect, display results | |
| │ │ ├── ComparisonView.tsx Side-by-side / difference viewer | |
| │ │ ├── RobustnessTest.tsx Automated attack battery (re-encode, crop, etc.) | |
| │ │ ├── HowItWorks.tsx Interactive explainer with D3 visualizations | |
| │ │ ├── StrengthSlider.tsx Preset selector with snap points | |
| │ │ ├── ResultCard.tsx Detection result display | |
| │ │ └── ApiDocs.tsx Inline API reference | |
| │ ├── lib/ | |
| │ │ └── video-io.ts Frame extraction, encoding, attack simulations | |
| │ └── workers/ | |
| │ └── watermark.worker.ts | |
| └── index.html | |
| server/ Node.js CLI + HTTP API | |
| ├── cli.ts CLI for embed/detect | |
| ├── api.ts HTTP server (serves web UI + REST endpoints) | |
| └── ffmpeg-io.ts FFmpeg subprocess for YUV420p I/O | |
| tests/ Vitest test suite | |
| ``` | |
| **Design principle:** `core/` has zero platform dependencies — it operates on raw `Uint8Array` Y-plane buffers. The same code runs in the browser (via Canvas + ffmpeg.wasm) and on the server (via Node.js + FFmpeg). | |
| ## Watermarking Pipeline | |
| ### Embedding | |
| ``` | |
| Y plane → 2-level Haar DWT → HL subband → periodic tile grid → | |
| per tile: 8×8 DCT blocks → select mid-freq zigzag coefficients → | |
| DM-QIM embed coded bits (with per-block dithering and perceptual masking) → | |
| inverse DCT → inverse DWT → modified Y plane | |
| ``` | |
| ### Payload Encoding | |
| ``` | |
| 32-bit payload → CRC-4 append → BCH(63,36,5) encode → keyed interleave → | |
| map to DCT coefficients across tiles (with wraparound redundancy) | |
| ``` | |
| ### Detection | |
| ``` | |
| Y plane(s) → DWT → HL subband → tile grid → | |
| per tile: DCT → DM-QIM soft extract → | |
| soft-combine across tiles and frames → keyed de-interleave → | |
| BCH soft decode → CRC verify → payload | |
| ``` | |
| ### Crop-Resilient Detection | |
| When the frame has been cropped, the detector doesn't know the original tile grid alignment. It searches over three alignment parameters: | |
| 1. **DWT padding** (0–3 per axis) — the crop may break DWT pixel pairing | |
| 2. **DCT block shift** (0–7 per axis) — the crop may misalign 8×8 block boundaries within the subband | |
| 3. **Tile dither offset** (0–N per axis) — the crop shifts which tile-phase position each block maps to | |
| The total search space is 16 × 64 × N² candidates (~37K for the strong preset). To make this fast: | |
| - DCT coefficients are precomputed once per (pad, shift) combination using only tile 0 | |
| - Dither offsets are swept cheaply using just DM-QIM re-extraction on cached coefficients | |
| - Candidates are ranked by signal magnitude (sum of squared averaged soft bits) | |
| - Only the top 50 candidates are fully decoded with all frames | |
| This runs in ~1 second for 32 frames on a 512×512 video. | |
| ## Presets | |
| | Preset | Delta | Tile Period | Zigzag Positions | Masking | Use Case | | |
| |--------|-------|-------------|------------------|---------|----------| | |
| | **Light** | 50 | 256px | 3–14 (mid-freq) | No | Near-invisible, mild compression | | |
| | **Moderate** | 62 | 240px | 3–14 (mid-freq) | Yes | Balanced with perceptual masking | | |
| | **Strong** | 110 | 208px | 1–20 (low+mid) | Yes | Heavy re-encoding, rescaling, cropping | | |
| | **Fortress** | 150 | 192px | 1–20 (low+mid) | Yes | Maximum robustness | | |
| All presets use BCH(63,36,5) with CRC-4 and 2-level DWT. | |
| Higher delta = stronger embedding = more visible artifacts but better survival under attacks. The "strong" and "fortress" presets use more DCT coefficients (zigzag positions 1–20 vs 3–14) for additional redundancy. | |
| ## Robustness | |
| The web UI includes an automated robustness test battery. Each test applies an attack to the watermarked video and attempts detection: | |
| | Attack | Variants Tested | | |
| |--------|----------------| | |
| | **Re-encode** | CRF 23, 28, 33, 38, 43 | | |
| | **Downscale** | 25%, 50%, 75%, 90% | | |
| | **Brightness** | -0.2, +0.2, +0.4 | | |
| | **Contrast** | 0.5×, 1.5×, 2.0× | | |
| | **Saturation** | 0×, 0.5×, 2.0× | | |
| | **Crop** | 5%, 10%, 15%, 20% (per side) | | |
| ## API | |
| ### Embedding | |
| ```typescript | |
| import { embedWatermark } from './core/embedder'; | |
| import { getPreset } from './core/presets'; | |
| const config = getPreset('moderate'); | |
| const result = embedWatermark(yPlane, width, height, payload, key, config); | |
| // result.yPlane: watermarked Y plane (Uint8Array) | |
| // result.psnr: quality metric (dB) | |
| ``` | |
| ### Detection | |
| ```typescript | |
| import { detectWatermarkMultiFrame } from './core/detector'; | |
| import { getPreset } from './core/presets'; | |
| const result = detectWatermarkMultiFrame(yPlanes, width, height, key, config); | |
| // result.detected: boolean | |
| // result.payload: Uint8Array | null | |
| // result.confidence: 0–1 | |
| ``` | |
| ### Crop-Resilient Detection | |
| ```typescript | |
| const result = detectWatermarkMultiFrame( | |
| yPlanes, width, height, key, config, | |
| { cropResilient: true } | |
| ); | |
| ``` | |
| ### Auto-Detection (tries all presets) | |
| ```typescript | |
| import { autoDetectMultiFrame } from './core/detector'; | |
| const result = autoDetectMultiFrame(yPlanes, width, height, key); | |
| // result.presetUsed: which preset matched | |
| ``` | |
| ## HTTP API | |
| ``` | |
| POST /api/embed { videoBase64, key, preset, payload } | |
| POST /api/detect { videoBase64, key, preset?, frames? } | |
| GET /api/health → { status: "ok" } | |
| ``` | |
| ## Testing | |
| ```bash | |
| npm test # Run all tests | |
| npm run test:watch # Watch mode | |
| ``` | |
| 25 tests across 6 files covering: DWT round-trip, DCT round-trip, DM-QIM embed/extract, BCH encode/decode with error correction, CRC append/verify, full embed-detect pipeline across presets, false positive rejection (wrong key, unwatermarked frame), crop-resilient detection (arbitrary offset and ~20% crop). | |
| ## Browser Encoding | |
| The web UI encodes watermarked video using ffmpeg.wasm (x264 in WebAssembly). To avoid memory pressure, frames are encoded in chunks of 100 and concatenated at the end. Peak memory stays proportional to chunk size rather than scaling with video length. | |