Home /Modules/signal-processing/API-CONTRACTS.md

API-CONTRACTS.md

signal-processing/docs/API-CONTRACTS.md · 62 line(s) · markdown

<!-- Author: Max Rupplin — MEARVK LLC — 2026 -->

API contracts

General rules

The public C interface is declared in include/sleela_signal_processing.h. Samples are represented as double precision values, and complex values use SleelaSPComplex with separate real and imaginary members. Callers own all input and output storage. APIs that accept a capacity require the capacity to be expressed in elements, not bytes.

Check every SleelaSPStatus return value. slsp_status_string() maps the library's status values to a short diagnostic. The API distinguishes invalid arguments, insufficient capacity, allocation failure, unsupported/overflowing size, and numeric failure.

Buffers and overlap

A capacity error is not permission to use a partial output. For some numeric errors, calculations may have written earlier output elements before detecting the failure; callers should discard that output unless an API specifically documents transactional behavior.

Status values

StatusMeaning
SLEELA_SP_OKOperation completed successfully
SLEELA_SP_ERR_INVALIDA required pointer, length, window, or mode is invalid
SLEELA_SP_ERR_CAPACITYOutput storage is too small
SLEELA_SP_ERR_ALLOCThe library could not allocate working storage
SLEELA_SP_ERR_SIZESize is unsupported or would overflow an allocation calculation
SLEELA_SP_ERR_NUMERICA non-finite input or result was detected

C++ vector helpers convert invalid parameters to std::invalid_argument, numeric failures to std::overflow_error, and other library errors to std::runtime_error. std::bad_alloc from vector allocation may propagate. The direct C++ fft() helper is noexcept and returns a status value instead of throwing.

Transform conventions

The library does not infer sample rate, physical units, ADC calibration, or frequency-axis labels. The caller derives frequency bin k as k * sample_rate / N for a uniformly sampled signal.