Perth: neural audio watermarking in Python

What the library does and who it is aimed at

Perth is described as a comprehensive Python library for audio watermarking and detection. The stated capability is that it enables you to embed imperceptible watermarks in audio files and later detect them, even after the audio has undergone various transformations or manipulations, and the library implements multiple watermarking techniques including neural network-based approaches.

The project comes from Resemble AI, and the repository belongs to the resemble-ai organisation with the project name Perth. The primary language is Python, the licence is MIT, and the package is published on PyPI under the name resemble-perth. The last push to the repository was on 2026-09-02, and the one release listed is v1.0.1 from 2025-05-13, while the pyproject.toml at the root records version 1.1.0.

The keywords in the package metadata describe the intended use more precisely than the README does. Alongside audio watermarking and perceptual watermarking, they list neural audio processing, ai safety, and security, and the classifiers include a Topic for Scientific/Engineering Artificial Intelligence and a Topic for Multimedia Sound/Audio.

That combination points at the use case. A watermark that survives transcoding is useful when you need to trace a piece of audio back to its origin after it has been through an ordinary media pipeline, which is the provenance problem, and the ai safety keyword says plainly that the project intends that framing rather than treating watermarking as a copyright-protection scheme.

Two entry points, and a CLI that does the whole job

Perth exposes the same capability through a command line interface and through a Python API, and the CLI is genuinely usable on its own for the common case.

Installing from PyPI is one command.

pip install resemble-perth

And the two operations are a single flag apart.

# Apply a watermark to an audio file
perth input.wav -o output.wav

# Extract a watermark from an audio file
perth input.wav --extract

The first embeds and writes to a new file, the second reads and reports. That is a complete workflow in two invocations, which is what makes the tool practical to try before committing to the API.

The Python API follows the same two-step shape, with a watermarker object that you initialise once and then use for both embedding and extraction.

import perth
import librosa
import soundfile as sf

# Load audio file
wav, sr = librosa.load("input.wav", sr=None)

# Initialize watermarker
watermarker = perth.PerthImplicitWatermarker()

# Apply watermark
watermarked_audio = watermarker.apply_watermark(wav, watermark=None, sample_rate=sr)

# Save watermarked audio
sf.write("output.wav", watermarked_audio, sr)

The extraction call mirrors it, and the README notes that the same watermarker instance used for embedding is used for detection, which is the expected symmetry.

watermark = watermarker.get_watermark(watermarked_audio, sample_rate=sr)
print(f"Extracted watermark: {watermark}")

One detail in the apply call is worth reading carefully. The watermark argument is passed as None, which means the library generates a watermark rather than embedding a specific one, and the extracted value is then whatever the model produced. For a provenance workflow where you want to tie a specific identifier to a file, that distinction decides whether the design works for you at all, and the README does not describe a separate API for embedding a caller-supplied payload.

Perth-Net Implicit, the dummy watermarker, and the GPU option

The feature list in the README names the Perth-Net Implicit neural network approach as one of the techniques, and the watermarker class that implements it can be constructed with a device.

from perth.perth_net.perth_net_implicit.perth_watermarker import PerthImplicitWatermarker

watermarker = PerthImplicitWatermarker(device="cuda")  # Use GPU for faster processing

The deep import path shows the layout, with the implementation under perth_net within a perth_net_implicit subpackage, and the device argument is the only configuration the README shows. There is no documented threshold, no documented payload size and no documented model checkpoint selection, so the class is meant to be used as a fixed configuration.

There is a second watermarker class, and it exists for a different purpose.

from perth import DummyWatermarker

watermarker = DummyWatermarker()

It is described as a simple placeholder watermarker for testing and demonstration purposes. That is worth taking at face value rather than as a minor feature. A dummy watermarker is what you use in a test suite so that the test does not have to load a neural network, and having one in the public API means the test dependency between your code and Perth is loose enough to stub out. For a library that ships a torch dependency, that is a deliberate and useful affordance, and it is also a signal that the interface is expected to be used by more than one implementation.

The README describes the Perth-Net Implicit watermarker as using a neural network-based approach for embedding and extracting watermarks, designed to be resilient against various audio manipulations while maintaining high audio quality.

Measuring the cost, and the metrics you get back

The library includes utilities for evaluating the quality and robustness of watermarked audio, and the README's example uses two of them: a metrics function and a comparison plot.

import librosa
from perth.utils import calculate_audio_metrics, plot_audio_comparison

# Load original and watermarked audio
original, sr = librosa.load("input.wav", sr=None)
watermarked, _ = librosa.load("output.wav", sr=None)

# Calculate quality metrics
metrics = calculate_audio_metrics(original, watermarked)
print(f"SNR: {metrics['snr']:.2f} dB")
print(f"PSNR: {metrics['psnr']:.2f} dB")

# Visualize differences
plot_audio_comparison(original, watermarked, sr, output_path="comparison.png")

Signal-to-noise ratio and peak signal-to-noise ratio are the two metrics the example prints, both in decibels, and the plot function writes a comparison image to a path you give it.

