aboutsummaryrefslogtreecommitdiff
/* svad: silero-vad v6.2 speech detection in portable C.
 *
 * The engine is a fixed-size state machine over a stream of audio chunks: one
 * call per chunk returns the speech probability for that chunk. No allocation,
 * no syscall and no lock happens inside svad_process_*; every buffer is sized
 * at create time. Weights are compiled in by default, so a process needs no
 * data files.
 *
 * A stream is a strict sequence of fixed-size chunks: 512 samples at 16 kHz,
 * 256 at 8 kHz (svad_chunk_samples). Consecutive chunks must not overlap; the
 * engine carries the 64 (or 32) sample context it needs internally.
 *
 * svad_segmenter turns that probability stream into speech start/end events as
 * they happen, and svad_speech_timestamps turns a complete probability
 * sequence into a segment list offline. Both mirror the upstream Python
 * behaviour (VADIterator and get_speech_timestamps) exactly.
 */

#ifndef SVAD_H
#define SVAD_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define SVAD_VERSION_MAJOR 1
#define SVAD_VERSION_MINOR 0

/* ---- engine ---------------------------------------------------------- */

typedef struct svad svad_t;

/* Creation flags. The defaults (0) select the fastest kernels available and
 * the rFFT short-time transform; the alternatives exist so a build can be
 * checked against a simpler implementation of the same arithmetic. */
enum {
    SVAD_SCALAR_KERNELS = 1u << 0, /* portable C kernels, no SIMD intrinsics */
    SVAD_DENSE_STFT = 1u << 1,     /* dense basis matvec instead of the rFFT */
    SVAD_NO_FTZ = 1u << 2,         /* leave denormal handling to the caller */
    SVAD_NO_VERIFY = 1u << 3,      /* skip checksum verification of a weight file */
};

/* sample_rate is 8000 or 16000. Returns NULL on an unsupported rate, on an
 * unreadable or corrupt weight file, or on allocation failure. */
svad_t *svad_create(int sample_rate);
svad_t *svad_create_from_file(const char *path, int sample_rate);
svad_t *svad_create_ex(const char *path, int sample_rate, unsigned flags);

void svad_destroy(svad_t *v);

/* Drops the LSTM state and the carried context, so the next chunk starts a new
 * stream. Required whenever the audio source changes. */
void svad_reset(svad_t *v);

/* Samples consumed per svad_process_* call: 512 at 16 kHz, 256 at 8 kHz. */
int svad_chunk_samples(const svad_t *v);
int svad_sample_rate(const svad_t *v);

/* Name of the active kernel set, for logs and benchmark output. */
const char *svad_backend_name(const svad_t *v);

/* Speech probability in [0,1] for one chunk. chunk holds exactly
 * svad_chunk_samples() samples; the f32 variant expects [-1,1], the s16
 * variant is scaled by 1/32768 to match. */
float svad_process_f32(svad_t *v, const float *chunk);
float svad_process_s16(svad_t *v, const int16_t *chunk);

/* Copies the LSTM state (h then c, 128 floats each). Intended for tests and
 * for saving a stream's position; out holds 256 floats. */
void svad_get_state(const svad_t *v, float *out);
void svad_set_state(svad_t *v, const float *in);

/* ---- streaming segmenter --------------------------------------------- */

typedef enum {
    SVAD_EVENT_NONE = 0,
    SVAD_EVENT_SPEECH_START,
    SVAD_EVENT_SPEECH_END,
} svad_event_kind;

typedef struct {
    svad_event_kind kind;
    int64_t sample; /* position of the event in the input stream */
} svad_event;

/* Caller-owned, no allocation. Fields above the state block may be adjusted
 * after init to retune; the state block is engine-managed. */
typedef struct {
    float threshold;
    float neg_threshold;
    int64_t min_silence_samples;
    int64_t speech_pad_samples;
    int64_t window_samples;

    int triggered;
    int64_t current_sample;
    int64_t temp_end; /* 0 means unset, matching the reference implementation */
} svad_segmenter;

void svad_segmenter_init(svad_segmenter *s, int sample_rate);
void svad_segmenter_reset(svad_segmenter *s);

/* Feeds one chunk probability and advances the sample cursor by one window.
 * Returns at most one event per chunk. */
svad_event svad_segmenter_update(svad_segmenter *s, float prob);

/* ---- offline segmentation -------------------------------------------- */

typedef struct {
    int64_t start;
    int64_t end;
} svad_segment;

typedef struct {
    float threshold;
    float neg_threshold; /* <= 0 selects max(threshold - 0.15, 0.01) */
    int min_speech_ms;
    double max_speech_s; /* HUGE_VAL for no limit */
    int min_silence_ms;
    int speech_pad_ms;
    /* Extra audio kept before a segment, on top of speech_pad_ms.
     *
     * A detector only becomes confident once speech is clearly under way, and
     * where a voice emerges from music it can score the first word at nearly
     * zero. Padding both ends equally is then the wrong shape: the opening is
     * what gets lost, and widening the tail by as much only adds audio nobody
     * needed. Zero, the default, leaves segmentation exactly as the reference
     * implementation defines it. */
    int lead_pad_ms;
    int min_silence_at_max_speech_ms;
    int use_max_poss_sil_at_max_speech;
} svad_segment_params;

void svad_segment_params_default(svad_segment_params *p);

/* Converts a complete probability sequence into speech segments. probs[i] is
 * the probability of the chunk starting at sample i * window.
 *
 * Returns the number of segments found. Segments are written only when the
 * whole list fits, because the final padding pass is defined over the complete
 * list; when out is NULL or out_cap is too small, nothing is written and the
 * caller should size a buffer from the return value and call again. */
size_t svad_speech_timestamps(const float *probs,
                              size_t n_probs,
                              int64_t audio_length_samples,
                              int sample_rate,
                              const svad_segment_params *params,
                              svad_segment *out,
                              size_t out_cap);

#ifdef __cplusplus
}
#endif

#endif /* SVAD_H */