Deepmark

DetectorConfig

vigil::DetectorConfig

Configuration structure for the detector. Passed to the constructor to control model loading, confidence calculation, and inference behavior.

Fields:

  • model_path — std::string (default: "")

    Path to the encrypted detector model file. This is the only field that must be set explicitly before use.

  • sample_rate — int (default: 48000)

    Sample rate of the input audio. Must match the sample rate the model was trained on. Currently supported model sample rates include 16, 24, 44.1, 48, and 96 kHz.

  • hop_length — int (default: 512)

    Internal hop length used by the model. Do not modify.

  • confidence_a — float (default: 150.0)

    Steepness parameter for the confidence calculation curve. Higher values produce a sharper confidence curve, meaning the model needs a stronger signal to report high confidence. In most cases, the default value does not need to be changed.

  • confidence_threshold — float (default: 0.75)

    Minimum confidence required for a frame to be included in the aggregated detection result. Frames below this threshold are ignored when computing the mean_logit and the final decision in DetectResult. Lowering this value includes more frames but potentially introduces noise.

  • intra_op_threads — int (default: 4)

    Number of threads used for parallelism within a single operator during inference. Use ThreadTuner to find the optimal value.

  • inter_op_threads — int (default: 4)

    Number of threads used to run independent operators in parallel during inference. Use ThreadTuner to find the optimal value.

  • enable_memory_arena — bool (default: true)

    When enabled, pre-allocates a memory arena for inference, reducing allocation overhead. Recommended to keep enabled.

Example:

vigil::DetectorConfig cfg;
cfg.model_path = "models/detector.enc";
cfg.confidence_threshold = 0.8f; // stricter confidence filtering

Detector

class vigil::Detector

Analyzes audio to determine whether a watermark is present. Supports two modes of operation: single-chunk detection via DetectChunk for real-time use, and full-buffer detection via Detect which processes an entire audio buffer and aggregates results across all chunks.

Detector constructor

vigil::Detector::Detector(const DetectorConfig& config)

Constructs a new detector instance with the given configuration. The model is not loaded at construction time — you must call Load before performing any detection.

Parameters:
  • config — const DetectorConfig&

    Configuration for the detector. At minimum, config.model_path must be set to a valid model file path.

Example:
vigil::DetectorConfig cfg;
cfg.model_path = "models/detector.enc";
vigil::Detector detector(cfg);

Detector.Load

vigil::Status vigil::Detector::Load()

Loads the detection model into memory and prepares the detector for processing. Should be called once during initialization; the loaded instance should be reused for all subsequent detection calls.

Returns:

Status — StatusCode::kOk on success. StatusCode::kModelLoadFailed if the model file cannot be found, read, or decrypted.

Example:
vigil::Detector detector(cfg);
vigil::Status status = detector.Load();
if (!status) {
    std::cerr << "Failed to load model: " << status.message() << "\n";
}

Detector.DetectChunk

vigil::Status vigil::Detector::DetectChunk(
    const float* samples,
    size_t count,
    DetectChunkResult& result
)

Runs watermark detection on a single chunk of audio. The chunk must contain exactly chunk_size samples. This function is suitable for real-time or streaming detection, where you accumulate audio into a buffer and call DetectChunk each time you have a full chunk.

Parameters:
  • samples — const float*

    Pointer to the audio samples to analyze. Must be mono, float32, at the sample rate specified in the configuration.

  • count — size_t

    Number of samples in the buffer. Must be exactly equal to the value returned by chunk_size.

  • result — DetectChunkResult&

    Reference to a result structure that will be populated with the detection output, containing logit and confidence.

Returns:

Status — StatusCode::kOk on success. StatusCode::kInvalidArgument if count does not match chunk_size or if any pointer is null. StatusCode::kInvalidState if Load has not been called.

Example:
const size_t chunk = static_cast<size_t>(detector.chunk_size());
std::vector<float> audio(chunk);
// ... fill audio with samples ...

vigil::DetectChunkResult result;
vigil::Status status = detector.DetectChunk(audio.data(), chunk, result);
if (status.ok()) {
    std::cout << "Logit: " << result.logit
              << ", Confidence: " << result.confidence << "\n";
}

