EmbedderConfig

vigil::EmbedderConfig

Configuration structure for the streaming embedder. Passed to the constructor to control model loading and inference behavior.

Fields:

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

  Path to the encrypted embedder 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.

• step_samples — int (default: 512)

  Number of samples consumed per EmbedStep call.

• intra_op_threads — int (default: 4)

  Number of threads used for parallelism within a single operator during inference. Increasing this value can improve performance on multi-core systems. Use ThreadTuner to find the optimal value for your hardware.

• 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 for your hardware.

• enable_memory_arena — bool (default: true)

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

Example:

vigil::EmbedderConfig cfg;
cfg.model_path = "models/embedder.enc";
cfg.intra_op_threads = 2;
cfg.inter_op_threads = 2;

StreamingEmbedder

class vigil::StreamingEmbedder

Processes audio in a step-by-step fashion, suitable for real-time pipelines. Internally maintains a ring buffer that must fill before watermarking begins. Once the buffer is full, each subsequent call to EmbedStep runs the watermarking model and produces watermarked output.

StreamingEmbedder constructor

vigil::StreamingEmbedder::StreamingEmbedder(const EmbedderConfig& config)

Constructs a new streaming embedder instance with the given configuration. The model is not loaded at construction time — you must call Load before processing any audio.

Parameters:

• config — const EmbedderConfig&

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

Example:

vigil::EmbedderConfig cfg;
cfg.model_path = "models/embedder.enc";
vigil::StreamingEmbedder embedder(cfg);

StreamingEmbedder.Load

vigil::Status vigil::StreamingEmbedder::Load()

Loads the watermarking model into memory and prepares it for processing. This operation may take several seconds depending on the model size and hardware. It should be called once during initialization, and the loaded instance should be reused across multiple audio streams by calling Reset between streams.

Returns:

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

Example:

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

StreamingEmbedder.Reset

vigil::Status vigil::StreamingEmbedder::Reset()

Clears the internal ring buffer and resets the state machine to its initial state. Must be called before starting a new audio stream — for example, when switching to a new file or a new live session.

If Reset is not called between streams, the embedder will continue from where it left off, using stale audio data from the previous stream in its buffer. This may corrupt the watermark in the new stream.

Returns:

Status — StatusCode::kOk on success.

Example:

// After finishing stream 1...
embedder.Reset();
// Now safe to process stream 2

StreamingEmbedder.EmbedStep

vigil::Status vigil::StreamingEmbedder::EmbedStep(
    const float* input,
    size_t count,
    float* output,
    size_t* out_count
)

The core processing function. Each call consumes a fixed number of input samples and writes the corresponding output samples — either pass-through or watermarked — into the output buffer. During the initial warm-up period (while the internal buffer is still filling), output is pass-through — unchanged audio. Once the buffer is full, all subsequent calls produce watermarked output. The exact number of samples per call is equal to the number of input samples set in EmbedderConfig during creation. This number is determined by the step_samples method, which should be queried beforehand to allocate buffers and control the processing loop. Call this function repeatedly for each step of audio in your pipeline.

Parameters:

• input — const float*

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

• count — size_t

  Number of input samples. Must be exactly equal to step_samples. Passing any other value will return an error.

• output — float*

  Pointer to the output buffer where samples will be written. Must have room for at least step_samples samples.

• out_count — size_t*

  Pointer to a variable that will receive the number of output samples actually written.

Returns:

Status — StatusCode::kOk on success. StatusCode::kInvalidArgument if count does not match step_samples or if any pointer is null. StatusCode::kInvalidState if Load has not been called. StatusCode::kInferenceFailed if the model inference fails.

Example:

const int step = embedder.step_samples();
std::vector<float> input(step); // filled with audio samples
std::vector<float> output(step);
size_t out_count = 0;

vigil::Status status = embedder.EmbedStep(input.data(), step, output.data(), &out_count);
if (status.ok()) {
    // Use the first out_count samples from output
    write_to_stream(output.data(), out_count);
}

StreamingEmbedder.IsLoaded

bool vigil::StreamingEmbedder::IsLoaded() const

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

Returns:

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

StreamingEmbedder.step_samples

int vigil::StreamingEmbedder::step_samples() const

Returns the number of input samples set in EmbedderConfig during creation.

Returns:

int — The step size in samples.