Vigil C API Reference | DeepMark Docs

API Reference

The C API provides a stable API for cross-language bindings — Python, Rust, Unity, and others. Include <vigil/c_api.h>.

All functions return vigil_status_t as an integer status code. Objects are managed through opaque handles: vigil_embedder_t and vigil_detector_t.

Python Wrapper

The SDK can be used from Python. The examples in this documentation use a pip-installable Python wheel that wraps the C API. You can write your own bindings if you prefer a different setup. Please contact us for more information.

Embedder Functions

vigil_embedder_config_t

typedef struct {
    const char* model_path;
    int sample_rate;
    int hop_length;
    int step_samples;
    int intra_op_threads;
    int inter_op_threads;
    int enable_memory_arena;
} vigil_embedder_config_t;

Configuration structure for the embedder. Passed to vigil_embedder_create to control model loading, processing behavior, and inference performance.

Fields:

model_path — const char*, default: NULL
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. It 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 call to vigil_embedder_step.
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 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 — int, default: 1
When set to 1, pre-allocates a memory arena for inference, reducing allocation overhead during processing. Recommended to keep enabled.

Example:

vigil_embedder_config_t cfg = {
    .model_path          = "models/embedder.enc",
    .sample_rate         = 48000,
    .hop_length          = 512,
    .step_samples        = 512,
    .intra_op_threads    = 4,
    .inter_op_threads    = 4,
    .enable_memory_arena = 1,
};

vigil_embedder_create

vigil_status_t vigil_embedder_create(
    const vigil_embedder_config_t* config,
    vigil_embedder_t* out_handle
)

Creates a new embedder instance. The model is not loaded — call vigil_embedder_load before processing.

Parameters:

config — const vigil_embedder_config_t*
Pointer to the embedder configuration. Must not be null.
out_handle — vigil_embedder_t*
Pointer to a handle that will receive the created embedder instance.

Returns:

VIGIL_OK on success, VIGIL_INVALID_ARGUMENT if any pointer is null. See C Status Codes for the full list.

vigil_embedder_load

vigil_status_t vigil_embedder_load(vigil_embedder_t handle)

Loads the model into memory. Must be called once before vigil_embedder_step.

Parameters:

handle — vigil_embedder_t
Embedder handle returned by vigil_embedder_create.

Returns:

VIGIL_OK on success, VIGIL_MODEL_LOAD_FAILED if the model file cannot be loaded.

vigil_embedder_step

vigil_status_t vigil_embedder_step(
    vigil_embedder_t handle,
    const float* input,
    size_t count,
    float* output,
    size_t* out_count
)

Feeds exactly vigil_embedder_step_samples() input samples and produces watermarked or pass-through output. 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. This is the C equivalent of StreamingEmbedder.EmbedStep — see that section for detailed output behavior.

Parameters:

handle — vigil_embedder_t
Embedder handle.
input — const float*
Pointer to input audio samples — mono, float32.
count — size_t
Number of input samples. Must be exactly vigil_embedder_step_samples().
output — float*
Pointer to output buffer. Must have room for at least 512 samples.
out_count — size_t*
Receives the number of output samples written.

Returns:

VIGIL_OK on success, VIGIL_INVALID_ARGUMENT if count is not 512, VIGIL_INVALID_STATE if the model is not loaded.

vigil_embedder_reset

vigil_status_t vigil_embedder_reset(vigil_embedder_t handle)

Resets the embedder state. Must be called before processing a new audio stream, as explained in StreamingEmbedder.Reset.

Parameters:

handle — vigil_embedder_t
Embedder handle.

Returns:

VIGIL_OK on success.

vigil_embedder_is_loaded

int vigil_embedder_is_loaded(vigil_embedder_t handle)

Checks whether the model is loaded.

Parameters:

handle — vigil_embedder_t
Embedder handle.

Returns:

1 if loaded, 0 otherwise.

vigil_embedder_step_samples

int vigil_embedder_step_samples(vigil_embedder_t handle)

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

Parameters:

handle — vigil_embedder_t
Embedder handle.

Returns:

Step size in samples.

vigil_embedder_destroy

void vigil_embedder_destroy(vigil_embedder_t handle)

Destroys the embedder instance and frees all associated resources. The handle must not be used after this call.

Parameters:

handle — vigil_embedder_t
Embedder handle to destroy.

Detector Functions

vigil_detector_config_t

typedef struct {
    const char* model_path;
    int sample_rate;
    int hop_length;
    float confidence_a;
    float confidence_threshold;
    int intra_op_threads;
    int inter_op_threads;
    int enable_memory_arena;
} vigil_detector_config_t;

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

Fields:

