README.md

---
library_name: transformers
tags:
  - audio
  - watermark
  - watermark-detection
  - provenance
  - vocbulwark
license: cc-by-4.0
---

# VocBulwark watermark detector

Standalone detector for the fixed **50-bit** provenance watermark embedded by the companion VocBulwark vocoder. Given an audio clip, it extracts the watermark bits with the Cage extractor and compares them to the known fixed code, reporting how many bits match.

Self-contained: loads with `trust_remote_code=True`, no training repo required.

## Companion Models

This detector is part of a set of 6 repositories:

| Repo | Role |
|------|------|
| `mlr2000/vocoder-large` | Large vocoder (generates the watermarked audio) |
| `mlr2000/vocoder-large-watermark-detector` | Watermark detector (this repo) |
| `mlr2000/vocoder-large-speaker-encoder` | Speaker encoder for the large model |
| `mlr2000/vocoder-small` | Small vocoder |
| `mlr2000/vocoder-small-watermark-detector` | Watermark detector for the small model |
| `mlr2000/vocoder-small-speaker-encoder` | Speaker encoder for the small model |


## Usage

```python
import torchaudio
from transformers import AutoModel

det = AutoModel.from_pretrained("mlr2000/vocoder-large-watermark-detector", trust_remote_code=True).eval()

wav, sr = torchaudio.load("clip.wav")          # [C, T]
res = det.detect(wav, input_sample_rate=sr)    # resampled to 24 kHz internally
print(res)
# {'matches': 50, 'n_bits': 50, 'p_value': 8.9e-16}
```

See **`example_roundtrip.ipynb`** in this repo for an end-to-end example
(generate with the vocoder → detect here).

## How detection works

`detect()` returns a dict with:

- `matches`: how many of the 50 extracted bits equal the fixed code.
- `n_bits`: 50.
- `p_value`: the probability an *unrelated* clip matches at least this well under
  `Binomial(50, 0.5)`.

A clip generated by our vocoder matches **all 50 bits** (`p_value` ~ 0). An unrelated clip matches about half of them (`p_value` ~ 1). There is no built-in yes/no threshold, read `matches` / `p_value` and pick whatever operating point you need. Requiring all 50 bits gives an astronomically small false-positive rate. Allowing a few mismatches trades that for robustness to lossy channels.

## Robustness

The detector achieves near-perfect bit accuracy (≥ 0.999) against common signal processing attacks including:

- Gaussian noise (SNR ≥ 20 dB)
- High-pass and band-pass filtering
- Amplitude scaling
- Echo addition
- Resampling to 16 kHz
- MP3 compression
- Bit-depth quantization (16-bit and 8-bit)

Performance degrades under extreme transformations such as low-pass filtering at 2 kHz and time stretching, which also severely impact audio quality

## Notes

- Detection runs on **24 kHz mono**. Other inputs are resampled when you pass `input_sample_rate`, and multi-channel audio is downmixed to mono.
- A fixed public watermark is for **attribution** ("did our model make this"), not a secret mark.
- Robustness to compression / resampling should be validated empirically.
- This detector is paired with `mlr2000/vocoder-large`. It will not correctly verify audio generated by the small vocoder (`mlr2000/vocoder-small`), which uses a different fixed watermark.

## Citation

If you use this model, please cite:

```bibtex
@misc{muletta2026,
  title  = {Training a Discriminator-Free Foundation Vocoder 
             with Integrated Audio Watermarking},
  author = {Muletta, Romolo and Deriu, Jan},
  year   = {2026},
  note   = {VT2 Project Report, ZHAW School of Engineering}
}
```

## License

`cc-by-4.0`. Trained on MLS (CC-BY-4.0) and Common Voice (CC0). Builds 
on BigVGAN (MIT) and wav2vec 2.0 (Apache-2.0). Please retain attribution 
when redistributing or building on this model.