aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 0199fd5597690222934ae64b47345785bf701d97 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# svad

Voice activity detection using [Silero VAD](https://github.com/snakers4/silero-vad) v6.2 weights. Supports mono 16 kHz and 8 kHz audio, speech probabilities, and speech segmentation.

## Build

To build the library, you need Make, a C11 compiler (GCC or Clang), and `ar`.

### Get the weights

This step needs `curl`, Python 3, and [uv](https://docs.astral.sh/uv/getting-started/installation/). The `uv` command below installs NumPy and ONNX for the script. Python is not needed to compile or run the C library.

Run these commands from the project folder. They download the Silero VAD v6.2 models and create `weights_16k.h` and `weights_8k.h`. Both headers must be in this folder before you run `make`:

```sh
mkdir -p build/models
base=https://raw.githubusercontent.com/snakers4/silero-vad/v6.2/src/silero_vad/data
curl -fL "$base/silero_vad_16k_op15.onnx" -o build/models/silero_vad_16k_op15.onnx
curl -fL "$base/silero_vad.onnx" -o build/models/silero_vad.onnx

uv run --no-project --with numpy --with onnx python scripts/export_weights.py \
  build/models/silero_vad_16k_op15.onnx \
  build/models/silero_vad.onnx \
  build/generated

cp build/generated/src/weights_16k.h build/generated/src/weights_8k.h .
```

The script also creates `build/generated/svad_weights.bin`. You only need that file if you use `svad_create_from_file` to load weights at run time.

### Build the library and command

```sh
make            # builds libsvad.a and svad
make debug      # optional debug build
make clean      # removes build outputs
```

Link your application with `libsvad.a` and `-lm`.

## Command-line usage

`svad` reads a 16-bit PCM WAV file at 8 kHz or 16 kHz. Multichannel audio is downmixed to mono. It prints speech start/end times in seconds and sample positions.

```sh
./svad audio.wav
./svad --json --quiet audio.wav > segments.json
./svad --stream audio.wav
```

Usage:

```text
svad [--stream] [--probs FILE] [--json] [--quiet]
     [--threshold X] [--neg-threshold X] [--min-speech-ms N]
     [--max-speech-s X] [--min-silence-ms N] [--speech-pad-ms N]
     [--weights FILE] [--scalar] [--dense-stft] [--no-ftz] INPUT.wav
```

* `--stream` prints speech start/end events while processing the file.
* `--json` formats offline segments as JSON. `--quiet` suppresses statistics.
* `--probs FILE` saves one native float32 probability per 32 ms chunk.

Use `--help` to display the available options.

## Library usage

Save this example as `example.c`. It reads raw mono signed 16-bit PCM in native byte order from standard input at 16 kHz and prints one speech probability per 32 ms chunk. Input must already be decoded and resampled; WAV headers are not accepted.

```c
#include "svad.h"
#include <stdio.h>

int main(void)
{
    svad_t *vad = svad_create(16000);
    if (!vad) return 1;

    const size_t chunk_size = (size_t)svad_chunk_samples(vad);
    int16_t chunk[512];
    size_t n;
    while ((n = fread(chunk, sizeof(*chunk), chunk_size, stdin)) > 0) {
        for (size_t i = n; i < chunk_size; ++i) chunk[i] = 0;
        printf("%.6f\n", svad_process_s16(vad, chunk));
    }

    svad_destroy(vad);
    return ferror(stdin) ? 1 : 0;
}
```

```sh
cc -std=c11 -I. example.c libsvad.a -lm -o example
./example < audio.pcm
```

Use `svad_create(8000)` for 8 kHz audio. Each call consumes exactly 512 samples at 16 kHz or 256 at 8 kHz, without overlap. `svad_process_f32` accepts float samples in `[-1, 1]`. Call `svad_reset` before starting a new audio stream and use a separate instance for each concurrent stream.

For speech boundaries, feed probabilities to `svad_segmenter_update` after `svad_segmenter_init`, or use `svad_speech_timestamps` for a complete recording.  See [svad.h](./svad.h) for the API and segmentation parameters.