model_path — const char*, default: NULL
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. It must match the sample rate the model was trained on. Currently supported model sample rates include 16, 24, 44.1, 48, and 96 kHz.
confidence_a — float, default: 150.0
Internal parameter for confidence calculation. It should not be modified.
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 vigil_detect_result_t. Lowering this value includes more frames but potentially introduces noise, while raising it requires higher certainty per frame.
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 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 — int, default: 1
When set to 1, pre-allocates a memory arena for inference, reducing allocation overhead during processing. Recommended to keep enabled.

Example:

vigil_detector_config_t cfg = {
    .model_path           = "models/detector.enc",
    .sample_rate          = 48000,
    .hop_length           = 512,
    .confidence_a         = 150.0f,
    .confidence_threshold = 0.8f,
    .intra_op_threads     = 4,
    .inter_op_threads     = 4,
    .enable_memory_arena  = 1,
};

vigil_detector_create

vigil_status_t vigil_detector_create(
    const vigil_detector_config_t* config,
    vigil_detector_t* out_handle
)

Creates a new detector instance. The model is not loaded — call vigil_detector_load before detection.

Parameters:

config — const vigil_detector_config_t*
Pointer to the detector configuration. Must not be null.
out_handle — vigil_detector_t*
Pointer to a handle that will receive the created detector instance.

Returns:

VIGIL_OK on success, VIGIL_INVALID_ARGUMENT if any pointer is null.

vigil_detector_load

vigil_status_t vigil_detector_load(vigil_detector_t handle)

Loads the model into memory. Must be called once before any detection functions.

Parameters:

handle — vigil_detector_t
Detector handle returned by vigil_detector_create.

Returns:

VIGIL_OK on success, VIGIL_MODEL_LOAD_FAILED if the model file cannot be loaded.

vigil_detector_detect_chunk

vigil_status_t vigil_detector_detect_chunk(
    vigil_detector_t handle,
    const float* samples,
    size_t count,
    vigil_chunk_result_t* result
)

Runs detection on a single chunk of audio. This is the C equivalent of Detector.DetectChunk.

Parameters:

handle — vigil_detector_t
Detector handle.
samples — const float*
Pointer to audio samples — mono, float32.
count — size_t
Number of samples. Must equal the value returned by vigil_detector_chunk_size.
result — vigil_chunk_result_t*
Pointer to result structure that receives logit and confidence.

Returns:

VIGIL_OK on success, VIGIL_INVALID_ARGUMENT if count does not match the expected chunk size.

vigil_detector_detect

vigil_status_t vigil_detector_detect(
    vigil_detector_t handle,
    const float* samples,
    size_t num_samples,
    vigil_detect_result_t* result,
    int pad_last
)

Runs detection across an entire audio buffer with aggregation. This is the C equivalent of Detector.Detect.

Parameters:

handle — vigil_detector_t
Detector handle.
samples — const float*
Pointer to the audio buffer — mono, float32.
num_samples — size_t
Total number of samples in the buffer.
result — vigil_detect_result_t*
Pointer to result structure that receives the aggregated detection output.
pad_last — int
If 1, zero-pads the last chunk. If 0, discards it.

Returns:

VIGIL_OK on success.

vigil_detector_is_loaded

int vigil_detector_is_loaded(vigil_detector_t handle)

Checks whether the model is loaded.

Parameters:

handle — vigil_detector_t
Detector handle.

Returns:

1 if loaded, 0 otherwise.

vigil_detector_chunk_size

int vigil_detector_chunk_size(vigil_detector_t handle)

Returns the expected number of samples per detection chunk, computed as (sample_rate / hop_length) * hop_length.

Parameters:

handle — vigil_detector_t
Detector handle.

Returns:

Chunk size in samples.

vigil_detector_destroy

void vigil_detector_destroy(vigil_detector_t handle)

Destroys the detector instance and frees all associated resources. The handle must not be used after this call.

Parameters:

handle — vigil_detector_t
Detector handle to destroy.

Utility Functions

vigil_version_string

const char* vigil_version_string(void)

Returns the SDK version as a string — for example, "0.2.0".

Returns:

Null-terminated version string. The pointer is valid for the lifetime of the process.

vigil_status_message

const char* vigil_status_message(vigil_status_t status)

Returns a human-readable description for a status code.

Parameters:

status — vigil_status_t
Status code to describe.

Returns:

Null-terminated string describing the status.

C Status Codes

Value	Name	Description
0	`VIGIL_OK`	Success.
1	`VIGIL_INVALID_ARGUMENT`	Invalid parameter.
2	`VIGIL_INVALID_STATE`	Wrong state.
3	`VIGIL_MODEL_LOAD_FAILED`	Model load failure.
4	`VIGIL_INFERENCE_FAILED`	Inference error.
5	`VIGIL_BUFFER_OVERFLOW`	Buffer overflow.
6	`VIGIL_INTERNAL_ERROR`	Internal error.