Marking

Cobalstamp adds watermarks to audio (marking) and finds watermarks in audio (detection). Marking embeds the watermark locally on your machine and registers the mark on the server. Detection sends the audio to the server, which looks for registered marks in it.

Both operations work with mono or multichannel audio as a numpy array of type float32 (or float64 for cobalstamp.mark()), with amplitudes in [-1, 1].

Minimal example

import numpy as np
import soundfile
import cobalstamp

# Load the audio as a float32 signal in [-1, 1].
wav, fs = soundfile.read("input.wav", dtype="float32")

# Add a watermark. isTest=True keeps the session erasable (on the
# website); pass isTest=False for production marks.
marked = cobalstamp.mark(wav, fs, isai=False, isTest=True)

# Detect a watermark. The audio is sent to the server, which looks
# for registered marks in it.
result = cobalstamp.detect(marked, fs)
print(result)

A detection returns a dictionary:

  • {"marked": False} when no registered mark is found, or

  • {"marked": True, "ppid": "XXXX-XXXX-XXXX", "isai": False} when a mark is found. ppid is the provider identifier of the entity that marked the audio, and isai says whether that mark declared the audio to be AI-generated.

isTest

Marks made with isTest=True belong to a test session that can be purged on the website. Marks made with isTest=False are permanent and are never purged.

API reference

All the functions and attributes below are available at the top level of the cobalstamp module (import cobalstamp).

Watermarking

cobalstamp.mark(wav, fs, isai, isTest=True)

Mark an audio signal with a Cobalstamp watermark and register it on the server.

Parameters:

  • wav – Input audio signal. A numpy array of type float32 or float64, with amplitudes in [-1, 1]. One-dimensional mono or two-dimensional (n_samples, n_channels) multichannel audio is accepted; the channels are averaged to mono before encoding.

  • fs (float) – Sampling rate in Hz.

  • isai (bool) – True if the audio is AI-generated.

  • isTest (bool) – Test-mode flag (default True). Test sessions (isTest=True) can be purged permanently via the website. Marks with isTest=False are kept on the server and cannot be erased. Pass isTest=False for production marks.

Returns:

The watermarked audio signal, as a one-dimensional float32 numpy array.

cobalstamp.detect(wav, fs)

Detect a Cobalstamp watermark in an audio signal.

The audio is sent to the server, and the server returns its verdict. Detection is done on the server.

Parameters:

  • wav – Input audio signal (numpy array, float32, [-1, 1]; multichannel input is averaged to mono).

  • fs (float) – Sampling rate in Hz.

Returns:

The server’s JSON response as a dictionary: {"marked": False}, or {"marked": True, "ppid": str, "isai": bool}.

Environment variables

  • COBALSTAMP_KEY: the API key (license token). It must start with api_ and be exactly 68 characters long. Create a key at https://www.cobalstamp.dev/app/api-keys.

  • COBALSTAMP_TIMEOUT: timeout in seconds for the connections to the server. It is applied when the SDK session starts, i.e. before the first call to the server, so it is in effect for the login (for example export COBALSTAMP_TIMEOUT=20 on a slow connection, see Slow connection). A call to cobalstamp.set_timeout overrides it.