Detector.Detect

vigil::Status vigil::Detector::Detect(
    const float* samples,
    size_t num_samples,
    DetectResult& result,
    bool pad_last = false
)

Runs watermark detection across an entire audio buffer. The buffer is split into chunks of chunk_size samples, detection is run on each chunk independently, and the results are aggregated into a single decision.

The aggregation considers only frames where confidence meets the threshold set in DetectorConfig. The final decision is determined by the mean logit of these confident frames: a positive mean logit indicates the audio is watermarked.

Parameters:
  • samples — const float*

    Pointer to the audio buffer to analyze. Must be mono, float32, at the sample rate specified in the configuration.

  • num_samples — size_t

    Total number of samples in the buffer. Can be any length — the buffer will be split into chunks automatically.

  • result — DetectResult&

    Reference to a result structure that will be populated with the aggregated detection output, including the final decision, per-frame breakdown, and statistics.

  • pad_last — bool (default: false)

    Controls how the last chunk is handled when the buffer length is not an exact multiple of chunk_size. If true, the final chunk is zero-padded and included. If false, the incomplete final chunk is discarded.

Returns:

Status — StatusCode::kOk on success. StatusCode::kInvalidState if Load has not been called. StatusCode::kInferenceFailed if inference fails on any chunk.

Example:
vigil::DetectResult result;
vigil::Status status = detector.Detect(audio, num_samples, result, true);
if (status.ok()) {
    std::cout << "Decision: " << (result.decision ? "WATERMARKED" : "CLEAN") << "\n";
    std::cout << "Mean logit: " << result.mean_logit << "\n";
    std::cout << "Confident frames: " << result.num_confident_frames
              << "/" << result.total_frames << "\n";
}

Detector.IsLoaded

bool vigil::Detector::IsLoaded() const

Checks whether the model has been successfully loaded into memory via Load.

Returns:

bool — true if the model is loaded, false otherwise.

Detector.chunk_size

int vigil::Detector::chunk_size() const

Returns the number of samples expected per detection chunk. This value is computed dynamically based on the configured sample rate, so it will differ depending on the model.

Returns:

int — The chunk size in samples.

DetectChunkResult

struct vigil::DetectChunkResult

Result structure returned by Detector.DetectChunk, representing the detection output for a single audio chunk.

Fields:

  • logit — float

    Raw detection score in the range [-1, 1]. A positive logit indicates the chunk contains a watermark. A negative logit indicates the chunk is clean. Values closer to the extremes indicate a stronger signal.

  • confidence — float

    Confidence value in the range [0, 1], indicating how certain the detector is about the logit. Higher confidence means the detector is more sure of its assessment. The confidence curve is controlled by the confidence_a parameter in DetectorConfig.

DetectResult

struct vigil::DetectResult

Aggregated detection result returned by Detector.Detect, covering all chunks in the analyzed audio buffer.

Fields:

  • decision — int

    Final detection verdict. 1 means the audio is determined to be watermarked, 0 means it is not. Based on the sign of mean_logit.

  • mean_logit — float

    Mean logit value computed over only the frames that meet the confidence threshold. This is the primary value used to determine the final decision.

  • num_confident_frames — int

    Number of chunks whose confidence met or exceeded the threshold set in DetectorConfig. Only these frames contribute to mean_logit and decision.

  • num_positive — int

    Number of chunks with a positive logit, indicating watermark presence, regardless of confidence.

  • num_negative — int

    Number of chunks with a negative logit, indicating clean audio, regardless of confidence.

  • total_frames — int

    Total number of chunks processed from the audio buffer.

  • positive_ratio — float

    Ratio of positive-logit frames to total frames.

  • negative_ratio — float

    Ratio of negative-logit frames to total frames.

  • confident_ratio — float

    Ratio of confident frames to total frames.

  • per_frame — std::vector<DetectChunkResult>

    Per-chunk breakdown. Each entry contains the logit and confidence for one chunk, in order. Useful for visualizing detection results across the audio timeline.