The dependency list explains why those two metrics are available and what else the project expects around them. The core dependencies are PyYAML, librosa, numpy, pydub, soundfile, torch and torchaudio, so the neural model and the audio I/O are both in the base install, and there is no GPU requirement declared even though the device argument exists.

The extra group is where the measurement tooling comes from, and it is large: Pillow, PyWavelets, bitstring, matplotlib, pandas, praat-parselmouth, pyloudnorm, scikit-learn, sox, tabulate and tensorboard. So an install with the extras pulls in a Praat parser for phonetics and loudness analysis, a Python wrapper around the SoX command line tools, scikit-learn and PyWavelets for signal analysis, and matplotlib and tensorboard for visualisation. The base install is enough to embed and detect; the extras are what make the evaluation and plotting examples run.

There is also a `tools/` directory in the repository, and a `tests/` directory, with pytest as the test runner and pytest-cov for coverage. A `makefile` at the root provides the task entry points, and a `.pre-commit-config.yaml` with ruff as the linter in the dev group, plus a `uv.lock` for reproducible resolution and a `.python-version` file. The Python floor is 3.10, with classifiers through 3.13.

The packaging picture, and what the version numbers say

The packaging metadata is worth reading closely because it has an inconsistency that a consumer will notice.

The project name in pyproject.toml is resemble-perth, and the version recorded there is 1.1.0, while the README's install instructions use pip install resemble-perth, which is consistent. The GitHub release list, however, shows v1.0.1 with the release name Perth Audio Watermarker from 2025-05-13. So the tagged release and the current package version are a minor version apart, and the README does not say which one the pip package currently corresponds to.

The build system is a standard PEP 621 project with a src/ layout, and the authors are listed as Resemble AI plus three individual contributors. The project URLs point at the GitHub repository for the homepage, the documentation and the issue tracker, and the documentation URL resolves to the repository's README rather than to a separate site, which means the README is the documentation.

The repository also has a docs/ directory and an examples/ directory split into basic and advanced, and the example directories are the closest thing to a tutorial in the project. A dependency group named examples adds tqdm, which suggests the examples include long-running loops with progress output.

The one dependency that deserves attention is sox in the extra group, which is the command line audio toolkit. It is used through a Python wrapper, so an installation of the extras needs the sox binary present on the system, and that is a system-level prerequisite rather than something pip can satisfy. The same is true of the parts of librosa that shell out. The base install with torch, torchaudio, soundfile, numpy, pydub and PyYAML is pure Python apart from the torch wheel, which is the practical reason the extras are optional rather than required.

Where Perth is the wrong choice

Three cases point elsewhere. The first is a project that needs a formal reliability claim. The README says the watermarks can survive common audio transformations like compression, resampling and more, and that the library can detect them even after the audio has undergone various transformations or manipulations, but it publishes no detection accuracy per transformation, no false positive rate, and no payload size. A regulatory or legal context that needs a number to point at is not served by this documentation, and the absence of published figures is itself the answer to whether one exists elsewhere.

The second is a project that needs to embed a specific identifier rather than a generated one. The apply call in the README passes watermark=None, and the extracted value is whatever comes out. The library also does not document a payload length, a character encoding, or any API for setting a chosen payload, so if your requirement is that the watermark carry a specific transaction id, that is not established by the documentation here.

The third is a project that must avoid a PyTorch dependency. The neural approach is the core of the library, and torch and torchaudio are base dependencies, so the install is heavy even before the extra group is added. A team that wants a lightweight perceptual watermark on a small service, or that already has a deterministic scheme in place, will find the dependency footprint disproportionate to the task.

The alternative worth weighing is a classical spread-spectrum or echo-based watermark, implemented directly against the samples, and the difference in approach is instructive. A classical scheme has no training, no model checkpoint and no GPU, and its robustness to a given transform is a property you can reason about and tune, at the cost of a much lower detection margin and a payload of a few bits. The neural approach buys robustness and imperceptibility by training a network to hide the signal in a way the model has learned to survive, and pays for it with a torch dependency, an opaque decision about the operating point, and the inability to reason about the failure cases from first principles. If your transforms are known and few, the classical route is defensible and inspectable. If your audio will pass through encoders you do not control, a learned scheme is the one that survives them, and Perth is a usable implementation of that idea with a small enough API to try in an afternoon.

Editorial conclusion

Perth fits a team building provenance tooling for generated or licensed audio that needs a watermark to survive transcoding, and that wants a Python API and a CLI rather than a model to train. It does not fit a project that needs a formal guarantee about detection reliability under adversarial attack, because the README describes the watermarks as surviving common transformations without publishing accuracy figures per transformation, and it does not fit a project that cannot take the PyTorch dependency. Before you adopt it, measure the payload you need against your own transform chain with the utilities in perth.utils, since the quality metrics and the detection rate move in opposite directions and the README does not give you the operating point.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. resemble-ai/Perth on GitHub