aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-13 20:03:39 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-13 20:13:28 +0200
commit64c3a1b528a88b4ae21bf3cbcff2537200477806 (patch)
tree85da00748d7bbb5036aeb5a7a4b60b5abf75aeea
downloadpyseg-64c3a1b528a88b4ae21bf3cbcff2537200477806.tar.gz
pyseg-64c3a1b528a88b4ae21bf3cbcff2537200477806.zip
Init
-rw-r--r--.gitignore12
-rw-r--r--Makefile132
-rw-r--r--README.md148
-rw-r--r--bench/bench.c158
-rw-r--r--src/kernels.c555
-rw-r--r--src/kernels.h67
-rw-r--r--src/pyseg.c503
-rw-r--r--src/pyseg.h215
-rw-r--r--src/pyseg_cli.c176
-rw-r--r--src/slide.c423
-rw-r--r--src/wav.c127
-rw-r--r--src/wav.h22
-rw-r--r--src/weights.c189
-rw-r--r--src/weights.h49
-rw-r--r--testdata_aepyx.wavbin0 -> 5412908 bytes
-rw-r--r--tests/test_kernels.c151
-rw-r--r--tests/test_parity.c214
-rw-r--r--tests/test_robust.c133
-rw-r--r--tests/test_slide.c212
-rw-r--r--tests/test_util.h29
-rw-r--r--tools/baseline.py137
-rw-r--r--tools/embed.py45
-rw-r--r--tools/export_weights.py153
-rw-r--r--tools/make_golden.py93
-rw-r--r--tools/model.py137
-rw-r--r--tools/pipeline.py169
-rw-r--r--tools/reference.py192
-rw-r--r--tools/verify_cli.py132
28 files changed, 4573 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..577655d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+build/
+.venv/
+pyseg_cli
+
+pyseg_weights.bin
+golden.npz
+*.o
+*.d
+*.a
+__pycache__/
+
+src/weights_blob.c
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..838a47a
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,132 @@
+CC ?= cc
+OPT ?= -O2 -g
+WARN = -Wall -Wextra
+CFLAGS = $(OPT) $(WARN) -std=gnu11
+CPPFLAGS = -Isrc
+LDLIBS = -lm
+
+# Parity depends on the compiler not reassociating or contracting the
+# reductions differently from the reference; -ffast-math is deliberately
+# absent.
+#
+# No architecture flags are needed or wanted. On x86 the AVX2 kernels carry
+# their own instruction set on the functions and are selected against the
+# running processor, so a default build is both safe on a host without AVX2
+# and fast on one with it.
+#
+# THREADS=0 drops the pthread dependency; the window loop then runs on the
+# calling thread whatever --threads asks for.
+# EMBED=0 leaves the weight blob out of the binary, which then needs
+# --weights pyseg_weights.bin.
+# STATIC=1 links a self-contained binary, for a container that carries
+# nothing but the executable.
+
+THREADS ?= 1
+EMBED ?= 1
+
+ifeq ($(THREADS),1)
+ CPPFLAGS += -DPYSEG_THREADS
+ LDLIBS += -lpthread
+endif
+ifeq ($(STATIC),1)
+ LDFLAGS += -static
+endif
+
+BUILD := build
+LIB := $(BUILD)/libpyseg.a
+BIN := pyseg_cli
+
+LIB_SRCS := src/pyseg.c src/kernels.c src/weights.c src/slide.c
+ifeq ($(EMBED),1)
+ CPPFLAGS += -DPYSEG_EMBED_WEIGHTS
+ LIB_SRCS += src/weights_blob.c
+endif
+LIB_OBJS := $(LIB_SRCS:%.c=$(BUILD)/%.o)
+CLI_SRCS := src/pyseg_cli.c src/wav.c
+CLI_OBJS := $(CLI_SRCS:%.c=$(BUILD)/%.o)
+
+TESTS := test_kernels test_parity test_robust test_slide
+TEST_BINS := $(TESTS:%=$(BUILD)/%)
+TEST_CPPFLAGS := $(CPPFLAGS) -Itests
+
+BENCH := $(BUILD)/bench
+
+WEIGHTS := pyseg_weights.bin
+GOLDEN := $(BUILD)/golden.bin
+SLIDE_GOLDEN := $(BUILD)/slide_golden.bin
+AUDIO ?= testdata_aepyx.wav
+PY := PYTHONPATH=tools .venv/bin/python
+PYTHON ?= python3
+
+.PHONY: all test bench clean weights golden verify
+
+all: $(LIB) $(BIN)
+
+$(LIB): $(LIB_OBJS)
+ @rm -f $@
+ ar rcs $@ $(LIB_OBJS)
+
+$(BIN): $(CLI_OBJS) $(LIB)
+ $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(CLI_OBJS) $(LIB) $(LDLIBS)
+
+$(BUILD)/%.o: %.c
+ @mkdir -p $(dir $@)
+ $(CC) $(CFLAGS) $(CPPFLAGS) -MMD -MP -c $< -o $@
+
+# The generated weight array is data, not code; optimising it only costs
+# compile time.
+$(BUILD)/src/weights_blob.o: src/weights_blob.c
+ @mkdir -p $(dir $@)
+ $(CC) -O0 -g0 -std=gnu11 -c $< -o $@
+
+$(BUILD)/test_%: tests/test_%.c $(LIB) tests/test_util.h
+ @mkdir -p $(dir $@)
+ $(CC) $(CFLAGS) $(TEST_CPPFLAGS) $(LDFLAGS) $< $(LIB) -o $@ $(LDLIBS)
+
+$(BENCH): bench/bench.c $(LIB)
+ @mkdir -p $(dir $@)
+ $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $< $(LIB) -o $@ $(LDLIBS)
+
+# Regenerates the weight blob from the checkpoint in the Hugging Face cache.
+# The blob is checked in, so this is only needed after a layout change; the
+# embedded copy is derived from it by a plain-stdlib script that runs anywhere,
+# including inside the container build.
+weights:
+ $(PY) tools/export_weights.py .
+ $(MAKE) src/weights_blob.c
+
+src/weights_blob.c: $(WEIGHTS) tools/embed.py
+ $(PYTHON) tools/embed.py $(WEIGHTS) $@
+
+golden: $(GOLDEN) $(SLIDE_GOLDEN)
+
+$(GOLDEN): golden.npz tools/make_golden.py
+ @mkdir -p $(BUILD)
+ $(PY) tools/make_golden.py chunks $< $@
+
+$(SLIDE_GOLDEN): $(AUDIO) tools/make_golden.py
+ @mkdir -p $(BUILD)
+ $(PY) tools/make_golden.py slide $< $@
+
+golden.npz: $(AUDIO) tools/baseline.py
+ $(PY) tools/baseline.py golden $< $@
+
+test: $(TEST_BINS) $(GOLDEN) $(SLIDE_GOLDEN)
+ @rc=0; \
+ $(BUILD)/test_kernels || rc=1; \
+ $(BUILD)/test_parity $(GOLDEN) || rc=1; \
+ $(BUILD)/test_robust || rc=1; \
+ $(BUILD)/test_slide $(SLIDE_GOLDEN) || rc=1; \
+ if [ $$rc -eq 0 ]; then echo "all ok"; else echo "not ok"; exit 1; fi
+
+bench: $(BENCH) $(GOLDEN)
+ $(BENCH) $(GOLDEN)
+
+# End-to-end against pyannote's own pipelines; needs the Python environment.
+verify: $(BIN)
+ $(PY) tools/verify_cli.py $(AUDIO)
+
+clean:
+ rm -rf $(BUILD) $(BIN)
+
+-include $(LIB_OBJS:.o=.d) $(CLI_OBJS:.o=.d)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f16a9ff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,148 @@
+# pyseg
+
+`pyannote/segmentation-3.0` speaker segmentation in dependency-free C.
+
+The model reads ten seconds of 16 kHz mono audio and returns, for each of 589
+output frames, a distribution over seven classes: no speaker, one of three
+speakers alone, or one of the three pairs. That is enough for voice activity
+detection, overlapped speech detection and per-frame speaker counting over a
+recording of any length, all of which this library does.
+
+The library is C11 and libc. The weights are compiled into the binary.
+Building the weight blob needs PyTorch and pyannote.audio once.
+
+## Build
+
+```sh
+make # library and CLI, weights embedded
+make test # all gates (needs the fixtures below)
+make bench # timings
+```
+
+Options: `THREADS=0` drops the pthread dependency, `EMBED=0` leaves the weights
+out of the binary so it loads `--weights pyseg_weights.bin` instead, `STATIC=1`
+links a self-contained executable, `OPT=...` overrides the compiler flags.
+
+Do not add `-ffast-math`. It changes how the reductions contract and moves the
+results outside the tolerances above.
+
+## Command line
+
+```
+pyseg_cli [options] file.wav
+
+ --mode speech|overlap|count|frames what to print (default speech)
+ --step SECONDS window hop, default 1.0 (a tenth of the window)
+ --threads N windows to run in parallel, default 1
+ --batch N windows per engine call, default 4
+ --weights FILE weight blob; default is the embedded copy
+ --onset X score above which a region opens, default 0.5
+ --offset X score below which it closes, default 0.5
+ --min-on SECONDS drop regions shorter than this, default 0
+ --min-off SECONDS fill gaps shorter than this, default 0
+ --scalar portable C kernels instead of SIMD
+```
+
+Input must be 16 kHz 16-bit PCM WAV; the first channel is used. `speech` and
+`overlap` print `start end` pairs in seconds, `count` prints the expected
+number of speakers per frame, and `frames` prints all three tracks.
+
+```console
+$ pyseg_cli --threads 8 meeting.wav
+0.031 0.588
+2.427 18.593
+18.897 27.149
+```
+
+Cost scales with `--step`: the default hop of one second means every part of
+the recording is covered by ten windows, which is what pyannote's pipelines are
+tuned for. A larger hop costs proportionally less and blurs the aggregate.
+
+## Library
+
+```c
+#include "pyseg.h"
+
+pyseg_t *v = pyseg_create(); /* embedded weights */
+float probs[PYSEG_FRAMES * PYSEG_CLASSES];
+pyseg_process_f32(v, samples, probs); /* 160000 samples in */
+pyseg_destroy(v);
+```
+
+`probs` holds one distribution over the seven powerset classes per frame.
+`pyseg_to_multilabel` turns that into per-speaker activity, and frame `f`
+covers the 991 samples starting at `f * PYSEG_FRAME_STEP`.
+
+For a whole recording:
+
+```c
+pyseg_slide_params p;
+pyseg_slide_params_default(&p);
+p.threads = 8;
+
+size_t n = pyseg_slide_frames(num_samples, p.step);
+float *tracks = malloc(n * PYSEG_TRACKS * sizeof(float));
+pyseg_slide_s16(samples, num_samples, &p, tracks);
+
+pyseg_segment segs[256];
+size_t count = pyseg_binarize(tracks, n, PYSEG_TRACK_SPEECH, NULL, segs, 256);
+```
+
+`pyseg_slide` covers the recording with overlapping windows and averages them
+exactly as `pyannote.audio.Inference` does. `pyseg_binarize` turns one track
+into segments the way `pyannote.audio.utils.signal.Binarize` does.
+
+No allocation, syscall or lock happens inside `pyseg_process_*`. An engine is
+not thread-safe and is not meant to be: `pyseg_slide` gives each thread its
+own, and so should any other caller.
+
+### What this does not do
+
+Speaker identities hold only inside a single ten-second window. Two
+overlapping windows may number the same person differently, so joining windows
+into whole-recording speakers needs a speaker embedding model and clustering,
+which is a separate model and outside this library. Speech activity,
+overlapped speech and the per-frame speaker count do carry across windows, and
+those are what `pyseg_slide` aggregates.
+
+The model is 16 kHz mono only, and the window length is fixed at ten seconds
+because the network was trained that way; per-channel statistics are computed
+over the whole window, so it also cannot be run as a stream.
+
+## Layout
+
+| path | content |
+|---|---|
+| `src/pyseg.h` | the public interface |
+| `src/pyseg.c` | the forward pass |
+| `src/kernels.c` | the one dense primitive, scalar and SIMD |
+| `src/weights.c` | weight blob reader |
+| `src/slide.c` | sliding window, aggregation, binarization |
+| `tools/reference.py` | numpy forward pass, the executable specification |
+| `tools/pipeline.py` | the aggregation reference |
+| `tools/export_weights.py` | checkpoint to `pyseg_weights.bin` |
+| `tools/embed.py` | blob to C source, standard library only |
+| `tools/verify_cli.py` | the built binary against pyannote's pipelines |
+
+## Regenerating the fixtures
+
+The parity tests need captured references, which need the Python environment:
+
+```sh
+uv venv --python 3.12 .venv
+VIRTUAL_ENV=.venv uv pip install "pyannote.audio>=3.1" numpy soundfile
+make weights # only after a layout change; the blob is checked in
+make golden # capture reference outputs
+make test
+make verify # end to end against pyannote's own pipelines
+```
+
+`make golden` needs a 16 kHz WAV at `testdata_aepyx.wav`; override with
+`AUDIO=...`.
+
+## Licence
+
+The code here is yours to license. The model weights are
+`pyannote/segmentation-3.0`, MIT, by Alexis Plaquet and Hervé Bredin; see the
+[model card](https://hf.co/pyannote/segmentation-3.0) and the
+[paper](https://www.isca-speech.org/archive/interspeech_2023/plaquet23_interspeech.html).
diff --git a/bench/bench.c b/bench/bench.c
new file mode 100644
index 0000000..a33d2d4
--- /dev/null
+++ b/bench/bench.c
@@ -0,0 +1,158 @@
+/* Benchmark for one window and for a whole recording.
+ *
+ * The protocol matches tools/baseline.py so the numbers sit next to PyTorch's
+ * on the same machine: three warm-up windows, then twenty timed ones on real
+ * speech taken from the parity fixture, reporting mean, median and the slowest
+ * of the twenty.
+ *
+ * Real speech rather than noise matters here. The engine's cost is fixed by
+ * the shapes, but denormal cell states on near-silent input are the one thing
+ * that can change it, and noise would hide that. */
+
+#include "pyseg.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/resource.h>
+#include <time.h>
+
+#define WARMUP 3
+#define ITERS 20
+
+static double now_ms(void) {
+ struct timespec ts;
+ clock_gettime(CLOCK_MONOTONIC, &ts);
+ return ts.tv_sec * 1e3 + ts.tv_nsec / 1e6;
+}
+
+static int cmp_double(const void *a, const void *b) {
+ const double x = *(const double *)a, y = *(const double *)b;
+ return x < y ? -1 : x > y;
+}
+
+static float *load_windows(const char *path, unsigned *count) {
+ FILE *fp = fopen(path, "rb");
+ if (!fp)
+ return NULL;
+ char magic[4];
+ unsigned n, samples, frames;
+ if (fread(magic, 1, 4, fp) != 4 || memcmp(magic, "PSGG", 4) != 0 || fread(&n, 4, 1, fp) != 1 ||
+ fread(&samples, 4, 1, fp) != 1 || fread(&frames, 4, 1, fp) != 1 ||
+ samples != PYSEG_WINDOW_SAMPLES) {
+ fclose(fp);
+ return NULL;
+ }
+ const size_t len = (size_t)n * PYSEG_WINDOW_SAMPLES;
+ float *data = malloc(len * sizeof(float));
+ if (data && fread(data, sizeof(float), len, fp) != len) {
+ free(data);
+ data = NULL;
+ }
+ fclose(fp);
+ *count = n;
+ return data;
+}
+
+/* Times whole batches and reports per window, so batch sizes compare directly.
+ * The fixture holds fewer windows than some batches, so windows are reused;
+ * that is fine because the cost does not depend on the audio. */
+static void bench_backend(unsigned flags, int batch, const float *windows, unsigned count) {
+ const double t_init = now_ms();
+ pyseg_t *v = pyseg_create_batch(NULL, flags, batch);
+ const double init_ms = now_ms() - t_init;
+ if (!v) {
+ fprintf(stderr, "batch %d: create failed\n", batch);
+ return;
+ }
+
+ float *input = malloc((size_t)batch * PYSEG_WINDOW_SAMPLES * sizeof(float));
+ float *probs = malloc((size_t)batch * PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+ for (int b = 0; b < batch; ++b)
+ memcpy(input + (size_t)b * PYSEG_WINDOW_SAMPLES,
+ windows + (size_t)(b % count) * PYSEG_WINDOW_SAMPLES,
+ PYSEG_WINDOW_SAMPLES * sizeof(float));
+
+ for (int i = 0; i < WARMUP; ++i)
+ pyseg_process_batch_f32(v, input, batch, probs);
+
+ double times[ITERS];
+ for (int i = 0; i < ITERS; ++i) {
+ const double t = now_ms();
+ pyseg_process_batch_f32(v, input, batch, probs);
+ times[i] = (now_ms() - t) / batch;
+ }
+ qsort(times, ITERS, sizeof(double), cmp_double);
+
+ double sum = 0.0;
+ for (int i = 0; i < ITERS; ++i)
+ sum += times[i];
+ const double mean = sum / ITERS;
+
+ printf("window %-6s batch %2d init %5.2f ms mean/p50/max %6.2f / %6.2f / %6.2f ms"
+ " %6.1fx realtime %5.1f MB\n",
+ pyseg_backend_name(v), batch, init_ms, mean, times[ITERS / 2], times[ITERS - 1],
+ 10.0 / (mean / 1e3), pyseg_memory_bytes(v) / 1e6);
+
+ free(probs);
+ free(input);
+ pyseg_destroy(v);
+}
+
+int main(int argc, char **argv) {
+ if (argc < 2) {
+ fprintf(stderr, "usage: bench <golden.bin>\n");
+ return 2;
+ }
+ unsigned count = 0;
+ float *windows = load_windows(argv[1], &count);
+ if (!windows || count == 0) {
+ fprintf(stderr, "cannot read %s\n", argv[1]);
+ return 2;
+ }
+
+ for (int batch = 1; batch <= 8; batch *= 2)
+ bench_backend(0, batch, windows, count);
+ bench_backend(PYSEG_SCALAR_KERNELS, 1, windows, count);
+
+ /* The whole-recording path, which is what a server actually runs: the
+ * fixture's windows are one second apart, so concatenating their first
+ * seconds reconstructs the recording they came from. */
+ const size_t step_samples = PYSEG_SAMPLE_RATE;
+ const size_t num_samples = PYSEG_WINDOW_SAMPLES + (count - 1) * step_samples;
+ float *audio = malloc(num_samples * sizeof(float));
+ memcpy(audio, windows, PYSEG_WINDOW_SAMPLES * sizeof(float));
+ for (unsigned c = 1; c < count; ++c)
+ memcpy(audio + PYSEG_WINDOW_SAMPLES + (size_t)(c - 1) * step_samples,
+ windows + (size_t)c * PYSEG_WINDOW_SAMPLES + PYSEG_WINDOW_SAMPLES - step_samples,
+ step_samples * sizeof(float));
+
+ const size_t frames = pyseg_slide_frames(num_samples, 1.0);
+ float *tracks = malloc(frames * PYSEG_TRACKS * sizeof(float));
+
+ for (int threads = 1; threads <= 16; threads *= 2) {
+ pyseg_slide_params p;
+ pyseg_slide_params_default(&p);
+ p.threads = threads;
+ const double t = now_ms();
+ const size_t got = pyseg_slide(audio, num_samples, &p, tracks);
+ const double ms = now_ms() - t;
+ if (got == 0) {
+ fprintf(stderr, "slide failed at %d threads\n", threads);
+ break;
+ }
+ printf("slide %2d thr %6.1f s of audio in %8.1f ms %6.1fx realtime\n", threads,
+ (double)num_samples / PYSEG_SAMPLE_RATE, ms,
+ (double)num_samples / PYSEG_SAMPLE_RATE / (ms / 1e3));
+ }
+
+ struct rusage ru;
+ getrusage(RUSAGE_SELF, &ru);
+ printf("max rss %.1f MB\n", (double)ru.ru_maxrss / 1e6);
+
+ free(tracks);
+ free(audio);
+ free(windows);
+ return 0;
+}
diff --git a/src/kernels.c b/src/kernels.c
new file mode 100644
index 0000000..01c1d19
--- /dev/null
+++ b/src/kernels.c
@@ -0,0 +1,555 @@
+/* Scalar and SIMD implementations of the dense primitive.
+ *
+ * Each variant blocks a rectangle of output positions against weight rows and
+ * accumulates along the window, and the rectangle is chosen by the register
+ * file rather than by the algorithm. AArch64 has 32 vector registers, so four
+ * positions by four rows fits: sixteen accumulators plus eight live operands,
+ * eight loads for sixteen multiply-adds. x86-64 has 16, so the same rectangle
+ * spills its accumulators to the stack every iteration and four by two is
+ * faster despite doing half as much per pass; on one server core that
+ * difference was a factor of 1.8 over a whole recording.
+ *
+ * Matrix-vector shapes, meaning the LSTM recurrence where there is only one
+ * output position, widen instead to eight weight rows. With a single
+ * activation window there is nothing to reuse but that window, so the weight
+ * loads are the entire cost and the only thing worth amortising is the
+ * activation.
+ *
+ * Accumulation order differs between the variants, so their results differ in
+ * the last bits; tests/test_kernels.c bounds that.
+ */
+
+#include "kernels.h"
+
+#include <math.h>
+#include <stddef.h>
+
+#if defined(__GNUC__) || defined(__clang__)
+# define PYSEG_INLINE static inline __attribute__((always_inline))
+#else
+# define PYSEG_INLINE static inline
+#endif
+
+static inline int min_int(int a, int b) { return a < b ? a : b; }
+
+/* ---- portable C ------------------------------------------------------ */
+
+PYSEG_INLINE void
+dot4x4_scalar(float *y, int ldy, const float *a, int lda, const float *w, const float *bias, int k) {
+ float acc[4][4] = {{0.0f}};
+ for (int j = 0; j < k; ++j) {
+ const float a0 = a[j], a1 = a[lda + j], a2 = a[2 * lda + j], a3 = a[3 * lda + j];
+ for (int i = 0; i < 4; ++i) {
+ const float wv = w[(size_t)i * k + j];
+ acc[0][i] += a0 * wv;
+ acc[1][i] += a1 * wv;
+ acc[2][i] += a2 * wv;
+ acc[3][i] += a3 * wv;
+ }
+ }
+ for (int s = 0; s < 4; ++s)
+ for (int i = 0; i < 4; ++i)
+ y[(size_t)s * ldy + i] = bias ? bias[i] + acc[s][i] : acc[s][i];
+}
+
+/* One output position against however many weight rows are left. */
+PYSEG_INLINE void
+row_scalar(float *y, const float *a, const float *w, const float *bias, int n, int k) {
+ for (int i = 0; i < n; ++i) {
+ const float *wr = w + (size_t)i * k;
+ float s0 = 0.0f, s1 = 0.0f, s2 = 0.0f, s3 = 0.0f;
+ int j = 0;
+ for (; j + 4 <= k; j += 4) {
+ s0 += a[j + 0] * wr[j + 0];
+ s1 += a[j + 1] * wr[j + 1];
+ s2 += a[j + 2] * wr[j + 2];
+ s3 += a[j + 3] * wr[j + 3];
+ }
+ const float s = (s0 + s1) + (s2 + s3);
+ y[i] = bias ? bias[i] + s : s;
+ }
+}
+
+static void gemm_nt_scalar(float *y,
+ int ldy,
+ const float *a,
+ int lda,
+ const float *w,
+ const float *bias,
+ int m,
+ int n,
+ int k) {
+ for (int m0 = 0; m0 < m; m0 += PYSEG_MPANEL) {
+ const int mend = min_int(m0 + PYSEG_MPANEL, m);
+ const int m4 = m0 + (mend - m0) / 4 * 4;
+ int i = 0;
+ for (; i + 4 <= n; i += 4)
+ for (int s = m0; s < m4; s += 4)
+ dot4x4_scalar(y + (size_t)s * ldy + i, ldy, a + (size_t)s * lda, lda,
+ w + (size_t)i * k, bias ? bias + i : NULL, k);
+ for (int s = m0; s < m4; ++s)
+ if (i < n)
+ row_scalar(y + (size_t)s * ldy + i, a + (size_t)s * lda, w + (size_t)i * k,
+ bias ? bias + i : NULL, n - i, k);
+ for (int s = m4; s < mend; ++s)
+ row_scalar(y + (size_t)s * ldy, a + (size_t)s * lda, w, bias, n, k);
+ }
+}
+
+static void lstm_cell_scalar(float *h, float *c, const float *rec, const float *in, int hid) {
+ for (int i = 0; i < hid; ++i) {
+ const float ig = 1.0f / (1.0f + expf(-(rec[i] + in[i])));
+ const float fg = 1.0f / (1.0f + expf(-(rec[hid + i] + in[hid + i])));
+ const float gg = tanhf(rec[2 * hid + i] + in[2 * hid + i]);
+ const float og = 1.0f / (1.0f + expf(-(rec[3 * hid + i] + in[3 * hid + i])));
+ const float cn = fg * c[i] + ig * gg;
+ c[i] = cn;
+ h[i] = og * tanhf(cn);
+ }
+}
+
+static const pyseg_kernels kernels_scalar = {"scalar", gemm_nt_scalar, lstm_cell_scalar};
+
+const pyseg_kernels *pyseg_kernels_scalar(void) { return &kernels_scalar; }
+
+/* ---- AArch64 NEON ---------------------------------------------------- */
+
+#if defined(__aarch64__) && defined(__ARM_NEON)
+# define PYSEG_HAVE_SIMD 1
+# include <arm_neon.h>
+
+/* Four lane-wise accumulators reduced to one vector holding their four totals.
+ * Pairwise adds do this in three instructions instead of four cross-lane
+ * reductions plus the moves back into a vector. */
+PYSEG_INLINE float32x4_t hsum4(float32x4_t a, float32x4_t b, float32x4_t c, float32x4_t d) {
+ return vpaddq_f32(vpaddq_f32(a, b), vpaddq_f32(c, d));
+}
+
+PYSEG_INLINE void
+dot4x4_neon(float *y, int ldy, const float *a, int lda, const float *w, const float *bias, int k) {
+ const float *a0 = a, *a1 = a + lda, *a2 = a + 2 * lda, *a3 = a + 3 * lda;
+ const float *w0 = w, *w1 = w + k, *w2 = w + 2 * k, *w3 = w + 3 * k;
+
+ float32x4_t c00 = vdupq_n_f32(0.0f), c01 = c00, c02 = c00, c03 = c00;
+ float32x4_t c10 = c00, c11 = c00, c12 = c00, c13 = c00;
+ float32x4_t c20 = c00, c21 = c00, c22 = c00, c23 = c00;
+ float32x4_t c30 = c00, c31 = c00, c32 = c00, c33 = c00;
+
+ for (int j = 0; j < k; j += 4) {
+ const float32x4_t x0 = vld1q_f32(a0 + j);
+ const float32x4_t x1 = vld1q_f32(a1 + j);
+ const float32x4_t x2 = vld1q_f32(a2 + j);
+ const float32x4_t x3 = vld1q_f32(a3 + j);
+ const float32x4_t v0 = vld1q_f32(w0 + j);
+ const float32x4_t v1 = vld1q_f32(w1 + j);
+ const float32x4_t v2 = vld1q_f32(w2 + j);
+ const float32x4_t v3 = vld1q_f32(w3 + j);
+ c00 = vfmaq_f32(c00, x0, v0);
+ c01 = vfmaq_f32(c01, x0, v1);
+ c02 = vfmaq_f32(c02, x0, v2);
+ c03 = vfmaq_f32(c03, x0, v3);
+ c10 = vfmaq_f32(c10, x1, v0);
+ c11 = vfmaq_f32(c11, x1, v1);
+ c12 = vfmaq_f32(c12, x1, v2);
+ c13 = vfmaq_f32(c13, x1, v3);
+ c20 = vfmaq_f32(c20, x2, v0);
+ c21 = vfmaq_f32(c21, x2, v1);
+ c22 = vfmaq_f32(c22, x2, v2);
+ c23 = vfmaq_f32(c23, x2, v3);
+ c30 = vfmaq_f32(c30, x3, v0);
+ c31 = vfmaq_f32(c31, x3, v1);
+ c32 = vfmaq_f32(c32, x3, v2);
+ c33 = vfmaq_f32(c33, x3, v3);
+ }
+
+ const float32x4_t b = bias ? vld1q_f32(bias) : vdupq_n_f32(0.0f);
+ vst1q_f32(y, vaddq_f32(b, hsum4(c00, c01, c02, c03)));
+ vst1q_f32(y + ldy, vaddq_f32(b, hsum4(c10, c11, c12, c13)));
+ vst1q_f32(y + 2 * ldy, vaddq_f32(b, hsum4(c20, c21, c22, c23)));
+ vst1q_f32(y + 3 * ldy, vaddq_f32(b, hsum4(c30, c31, c32, c33)));
+}
+
+/* Single output position, eight weight rows at a time.
+ *
+ * With one activation window there is nothing to reuse but the window itself,
+ * so this shape costs one weight load per multiply-add and runs at whatever
+ * rate the memory system delivers weights, not at the multiply pipes' rate.
+ * Eight rows measured fastest here: four leaves the load pipeline too shallow,
+ * and sixteen has enough concurrent streams to start working against the
+ * hardware prefetcher. */
+PYSEG_INLINE void
+row_neon(float *y, const float *a, const float *w, const float *bias, int n, int k) {
+ int i = 0;
+ for (; i + 8 <= n; i += 8) {
+ const float *w0 = w + (size_t)i * k;
+ float32x4_t c0 = vdupq_n_f32(0.0f), c1 = c0, c2 = c0, c3 = c0;
+ float32x4_t c4 = c0, c5 = c0, c6 = c0, c7 = c0;
+ for (int j = 0; j < k; j += 4) {
+ const float32x4_t x = vld1q_f32(a + j);
+ c0 = vfmaq_f32(c0, x, vld1q_f32(w0 + j));
+ c1 = vfmaq_f32(c1, x, vld1q_f32(w0 + k + j));
+ c2 = vfmaq_f32(c2, x, vld1q_f32(w0 + 2 * k + j));
+ c3 = vfmaq_f32(c3, x, vld1q_f32(w0 + 3 * k + j));
+ c4 = vfmaq_f32(c4, x, vld1q_f32(w0 + 4 * k + j));
+ c5 = vfmaq_f32(c5, x, vld1q_f32(w0 + 5 * k + j));
+ c6 = vfmaq_f32(c6, x, vld1q_f32(w0 + 6 * k + j));
+ c7 = vfmaq_f32(c7, x, vld1q_f32(w0 + 7 * k + j));
+ }
+ const float32x4_t lo = hsum4(c0, c1, c2, c3);
+ const float32x4_t hi = hsum4(c4, c5, c6, c7);
+ if (bias) {
+ vst1q_f32(y + i, vaddq_f32(vld1q_f32(bias + i), lo));
+ vst1q_f32(y + i + 4, vaddq_f32(vld1q_f32(bias + i + 4), hi));
+ } else {
+ vst1q_f32(y + i, lo);
+ vst1q_f32(y + i + 4, hi);
+ }
+ }
+ for (; i + 4 <= n; i += 4) {
+ const float *w0 = w + (size_t)i * k;
+ float32x4_t c0 = vdupq_n_f32(0.0f), c1 = c0, c2 = c0, c3 = c0;
+ for (int j = 0; j < k; j += 4) {
+ const float32x4_t x = vld1q_f32(a + j);
+ c0 = vfmaq_f32(c0, x, vld1q_f32(w0 + j));
+ c1 = vfmaq_f32(c1, x, vld1q_f32(w0 + k + j));
+ c2 = vfmaq_f32(c2, x, vld1q_f32(w0 + 2 * k + j));
+ c3 = vfmaq_f32(c3, x, vld1q_f32(w0 + 3 * k + j));
+ }
+ const float32x4_t v = hsum4(c0, c1, c2, c3);
+ vst1q_f32(y + i, bias ? vaddq_f32(vld1q_f32(bias + i), v) : v);
+ }
+ for (; i < n; ++i) {
+ const float *wr = w + (size_t)i * k;
+ float32x4_t c0 = vdupq_n_f32(0.0f);
+ for (int j = 0; j < k; j += 4)
+ c0 = vfmaq_f32(c0, vld1q_f32(a + j), vld1q_f32(wr + j));
+ const float s = vaddvq_f32(c0);
+ y[i] = bias ? bias[i] + s : s;
+ }
+}
+
+static void gemm_nt_neon(float *y,
+ int ldy,
+ const float *a,
+ int lda,
+ const float *w,
+ const float *bias,
+ int m,
+ int n,
+ int k) {
+ if (m == 1) {
+ row_neon(y, a, w, bias, n, k);
+ return;
+ }
+ for (int m0 = 0; m0 < m; m0 += PYSEG_MPANEL) {
+ const int mend = min_int(m0 + PYSEG_MPANEL, m);
+ const int m4 = m0 + (mend - m0) / 4 * 4;
+ int i = 0;
+ for (; i + 4 <= n; i += 4)
+ for (int s = m0; s < m4; s += 4)
+ dot4x4_neon(y + (size_t)s * ldy + i, ldy, a + (size_t)s * lda, lda, w + (size_t)i * k,
+ bias ? bias + i : NULL, k);
+ for (int s = m0; s < m4; ++s)
+ if (i < n)
+ row_neon(y + (size_t)s * ldy + i, a + (size_t)s * lda, w + (size_t)i * k,
+ bias ? bias + i : NULL, n - i, k);
+ for (int s = m4; s < mend; ++s)
+ row_neon(y + (size_t)s * ldy, a + (size_t)s * lda, w, bias, n, k);
+ }
+}
+
+/* Vector exponential, the Cephes single-precision scheme: split the argument
+ * into an integer power of two and a remainder inside half a ln 2, evaluate a
+ * degree-six polynomial on the remainder, then scale by assembling the power
+ * of two directly in the exponent field. Accurate to about one unit in the
+ * last place, which is the same claim libm makes.
+ *
+ * The clamp is what keeps the exponent assembly in range; beyond it the
+ * logistic and hyperbolic functions built on this are saturated anyway. */
+PYSEG_INLINE float32x4_t vexpq(float32x4_t x) {
+ x = vminq_f32(vmaxq_f32(x, vdupq_n_f32(-88.0f)), vdupq_n_f32(88.0f));
+
+ const float32x4_t n = vrndnq_f32(vmulq_f32(x, vdupq_n_f32(1.44269504088896341f)));
+ /* ln 2 split in two so the product with n stays exact in the high part. */
+ float32x4_t r = vfmsq_f32(x, n, vdupq_n_f32(0.693359375f));
+ r = vfmsq_f32(r, n, vdupq_n_f32(-2.12194440e-4f));
+
+ float32x4_t p = vdupq_n_f32(1.9875691500e-4f);
+ p = vfmaq_f32(vdupq_n_f32(1.3981999507e-3f), p, r);
+ p = vfmaq_f32(vdupq_n_f32(8.3334519073e-3f), p, r);
+ p = vfmaq_f32(vdupq_n_f32(4.1665795894e-2f), p, r);
+ p = vfmaq_f32(vdupq_n_f32(1.6666665459e-1f), p, r);
+ p = vfmaq_f32(vdupq_n_f32(5.0000001201e-1f), p, r);
+ p = vfmaq_f32(vaddq_f32(r, vdupq_n_f32(1.0f)), p, vmulq_f32(r, r));
+
+ const int32x4_t bits = vshlq_n_s32(vaddq_s32(vcvtq_s32_f32(n), vdupq_n_s32(127)), 23);
+ return vmulq_f32(p, vreinterpretq_f32_s32(bits));
+}
+
+PYSEG_INLINE float32x4_t vsigmoidq(float32x4_t x) {
+ return vdivq_f32(vdupq_n_f32(1.0f), vaddq_f32(vdupq_n_f32(1.0f), vexpq(vnegq_f32(x))));
+}
+
+/* tanh x = 2 sigmoid(2x) - 1. The subtraction loses relative accuracy near
+ * zero, where sigmoid is close to a half, but the absolute error stays at the
+ * rounding level of the result and that is what propagates into the cell
+ * state. */
+PYSEG_INLINE float32x4_t vtanhq(float32x4_t x) {
+ return vfmsq_f32(vdupq_n_f32(-1.0f), vsigmoidq(vaddq_f32(x, x)), vdupq_n_f32(-2.0f));
+}
+
+static void lstm_cell_neon(float *h, float *c, const float *rec, const float *in, int hid) {
+ for (int i = 0; i < hid; i += 4) {
+ const float32x4_t ig = vsigmoidq(vaddq_f32(vld1q_f32(rec + i), vld1q_f32(in + i)));
+ const float32x4_t fg =
+ vsigmoidq(vaddq_f32(vld1q_f32(rec + hid + i), vld1q_f32(in + hid + i)));
+ const float32x4_t gg =
+ vtanhq(vaddq_f32(vld1q_f32(rec + 2 * hid + i), vld1q_f32(in + 2 * hid + i)));
+ const float32x4_t og =
+ vsigmoidq(vaddq_f32(vld1q_f32(rec + 3 * hid + i), vld1q_f32(in + 3 * hid + i)));
+ const float32x4_t cn = vfmaq_f32(vmulq_f32(ig, gg), fg, vld1q_f32(c + i));
+ vst1q_f32(c + i, cn);
+ vst1q_f32(h + i, vmulq_f32(og, vtanhq(cn)));
+ }
+}
+
+static const pyseg_kernels kernels_simd = {"neon", gemm_nt_neon, lstm_cell_neon};
+#endif /* aarch64 NEON */
+
+/* ---- x86-64 AVX2 -----------------------------------------------------
+ *
+ * Compiled into every x86 build whatever baseline the rest of the file uses,
+ * by carrying the instruction set on the functions rather than on the command
+ * line, and selected at startup against the running processor. One binary is
+ * then both safe on a host without AVX2 and fast on one with it.
+ *
+ * Every function reachable from an AVX2 entry point needs the same attribute,
+ * including the always-inlined ones, or the compiler refuses to inline across
+ * the mismatch. */
+
+#if (defined(__x86_64__) || defined(__i386__)) && (defined(__GNUC__) || defined(__clang__))
+# define PYSEG_HAVE_SIMD 1
+# define PYSEG_X86_DISPATCH 1
+# include <immintrin.h>
+
+# define PYSEG_AVX2 __attribute__((target("avx2,fma")))
+# define PYSEG_AVX2_INLINE static inline __attribute__((always_inline, target("avx2,fma")))
+
+PYSEG_AVX2_INLINE float hsum256(__m256 v) {
+ __m128 lo = _mm256_castps256_ps128(v);
+ __m128 hi = _mm256_extractf128_ps(v, 1);
+ lo = _mm_add_ps(lo, hi);
+ lo = _mm_add_ps(lo, _mm_movehl_ps(lo, lo));
+ lo = _mm_add_ss(lo, _mm_shuffle_ps(lo, lo, 0x55));
+ return _mm_cvtss_f32(lo);
+}
+
+/* Four output positions against two weight rows: eight accumulators, which is
+ * half the register file. That is the shape this instruction set allows. The
+ * NEON kernel above blocks four by four because it has thirty-two vector
+ * registers to hold sixteen accumulators plus the operands; asking for the
+ * same here spills the accumulators to the stack every iteration and costs
+ * more than the blocking saves.
+ *
+ * The window length is a multiple of four but not always of eight, so the
+ * eight-wide body is followed by at most one four-wide step, done in scalar
+ * code since it is at most four elements of at least sixty. */
+PYSEG_AVX2_INLINE void
+dot4x2_avx2(float *y, int ldy, const float *a, int lda, const float *w, const float *bias, int k) {
+ const float *a0 = a, *a1 = a + lda, *a2 = a + 2 * lda, *a3 = a + 3 * lda;
+ const float *w0 = w, *w1 = w + k;
+
+ __m256 c00 = _mm256_setzero_ps(), c01 = c00, c10 = c00, c11 = c00;
+ __m256 c20 = c00, c21 = c00, c30 = c00, c31 = c00;
+
+ int j = 0;
+ for (; j + 8 <= k; j += 8) {
+ const __m256 v0 = _mm256_loadu_ps(w0 + j);
+ const __m256 v1 = _mm256_loadu_ps(w1 + j);
+ const __m256 x0 = _mm256_loadu_ps(a0 + j);
+ const __m256 x1 = _mm256_loadu_ps(a1 + j);
+ const __m256 x2 = _mm256_loadu_ps(a2 + j);
+ const __m256 x3 = _mm256_loadu_ps(a3 + j);
+ c00 = _mm256_fmadd_ps(x0, v0, c00);
+ c01 = _mm256_fmadd_ps(x0, v1, c01);
+ c10 = _mm256_fmadd_ps(x1, v0, c10);
+ c11 = _mm256_fmadd_ps(x1, v1, c11);
+ c20 = _mm256_fmadd_ps(x2, v0, c20);
+ c21 = _mm256_fmadd_ps(x2, v1, c21);
+ c30 = _mm256_fmadd_ps(x3, v0, c30);
+ c31 = _mm256_fmadd_ps(x3, v1, c31);
+ }
+
+ const float *ar[4] = {a0, a1, a2, a3};
+ __m256 acc[4][2] = {{c00, c01}, {c10, c11}, {c20, c21}, {c30, c31}};
+ for (int s = 0; s < 4; ++s)
+ for (int i = 0; i < 2; ++i) {
+ float v = hsum256(acc[s][i]);
+ for (int t = j; t < k; ++t)
+ v += ar[s][t] * w[(size_t)i * k + t];
+ y[(size_t)s * ldy + i] = bias ? bias[i] + v : v;
+ }
+}
+
+/* Single output position, eight weight rows at a time; the matrix-vector shape
+ * of the LSTM recurrence. Eight accumulators fit, and one activation load then
+ * serves eight weight loads. */
+PYSEG_AVX2_INLINE void
+row_avx2(float *y, const float *a, const float *w, const float *bias, int n, int k) {
+ int i = 0;
+ for (; i + 8 <= n; i += 8) {
+ const float *w0 = w + (size_t)i * k;
+ __m256 c0 = _mm256_setzero_ps(), c1 = c0, c2 = c0, c3 = c0;
+ __m256 c4 = c0, c5 = c0, c6 = c0, c7 = c0;
+ int j = 0;
+ for (; j + 8 <= k; j += 8) {
+ const __m256 x = _mm256_loadu_ps(a + j);
+ const float *p = w0 + j;
+ c0 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p), c0);
+ c1 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + k), c1);
+ c2 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 2 * k), c2);
+ c3 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 3 * k), c3);
+ c4 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 4 * k), c4);
+ c5 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 5 * k), c5);
+ c6 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 6 * k), c6);
+ c7 = _mm256_fmadd_ps(x, _mm256_loadu_ps(p + 7 * k), c7);
+ }
+ const __m256 acc[8] = {c0, c1, c2, c3, c4, c5, c6, c7};
+ for (int q = 0; q < 8; ++q) {
+ float v = hsum256(acc[q]);
+ for (int t = j; t < k; ++t)
+ v += a[t] * w0[(size_t)q * k + t];
+ y[i + q] = bias ? bias[i + q] + v : v;
+ }
+ }
+ for (; i < n; ++i) {
+ const float *wr = w + (size_t)i * k;
+ __m256 acc = _mm256_setzero_ps();
+ int j = 0;
+ for (; j + 8 <= k; j += 8)
+ acc = _mm256_fmadd_ps(_mm256_loadu_ps(a + j), _mm256_loadu_ps(wr + j), acc);
+ float v = hsum256(acc);
+ for (; j < k; ++j)
+ v += a[j] * wr[j];
+ y[i] = bias ? bias[i] + v : v;
+ }
+}
+
+PYSEG_AVX2 static void gemm_nt_avx2(float *y,
+ int ldy,
+ const float *a,
+ int lda,
+ const float *w,
+ const float *bias,
+ int m,
+ int n,
+ int k) {
+ if (m == 1) {
+ row_avx2(y, a, w, bias, n, k);
+ return;
+ }
+ for (int m0 = 0; m0 < m; m0 += PYSEG_MPANEL) {
+ const int mend = min_int(m0 + PYSEG_MPANEL, m);
+ const int m4 = m0 + (mend - m0) / 4 * 4;
+ int i = 0;
+ for (; i + 2 <= n; i += 2)
+ for (int s = m0; s < m4; s += 4)
+ dot4x2_avx2(y + (size_t)s * ldy + i, ldy, a + (size_t)s * lda, lda, w + (size_t)i * k,
+ bias ? bias + i : NULL, k);
+ for (int s = m0; s < m4; ++s)
+ if (i < n)
+ row_avx2(y + (size_t)s * ldy + i, a + (size_t)s * lda, w + (size_t)i * k,
+ bias ? bias + i : NULL, n - i, k);
+ for (int s = m4; s < mend; ++s)
+ row_avx2(y + (size_t)s * ldy, a + (size_t)s * lda, w, bias, n, k);
+ }
+}
+
+/* The same Cephes scheme as the NEON path; see the comment there. */
+PYSEG_AVX2_INLINE __m256 vexp256(__m256 x) {
+ x = _mm256_min_ps(_mm256_max_ps(x, _mm256_set1_ps(-88.0f)), _mm256_set1_ps(88.0f));
+
+ const __m256 n = _mm256_round_ps(_mm256_mul_ps(x, _mm256_set1_ps(1.44269504088896341f)),
+ _MM_FROUND_TO_NEAREST_INT | _MM_FROUND_NO_EXC);
+ __m256 r = _mm256_fnmadd_ps(n, _mm256_set1_ps(0.693359375f), x);
+ r = _mm256_fnmadd_ps(n, _mm256_set1_ps(-2.12194440e-4f), r);
+
+ __m256 p = _mm256_set1_ps(1.9875691500e-4f);
+ p = _mm256_fmadd_ps(p, r, _mm256_set1_ps(1.3981999507e-3f));
+ p = _mm256_fmadd_ps(p, r, _mm256_set1_ps(8.3334519073e-3f));
+ p = _mm256_fmadd_ps(p, r, _mm256_set1_ps(4.1665795894e-2f));
+ p = _mm256_fmadd_ps(p, r, _mm256_set1_ps(1.6666665459e-1f));
+ p = _mm256_fmadd_ps(p, r, _mm256_set1_ps(5.0000001201e-1f));
+ p = _mm256_fmadd_ps(p, _mm256_mul_ps(r, r), _mm256_add_ps(r, _mm256_set1_ps(1.0f)));
+
+ const __m256i bits =
+ _mm256_slli_epi32(_mm256_add_epi32(_mm256_cvtps_epi32(n), _mm256_set1_epi32(127)), 23);
+ return _mm256_mul_ps(p, _mm256_castsi256_ps(bits));
+}
+
+PYSEG_AVX2_INLINE __m256 vsigmoid256(__m256 x) {
+ const __m256 one = _mm256_set1_ps(1.0f);
+ return _mm256_div_ps(one, _mm256_add_ps(one, vexp256(_mm256_sub_ps(_mm256_setzero_ps(), x))));
+}
+
+PYSEG_AVX2_INLINE __m256 vtanh256(__m256 x) {
+ return _mm256_fmsub_ps(vsigmoid256(_mm256_add_ps(x, x)), _mm256_set1_ps(2.0f),
+ _mm256_set1_ps(1.0f));
+}
+
+PYSEG_AVX2_INLINE __m256 gate256(const float *rec, const float *in, int offset) {
+ return _mm256_add_ps(_mm256_loadu_ps(rec + offset), _mm256_loadu_ps(in + offset));
+}
+
+PYSEG_AVX2 static void
+lstm_cell_avx2(float *h, float *c, const float *rec, const float *in, int hid) {
+ int i = 0;
+ for (; i + 8 <= hid; i += 8) {
+ const __m256 ig = vsigmoid256(gate256(rec, in, i));
+ const __m256 fg = vsigmoid256(gate256(rec, in, hid + i));
+ const __m256 gg = vtanh256(gate256(rec, in, 2 * hid + i));
+ const __m256 og = vsigmoid256(gate256(rec, in, 3 * hid + i));
+ const __m256 cn = _mm256_fmadd_ps(fg, _mm256_loadu_ps(c + i), _mm256_mul_ps(ig, gg));
+ _mm256_storeu_ps(c + i, cn);
+ _mm256_storeu_ps(h + i, _mm256_mul_ps(og, vtanh256(cn)));
+ }
+ for (; i < hid; ++i) {
+ const float ig = 1.0f / (1.0f + expf(-(rec[i] + in[i])));
+ const float fg = 1.0f / (1.0f + expf(-(rec[hid + i] + in[hid + i])));
+ const float gg = tanhf(rec[2 * hid + i] + in[2 * hid + i]);
+ const float og = 1.0f / (1.0f + expf(-(rec[3 * hid + i] + in[3 * hid + i])));
+ const float cn = fg * c[i] + ig * gg;
+ c[i] = cn;
+ h[i] = og * tanhf(cn);
+ }
+}
+
+static const pyseg_kernels kernels_avx2 = {"avx2", gemm_nt_avx2, lstm_cell_avx2};
+
+/* AVX2 also needs the operating system to have enabled the wider register
+ * state, which __builtin_cpu_supports checks along with the feature bits. */
+static int cpu_has_avx2(void) {
+# if defined(__has_builtin)
+# if __has_builtin(__builtin_cpu_init)
+ __builtin_cpu_init();
+# endif
+# elif defined(__GNUC__)
+ __builtin_cpu_init();
+# endif
+ return __builtin_cpu_supports("avx2") && __builtin_cpu_supports("fma");
+}
+#endif /* x86 */
+
+const pyseg_kernels *pyseg_kernels_simd(void) {
+#if defined(PYSEG_X86_DISPATCH)
+ /* Resolved once; the answer cannot change while the process runs. */
+ static const pyseg_kernels *chosen;
+ if (!chosen)
+ chosen = cpu_has_avx2() ? &kernels_avx2 : &kernels_scalar;
+ return chosen;
+#elif defined(PYSEG_HAVE_SIMD)
+ return &kernels_simd;
+#else
+ return &kernels_scalar;
+#endif
+}
diff --git a/src/kernels.h b/src/kernels.h
new file mode 100644
index 0000000..678b844
--- /dev/null
+++ b/src/kernels.h
@@ -0,0 +1,67 @@
+/* The single dense primitive behind the whole forward pass.
+ *
+ * Every layer of this model computes, for a run of output positions, the dot
+ * products of a window of activations against a fixed set of weight rows. The
+ * convolutions reach that form because activations are stored time-major: the
+ * taps a kernel-5 convolution needs for one output step are five consecutive
+ * frames, which is one contiguous span, and the next output step starts one
+ * frame later. The sinc filterbank is the same thing with a span of 251
+ * samples advancing ten samples at a time. So the only parameter that changes
+ * between layers is how far apart consecutive windows start, which is what
+ * lda is; it is unrelated to the window length k.
+ *
+ * Taking every output position in one call is what makes this fast. A single
+ * position would re-read the whole weight matrix; taking four at a time reuses
+ * each loaded weight vector four times, and the outer panel loop keeps the
+ * activations that those four rows share resident in L1 while the weights
+ * stream past once.
+ *
+ * Both implementations are always compiled and chosen through this table, so
+ * one binary can compare them.
+ */
+
+#ifndef PYSEG_KERNELS_H
+#define PYSEG_KERNELS_H
+
+/* Output rows processed against the full weight matrix before moving on. Sized
+ * so the activation window and the output panel together stay inside L1. */
+#define PYSEG_MPANEL 32
+
+typedef struct {
+ const char *name;
+
+ /* For s in 0..m-1 and i in 0..n-1:
+ * y[s*ldy + i] = (bias ? bias[i] : 0) + dot(a + s*lda, w + i*k, k)
+ * k must be a multiple of four. */
+ void (*gemm_nt)(float *y,
+ int ldy,
+ const float *a,
+ int lda,
+ const float *w,
+ const float *bias,
+ int m,
+ int n,
+ int k);
+
+ /* One LSTM cell update in place. The preactivations are the sum of rec,
+ * the hidden-to-hidden product, and in, the projected input for this
+ * time step; both hold the four gate blocks in PyTorch's order, input then
+ * forget then candidate then output, each hid long:
+ * c = sigmoid(f) * c + sigmoid(i) * tanh(g)
+ * h = sigmoid(o) * tanh(c)
+ *
+ * This is here rather than in the forward pass because it is not a
+ * negligible epilogue. A window drives 4712 cell updates, which is three
+ * million logistic and hyperbolic evaluations; called one at a time
+ * through libm that costs more than either convolution stage. hid is a
+ * multiple of four. */
+ void (*lstm_cell)(float *h, float *c, const float *rec, const float *in, int hid);
+} pyseg_kernels;
+
+const pyseg_kernels *pyseg_kernels_scalar(void);
+
+/* The best set this build supports; equals the scalar set on architectures
+ * without an implementation here. */
+const pyseg_kernels *pyseg_kernels_simd(void);
+
+#endif /* PYSEG_KERNELS_H */
diff --git a/src/pyseg.c b/src/pyseg.c
new file mode 100644
index 0000000..6860d54
--- /dev/null
+++ b/src/pyseg.c
@@ -0,0 +1,503 @@
+/* pyannote/segmentation-3.0 forward pass.
+ *
+ * Per window: normalise the waveform, one 251-tap filterbank and two ordinary
+ * convolutions each followed by max-pooling and per-channel normalisation, a
+ * four-layer bidirectional LSTM over the resulting 589 frames, two feed-forward
+ * layers and a seven-way softmax. Every buffer is allocated once in
+ * pyseg_create and reused, so a window costs no allocation, no syscall and no
+ * lock. The working set is 5.4 MB of activations plus 6 MB of read-only
+ * weights, which are shared by every engine mapping the same blob.
+ *
+ * Activations are stored time-major throughout, so the taps a convolution
+ * needs for one output step are one contiguous span and the whole network,
+ * convolutions included, runs through the single kernel in kernels.h.
+ *
+ * The convolutions are computed in tiles whose outputs are max-pooled on the
+ * spot. Only the pooled result is ever stored: the filterbank produces 15975
+ * steps of 80 channels, 5.1 MB, of which only the 1.7 MB pooled form is needed
+ * downstream, and the same holds for the two later stages. */
+
+#include "pyseg.h"
+
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "kernels.h"
+#include "weights.h"
+
+/* Stage geometry. Each convolution is followed by max-pooling by three, so
+ * only a multiple of three of its output steps is ever used; the last one or
+ * two steps of the later stages fall off the end and are not computed. */
+#define SINC_K 256 /* 251 taps padded with five zero weights */
+#define SINC_HOP 10 /* filterbank stride */
+#define C1 80 /* filterbank channels */
+#define T1 15975 /* filterbank output steps */
+#define P1 5325 /* after pooling */
+
+#define C2 60
+#define K2 400 /* five taps of 80 channels */
+#define T2 5319 /* of 5321 produced by a valid kernel-5 convolution */
+#define P2 1773
+
+#define C3 60
+#define K3 300 /* five taps of 60 channels */
+#define T3 1767 /* of 1769 */
+#define P3 PYSEG_FRAMES
+
+#define HID 128
+#define GATES (4 * HID)
+#define BIDIR (2 * HID)
+
+/* Output steps per convolution tile. A multiple of three so pooling groups
+ * never straddle a tile boundary, and small enough that the tile stays in L1
+ * while the weights stream past. */
+#define TILE 384
+
+#define INSTANCE_NORM_EPS 1e-5
+#define LEAKY_SLOPE 0.01f
+
+/* Per-window buffer lengths, in floats. Everything before the LSTM is scratch
+ * shared by the windows of a batch, because they run through the front end one
+ * at a time; from the LSTM on, a batch is processed together and each window
+ * needs its own. */
+#define FEAT_STRIDE ((size_t)PYSEG_FRAMES * C3)
+#define PRE_STRIDE ((size_t)PYSEG_FRAMES * GATES)
+#define ACT_STRIDE ((size_t)PYSEG_FRAMES * BIDIR)
+
+struct pyseg {
+ const pyseg_kernels *k;
+ pyseg_weights w;
+ int ftz;
+ int batch;
+
+ void *map;
+ size_t map_len;
+ size_t arena_bytes;
+
+ void *arena;
+ float *wav; /* [PYSEG_WINDOW_SAMPLES + 8] */
+ float *pool1; /* [P1][C1] */
+ float *pool2; /* [P2][C2] */
+ float *tile; /* [TILE][C1] */
+ float *feat; /* [batch][P3][C3] */
+ float *pre; /* [batch][PYSEG_FRAMES][GATES] */
+ float *acta; /* [batch][PYSEG_FRAMES][BIDIR] */
+ float *actb; /* [batch][PYSEG_FRAMES][BIDIR] */
+ float *gates; /* [batch][GATES] */
+ float *state; /* [2][batch][HID]: hidden then cell */
+};
+
+/* ---- denormal handling ------------------------------------------------
+ *
+ * The LSTM cell state decays toward zero across long silences, and denormal
+ * operands are slow on several targets. Flushing them is scoped to the call so
+ * the library never leaves the caller's floating point mode altered. */
+
+typedef struct {
+ unsigned long long saved;
+ int active;
+} fp_scope;
+
+#if defined(__aarch64__)
+# define FPCR_FZ (1ull << 24)
+static inline void fp_scope_enter(fp_scope *s, int enable) {
+ s->active = enable;
+ if (!enable)
+ return;
+ unsigned long long r;
+ __asm__ __volatile__("mrs %0, fpcr" : "=r"(r));
+ s->saved = r;
+ if (!(r & FPCR_FZ))
+ __asm__ __volatile__("msr fpcr, %0" : : "r"(r | FPCR_FZ));
+}
+static inline void fp_scope_leave(const fp_scope *s) {
+ if (s->active)
+ __asm__ __volatile__("msr fpcr, %0" : : "r"(s->saved));
+}
+#elif defined(__SSE2__) || defined(__x86_64__) || defined(_M_X64)
+# include <xmmintrin.h>
+/* Bit 15 of MXCSR flushes a denormal result to zero. The neighbouring
+ * denormals-are-zero bit is left alone: it only affects denormal inputs, and
+ * it is absent on the earliest x86-64 parts, where writing it would fault. */
+# define MXCSR_FTZ 0x8000u
+static inline void fp_scope_enter(fp_scope *s, int enable) {
+ s->active = enable;
+ if (!enable)
+ return;
+ s->saved = _mm_getcsr();
+ _mm_setcsr((unsigned)s->saved | MXCSR_FTZ);
+}
+static inline void fp_scope_leave(const fp_scope *s) {
+ if (s->active)
+ _mm_setcsr((unsigned)s->saved);
+}
+#else
+static inline void fp_scope_enter(fp_scope *s, int enable) {
+ s->saved = 0;
+ s->active = enable;
+}
+static inline void fp_scope_leave(const fp_scope *s) { (void)s; }
+#endif
+
+/* ---- pointwise ------------------------------------------------------- */
+
+static inline float leaky_(float x) { return x >= 0.0f ? x : LEAKY_SLOPE * x; }
+
+/* ---- normalisation ----------------------------------------------------
+ *
+ * InstanceNorm1d over the whole window, one statistic pair per channel. The
+ * moments are accumulated in double and the deviations in a second pass: the
+ * filterbank output runs to five significant digits over 5325 steps, and a
+ * single-pass float variance loses the low ones to cancellation.
+ *
+ * This is also why the model cannot be run as a stream. Every frame's value
+ * depends on statistics of the entire ten-second window. */
+#define MAX_CHANNELS C1
+
+static void instance_norm_leaky(float *x, int steps, int ch, const float *scale, const float *shift) {
+ double mean[MAX_CHANNELS], inv[MAX_CHANNELS];
+
+ for (int c = 0; c < ch; ++c)
+ mean[c] = 0.0;
+ for (int t = 0; t < steps; ++t) {
+ const float *row = x + (size_t)t * ch;
+ for (int c = 0; c < ch; ++c)
+ mean[c] += row[c];
+ }
+ for (int c = 0; c < ch; ++c)
+ mean[c] /= steps;
+
+ for (int c = 0; c < ch; ++c)
+ inv[c] = 0.0;
+ for (int t = 0; t < steps; ++t) {
+ const float *row = x + (size_t)t * ch;
+ for (int c = 0; c < ch; ++c) {
+ const double d = row[c] - mean[c];
+ inv[c] += d * d;
+ }
+ }
+ for (int c = 0; c < ch; ++c)
+ inv[c] = 1.0 / sqrt(inv[c] / steps + INSTANCE_NORM_EPS);
+
+ for (int t = 0; t < steps; ++t) {
+ float *row = x + (size_t)t * ch;
+ for (int c = 0; c < ch; ++c)
+ row[c] = leaky_((float)((row[c] - mean[c]) * inv[c] * scale[c] + shift[c]));
+ }
+}
+
+/* ---- convolution stages ----------------------------------------------
+ *
+ * One call covers a whole stage: convolution, optional magnitude, pooling by
+ * three, then the channel statistics. lda is how far apart consecutive
+ * output windows start in the source, which is the filterbank's hop for the
+ * first stage and one frame for the later ones. */
+static void conv_pool_norm(pyseg_t *v,
+ float *dst,
+ const float *src,
+ int lda,
+ const float *weight,
+ const float *bias,
+ int steps,
+ int ch,
+ int k,
+ int take_abs,
+ const float *scale,
+ const float *shift) {
+ for (int t0 = 0; t0 < steps; t0 += TILE) {
+ const int n = steps - t0 < TILE ? steps - t0 : TILE;
+ v->k->gemm_nt(v->tile, ch, src + (size_t)t0 * lda, lda, weight, bias, n, ch, k);
+
+ float *out = dst + (size_t)(t0 / 3) * ch;
+ for (int p = 0; p < n / 3; ++p) {
+ const float *a = v->tile + (size_t)(3 * p) * ch;
+ const float *b = a + ch, *c = b + ch;
+ float *o = out + (size_t)p * ch;
+ if (take_abs) {
+ for (int i = 0; i < ch; ++i) {
+ const float x = fabsf(a[i]), y = fabsf(b[i]), z = fabsf(c[i]);
+ o[i] = x > y ? (x > z ? x : z) : (y > z ? y : z);
+ }
+ } else {
+ for (int i = 0; i < ch; ++i) {
+ const float x = a[i], y = b[i], z = c[i];
+ o[i] = x > y ? (x > z ? x : z) : (y > z ? y : z);
+ }
+ }
+ }
+ }
+ instance_norm_leaky(dst, steps / 3, ch, scale, shift);
+}
+
+/* ---- LSTM -------------------------------------------------------------
+ *
+ * The input projection of every time step shares one weight matrix, so it runs
+ * as a single pass over every step of every window in the batch before the
+ * recurrence starts, which is three fifths of the layer's arithmetic done at
+ * full matrix-multiply efficiency.
+ *
+ * What is left is the hidden-to-hidden product, one per step, and it is the
+ * reason batching exists. On its own it reads a 256 KB weight matrix to
+ * perform 65536 multiply-adds, so it runs at the speed of memory rather than
+ * of arithmetic and is the single most expensive part of a window. Windows are
+ * independent, so running several of them in step turns that matrix-vector
+ * product into a small matrix-matrix product: one weight load then serves
+ * every window, and the recurrence speeds up by better than a factor of two at
+ * a batch of four. */
+static void lstm_direction(pyseg_t *v,
+ int count,
+ const float *in,
+ int lda,
+ int k,
+ const pyseg_lstm_weights *w,
+ float *out,
+ int offset,
+ int reverse) {
+ v->k->gemm_nt(v->pre, GATES, in, lda, w->ih, w->bias, count * PYSEG_FRAMES, GATES, k);
+
+ float *h = v->state, *c = v->state + (size_t)v->batch * HID;
+ memset(h, 0, (size_t)count * HID * sizeof(float));
+ memset(c, 0, (size_t)count * HID * sizeof(float));
+
+ for (int step = 0; step < PYSEG_FRAMES; ++step) {
+ const int t = reverse ? PYSEG_FRAMES - 1 - step : step;
+ v->k->gemm_nt(v->gates, GATES, h, HID, w->hh, NULL, count, GATES, HID);
+ for (int b = 0; b < count; ++b) {
+ float *hb = h + (size_t)b * HID;
+ v->k->lstm_cell(hb, c + (size_t)b * HID, v->gates + (size_t)b * GATES,
+ v->pre + (size_t)b * PRE_STRIDE + (size_t)t * GATES, HID);
+ memcpy(out + (size_t)b * ACT_STRIDE + (size_t)t * BIDIR + offset, hb,
+ HID * sizeof(float));
+ }
+ }
+}
+
+/* ---- forward pass ---------------------------------------------------- */
+
+/* Everything up to the LSTM, for one window of the batch. */
+static void front_end(pyseg_t *v, int slot) {
+ const pyseg_weights *w = &v->w;
+
+ /* Waveform normalisation: one channel, statistics over the whole window. */
+ {
+ double mean = 0.0, var = 0.0;
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ mean += v->wav[i];
+ mean /= PYSEG_WINDOW_SAMPLES;
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i) {
+ const double d = v->wav[i] - mean;
+ var += d * d;
+ }
+ const double inv = 1.0 / sqrt(var / PYSEG_WINDOW_SAMPLES + INSTANCE_NORM_EPS);
+ const float scale = w->wavnorm[0], shift = w->wavnorm[1];
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ v->wav[i] = (float)((v->wav[i] - mean) * inv) * scale + shift;
+ }
+
+ conv_pool_norm(v, v->pool1, v->wav, SINC_HOP, w->sinc_w, NULL, T1, C1, SINC_K, 1, w->norm_w[0],
+ w->norm_b[0]);
+ conv_pool_norm(v, v->pool2, v->pool1, C1, w->conv_w[0], w->conv_b[0], T2, C2, K2, 0, w->norm_w[1],
+ w->norm_b[1]);
+ conv_pool_norm(v, v->feat + (size_t)slot * FEAT_STRIDE, v->pool2, C2, w->conv_w[1], w->conv_b[1],
+ T3, C3, K3, 0, w->norm_w[2], w->norm_b[2]);
+}
+
+/* The LSTM stack, the feed-forward layers and the softmax, over a whole batch
+ * whose features the front end has already produced. */
+static void back_end(pyseg_t *v, int count, float *probs) {
+ const pyseg_weights *w = &v->w;
+ const pyseg_kernels *k = v->k;
+ const int rows = count * PYSEG_FRAMES;
+
+ lstm_direction(v, count, v->feat, C3, C3, &w->lstm[0][0], v->acta, 0, 0);
+ lstm_direction(v, count, v->feat, C3, C3, &w->lstm[0][1], v->acta, HID, 1);
+ for (int layer = 1; layer < 4; ++layer) {
+ const float *in = (layer & 1) ? v->acta : v->actb;
+ float *out = (layer & 1) ? v->actb : v->acta;
+ lstm_direction(v, count, in, BIDIR, BIDIR, &w->lstm[layer][0], out, 0, 0);
+ lstm_direction(v, count, in, BIDIR, BIDIR, &w->lstm[layer][1], out, HID, 1);
+ }
+
+ /* Layer 3 wrote actb; the feed-forward stack then ping-pongs back. Both
+ * layers are narrower than what they read, so writing over the buffer the
+ * previous layer occupied is safe. */
+ k->gemm_nt(v->acta, HID, v->actb, BIDIR, w->lin_w[0], w->lin_b[0], rows, HID, BIDIR);
+ for (int i = 0; i < rows * HID; ++i)
+ v->acta[i] = leaky_(v->acta[i]);
+ k->gemm_nt(v->actb, HID, v->acta, HID, w->lin_w[1], w->lin_b[1], rows, HID, HID);
+ for (int i = 0; i < rows * HID; ++i)
+ v->actb[i] = leaky_(v->actb[i]);
+
+ k->gemm_nt(probs, PYSEG_CLASSES, v->actb, HID, w->cls_w, w->cls_b, rows, PYSEG_CLASSES, HID);
+
+ for (int t = 0; t < rows; ++t) {
+ float *row = probs + (size_t)t * PYSEG_CLASSES;
+ float max = row[0];
+ for (int i = 1; i < PYSEG_CLASSES; ++i)
+ if (row[i] > max)
+ max = row[i];
+ float sum = 0.0f;
+ for (int i = 0; i < PYSEG_CLASSES; ++i) {
+ row[i] = expf(row[i] - max);
+ sum += row[i];
+ }
+ const float inv = 1.0f / sum;
+ for (int i = 0; i < PYSEG_CLASSES; ++i)
+ row[i] *= inv;
+ }
+}
+
+/* ---- lifecycle ------------------------------------------------------- */
+
+pyseg_t *pyseg_create_batch(const char *path, unsigned flags, int batch) {
+ if (batch < 1 || batch > PYSEG_MAX_BATCH)
+ return NULL;
+
+ pyseg_t *v = calloc(1, sizeof *v);
+ if (!v)
+ return NULL;
+ v->batch = batch;
+
+ if (path) {
+ const int verify = !(flags & PYSEG_NO_VERIFY);
+ if (pyseg_weights_map(path, verify, &v->w, &v->map, &v->map_len) != 0) {
+ free(v);
+ return NULL;
+ }
+ } else {
+ size_t len = 0;
+ const void *blob = pyseg_weights_embedded(&len);
+ if (!blob || pyseg_weights_parse(blob, len, 0, &v->w) != 0) {
+ free(v);
+ return NULL;
+ }
+ }
+
+ /* One allocation, carved into 64-byte aligned buffers in this order. */
+ const size_t b = (size_t)batch;
+ const size_t sizes[] = {
+ PYSEG_WINDOW_SAMPLES + 8, /* wav, with slack past the last filter window */
+ (size_t)P1 * C1, /* pool1 */
+ (size_t)P2 * C2, /* pool2 */
+ (size_t)TILE * C1, /* tile */
+ b * FEAT_STRIDE, /* feat */
+ b * PRE_STRIDE, /* pre */
+ b * ACT_STRIDE, /* acta */
+ b * ACT_STRIDE, /* actb */
+ b * GATES, /* gates */
+ 2 * b * HID, /* state */
+ };
+ float **slots[] = {&v->wav, &v->pool1, &v->pool2, &v->tile, &v->feat,
+ &v->pre, &v->acta, &v->actb, &v->gates, &v->state};
+
+ size_t total = 0;
+ for (size_t i = 0; i < sizeof sizes / sizeof *sizes; ++i)
+ total += (sizes[i] * sizeof(float) + 63) / 64 * 64;
+ if (posix_memalign(&v->arena, 64, total) != 0 || !v->arena) {
+ pyseg_weights_unmap(v->map, v->map_len);
+ free(v);
+ return NULL;
+ }
+ memset(v->arena, 0, total);
+ v->arena_bytes = total;
+
+ unsigned char *p = v->arena;
+ for (size_t i = 0; i < sizeof sizes / sizeof *sizes; ++i) {
+ *slots[i] = (float *)(void *)p;
+ p += (sizes[i] * sizeof(float) + 63) / 64 * 64;
+ }
+
+ v->k = (flags & PYSEG_SCALAR_KERNELS) ? pyseg_kernels_scalar() : pyseg_kernels_simd();
+ v->ftz = (flags & PYSEG_NO_FTZ) == 0;
+ return v;
+}
+
+pyseg_t *pyseg_create_ex(const char *path, unsigned flags) {
+ return pyseg_create_batch(path, flags, 1);
+}
+
+pyseg_t *pyseg_create(void) { return pyseg_create_ex(NULL, 0); }
+
+pyseg_t *pyseg_create_from_file(const char *path) { return pyseg_create_ex(path, 0); }
+
+void pyseg_destroy(pyseg_t *v) {
+ if (!v)
+ return;
+ pyseg_weights_unmap(v->map, v->map_len);
+ free(v->arena);
+ free(v);
+}
+
+const char *pyseg_backend_name(const pyseg_t *v) { return v->k->name; }
+
+int pyseg_batch(const pyseg_t *v) { return v->batch; }
+
+size_t pyseg_memory_bytes(const pyseg_t *v) {
+ return sizeof *v + v->arena_bytes + (v->map ? v->map_len : 0);
+}
+
+/* ---- entry points ----------------------------------------------------- */
+
+void pyseg_process_batch_f32(pyseg_t *v, const float *samples, int count, float *probs) {
+ if (count < 1 || count > v->batch)
+ return;
+ fp_scope fp;
+ fp_scope_enter(&fp, v->ftz);
+ for (int b = 0; b < count; ++b) {
+ memcpy(v->wav, samples + (size_t)b * PYSEG_WINDOW_SAMPLES,
+ PYSEG_WINDOW_SAMPLES * sizeof(float));
+ front_end(v, b);
+ }
+ back_end(v, count, probs);
+ fp_scope_leave(&fp);
+}
+
+void pyseg_process_f32(pyseg_t *v, const float *samples, float *probs) {
+ pyseg_process_batch_f32(v, samples, 1, probs);
+}
+
+void pyseg_process_s16(pyseg_t *v, const int16_t *samples, float *probs) {
+ fp_scope fp;
+ fp_scope_enter(&fp, v->ftz);
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ v->wav[i] = (float)samples[i] * (1.0f / 32768.0f);
+ front_end(v, 0);
+ back_end(v, 1, probs);
+ fp_scope_leave(&fp);
+}
+
+/* ---- powerset decoding -----------------------------------------------
+ *
+ * The seven classes are, in order, the empty set, the three singletons and the
+ * three pairs, which is the order itertools.combinations produces and the
+ * order the classifier was trained in. */
+static const unsigned char powerset_members[PYSEG_CLASSES] = {
+ 0x0, 0x1, 0x2, 0x4, 0x3, 0x5, 0x6,
+};
+
+void pyseg_to_multilabel(const float *probs, float *active) {
+ for (int t = 0; t < PYSEG_FRAMES; ++t) {
+ const float *row = probs + (size_t)t * PYSEG_CLASSES;
+ int best = 0;
+ for (int i = 1; i < PYSEG_CLASSES; ++i)
+ if (row[i] > row[best])
+ best = i;
+ const unsigned mask = powerset_members[best];
+ float *out = active + (size_t)t * PYSEG_SPEAKERS;
+ for (int s = 0; s < PYSEG_SPEAKERS; ++s)
+ out[s] = (mask >> s) & 1u ? 1.0f : 0.0f;
+ }
+}
+
+int pyseg_powerset_class(int speaker_a, int speaker_b) {
+ unsigned mask = 0;
+ if (speaker_a >= 0)
+ mask |= 1u << speaker_a;
+ if (speaker_b >= 0)
+ mask |= 1u << speaker_b;
+ for (int i = 0; i < PYSEG_CLASSES; ++i)
+ if (powerset_members[i] == mask)
+ return i;
+ return -1;
+}
diff --git a/src/pyseg.h b/src/pyseg.h
new file mode 100644
index 0000000..b08f7b3
--- /dev/null
+++ b/src/pyseg.h
@@ -0,0 +1,215 @@
+/* pyseg: pyannote/segmentation-3.0 speaker segmentation in portable C.
+ *
+ * The model reads exactly ten seconds of 16 kHz mono audio and returns, for
+ * each of 589 output frames, a distribution over seven classes: no speaker,
+ * one of three speakers alone, or one of the three pairs. That "powerset"
+ * encoding is what the model was trained on; pyseg_to_multilabel turns it into
+ * per-speaker activity, and the sliding-window driver in this header turns a
+ * recording of any length into speech, overlap and speaker-count tracks.
+ *
+ * Speaker identities hold only inside a single window. Two windows that
+ * overlap may number the same person differently, so joining windows into
+ * whole-recording speakers needs a speaker embedding model, which is outside
+ * the scope of this library. Speech activity, overlapped speech and the
+ * per-frame speaker count do carry across windows and are what the sliding
+ * window aggregates.
+ *
+ * One engine handles one window at a time and owns all its scratch, so a
+ * process runs as many engines as it has threads. No allocation, no syscall
+ * and no lock happens inside pyseg_process. */
+
+#ifndef PYSEG_H
+#define PYSEG_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define PYSEG_VERSION_MAJOR 1
+#define PYSEG_VERSION_MINOR 0
+
+#define PYSEG_SAMPLE_RATE 16000
+#define PYSEG_WINDOW_SAMPLES 160000 /* 10 s */
+#define PYSEG_FRAMES 589
+#define PYSEG_CLASSES 7 /* powerset classes */
+#define PYSEG_SPEAKERS 3
+
+/* Output frame grid, in samples: frame f covers the 991 input samples starting
+ * at f * PYSEG_FRAME_STEP, relative to the start of the window. */
+#define PYSEG_FRAME_STEP 270
+#define PYSEG_FRAME_SIZE 991
+
+/* ---- engine ---------------------------------------------------------- */
+
+typedef struct pyseg pyseg_t;
+
+/* Windows an engine can hold at once, and engines pyseg_slide will run at
+ * once. Both are bounded so a caller cannot turn a large number into an
+ * allocation proportional to it: each engine holds several megabytes. */
+#define PYSEG_MAX_BATCH 64
+#define PYSEG_MAX_THREADS 256
+
+/* Creation flags. The defaults (0) select the fastest kernels available. */
+enum {
+ PYSEG_SCALAR_KERNELS = 1u << 0, /* portable C kernels, no SIMD intrinsics */
+ PYSEG_NO_FTZ = 1u << 1, /* leave denormal handling to the caller */
+ PYSEG_NO_VERIFY = 1u << 2, /* skip checksum verification of a weight file */
+};
+
+/* Uses the weights compiled into the binary. Returns NULL when the build has
+ * none, or on allocation failure. */
+pyseg_t *pyseg_create(void);
+
+/* Reads a blob produced by tools/export_weights.py. The mapping is private to
+ * the engine and released by pyseg_destroy. */
+pyseg_t *pyseg_create_from_file(const char *path);
+
+pyseg_t *pyseg_create_ex(const char *path, unsigned flags);
+
+/* An engine that processes batch windows per call.
+ *
+ * Batching exists for one reason: the LSTM recurrence reads a 256 KB weight
+ * matrix per time step to do 65536 multiply-adds, so on its own it runs at the
+ * speed of memory. Windows are independent, so several of them stepped
+ * together share each weight load, and a batch of four cuts the recurrence,
+ * which is nearly half of a window's cost, by better than half.
+ *
+ * The price is memory: the front end's scratch is shared, but each window
+ * needs about 2.5 MB of its own from the LSTM on. A batch of one is the
+ * smallest footprint and the lowest latency for a single window; four is the
+ * best throughput per byte on the machines measured. Batches are also the
+ * wrong lever for using more cores; for that, run one engine per thread.
+ *
+ * Returns NULL for a batch outside 1..PYSEG_MAX_BATCH. */
+pyseg_t *pyseg_create_batch(const char *path, unsigned flags, int batch);
+
+int pyseg_batch(const pyseg_t *v);
+
+void pyseg_destroy(pyseg_t *v);
+
+/* Name of the active kernel set, for logs and benchmark output. */
+const char *pyseg_backend_name(const pyseg_t *v);
+
+/* Bytes of scratch and weights the engine holds, for capacity planning. */
+size_t pyseg_memory_bytes(const pyseg_t *v);
+
+/* One window. samples holds PYSEG_WINDOW_SAMPLES values; the f32 variant
+ * expects [-1, 1] and the s16 variant is scaled by 1/32768 to match. probs
+ * receives PYSEG_FRAMES * PYSEG_CLASSES values, frame-major, each frame a
+ * distribution summing to one. */
+void pyseg_process_f32(pyseg_t *v, const float *samples, float *probs);
+void pyseg_process_s16(pyseg_t *v, const int16_t *samples, float *probs);
+
+/* count consecutive windows, at most pyseg_batch(); outside that range the
+ * call does nothing and leaves probs untouched. samples holds
+ * count * PYSEG_WINDOW_SAMPLES values and probs receives
+ * count * PYSEG_FRAMES * PYSEG_CLASSES, both window-major. Results do not
+ * depend on how windows are grouped into batches, only on the windows
+ * themselves. */
+void pyseg_process_batch_f32(pyseg_t *v, const float *samples, int count, float *probs);
+
+/* ---- powerset decoding ----------------------------------------------- */
+
+/* Per-frame speaker activity from powerset probabilities: active receives
+ * PYSEG_FRAMES * PYSEG_SPEAKERS values, 1.0 where the most likely class
+ * contains that speaker and 0.0 elsewhere. This is the hard decoding pyannote
+ * uses; it is not a per-speaker probability. */
+void pyseg_to_multilabel(const float *probs, float *active);
+
+/* Class index whose members are exactly the given speaker set, for tests. */
+int pyseg_powerset_class(int speaker_a, int speaker_b);
+
+/* ---- sliding window over a whole recording --------------------------- */
+
+/* Tracks produced per aggregated frame, in this order. */
+enum {
+ PYSEG_TRACK_SPEECH = 0, /* at least one speaker */
+ PYSEG_TRACK_OVERLAP = 1, /* at least two speakers */
+ PYSEG_TRACK_COUNT = 2, /* expected number of speakers */
+ PYSEG_TRACKS = 3,
+};
+
+typedef struct {
+ /* Seconds between consecutive windows. pyannote's default is 1.0, one
+ * tenth of the window, which is also what its pipelines are tuned for.
+ * Larger steps cost proportionally less and blur the aggregate. */
+ double step;
+ /* Threads used for the window loop. 0 or 1 runs on the calling thread;
+ * more than PYSEG_MAX_THREADS is clamped to it. */
+ int threads;
+ /* Windows each thread's engine processes per call; see
+ * pyseg_create_batch. 0 selects the default. */
+ int batch;
+ /* Passed to pyseg_create_ex for the per-thread engines. */
+ unsigned flags;
+ /* Weight file for those engines; NULL uses the embedded blob. */
+ const char *weights;
+} pyseg_slide_params;
+
+void pyseg_slide_params_default(pyseg_slide_params *p);
+
+/* Number of aggregated frames a recording of num_samples produces. */
+size_t pyseg_slide_frames(size_t num_samples, double step);
+
+/* Runs the model over the whole recording and overlap-adds the windows the way
+ * pyannote's Inference does: a Hamming taper across each window's frames, then
+ * a weighted average per frame. tracks receives
+ * pyseg_slide_frames() * PYSEG_TRACKS values, frame-major.
+ *
+ * Returns the number of aggregated frames, or 0 on failure. */
+size_t pyseg_slide(const float *samples,
+ size_t num_samples,
+ const pyseg_slide_params *params,
+ float *tracks);
+
+/* The same over 16-bit samples, scaled by 1/32768 one window at a time.
+ * Recordings arrive as 16-bit PCM, and holding an hour of it as float32 costs
+ * 230 MB against 115 MB, more than everything else this library allocates put
+ * together. */
+size_t pyseg_slide_s16(const int16_t *samples,
+ size_t num_samples,
+ const pyseg_slide_params *params,
+ float *tracks);
+
+/* Seconds covered by aggregated frame f. The grid matches the model's own
+ * receptive field, so frame centres are PYSEG_FRAME_STEP samples apart. */
+double pyseg_frame_time(size_t frame);
+
+/* ---- binarization ---------------------------------------------------- */
+
+typedef struct {
+ double start;
+ double end;
+} pyseg_segment;
+
+typedef struct {
+ double onset; /* enter a region above this score */
+ double offset; /* leave it below this one */
+ double min_duration_on; /* drop regions shorter than this, in seconds */
+ double min_duration_off; /* fill gaps shorter than this, in seconds */
+} pyseg_binarize_params;
+
+void pyseg_binarize_params_default(pyseg_binarize_params *p);
+
+/* Turns one track of an aggregated score sequence into segments, mirroring
+ * pyannote.audio.utils.signal.Binarize. scores is strided by PYSEG_TRACKS.
+ *
+ * Returns the number of segments found. Nothing is written unless the whole
+ * list fits, because the gap-filling pass is defined over the complete list;
+ * when out is NULL or too small, size a buffer from the return value and
+ * call again. */
+size_t pyseg_binarize(const float *scores,
+ size_t num_frames,
+ int track,
+ const pyseg_binarize_params *params,
+ pyseg_segment *out,
+ size_t out_cap);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PYSEG_H */
diff --git a/src/pyseg_cli.c b/src/pyseg_cli.c
new file mode 100644
index 0000000..f694f57
--- /dev/null
+++ b/src/pyseg_cli.c
@@ -0,0 +1,176 @@
+/* Command line front end: a 16 kHz mono WAV in, segments or frame scores out. */
+
+#include "pyseg.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "wav.h"
+
+static const char *usage = "usage: pyseg_cli [options] file.wav\n"
+ "\n"
+ " --mode speech|overlap|count|frames what to print (default speech)\n"
+ " --step SECONDS window hop, default 1.0 (a tenth of the window)\n"
+ " --threads N windows to run in parallel, default 1\n"
+ " --batch N windows per engine call, default 4\n"
+ " --weights FILE weight blob; default is the embedded copy\n"
+ " --onset X score above which a region opens, default 0.5\n"
+ " --offset X score below which it closes, default 0.5\n"
+ " --min-on SECONDS drop regions shorter than this, default 0\n"
+ " --min-off SECONDS fill gaps shorter than this, default 0\n"
+ " --scalar portable C kernels instead of SIMD\n"
+ "\n"
+ "speech and overlap print [start end] pairs in seconds; count and frames\n"
+ "print one line per frame.\n";
+
+enum { MODE_SPEECH, MODE_OVERLAP, MODE_COUNT, MODE_FRAMES };
+
+static int parse_mode(const char *s, int *mode) {
+ if (strcmp(s, "speech") == 0 || strcmp(s, "vad") == 0)
+ *mode = MODE_SPEECH;
+ else if (strcmp(s, "overlap") == 0 || strcmp(s, "osd") == 0)
+ *mode = MODE_OVERLAP;
+ else if (strcmp(s, "count") == 0)
+ *mode = MODE_COUNT;
+ else if (strcmp(s, "frames") == 0)
+ *mode = MODE_FRAMES;
+ else
+ return -1;
+ return 0;
+}
+
+int main(int argc, char **argv) {
+ pyseg_slide_params slide;
+ pyseg_binarize_params bin;
+ pyseg_slide_params_default(&slide);
+ pyseg_binarize_params_default(&bin);
+
+ int mode = MODE_SPEECH;
+ const char *path = NULL;
+
+ for (int i = 1; i < argc; ++i) {
+ const char *a = argv[i];
+ const char *v = (i + 1 < argc) ? argv[i + 1] : NULL;
+#define NEED(name) \
+ if (!v) { \
+ fprintf(stderr, "%s needs a value\n", name); \
+ return 2; \
+ }
+ if (strcmp(a, "--mode") == 0) {
+ NEED("--mode");
+ if (parse_mode(v, &mode) != 0) {
+ fprintf(stderr, "unknown mode: %s\n", v);
+ return 2;
+ }
+ ++i;
+ } else if (strcmp(a, "--step") == 0) {
+ NEED("--step");
+ slide.step = atof(v);
+ ++i;
+ } else if (strcmp(a, "--threads") == 0) {
+ NEED("--threads");
+ slide.threads = atoi(v);
+ ++i;
+ } else if (strcmp(a, "--batch") == 0) {
+ NEED("--batch");
+ slide.batch = atoi(v);
+ ++i;
+ } else if (strcmp(a, "--weights") == 0) {
+ NEED("--weights");
+ slide.weights = v;
+ ++i;
+ } else if (strcmp(a, "--onset") == 0) {
+ NEED("--onset");
+ bin.onset = atof(v);
+ ++i;
+ } else if (strcmp(a, "--offset") == 0) {
+ NEED("--offset");
+ bin.offset = atof(v);
+ ++i;
+ } else if (strcmp(a, "--min-on") == 0) {
+ NEED("--min-on");
+ bin.min_duration_on = atof(v);
+ ++i;
+ } else if (strcmp(a, "--min-off") == 0) {
+ NEED("--min-off");
+ bin.min_duration_off = atof(v);
+ ++i;
+ } else if (strcmp(a, "--scalar") == 0) {
+ slide.flags |= PYSEG_SCALAR_KERNELS;
+ } else if (strcmp(a, "-h") == 0 || strcmp(a, "--help") == 0) {
+ fputs(usage, stdout);
+ return 0;
+ } else if (a[0] == '-') {
+ fprintf(stderr, "unknown option: %s\n%s", a, usage);
+ return 2;
+ } else {
+ path = a;
+ }
+#undef NEED
+ }
+
+ if (!path) {
+ fputs(usage, stderr);
+ return 2;
+ }
+
+ wav_t wav;
+ const char *err = NULL;
+ if (wav_read_mono_s16(path, &wav, &err) != 0) {
+ fprintf(stderr, "%s: %s\n", path, err ? err : "read failed");
+ return 1;
+ }
+ if (wav.sample_rate != PYSEG_SAMPLE_RATE) {
+ fprintf(stderr, "%s: expected %d Hz, got %d\n", path, PYSEG_SAMPLE_RATE, wav.sample_rate);
+ wav_free(&wav);
+ return 1;
+ }
+
+ const size_t count = wav.count;
+ const size_t frames = pyseg_slide_frames(count, slide.step);
+ float *tracks = malloc(frames * PYSEG_TRACKS * sizeof(float));
+ if (!tracks) {
+ wav_free(&wav);
+ return 1;
+ }
+
+ const size_t got = pyseg_slide_s16(wav.samples, count, &slide, tracks);
+ wav_free(&wav);
+ if (got == 0) {
+ fprintf(stderr, "inference failed: no engine could be created%s\n",
+ slide.weights ? " from the given weight file"
+ : "; this build may carry no embedded weights, "
+ "in which case pass --weights pyseg_weights.bin");
+ free(tracks);
+ return 1;
+ }
+
+ if (mode == MODE_FRAMES || mode == MODE_COUNT) {
+ for (size_t f = 0; f < got; ++f) {
+ const float *row = tracks + f * PYSEG_TRACKS;
+ if (mode == MODE_COUNT)
+ printf("%.3f %.4f\n", pyseg_frame_time(f), row[PYSEG_TRACK_COUNT]);
+ else
+ printf("%.3f %.4f %.4f %.4f\n", pyseg_frame_time(f), row[PYSEG_TRACK_SPEECH],
+ row[PYSEG_TRACK_OVERLAP], row[PYSEG_TRACK_COUNT]);
+ }
+ free(tracks);
+ return 0;
+ }
+
+ const int track = mode == MODE_SPEECH ? PYSEG_TRACK_SPEECH : PYSEG_TRACK_OVERLAP;
+ const size_t n = pyseg_binarize(tracks, got, track, &bin, NULL, 0);
+ pyseg_segment *segments = n ? malloc(n * sizeof *segments) : NULL;
+ if (n && !segments) {
+ free(tracks);
+ return 1;
+ }
+ const size_t written = pyseg_binarize(tracks, got, track, &bin, segments, n);
+ for (size_t i = 0; i < written; ++i)
+ printf("%.3f %.3f\n", segments[i].start, segments[i].end);
+
+ free(segments);
+ free(tracks);
+ return 0;
+}
diff --git a/src/slide.c b/src/slide.c
new file mode 100644
index 0000000..be23ec4
--- /dev/null
+++ b/src/slide.c
@@ -0,0 +1,423 @@
+/* Sliding-window inference over a whole recording, and binarization.
+ *
+ * The model sees ten seconds at a time and its per-frame statistics depend on
+ * the whole window, so a recording is covered by overlapping windows and their
+ * frame scores are averaged. pyannote weights that average with a Hamming
+ * taper, which lets a frame near a window's edge, where the LSTM has seen
+ * context on one side only, defer to the window that holds it in the middle.
+ *
+ * Windows are independent, so the loop parallelises exactly. Each thread takes
+ * a contiguous run of windows and accumulates into a private plane covering
+ * only the frames that run reaches; the planes of two adjacent threads overlap
+ * by at most one window's worth of frames, and the main thread sums them at
+ * the end. Contiguous runs rather than interleaved ones are what keeps those
+ * planes small: interleaving would give every thread a plane as large as the
+ * whole recording. */
+
+#include "pyseg.h"
+
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef PYSEG_THREADS
+# include <pthread.h>
+#endif
+
+#define AGG_EPSILON 1e-12f
+
+/* Four windows per engine call: the point at which sharing each LSTM weight
+ * load stops paying for the registers it costs, measured on both an Apple
+ * M-series core and an x86 server core. */
+#define DEFAULT_BATCH 4
+
+void pyseg_slide_params_default(pyseg_slide_params *p) {
+ p->step = 1.0;
+ p->threads = 1;
+ p->batch = DEFAULT_BATCH;
+ p->flags = 0;
+ p->weights = NULL;
+}
+
+void pyseg_binarize_params_default(pyseg_binarize_params *p) {
+ /* The powerset model emits hard per-frame decisions, so an aggregated
+ * score is the fraction of windows that voted yes and the thresholds sit
+ * at one half. pyannote fixes them there for this model rather than
+ * tuning them per corpus. */
+ p->onset = 0.5;
+ p->offset = 0.5;
+ p->min_duration_on = 0.0;
+ p->min_duration_off = 0.0;
+}
+
+double pyseg_frame_time(size_t frame) {
+ return (double)(frame * PYSEG_FRAME_STEP) / PYSEG_SAMPLE_RATE;
+}
+
+/* Centre of a frame, which is where its score is defined and therefore where
+ * segment boundaries land. */
+static double frame_middle(size_t frame) {
+ return pyseg_frame_time(frame) + 0.5 * PYSEG_FRAME_SIZE / PYSEG_SAMPLE_RATE;
+}
+
+/* Rounds n/d to the nearest integer, halves to even, in exact integer
+ * arithmetic. Window starts do not fall on frame boundaries, so which way a
+ * tie goes decides a frame of alignment against the reference. */
+static size_t rint_div(size_t n, size_t d) {
+ const size_t q = n / d, r = n % d;
+ if (2 * r < d)
+ return q;
+ if (2 * r > d)
+ return q + 1;
+ return q + (q & 1);
+}
+
+/* Windows the recording is cut into: the complete ones plus, when the tail
+ * does not land on a window boundary, one zero-padded window covering it. */
+static size_t window_count(size_t num_samples, size_t step_samples) {
+ if (num_samples < PYSEG_WINDOW_SAMPLES)
+ return 1;
+ const size_t whole = (num_samples - PYSEG_WINDOW_SAMPLES) / step_samples + 1;
+ return whole + ((num_samples - PYSEG_WINDOW_SAMPLES) % step_samples > 0 ? 1 : 0);
+}
+
+static size_t step_samples_of(double step) {
+ const double s = step * PYSEG_SAMPLE_RATE + 0.5;
+ return s < 1.0 ? 1 : (size_t)s;
+}
+
+/* First aggregated frame a window starting at sample contributes to. */
+static size_t start_frame_of(size_t sample) { return rint_div(sample, PYSEG_FRAME_STEP); }
+
+size_t pyseg_slide_frames(size_t num_samples, double step) {
+ if (num_samples == 0 || step <= 0.0)
+ return 0;
+ const size_t step_samples = step_samples_of(step);
+ const size_t windows = window_count(num_samples, step_samples);
+ size_t frames =
+ rint_div(PYSEG_WINDOW_SAMPLES + (windows - 1) * step_samples, PYSEG_FRAME_STEP) + 1;
+
+ /* A zero-padded tail window predicts past the end of the recording; those
+ * frames are dropped, as pyannote does after aggregating. */
+ const int padded =
+ num_samples < PYSEG_WINDOW_SAMPLES || (num_samples - PYSEG_WINDOW_SAMPLES) % step_samples > 0;
+ if (padded) {
+ const size_t limit = num_samples / PYSEG_FRAME_STEP + 1;
+ if (limit < frames)
+ frames = limit;
+ }
+ return frames;
+}
+
+/* ---- window loop ------------------------------------------------------ */
+
+typedef struct {
+ const float *samples; /* one of these two is set */
+ const int16_t *samples_s16;
+ size_t num_samples;
+ size_t step_samples;
+ size_t frames;
+ const float *taper; /* [PYSEG_FRAMES] */
+ const char *weights;
+ unsigned flags;
+ int batch;
+} slide_job;
+
+typedef struct {
+ const slide_job *job;
+ size_t first_window, last_window; /* half-open */
+ size_t first_frame, frame_count;
+ float *sum; /* [frame_count][PYSEG_TRACKS] */
+ float *count; /* [frame_count][PYSEG_TRACKS] */
+ int failed;
+} slide_worker;
+
+/* Copies one window out of the recording, zero-filling past the end. */
+static void gather(const slide_job *job, size_t index, float *dst) {
+ const size_t start = index * job->step_samples;
+ size_t n = 0;
+ if (start < job->num_samples) {
+ n = job->num_samples - start;
+ if (n > PYSEG_WINDOW_SAMPLES)
+ n = PYSEG_WINDOW_SAMPLES;
+ if (job->samples)
+ memcpy(dst, job->samples + start, n * sizeof(float));
+ else
+ for (size_t i = 0; i < n; ++i)
+ dst[i] = (float)job->samples_s16[start + i] * (1.0f / 32768.0f);
+ }
+ memset(dst + n, 0, (PYSEG_WINDOW_SAMPLES - n) * sizeof(float));
+}
+
+/* Adds one window's decoded votes into this thread's plane. */
+static void accumulate(slide_worker *self, size_t index, const float *active) {
+ const slide_job *job = self->job;
+ const size_t base = start_frame_of(index * job->step_samples) - self->first_frame;
+ for (int t = 0; t < PYSEG_FRAMES; ++t) {
+ const size_t row = base + (size_t)t;
+ if (row >= self->frame_count)
+ break;
+ const float *a = active + (size_t)t * PYSEG_SPEAKERS;
+ const float speakers = a[0] + a[1] + a[2];
+ const float weight = job->taper[t];
+ float *sum = self->sum + row * PYSEG_TRACKS;
+ float *count = self->count + row * PYSEG_TRACKS;
+ sum[PYSEG_TRACK_SPEECH] += (speakers >= 1.0f ? weight : 0.0f);
+ sum[PYSEG_TRACK_OVERLAP] += (speakers >= 2.0f ? weight : 0.0f);
+ sum[PYSEG_TRACK_COUNT] += speakers * weight;
+ count[PYSEG_TRACK_SPEECH] += weight;
+ count[PYSEG_TRACK_OVERLAP] += weight;
+ count[PYSEG_TRACK_COUNT] += weight;
+ }
+}
+
+static void *worker_run(void *arg) {
+ slide_worker *self = arg;
+ const slide_job *job = self->job;
+ const int batch = job->batch;
+
+ pyseg_t *engine = pyseg_create_batch(job->weights, job->flags, batch);
+ float *windows = malloc((size_t)batch * PYSEG_WINDOW_SAMPLES * sizeof(float));
+ float *probs = malloc((size_t)batch * PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+ float *active = malloc((size_t)PYSEG_FRAMES * PYSEG_SPEAKERS * sizeof(float));
+ if (!engine || !windows || !probs || !active) {
+ self->failed = 1;
+ goto done;
+ }
+
+ for (size_t index = self->first_window; index < self->last_window;) {
+ int count = 0;
+ while (count < batch && index + (size_t)count < self->last_window) {
+ gather(job, index + (size_t)count, windows + (size_t)count * PYSEG_WINDOW_SAMPLES);
+ ++count;
+ }
+ pyseg_process_batch_f32(engine, windows, count, probs);
+ for (int b = 0; b < count; ++b) {
+ pyseg_to_multilabel(probs + (size_t)b * PYSEG_FRAMES * PYSEG_CLASSES, active);
+ accumulate(self, index + (size_t)b, active);
+ }
+ index += (size_t)count;
+ }
+
+done:
+ free(active);
+ free(probs);
+ free(windows);
+ pyseg_destroy(engine);
+ return NULL;
+}
+
+static size_t slide_run(const float *samples,
+ const int16_t *samples_s16,
+ size_t num_samples,
+ const pyseg_slide_params *params,
+ float *tracks) {
+ pyseg_slide_params defaults;
+ if (!params) {
+ pyseg_slide_params_default(&defaults);
+ params = &defaults;
+ }
+ if ((!samples && !samples_s16) || num_samples == 0 || !tracks || params->step <= 0.0)
+ return 0;
+
+ const size_t step_samples = step_samples_of(params->step);
+ if (step_samples > PYSEG_WINDOW_SAMPLES || params->batch > PYSEG_MAX_BATCH)
+ return 0;
+
+ const size_t windows = window_count(num_samples, step_samples);
+ const size_t frames = pyseg_slide_frames(num_samples, params->step);
+ if (frames == 0)
+ return 0;
+
+ /* np.hamming over the window's frames. It never reaches zero, so every
+ * frame keeps a vote however close to the edge it sits. */
+ float taper[PYSEG_FRAMES];
+ for (int t = 0; t < PYSEG_FRAMES; ++t)
+ taper[t] = (float)(0.54 - 0.46 * cos(2.0 * M_PI * t / (PYSEG_FRAMES - 1)));
+
+ const slide_job job = {
+ .samples = samples,
+ .samples_s16 = samples_s16,
+ .num_samples = num_samples,
+ .step_samples = step_samples,
+ .frames = frames,
+ .taper = taper,
+ .weights = params->weights,
+ .flags = params->flags,
+ .batch = params->batch > 0 ? params->batch : DEFAULT_BATCH,
+ };
+
+ int nthreads = params->threads > 0 ? params->threads : 1;
+ if (nthreads > PYSEG_MAX_THREADS)
+ nthreads = PYSEG_MAX_THREADS;
+#ifndef PYSEG_THREADS
+ nthreads = 1;
+#endif
+ if ((size_t)nthreads > windows)
+ nthreads = (int)windows;
+
+ slide_worker *workers = calloc((size_t)nthreads, sizeof *workers);
+ if (!workers)
+ return 0;
+
+ int failed = 0;
+ for (int i = 0; i < nthreads; ++i) {
+ slide_worker *w = &workers[i];
+ w->job = &job;
+ w->first_window = windows * (size_t)i / (size_t)nthreads;
+ w->last_window = windows * (size_t)(i + 1) / (size_t)nthreads;
+ w->first_frame = start_frame_of(w->first_window * step_samples);
+ size_t end = start_frame_of((w->last_window - 1) * step_samples) + PYSEG_FRAMES;
+ if (end > frames)
+ end = frames;
+ w->frame_count = end > w->first_frame ? end - w->first_frame : 0;
+ w->sum = calloc(w->frame_count * PYSEG_TRACKS + 1, sizeof(float));
+ w->count = calloc(w->frame_count * PYSEG_TRACKS + 1, sizeof(float));
+ if (!w->sum || !w->count)
+ failed = 1;
+ }
+
+#ifdef PYSEG_THREADS
+ pthread_t *threads = nthreads > 1 ? calloc((size_t)nthreads - 1, sizeof *threads) : NULL;
+ int spawned = 0;
+ if (!failed && nthreads > 1 && !threads)
+ failed = 1;
+ if (!failed)
+ for (int i = 1; i < nthreads; ++i) {
+ if (pthread_create(&threads[spawned], NULL, worker_run, &workers[i]) != 0) {
+ failed = 1;
+ break;
+ }
+ ++spawned;
+ }
+#endif
+ if (!failed)
+ worker_run(&workers[0]);
+#ifdef PYSEG_THREADS
+ for (int i = 0; i < spawned; ++i)
+ pthread_join(threads[i], NULL);
+ free(threads);
+#endif
+
+ for (int i = 0; i < nthreads; ++i)
+ failed |= workers[i].failed;
+
+ if (!failed) {
+ memset(tracks, 0, frames * PYSEG_TRACKS * sizeof(float));
+ float *count = calloc(frames * PYSEG_TRACKS, sizeof(float));
+ if (!count) {
+ failed = 1;
+ } else {
+ for (int i = 0; i < nthreads; ++i) {
+ const slide_worker *w = &workers[i];
+ const size_t base = w->first_frame * PYSEG_TRACKS;
+ for (size_t j = 0; j < w->frame_count * PYSEG_TRACKS; ++j) {
+ tracks[base + j] += w->sum[j];
+ count[base + j] += w->count[j];
+ }
+ }
+ for (size_t j = 0; j < frames * PYSEG_TRACKS; ++j)
+ tracks[j] = count[j] > AGG_EPSILON ? tracks[j] / count[j] : 0.0f;
+ free(count);
+ }
+ }
+
+ for (int i = 0; i < nthreads; ++i) {
+ free(workers[i].sum);
+ free(workers[i].count);
+ }
+ free(workers);
+ return failed ? 0 : frames;
+}
+
+size_t pyseg_slide(const float *samples,
+ size_t num_samples,
+ const pyseg_slide_params *params,
+ float *tracks) {
+ return slide_run(samples, NULL, num_samples, params, tracks);
+}
+
+size_t pyseg_slide_s16(const int16_t *samples,
+ size_t num_samples,
+ const pyseg_slide_params *params,
+ float *tracks) {
+ return slide_run(NULL, samples, num_samples, params, tracks);
+}
+
+/* ---- binarization -----------------------------------------------------
+ *
+ * Hysteresis over the aggregated score: a region opens when the score rises
+ * above onset and closes when it falls below offset, so a score hovering
+ * at the threshold does not chatter. The first frame decides the initial state
+ * on its own; every later frame is a possible transition, and a transition is
+ * timestamped at the frame that caused it. */
+size_t pyseg_binarize(const float *scores,
+ size_t num_frames,
+ int track,
+ const pyseg_binarize_params *params,
+ pyseg_segment *out,
+ size_t out_cap) {
+ pyseg_binarize_params defaults;
+ if (!params) {
+ pyseg_binarize_params_default(&defaults);
+ params = &defaults;
+ }
+ if (!scores || num_frames == 0 || track < 0 || track >= PYSEG_TRACKS)
+ return 0;
+
+ const size_t cap = out ? out_cap : 0;
+ size_t n = 0;
+ int is_active = scores[(size_t)track] > params->onset;
+ double start = frame_middle(0);
+ double time = start;
+
+ for (size_t f = 1; f < num_frames; ++f) {
+ const double value = scores[f * PYSEG_TRACKS + (size_t)track];
+ time = frame_middle(f);
+ if (is_active) {
+ if (value < params->offset) {
+ if (n < cap) {
+ out[n].start = start;
+ out[n].end = time;
+ }
+ ++n;
+ is_active = 0;
+ }
+ } else if (value > params->onset) {
+ start = time;
+ is_active = 1;
+ }
+ }
+ if (is_active) {
+ if (n < cap) {
+ out[n].start = start;
+ out[n].end = time;
+ }
+ ++n;
+ }
+
+ if (!out || n > cap)
+ return n;
+
+ /* Both passes look across neighbours, so they run over the collected list
+ * rather than during the scan: a gap is only short once both of the
+ * segments around it are known. */
+ if (params->min_duration_off > 0.0) {
+ size_t w = 0;
+ for (size_t i = 0; i < n; ++i) {
+ if (w > 0 && out[i].start - out[w - 1].end < params->min_duration_off)
+ out[w - 1].end = out[i].end;
+ else
+ out[w++] = out[i];
+ }
+ n = w;
+ }
+ if (params->min_duration_on > 0.0) {
+ size_t w = 0;
+ for (size_t i = 0; i < n; ++i)
+ if (out[i].end - out[i].start >= params->min_duration_on)
+ out[w++] = out[i];
+ n = w;
+ }
+ return n;
+}
diff --git a/src/wav.c b/src/wav.c
new file mode 100644
index 0000000..2dcf27a
--- /dev/null
+++ b/src/wav.c
@@ -0,0 +1,127 @@
+#include "wav.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int rd_u32(FILE *f, uint32_t *v) {
+ unsigned char b[4];
+ if (fread(b, 1, 4, f) != 4)
+ return -1;
+ *v = (uint32_t)b[0] | (uint32_t)b[1] << 8 | (uint32_t)b[2] << 16 | (uint32_t)b[3] << 24;
+ return 0;
+}
+
+static int rd_u16(FILE *f, uint16_t *v) {
+ unsigned char b[2];
+ if (fread(b, 1, 2, f) != 2)
+ return -1;
+ *v = (uint16_t)((uint32_t)b[0] | (uint32_t)b[1] << 8);
+ return 0;
+}
+
+#define FAIL(msg) \
+ do { \
+ if (err) \
+ *err = (msg); \
+ goto fail; \
+ } while (0)
+
+int wav_read_mono_s16(const char *path, wav_t *out, const char **err) {
+ memset(out, 0, sizeof *out);
+ FILE *f = fopen(path, "rb");
+ if (!f) {
+ if (err)
+ *err = "cannot open file";
+ return -1;
+ }
+
+ char id[4];
+ uint32_t riff_size = 0;
+ if (fread(id, 1, 4, f) != 4 || memcmp(id, "RIFF", 4) != 0)
+ FAIL("not a RIFF file");
+ if (rd_u32(f, &riff_size) != 0)
+ FAIL("truncated header");
+ if (fread(id, 1, 4, f) != 4 || memcmp(id, "WAVE", 4) != 0)
+ FAIL("not a WAVE file");
+
+ uint16_t fmt = 0, channels = 0, bits = 0;
+ uint32_t rate = 0;
+ int have_fmt = 0;
+
+ for (;;) {
+ uint32_t size;
+ if (fread(id, 1, 4, f) != 4 || rd_u32(f, &size) != 0)
+ break; /* end of file, or a truncated trailing chunk */
+
+ if (memcmp(id, "fmt ", 4) == 0) {
+ uint16_t block_align;
+ uint32_t byte_rate;
+ if (size < 16)
+ FAIL("short fmt chunk");
+ if (rd_u16(f, &fmt) || rd_u16(f, &channels) || rd_u32(f, &rate) ||
+ rd_u32(f, &byte_rate) || rd_u16(f, &block_align) || rd_u16(f, &bits))
+ FAIL("truncated fmt chunk");
+ if (fseek(f, (long)size - 16, SEEK_CUR) != 0)
+ FAIL("bad fmt chunk size");
+ have_fmt = 1;
+ continue;
+ }
+
+ if (memcmp(id, "data", 4) == 0) {
+ if (!have_fmt)
+ FAIL("data chunk before fmt chunk");
+ /* Format 1 is PCM; 0xFFFE is extensible, whose subformat this
+ * reader does not inspect, so it is accepted only at 16 bits. */
+ if ((fmt != 1 && fmt != 0xFFFE) || bits != 16)
+ FAIL("only 16-bit PCM is supported");
+ if (channels == 0)
+ FAIL("zero channels");
+
+ const size_t frames = size / (2u * channels);
+ if (frames == 0)
+ FAIL("empty data chunk");
+ int16_t *mono = malloc(frames * sizeof(int16_t));
+ if (!mono)
+ FAIL("out of memory");
+
+ const size_t step = channels;
+ int16_t buf[1024];
+ size_t got = 0;
+ while (got < frames) {
+ const size_t want = (frames - got) < (sizeof buf / sizeof buf[0]) / step
+ ? (frames - got) * step
+ : (sizeof buf / sizeof buf[0]) / step * step;
+ const size_t n = fread(buf, sizeof(int16_t), want, f);
+ if (n < step)
+ break;
+ for (size_t i = 0; i + step <= n; i += step)
+ mono[got++] = buf[i];
+ }
+ if (got == 0) {
+ free(mono);
+ FAIL("no samples read");
+ }
+ out->samples = mono;
+ out->count = got;
+ out->sample_rate = (int)rate;
+ out->channels = (int)channels;
+ fclose(f);
+ return 0;
+ }
+
+ /* Skip unknown chunks; RIFF chunks are word aligned. */
+ if (fseek(f, (long)size + (size & 1u), SEEK_CUR) != 0)
+ break;
+ }
+ FAIL("no data chunk");
+
+fail:
+ fclose(f);
+ return -1;
+}
+
+void wav_free(wav_t *w) {
+ free(w->samples);
+ memset(w, 0, sizeof *w);
+}
diff --git a/src/wav.h b/src/wav.h
new file mode 100644
index 0000000..859b535
--- /dev/null
+++ b/src/wav.h
@@ -0,0 +1,22 @@
+/* Minimal RIFF/WAVE reader for the command line tool: uncompressed 16-bit PCM
+ * only, first channel extracted. The library itself never touches files. */
+
+#ifndef PYSEG_WAV_H
+#define PYSEG_WAV_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+typedef struct {
+ int16_t *samples; /* mono, first channel of the source */
+ size_t count;
+ int sample_rate;
+ int channels;
+} wav_t;
+
+/* Returns 0 on success. On failure returns non-zero and, when err is
+ * non-NULL, writes a short reason there. */
+int wav_read_mono_s16(const char *path, wav_t *out, const char **err);
+void wav_free(wav_t *w);
+
+#endif /* PYSEG_WAV_H */
diff --git a/src/weights.c b/src/weights.c
new file mode 100644
index 0000000..42e3c9c
--- /dev/null
+++ b/src/weights.c
@@ -0,0 +1,189 @@
+/* Weight blob reader.
+ *
+ * The file is a header, a fixed-size table of named tensors, then the tensor
+ * data at 64-byte boundaries. Parsing checks that every tensor the engine
+ * needs is present with the exact byte count that shape implies, so a blob
+ * exported from a different checkpoint or a different layout is rejected at
+ * load time rather than producing plausible wrong numbers. */
+
+#include "weights.h"
+
+#include <fcntl.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdint.h>
+
+#define MAGIC "PSG1"
+#define VERSION 1u
+#define NAME_LEN 24
+
+typedef struct {
+ char magic[4];
+ uint32_t version;
+ uint32_t count;
+ uint32_t total;
+} blob_header;
+
+typedef struct {
+ char name[NAME_LEN];
+ uint32_t offset;
+ uint32_t nbytes;
+ uint32_t digest;
+} blob_entry;
+
+typedef struct {
+ const unsigned char *base;
+ size_t len;
+ const blob_entry *table;
+ uint32_t count;
+ int verify;
+ int failed;
+} reader;
+
+static uint32_t fnv1a(const unsigned char *p, size_t n) {
+ uint32_t h = 0x811C9DC5u;
+ for (size_t i = 0; i < n; ++i)
+ h = (h ^ p[i]) * 0x01000193u;
+ return h;
+}
+
+/* Looks up one tensor and checks it is exactly floats long. A miss sets the
+ * reader's failure flag rather than returning it, so the caller can list every
+ * tensor once and test the flag at the end. */
+static const float *take(reader *r, const char *name, size_t floats) {
+ if (r->failed)
+ return NULL;
+ for (uint32_t i = 0; i < r->count; ++i) {
+ const blob_entry *e = &r->table[i];
+ if (strncmp(e->name, name, NAME_LEN) != 0)
+ continue;
+ if (e->nbytes != floats * sizeof(float) || e->offset % 64 != 0 || e->offset > r->len ||
+ e->nbytes > r->len - e->offset)
+ break;
+ const unsigned char *data = r->base + e->offset;
+ if (r->verify && fnv1a(data, e->nbytes) != e->digest)
+ break;
+ return (const float *)(const void *)data;
+ }
+ r->failed = 1;
+ return NULL;
+}
+
+int pyseg_weights_parse(const void *blob, size_t len, int verify, pyseg_weights *out) {
+ if (!blob || len < sizeof(blob_header))
+ return -1;
+ const blob_header *h = (const blob_header *)blob;
+ if (memcmp(h->magic, MAGIC, 4) != 0 || h->version != VERSION)
+ return -1;
+ if (h->count > 1024)
+ return -1;
+ const size_t table_bytes = (size_t)h->count * sizeof(blob_entry);
+ if (len < sizeof(blob_header) + table_bytes || len < h->total)
+ return -1;
+
+ reader r = {
+ .base = (const unsigned char *)blob,
+ .len = len,
+ .table = (const blob_entry *)(const void *)((const unsigned char *)blob + sizeof *h),
+ .count = h->count,
+ .verify = verify,
+ .failed = 0,
+ };
+
+ memset(out, 0, sizeof *out);
+ out->wavnorm = take(&r, "wavnorm", 2);
+ out->sinc_w = take(&r, "sinc_w", 80 * 256);
+
+ static const int norm_ch[3] = {80, 60, 60};
+ for (int i = 0; i < 3; ++i) {
+ char name[NAME_LEN];
+ snprintf(name, sizeof name, "norm%d_w", i + 1);
+ out->norm_w[i] = take(&r, name, (size_t)norm_ch[i]);
+ snprintf(name, sizeof name, "norm%d_b", i + 1);
+ out->norm_b[i] = take(&r, name, (size_t)norm_ch[i]);
+ }
+
+ static const int conv_k[2] = {400, 300};
+ for (int i = 0; i < 2; ++i) {
+ char name[NAME_LEN];
+ snprintf(name, sizeof name, "conv%d_w", i + 2);
+ out->conv_w[i] = take(&r, name, 60u * (size_t)conv_k[i]);
+ snprintf(name, sizeof name, "conv%d_b", i + 2);
+ out->conv_b[i] = take(&r, name, 60);
+ }
+
+ for (int l = 0; l < 4; ++l) {
+ const size_t in_dim = l == 0 ? 60 : 256;
+ for (int d = 0; d < 2; ++d) {
+ char name[NAME_LEN];
+ const char tag = d == 0 ? 'f' : 'b';
+ snprintf(name, sizeof name, "lstm%d%c_ih", l, tag);
+ out->lstm[l][d].ih = take(&r, name, 512 * in_dim);
+ snprintf(name, sizeof name, "lstm%d%c_hh", l, tag);
+ out->lstm[l][d].hh = take(&r, name, 512 * 128);
+ snprintf(name, sizeof name, "lstm%d%c_bias", l, tag);
+ out->lstm[l][d].bias = take(&r, name, 512);
+ }
+ }
+
+ static const int lin_k[2] = {256, 128};
+ for (int i = 0; i < 2; ++i) {
+ char name[NAME_LEN];
+ snprintf(name, sizeof name, "lin%d_w", i);
+ out->lin_w[i] = take(&r, name, 128u * (size_t)lin_k[i]);
+ snprintf(name, sizeof name, "lin%d_b", i);
+ out->lin_b[i] = take(&r, name, 128);
+ }
+
+ out->cls_w = take(&r, "cls_w", 7 * 128);
+ out->cls_b = take(&r, "cls_b", 7);
+
+ return r.failed ? -1 : 0;
+}
+
+int pyseg_weights_map(const char *path, int verify, pyseg_weights *out, void **map, size_t *map_len) {
+ const int fd = open(path, O_RDONLY);
+ if (fd < 0)
+ return -1;
+ struct stat st;
+ if (fstat(fd, &st) != 0 || st.st_size <= 0) {
+ close(fd);
+ return -1;
+ }
+ const size_t len = (size_t)st.st_size;
+ void *addr = mmap(NULL, len, PROT_READ, MAP_PRIVATE, fd, 0);
+ close(fd);
+ if (addr == MAP_FAILED)
+ return -1;
+ if (pyseg_weights_parse(addr, len, verify, out) != 0) {
+ munmap(addr, len);
+ return -1;
+ }
+ *map = addr;
+ *map_len = len;
+ return 0;
+}
+
+void pyseg_weights_unmap(void *map, size_t len) {
+ if (map)
+ munmap(map, len);
+}
+
+#ifdef PYSEG_EMBED_WEIGHTS
+extern const unsigned char pyseg_weights_blob[];
+extern const size_t pyseg_weights_blob_len;
+
+const void *pyseg_weights_embedded(size_t *len) {
+ *len = pyseg_weights_blob_len;
+ return pyseg_weights_blob;
+}
+#else
+const void *pyseg_weights_embedded(size_t *len) {
+ *len = 0;
+ return NULL;
+}
+#endif
diff --git a/src/weights.h b/src/weights.h
new file mode 100644
index 0000000..f32cdfb
--- /dev/null
+++ b/src/weights.h
@@ -0,0 +1,49 @@
+/* Access to the packed weight blob produced by tools/export_weights.py.
+ *
+ * The blob is already in the layout the kernels read, so loading it is a table
+ * walk that hands out pointers: no transposing, no unpacking, no allocation
+ * for the weights themselves. That holds both for the copy compiled into the
+ * binary and for a file, which is mapped read-only and shared between every
+ * process on the host that maps it. */
+
+#ifndef PYSEG_WEIGHTS_H
+#define PYSEG_WEIGHTS_H
+
+#include <stddef.h>
+
+#define PYSEG_ALIGN64 __attribute__((aligned(64)))
+
+/* Every weight matrix is [rows, window] row-major, matching pyseg_kernels. */
+typedef struct {
+ const float *ih; /* [512, input] */
+ const float *hh; /* [512, 128] */
+ const float *bias; /* [512], the two PyTorch bias vectors already summed */
+} pyseg_lstm_weights;
+
+typedef struct {
+ const float *wavnorm; /* [2]: InstanceNorm1d scale then shift */
+ const float *sinc_w; /* [80, 256]: 251 taps then five zero columns */
+ const float *norm_w[3]; /* [80], [60], [60] */
+ const float *norm_b[3];
+ const float *conv_w[2]; /* [60, 400] and [60, 300] */
+ const float *conv_b[2];
+ pyseg_lstm_weights lstm[4][2]; /* [layer][0 = forward, 1 = backward] */
+ const float *lin_w[2]; /* [128, 256] and [128, 128] */
+ const float *lin_b[2];
+ const float *cls_w; /* [7, 128] */
+ const float *cls_b;
+} pyseg_weights;
+
+/* Returns 0 on success. verify recomputes the per-tensor checksum. */
+int pyseg_weights_parse(const void *blob, size_t len, int verify, pyseg_weights *out);
+
+/* Maps path read-only and parses it. On success the caller must keep the
+ * mapping alive for as long as the weights are used. */
+int pyseg_weights_map(const char *path, int verify, pyseg_weights *out, void **map, size_t *map_len);
+
+void pyseg_weights_unmap(void *map, size_t len);
+
+/* The blob compiled into this binary, or NULL when built without one. */
+const void *pyseg_weights_embedded(size_t *len);
+
+#endif /* PYSEG_WEIGHTS_H */
diff --git a/testdata_aepyx.wav b/testdata_aepyx.wav
new file mode 100644
index 0000000..e7cc293
--- /dev/null
+++ b/testdata_aepyx.wav
Binary files differ
diff --git a/tests/test_kernels.c b/tests/test_kernels.c
new file mode 100644
index 0000000..d4f25d6
--- /dev/null
+++ b/tests/test_kernels.c
@@ -0,0 +1,151 @@
+/* The dense primitive against a naive triple loop, over the shapes the model
+ * actually uses plus enough odd ones to exercise every edge path.
+ *
+ * The reference here is deliberately the most obvious implementation possible:
+ * the point is to catch a blocking or tail-handling mistake, and a second
+ * clever implementation would be liable to the same mistakes. */
+
+#include "kernels.h"
+#include "test_util.h"
+
+#include <math.h>
+#include <stdlib.h>
+
+static unsigned rng_state = 12345u;
+
+static float next_float(void) {
+ rng_state = rng_state * 1664525u + 1013904223u;
+ return (float)((rng_state >> 8) & 0xFFFF) / 32768.0f - 1.0f;
+}
+
+static void gemm_ref(float *y,
+ int ldy,
+ const float *a,
+ int lda,
+ const float *w,
+ const float *bias,
+ int m,
+ int n,
+ int k) {
+ for (int s = 0; s < m; ++s)
+ for (int i = 0; i < n; ++i) {
+ double acc = bias ? bias[i] : 0.0;
+ for (int j = 0; j < k; ++j)
+ acc += (double)a[(size_t)s * lda + j] * w[(size_t)i * k + j];
+ y[(size_t)s * ldy + i] = (float)acc;
+ }
+}
+
+/* Tolerance scales with the window length because that is how many terms the
+ * two orders can disagree over. */
+static int
+check(const char *label, const pyseg_kernels *kern, int m, int n, int k, int lda, int with_bias) {
+ const size_t a_len = (size_t)(m - 1) * lda + k + 8;
+ float *a = malloc(a_len * sizeof(float));
+ float *w = malloc((size_t)n * k * sizeof(float));
+ float *bias = malloc((size_t)n * sizeof(float));
+ float *got = malloc((size_t)m * n * sizeof(float));
+ float *want = malloc((size_t)m * n * sizeof(float));
+
+ for (size_t i = 0; i < a_len; ++i)
+ a[i] = next_float();
+ for (size_t i = 0; i < (size_t)n * k; ++i)
+ w[i] = next_float();
+ for (int i = 0; i < n; ++i)
+ bias[i] = next_float();
+
+ kern->gemm_nt(got, n, a, lda, w, with_bias ? bias : NULL, m, n, k);
+ gemm_ref(want, n, a, lda, w, with_bias ? bias : NULL, m, n, k);
+
+ double worst = 0.0;
+ for (int i = 0; i < m * n; ++i) {
+ const double d = fabs((double)got[i] - want[i]);
+ if (d > worst)
+ worst = d;
+ }
+ const double limit = 2e-6 * k;
+ TEST_ASSERT(worst <= limit, "%s %s m=%d n=%d k=%d lda=%d bias=%d: worst %.3e > %.3e", label,
+ kern->name, m, n, k, lda, with_bias, worst, limit);
+
+ free(a);
+ free(w);
+ free(bias);
+ free(got);
+ free(want);
+ return 0;
+}
+
+/* The SIMD cell update replaces libm's exponential and hyperbolic tangent with
+ * polynomial approximations, so it is checked against libm directly rather
+ * than only through the model. The gate arguments are swept well past the
+ * range where both saturate, because that range is where a range reduction
+ * built on assembling an exponent by hand goes wrong. */
+static void check_lstm_cell(void) {
+ enum { HID = 128 };
+ float rec[4 * HID], in[4 * HID];
+ float h_scalar[HID], c_scalar[HID], h_simd[HID], c_simd[HID];
+
+ for (int trial = 0; trial < 64; ++trial) {
+ const float span = 1.0f + (float)trial * 3.0f; /* up to about 190 */
+ for (int i = 0; i < 4 * HID; ++i) {
+ rec[i] = next_float() * span;
+ in[i] = next_float() * span;
+ }
+ for (int i = 0; i < HID; ++i)
+ c_scalar[i] = c_simd[i] = next_float() * 8.0f;
+
+ pyseg_kernels_scalar()->lstm_cell(h_scalar, c_scalar, rec, in, HID);
+ pyseg_kernels_simd()->lstm_cell(h_simd, c_simd, rec, in, HID);
+
+ double worst = 0.0;
+ for (int i = 0; i < HID; ++i) {
+ const double dh = fabs((double)h_scalar[i] - h_simd[i]);
+ const double dc = fabs((double)c_scalar[i] - c_simd[i]);
+ if (dh > worst)
+ worst = dh;
+ if (dc > worst)
+ worst = dc;
+ if (!isfinite(h_simd[i]) || !isfinite(c_simd[i]))
+ worst = 1.0;
+ }
+ TEST_ASSERT(worst <= 1e-6, "lstm_cell over +/-%.0f: worst %.3e", span, worst);
+ }
+}
+
+int main(void) {
+ const pyseg_kernels *sets[] = {pyseg_kernels_scalar(), pyseg_kernels_simd()};
+
+ /* The shapes the forward pass issues, in order. */
+ static const struct {
+ const char *label;
+ int m, n, k, lda, bias;
+ } model_shapes[] = {
+ {"sinc", 384, 80, 256, 10, 0}, {"sinc-tail", 231, 80, 256, 10, 0},
+ {"conv2", 384, 60, 400, 80, 1}, {"conv3", 231, 60, 300, 60, 1},
+ {"lstm-in-l0", 589, 512, 60, 60, 1}, {"lstm-in-l1", 589, 512, 256, 256, 1},
+ {"lstm-hh", 1, 512, 128, 0, 1}, {"linear0", 589, 128, 256, 256, 1},
+ {"linear1", 589, 128, 128, 128, 1}, {"classifier", 589, 7, 128, 128, 1},
+ };
+
+ for (size_t s = 0; s < sizeof sets / sizeof *sets; ++s)
+ for (size_t i = 0; i < sizeof model_shapes / sizeof *model_shapes; ++i)
+ check(model_shapes[i].label, sets[s], model_shapes[i].m, model_shapes[i].n,
+ model_shapes[i].k, model_shapes[i].lda ? model_shapes[i].lda : model_shapes[i].k,
+ model_shapes[i].bias);
+
+ /* Every combination of leftover rows and leftover weight rows. */
+ for (size_t s = 0; s < sizeof sets / sizeof *sets; ++s)
+ for (int m = 1; m <= 9; ++m)
+ for (int n = 1; n <= 13; ++n)
+ for (int k = 4; k <= 20; k += 4)
+ check("edge", sets[s], m, n, k, k + 3, m & 1);
+
+ /* Panels: a shape larger than one panel and one that straddles a boundary. */
+ for (size_t s = 0; s < sizeof sets / sizeof *sets; ++s) {
+ check("panel-exact", sets[s], 2 * PYSEG_MPANEL, 8, 16, 16, 1);
+ check("panel-split", sets[s], 2 * PYSEG_MPANEL + 3, 9, 12, 17, 1);
+ }
+
+ check_lstm_cell();
+ return TEST_REPORT();
+}
diff --git a/tests/test_parity.c b/tests/test_parity.c
new file mode 100644
index 0000000..5002185
--- /dev/null
+++ b/tests/test_parity.c
@@ -0,0 +1,214 @@
+/* The engine against the PyTorch model on real speech.
+ *
+ * Two thresholds, because they answer different questions. The probability
+ * difference says the arithmetic agrees; the decision agreement says nothing
+ * downstream changes, which is what actually matters, since every consumer of
+ * this model takes the most likely class per frame and throws the rest away.
+ *
+ * Bit-exactness is not a goal and is not achievable: the reference sums in a
+ * different order, and float32 addition is not associative. */
+
+#include "pyseg.h"
+#include "test_util.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define PROB_TOLERANCE 2e-3
+
+typedef struct {
+ unsigned windows;
+ float *inputs; /* [windows][PYSEG_WINDOW_SAMPLES] */
+ float *probs; /* [windows][PYSEG_FRAMES][PYSEG_CLASSES] */
+} fixture;
+
+static int load(const char *path, fixture *f) {
+ FILE *fp = fopen(path, "rb");
+ if (!fp) {
+ fprintf(stderr, "cannot open %s\n", path);
+ return -1;
+ }
+ char magic[4];
+ unsigned n, samples, frames;
+ if (fread(magic, 1, 4, fp) != 4 || memcmp(magic, "PSGG", 4) != 0 || fread(&n, 4, 1, fp) != 1 ||
+ fread(&samples, 4, 1, fp) != 1 || fread(&frames, 4, 1, fp) != 1 ||
+ samples != PYSEG_WINDOW_SAMPLES || frames != PYSEG_FRAMES) {
+ fprintf(stderr, "%s: not a matching fixture\n", path);
+ fclose(fp);
+ return -1;
+ }
+ const size_t in_len = (size_t)n * PYSEG_WINDOW_SAMPLES;
+ const size_t out_len = (size_t)n * PYSEG_FRAMES * PYSEG_CLASSES;
+ f->windows = n;
+ f->inputs = malloc(in_len * sizeof(float));
+ f->probs = malloc(out_len * sizeof(float));
+ const int ok = f->inputs && f->probs && fread(f->inputs, sizeof(float), in_len, fp) == in_len &&
+ fread(f->probs, sizeof(float), out_len, fp) == out_len;
+ fclose(fp);
+ if (!ok) {
+ fprintf(stderr, "%s: truncated\n", path);
+ return -1;
+ }
+ return 0;
+}
+
+static int argmax(const float *row) {
+ int best = 0;
+ for (int i = 1; i < PYSEG_CLASSES; ++i)
+ if (row[i] > row[best])
+ best = i;
+ return best;
+}
+
+static int run(const fixture *f, unsigned flags, const char *label, float *first_window_out) {
+ pyseg_t *v = pyseg_create_ex(NULL, flags);
+ TEST_ASSERT(v != NULL, "%s: create failed", label);
+ if (!v)
+ return -1;
+
+ float *probs = malloc((size_t)PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+ double worst_prob = 0.0, worst_sum = 0.0;
+ size_t disagreements = 0, total = 0;
+
+ for (unsigned c = 0; c < f->windows; ++c) {
+ pyseg_process_f32(v, f->inputs + (size_t)c * PYSEG_WINDOW_SAMPLES, probs);
+ if (c == 0 && first_window_out)
+ memcpy(first_window_out, probs, (size_t)PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+
+ const float *want = f->probs + (size_t)c * PYSEG_FRAMES * PYSEG_CLASSES;
+ for (int t = 0; t < PYSEG_FRAMES; ++t) {
+ const float *g = probs + (size_t)t * PYSEG_CLASSES;
+ const float *e = want + (size_t)t * PYSEG_CLASSES;
+ double sum = 0.0;
+ for (int i = 0; i < PYSEG_CLASSES; ++i) {
+ const double d = fabs((double)g[i] - e[i]);
+ if (d > worst_prob)
+ worst_prob = d;
+ sum += g[i];
+ }
+ if (fabs(sum - 1.0) > worst_sum)
+ worst_sum = fabs(sum - 1.0);
+ if (argmax(g) != argmax(e))
+ ++disagreements;
+ ++total;
+ }
+ }
+
+ fprintf(stderr, "%-8s %-6s %u windows: max |prob diff| %.3e, %zu/%zu frames disagree\n", label,
+ pyseg_backend_name(v), f->windows, worst_prob, disagreements, total);
+
+ TEST_ASSERT(worst_prob <= PROB_TOLERANCE, "%s: max |prob diff| %.3e > %.3e", label, worst_prob,
+ PROB_TOLERANCE);
+ TEST_ASSERT(worst_sum <= 1e-5, "%s: probabilities sum to 1 +/- %.3e", label, worst_sum);
+ TEST_ASSERT(disagreements == 0, "%s: %zu of %zu frames pick a different class", label,
+ disagreements, total);
+
+ free(probs);
+ pyseg_destroy(v);
+ return 0;
+}
+
+int main(int argc, char **argv) {
+ if (argc < 2) {
+ fprintf(stderr, "usage: test_parity <golden.bin>\n");
+ return 2;
+ }
+ fixture f;
+ if (load(argv[1], &f) != 0)
+ return 2;
+
+ const size_t out_len = (size_t)PYSEG_FRAMES * PYSEG_CLASSES;
+ float *simd_first = malloc(out_len * sizeof(float));
+ float *scalar_first = malloc(out_len * sizeof(float));
+
+ run(&f, 0, "simd", simd_first);
+ run(&f, PYSEG_SCALAR_KERNELS, "scalar", scalar_first);
+
+ /* The two kernel sets accumulate in different orders, so they are held to
+ * each other more tightly than either is held to the reference. */
+ double worst = 0.0;
+ for (size_t i = 0; i < out_len; ++i) {
+ const double d = fabs((double)simd_first[i] - scalar_first[i]);
+ if (d > worst)
+ worst = d;
+ }
+ fprintf(stderr, "simd vs scalar: max |prob diff| %.3e\n", worst);
+ TEST_ASSERT(worst <= 1e-4, "simd vs scalar diverge by %.3e", worst);
+
+ /* Batching is a scheduling decision, not a numerical one: the windows of a
+ * batch share weight loads but never touch each other's activations, so
+ * grouping must not move a single bit. */
+ if (f.windows >= 4) {
+ pyseg_t *batched = pyseg_create_batch(NULL, 0, 4);
+ pyseg_t *single = pyseg_create();
+ TEST_ASSERT(batched && pyseg_batch(batched) == 4, "batched create failed");
+ if (batched && single) {
+ float *grouped = malloc(4 * out_len * sizeof(float));
+ float *apart = malloc(4 * out_len * sizeof(float));
+ pyseg_process_batch_f32(batched, f.inputs, 4, grouped);
+ for (int i = 0; i < 4; ++i)
+ pyseg_process_f32(single, f.inputs + (size_t)i * PYSEG_WINDOW_SAMPLES,
+ apart + (size_t)i * out_len);
+ TEST_ASSERT(memcmp(grouped, apart, 4 * out_len * sizeof(float)) == 0,
+ "a batch of four disagrees with four separate windows");
+
+ /* A partial batch is the tail of every recording. */
+ pyseg_process_batch_f32(batched, f.inputs, 3, grouped);
+ TEST_ASSERT(memcmp(grouped, apart, 3 * out_len * sizeof(float)) == 0,
+ "a partial batch disagrees with separate windows");
+ free(grouped);
+ free(apart);
+ }
+ pyseg_destroy(batched);
+ pyseg_destroy(single);
+ }
+
+ TEST_ASSERT(pyseg_create_batch(NULL, 0, 0) == NULL, "a batch of zero was accepted");
+ TEST_ASSERT(pyseg_create_batch(NULL, 0, PYSEG_MAX_BATCH + 1) == NULL,
+ "an oversized batch was accepted");
+
+ /* Determinism: the engine carries no state between windows, so re-running
+ * a window must reproduce it bit for bit. */
+ pyseg_t *v = pyseg_create();
+ float *again = malloc(out_len * sizeof(float));
+ if (v) {
+ pyseg_process_f32(v, f.inputs + (size_t)(f.windows - 1) * PYSEG_WINDOW_SAMPLES, again);
+ float *repeat = malloc(out_len * sizeof(float));
+ pyseg_process_f32(v, f.inputs, repeat);
+ pyseg_process_f32(v, f.inputs + (size_t)(f.windows - 1) * PYSEG_WINDOW_SAMPLES, repeat);
+ TEST_ASSERT(memcmp(again, repeat, out_len * sizeof(float)) == 0,
+ "a repeated window produced different bits");
+ free(repeat);
+ pyseg_destroy(v);
+ }
+
+ /* A weight file must parse to the same numbers as the embedded copy. */
+ pyseg_t *fromfile = pyseg_create_from_file("pyseg_weights.bin");
+ if (fromfile) {
+ float *filed = malloc(out_len * sizeof(float));
+ pyseg_process_f32(fromfile, f.inputs, filed);
+ pyseg_t *embedded = pyseg_create();
+ float *builtin = malloc(out_len * sizeof(float));
+ pyseg_process_f32(embedded, f.inputs, builtin);
+ TEST_ASSERT(memcmp(filed, builtin, out_len * sizeof(float)) == 0,
+ "mapped weights disagree with the embedded copy");
+ free(filed);
+ free(builtin);
+ pyseg_destroy(embedded);
+ pyseg_destroy(fromfile);
+ } else {
+ fprintf(stderr, "note: pyseg_weights.bin not readable, file path untested\n");
+ }
+
+ TEST_ASSERT(pyseg_create_from_file("/nonexistent/pyseg.bin") == NULL,
+ "a missing weight file was accepted");
+
+ free(again);
+ free(simd_first);
+ free(scalar_first);
+ free(f.inputs);
+ free(f.probs);
+ return TEST_REPORT();
+}
diff --git a/tests/test_robust.c b/tests/test_robust.c
new file mode 100644
index 0000000..7dd43a7
--- /dev/null
+++ b/tests/test_robust.c
@@ -0,0 +1,133 @@
+/* Inputs the model will never see in training but will see in production.
+ *
+ * The model normalises its input by the window's own standard deviation, so
+ * digital silence divides by roughly the epsilon in the normalisation and a
+ * constant offset does the same. Those are the cases that produce infinities
+ * if the epsilon is dropped or applied in the wrong place, and a whole window
+ * of silence is entirely ordinary in a real recording. */
+
+#include "pyseg.h"
+#include "test_util.h"
+
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+static unsigned rng_state = 987654321u;
+
+static float next_float(void) {
+ rng_state = rng_state * 1664525u + 1013904223u;
+ return (float)((rng_state >> 8) & 0xFFFF) / 32768.0f - 1.0f;
+}
+
+static void check_output(const char *label, const float *probs) {
+ for (int t = 0; t < PYSEG_FRAMES; ++t) {
+ const float *row = probs + (size_t)t * PYSEG_CLASSES;
+ double sum = 0.0;
+ for (int i = 0; i < PYSEG_CLASSES; ++i) {
+ if (!isfinite(row[i]) || row[i] < 0.0f || row[i] > 1.0f) {
+ TEST_ASSERT(0, "%s: frame %d class %d is %g", label, t, i, row[i]);
+ return;
+ }
+ sum += row[i];
+ }
+ if (fabs(sum - 1.0) > 1e-5) {
+ TEST_ASSERT(0, "%s: frame %d sums to %.9f", label, t, sum);
+ return;
+ }
+ }
+ TEST_ASSERT(1, "%s", label);
+}
+
+int main(void) {
+ pyseg_t *v = pyseg_create();
+ TEST_ASSERT(v != NULL, "create failed");
+ if (!v)
+ return TEST_REPORT();
+
+ float *wav = malloc(PYSEG_WINDOW_SAMPLES * sizeof(float));
+ float *probs = malloc((size_t)PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+ float *active = malloc((size_t)PYSEG_FRAMES * PYSEG_SPEAKERS * sizeof(float));
+ int16_t *pcm = malloc(PYSEG_WINDOW_SAMPLES * sizeof(int16_t));
+
+ memset(wav, 0, PYSEG_WINDOW_SAMPLES * sizeof(float));
+ pyseg_process_f32(v, wav, probs);
+ check_output("digital silence", probs);
+
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ wav[i] = 0.5f;
+ pyseg_process_f32(v, wav, probs);
+ check_output("constant offset", probs);
+
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ wav[i] = (i & 1) ? 1.0f : -1.0f;
+ pyseg_process_f32(v, wav, probs);
+ check_output("full-scale square wave", probs);
+
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ wav[i] = next_float() * 4.0f;
+ pyseg_process_f32(v, wav, probs);
+ check_output("out-of-range noise", probs);
+
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ wav[i] = next_float() * 1e-8f;
+ pyseg_process_f32(v, wav, probs);
+ check_output("near-denormal noise", probs);
+
+ /* A single impulse in an otherwise silent window: the normalisation
+ * amplifies the silence around it by the full dynamic range. */
+ memset(wav, 0, PYSEG_WINDOW_SAMPLES * sizeof(float));
+ wav[PYSEG_WINDOW_SAMPLES / 2] = 1.0f;
+ pyseg_process_f32(v, wav, probs);
+ check_output("lone impulse", probs);
+
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i)
+ pcm[i] = (int16_t)(i & 1 ? 32767 : -32768);
+ pyseg_process_s16(v, pcm, probs);
+ check_output("s16 full scale", probs);
+
+ /* The s16 entry point must be the f32 one with a fixed scaling. */
+ for (int i = 0; i < PYSEG_WINDOW_SAMPLES; ++i) {
+ pcm[i] = (int16_t)((int)(next_float() * 16000.0f));
+ wav[i] = (float)pcm[i] * (1.0f / 32768.0f);
+ }
+ float *from_s16 = malloc((size_t)PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float));
+ pyseg_process_s16(v, pcm, from_s16);
+ pyseg_process_f32(v, wav, probs);
+ TEST_ASSERT(memcmp(from_s16, probs, (size_t)PYSEG_FRAMES * PYSEG_CLASSES * sizeof(float)) == 0,
+ "s16 and f32 entry points disagree on identical audio");
+
+ /* Decoding must land inside the powerset and stay consistent with it. */
+ pyseg_to_multilabel(probs, active);
+ for (int t = 0; t < PYSEG_FRAMES; ++t) {
+ const float *a = active + (size_t)t * PYSEG_SPEAKERS;
+ int count = 0;
+ for (int s = 0; s < PYSEG_SPEAKERS; ++s) {
+ if (a[s] != 0.0f && a[s] != 1.0f) {
+ TEST_ASSERT(0, "frame %d speaker %d is %g, not a hard decision", t, s, a[s]);
+ break;
+ }
+ count += a[s] != 0.0f;
+ }
+ if (count > 2) {
+ TEST_ASSERT(0, "frame %d has %d speakers, more than the powerset allows", t, count);
+ break;
+ }
+ }
+ TEST_ASSERT(1, "multilabel decoding stays inside the powerset");
+
+ TEST_ASSERT(pyseg_powerset_class(-1, -1) == 0, "empty set is not class 0");
+ TEST_ASSERT(pyseg_powerset_class(0, -1) == 1, "speaker 0 alone is not class 1");
+ TEST_ASSERT(pyseg_powerset_class(2, -1) == 3, "speaker 2 alone is not class 3");
+ TEST_ASSERT(pyseg_powerset_class(0, 1) == 4, "speakers 0 and 1 are not class 4");
+ TEST_ASSERT(pyseg_powerset_class(1, 2) == 6, "speakers 1 and 2 are not class 6");
+
+ free(from_s16);
+ free(pcm);
+ free(active);
+ free(probs);
+ free(wav);
+ pyseg_destroy(v);
+ pyseg_destroy(NULL);
+ return TEST_REPORT();
+}
diff --git a/tests/test_slide.c b/tests/test_slide.c
new file mode 100644
index 0000000..a0fc8ca
--- /dev/null
+++ b/tests/test_slide.c
@@ -0,0 +1,212 @@
+/* The sliding-window driver against the aggregation pyannote performs, and the
+ * binarizer against its own definition.
+ *
+ * The aggregate is not just the model run repeatedly: window placement,
+ * rounding onto the frame grid, the Hamming weights and the dropped tail all
+ * have to match, and each is a place where an off-by-one produces output that
+ * looks entirely reasonable and is shifted by a frame. */
+
+#include "pyseg.h"
+#include "test_util.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+ unsigned num_samples;
+ unsigned frames;
+ double step;
+ float *samples;
+ float *tracks; /* [frames][PYSEG_TRACKS] */
+} fixture;
+
+static int load(const char *path, fixture *f) {
+ FILE *fp = fopen(path, "rb");
+ if (!fp) {
+ fprintf(stderr, "cannot open %s\n", path);
+ return -1;
+ }
+ char magic[4];
+ if (fread(magic, 1, 4, fp) != 4 || memcmp(magic, "PSGS", 4) != 0 ||
+ fread(&f->num_samples, 4, 1, fp) != 1 || fread(&f->frames, 4, 1, fp) != 1 ||
+ fread(&f->step, 8, 1, fp) != 1) {
+ fprintf(stderr, "%s: not a matching fixture\n", path);
+ fclose(fp);
+ return -1;
+ }
+ f->samples = malloc((size_t)f->num_samples * sizeof(float));
+ f->tracks = malloc((size_t)f->frames * PYSEG_TRACKS * sizeof(float));
+ const int ok = f->samples && f->tracks &&
+ fread(f->samples, sizeof(float), f->num_samples, fp) == f->num_samples &&
+ fread(f->tracks, sizeof(float), (size_t)f->frames * PYSEG_TRACKS, fp) ==
+ (size_t)f->frames * PYSEG_TRACKS;
+ fclose(fp);
+ if (!ok) {
+ fprintf(stderr, "%s: truncated\n", path);
+ return -1;
+ }
+ return 0;
+}
+
+static double compare(const float *got, const float *want, size_t n) {
+ double worst = 0.0;
+ for (size_t i = 0; i < n; ++i) {
+ const double d = fabs((double)got[i] - want[i]);
+ if (d > worst)
+ worst = d;
+ }
+ return worst;
+}
+
+static void check_slide(const fixture *f, int threads) {
+ pyseg_slide_params p;
+ pyseg_slide_params_default(&p);
+ p.step = f->step;
+ p.threads = threads;
+
+ const size_t frames = pyseg_slide_frames(f->num_samples, p.step);
+ TEST_ASSERT(frames == f->frames, "threads=%d: %zu frames, reference has %u", threads, frames,
+ f->frames);
+ if (frames != f->frames)
+ return;
+
+ float *tracks = malloc(frames * PYSEG_TRACKS * sizeof(float));
+ const size_t got = pyseg_slide(f->samples, f->num_samples, &p, tracks);
+ TEST_ASSERT(got == frames, "threads=%d: slide returned %zu", threads, got);
+
+ if (got == frames) {
+ const double worst = compare(tracks, f->tracks, frames * PYSEG_TRACKS);
+ fprintf(stderr, "slide threads=%d: %zu frames, max |track diff| %.3e\n", threads, frames,
+ worst);
+ TEST_ASSERT(worst <= 1e-5, "threads=%d: max |track diff| %.3e", threads, worst);
+ }
+ free(tracks);
+}
+
+/* A hand-built score sequence, so the expected segments can be reasoned about
+ * rather than captured. */
+static void check_binarize(void) {
+ enum { N = 40 };
+ float scores[N * PYSEG_TRACKS];
+ memset(scores, 0, sizeof scores);
+ for (int f = 10; f < 20; ++f)
+ scores[f * PYSEG_TRACKS] = 1.0f;
+ for (int f = 22; f < 25; ++f)
+ scores[f * PYSEG_TRACKS] = 1.0f;
+
+ pyseg_binarize_params p;
+ pyseg_binarize_params_default(&p);
+
+ pyseg_segment out[8];
+ size_t n = pyseg_binarize(scores, N, PYSEG_TRACK_SPEECH, &p, out, 8);
+ TEST_ASSERT(n == 2, "two runs of ones gave %zu segments", n);
+ if (n == 2) {
+ const double half = 0.5 * PYSEG_FRAME_SIZE / PYSEG_SAMPLE_RATE;
+ TEST_ASSERT(fabs(out[0].start - (pyseg_frame_time(10) + half)) < 1e-9,
+ "first segment starts at %.6f", out[0].start);
+ TEST_ASSERT(fabs(out[0].end - (pyseg_frame_time(20) + half)) < 1e-9,
+ "first segment ends at %.6f", out[0].end);
+ TEST_ASSERT(fabs(out[1].start - (pyseg_frame_time(22) + half)) < 1e-9,
+ "second segment starts at %.6f", out[1].start);
+ }
+
+ /* The gap between the two runs is two frames, about 34 ms. */
+ p.min_duration_off = 0.1;
+ n = pyseg_binarize(scores, N, PYSEG_TRACK_SPEECH, &p, out, 8);
+ TEST_ASSERT(n == 1, "a 34 ms gap survived a 100 ms fill: %zu segments", n);
+
+ p.min_duration_off = 0.0;
+ p.min_duration_on = 0.1;
+ n = pyseg_binarize(scores, N, PYSEG_TRACK_SPEECH, &p, out, 8);
+ TEST_ASSERT(n == 1, "a 51 ms segment survived a 100 ms minimum: %zu segments", n);
+
+ /* Counting without writing must agree with writing. */
+ pyseg_binarize_params_default(&p);
+ TEST_ASSERT(pyseg_binarize(scores, N, PYSEG_TRACK_SPEECH, &p, NULL, 0) == 2,
+ "counting pass disagrees with the writing pass");
+ TEST_ASSERT(pyseg_binarize(scores, N, PYSEG_TRACK_SPEECH, &p, out, 1) == 2,
+ "an undersized buffer did not report the full count");
+
+ /* A track that is high from the first frame to the last is one segment. */
+ for (int f = 0; f < N; ++f)
+ scores[f * PYSEG_TRACKS + PYSEG_TRACK_OVERLAP] = 1.0f;
+ n = pyseg_binarize(scores, N, PYSEG_TRACK_OVERLAP, &p, out, 8);
+ TEST_ASSERT(n == 1, "an always-active track gave %zu segments", n);
+
+ TEST_ASSERT(pyseg_binarize(scores, N, PYSEG_TRACKS, &p, out, 8) == 0,
+ "an out-of-range track was accepted");
+}
+
+/* Frame counts read off pyannote's Inference for the same inputs. The formula
+ * involves two roundings and a tail-window rule, so a table of answers taken
+ * from the reference is worth more than a second derivation of the formula. */
+static void check_frame_counts(void) {
+ static const struct {
+ size_t samples;
+ double step;
+ size_t frames;
+ } cases[] = {
+ {720000, 1.0, 2668}, {640000, 2.0, 2371}, {592000, 0.5, 2194},
+ {400000, 3.0, 1482}, {144000, 1.0, 534}, {160000, 1.0, 594},
+ };
+ for (size_t i = 0; i < sizeof cases / sizeof *cases; ++i) {
+ const size_t got = pyseg_slide_frames(cases[i].samples, cases[i].step);
+ TEST_ASSERT(got == cases[i].frames, "%zu samples at step %g: %zu frames, expected %zu",
+ cases[i].samples, cases[i].step, got, cases[i].frames);
+ }
+ TEST_ASSERT(pyseg_slide_frames(0, 1.0) == 0, "an empty recording gave frames");
+ TEST_ASSERT(pyseg_slide_frames(160000, 0.0) == 0, "a zero step gave frames");
+}
+
+int main(int argc, char **argv) {
+ if (argc < 2) {
+ fprintf(stderr, "usage: test_slide <slide_golden.bin>\n");
+ return 2;
+ }
+ fixture f;
+ if (load(argv[1], &f) != 0)
+ return 2;
+
+ check_frame_counts();
+
+ check_slide(&f, 1);
+ check_slide(&f, 4);
+ check_binarize();
+
+ /* The 16-bit entry point must agree with the float one on audio that came
+ * from 16-bit samples in the first place, which the fixture did. */
+ {
+ int16_t *pcm = malloc(f.num_samples * sizeof(int16_t));
+ float *from_s16 = malloc((size_t)f.frames * PYSEG_TRACKS * sizeof(float));
+ for (unsigned i = 0; i < f.num_samples; ++i)
+ pcm[i] = (int16_t)lrintf(f.samples[i] * 32768.0f);
+ pyseg_slide_params p;
+ pyseg_slide_params_default(&p);
+ p.step = f.step;
+ TEST_ASSERT(pyseg_slide_s16(pcm, f.num_samples, &p, from_s16) == f.frames,
+ "the 16-bit slide failed");
+ const double worst = compare(from_s16, f.tracks, (size_t)f.frames * PYSEG_TRACKS);
+ TEST_ASSERT(worst <= 1e-5, "16-bit slide differs by %.3e", worst);
+ free(from_s16);
+ free(pcm);
+ }
+
+ /* Recordings shorter than one window are padded, not rejected. */
+ float *tiny = calloc(PYSEG_SAMPLE_RATE, sizeof(float));
+ for (int i = 0; i < PYSEG_SAMPLE_RATE; ++i)
+ tiny[i] = 0.1f * sinf((float)i * 0.01f);
+ const size_t tiny_frames = pyseg_slide_frames(PYSEG_SAMPLE_RATE, 1.0);
+ TEST_ASSERT(tiny_frames == PYSEG_SAMPLE_RATE / PYSEG_FRAME_STEP + 1,
+ "a one-second recording gave %zu frames", tiny_frames);
+ float *tiny_tracks = malloc(tiny_frames * PYSEG_TRACKS * sizeof(float));
+ TEST_ASSERT(pyseg_slide(tiny, PYSEG_SAMPLE_RATE, NULL, tiny_tracks) == tiny_frames,
+ "a one-second recording failed");
+ free(tiny_tracks);
+ free(tiny);
+
+ free(f.samples);
+ free(f.tracks);
+ return TEST_REPORT();
+}
diff --git a/tests/test_util.h b/tests/test_util.h
new file mode 100644
index 0000000..1d8c80e
--- /dev/null
+++ b/tests/test_util.h
@@ -0,0 +1,29 @@
+/* Assertion harness for the C tests: every check reports, nothing aborts, and
+ * the process exit status is the verdict. Keeping going after a failure is
+ * deliberate; when a numeric change breaks several gates at once, the full
+ * list localises it faster than the first failure alone. */
+
+#ifndef PYSEG_TEST_UTIL_H
+#define PYSEG_TEST_UTIL_H
+
+#include <stdio.h>
+
+static int test_failures;
+static int test_checks;
+
+#define TEST_ASSERT(cond, ...) \
+ do { \
+ ++test_checks; \
+ if (!(cond)) { \
+ ++test_failures; \
+ fprintf(stderr, "FAIL %s:%d: ", __FILE__, __LINE__); \
+ fprintf(stderr, __VA_ARGS__); \
+ fputc('\n', stderr); \
+ } \
+ } while (0)
+
+#define TEST_REPORT() \
+ (fprintf(stderr, "%s: %d checks, %d failed\n", __FILE__, test_checks, test_failures), \
+ test_failures ? 1 : 0)
+
+#endif /* PYSEG_TEST_UTIL_H */
diff --git a/tools/baseline.py b/tools/baseline.py
new file mode 100644
index 0000000..08ae72a
--- /dev/null
+++ b/tools/baseline.py
@@ -0,0 +1,137 @@
+"""PyTorch baseline measurement and golden-vector capture.
+
+Usage:
+ python tools/baseline.py bench [--batch N]
+ python tools/baseline.py golden <audio.wav> <out.npz> [--chunks N]
+
+The benchmark protocol is fixed here and mirrored by bench/bench.c so the two
+numbers are comparable: 3 warm-up forwards, then 20 timed forwards on the same
+input, reporting mean, p50 and p99 in milliseconds plus the realtime factor.
+"""
+
+import argparse
+import resource
+import statistics
+import sys
+import time
+
+import numpy as np
+
+from model import NUM_FRAMES, NUM_SAMPLES, SAMPLE_RATE, checkpoint_path
+
+
+def load_torch_model():
+ import torch
+ from pyannote.audio import Model
+
+ torch.set_num_threads(1)
+ model = Model.from_pretrained(checkpoint_path())
+ model.eval()
+ return model
+
+
+def read_wav(path: str) -> np.ndarray:
+ import soundfile as sf
+
+ data, rate = sf.read(path, dtype="float32", always_2d=True)
+ if rate != SAMPLE_RATE:
+ raise SystemExit(f"{path}: expected {SAMPLE_RATE} Hz, got {rate}")
+ return np.ascontiguousarray(data[:, 0])
+
+
+def bench(args) -> int:
+ import torch
+
+ t0 = time.perf_counter()
+ model = load_torch_model()
+ init_ms = (time.perf_counter() - t0) * 1e3
+
+ rng = np.random.default_rng(1)
+ wav = rng.standard_normal((args.batch, 1, NUM_SAMPLES)).astype(np.float32) * 0.1
+ x = torch.from_numpy(wav)
+
+ with torch.no_grad():
+ for _ in range(3):
+ model(x)
+ times = []
+ for _ in range(20):
+ t = time.perf_counter()
+ model(x)
+ times.append((time.perf_counter() - t) * 1e3)
+
+ times.sort()
+ mean = statistics.fmean(times)
+ p50 = times[len(times) // 2]
+ p99 = times[min(len(times) - 1, int(0.99 * len(times)))]
+ audio_s = 10.0 * args.batch
+ rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1e6
+
+ print(f"torch batch={args.batch} threads=1")
+ print(f" init {init_ms:8.1f} ms")
+ print(f" mean/p50/p99 {mean:8.2f} / {p50:.2f} / {p99:.2f} ms")
+ print(f" per chunk {mean / args.batch:8.2f} ms")
+ print(f" realtime factor {audio_s / (mean / 1e3):8.1f}x")
+ print(f" max rss {rss:8.1f} MB")
+ return 0
+
+
+def golden(args) -> int:
+ import torch
+
+ from reference import Reference
+ from model import load_state_dict
+
+ wav = read_wav(args.audio)
+ step = int(1.0 * SAMPLE_RATE)
+ starts = list(range(0, len(wav) - NUM_SAMPLES + 1, step))[: args.chunks]
+ if not starts:
+ raise SystemExit("audio shorter than one 10 s window")
+
+ model = load_torch_model()
+ inputs = np.stack([wav[s : s + NUM_SAMPLES] for s in starts])
+
+ outs = []
+ with torch.no_grad():
+ for i in range(0, len(inputs), 8):
+ batch = torch.from_numpy(inputs[i : i + 8])[:, None, :]
+ outs.append(model(batch).numpy())
+ outputs = np.concatenate(outs)
+ assert outputs.shape == (len(starts), NUM_FRAMES, 7)
+
+ # A numpy-reference pass over the same inputs pins the tolerance the C
+ # engine is later judged against.
+ ref = Reference(load_state_dict())
+ ref_out = np.stack([ref.forward(x) for x in inputs[: min(8, len(inputs))]])
+ diff = np.abs(ref_out - outputs[: len(ref_out)]).max()
+ print(f"numpy reference vs torch on {len(ref_out)} chunks: max diff {diff:.3e}")
+
+ np.savez_compressed(
+ args.out,
+ inputs=inputs.astype(np.float32),
+ outputs=outputs.astype(np.float32),
+ starts=np.array(starts, dtype=np.int64),
+ )
+ print(f"wrote {args.out}: {len(starts)} chunks from {args.audio}")
+ return 0
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ sub = ap.add_subparsers(dest="cmd", required=True)
+
+ b = sub.add_parser("bench")
+ b.add_argument("--batch", type=int, default=1)
+ b.set_defaults(func=bench)
+
+ g = sub.add_parser("golden")
+ g.add_argument("audio")
+ g.add_argument("out")
+ g.add_argument("--chunks", type=int, default=32)
+ g.set_defaults(func=golden)
+
+ args = ap.parse_args()
+ return args.func(args)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/embed.py b/tools/embed.py
new file mode 100644
index 0000000..bc4157e
--- /dev/null
+++ b/tools/embed.py
@@ -0,0 +1,45 @@
+"""Turns the weight blob into a C source file so a binary carries no data file.
+
+Deliberately depends on nothing but the standard library: this runs inside the
+container build, where the checkpoint, PyTorch and pyannote are not present and
+should not have to be. Regenerating the blob itself needs all three and is a
+separate step.
+
+ python3 tools/embed.py pyseg_weights.bin src/weights_blob.c
+"""
+
+import sys
+
+HEADER = """/* Generated by tools/embed.py from {name}. Do not edit.
+ *
+ * The packed weight blob, so a binary needs no data file at runtime.
+ * pyseg_create_from_file reads the identical bytes from disk instead. */
+
+#include <stddef.h>
+
+__attribute__((aligned(64)))
+const unsigned char pyseg_weights_blob[] = {{
+"""
+
+
+def main(argv: list[str]) -> int:
+ if len(argv) != 3:
+ print(__doc__.strip(), file=sys.stderr)
+ return 2
+
+ with open(argv[1], "rb") as f:
+ data = f.read()
+
+ step = 24
+ with open(argv[2], "w") as out:
+ out.write(HEADER.format(name=argv[1]))
+ for i in range(0, len(data), step):
+ out.write("".join(f"{b:d}," for b in data[i : i + step]))
+ out.write("\n")
+ out.write("};\n")
+ out.write(f"const size_t pyseg_weights_blob_len = {len(data)};\n")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))
diff --git a/tools/export_weights.py b/tools/export_weights.py
new file mode 100644
index 0000000..f25455b
--- /dev/null
+++ b/tools/export_weights.py
@@ -0,0 +1,153 @@
+"""Packs the checkpoint into the layout the C engine reads.
+
+Everything the engine needs is a matrix of shape [N, K] multiplied against
+activation windows of K contiguous floats, so the export repacks convolution
+kernels from PyTorch's [out, in, tap] order into [out, tap * in], materialises
+the parametric sinc filterbank, and merges the two LSTM bias vectors. Nothing
+is transformed at load time.
+
+ python tools/export_weights.py <out-dir>
+
+writes <out-dir>/pyseg_weights.bin. tools/embed.py turns that into the C
+source a self-contained binary compiles in; it is kept separate because it
+needs nothing but the standard library and therefore runs anywhere, including
+inside a container build.
+"""
+
+import argparse
+import struct
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from model import SINC_FILTERS, load_state_dict, sinc_filters
+
+MAGIC = b"PSG1"
+VERSION = 1
+NAME_LEN = 24
+ALIGN = 64
+
+# Column count the sinc kernel is padded to. The 251 real taps are followed by
+# five zero weights so the kernel's K is a multiple of four and the innermost
+# loop needs no tail; the samples those zeros multiply are always in range
+# because the last window starts at sample 159740 of 160000.
+SINC_K = 256
+
+
+def fnv1a(data: bytes) -> int:
+ h = 0x811C9DC5
+ for b in data:
+ h = ((h ^ b) * 0x01000193) & 0xFFFFFFFF
+ return h
+
+
+class Blob:
+ def __init__(self):
+ self.tensors = []
+
+ def add(self, name: str, array: np.ndarray) -> None:
+ if len(name) >= NAME_LEN:
+ raise ValueError(f"name too long: {name}")
+ data = np.ascontiguousarray(array, dtype=np.float32)
+ self.tensors.append((name, data))
+
+ def pack(self) -> bytes:
+ header = struct.calcsize("<4sIII")
+ entry = struct.calcsize(f"<{NAME_LEN}sIII")
+ offset = header + entry * len(self.tensors)
+ offset = (offset + ALIGN - 1) // ALIGN * ALIGN
+
+ table, payload, cursor = [], [], offset
+ for name, data in self.tensors:
+ raw = data.tobytes()
+ table.append((name, cursor, len(raw), fnv1a(raw)))
+ payload.append(raw)
+ cursor += len(raw)
+ pad = (-cursor) % ALIGN
+ payload.append(b"\0" * pad)
+ cursor += pad
+
+ out = bytearray()
+ out += struct.pack("<4sIII", MAGIC, VERSION, len(self.tensors), cursor)
+ for name, off, nbytes, digest in table:
+ out += struct.pack(
+ f"<{NAME_LEN}sIII", name.encode(), off, nbytes, digest
+ )
+ out += b"\0" * (offset - len(out))
+ for chunk in payload:
+ out += chunk
+ assert len(out) == cursor
+ return bytes(out)
+
+
+def repack_conv(weight: np.ndarray) -> np.ndarray:
+ """[out, in, tap] -> [out, tap * in], matching a window of tap frames.
+
+ Activations are stored time-major, so the taps a kernel needs for one
+ output step are tap consecutive frames of in channels each: one
+ contiguous span whose element order is tap-major.
+ """
+ out_ch, in_ch, taps = weight.shape
+ return np.ascontiguousarray(weight.transpose(0, 2, 1).reshape(out_ch, taps * in_ch))
+
+
+def build(sd: dict) -> Blob:
+ blob = Blob()
+
+ blob.add("wavnorm", np.stack([sd["sincnet.wav_norm1d.weight"], sd["sincnet.wav_norm1d.bias"]]))
+
+ sinc = np.zeros((SINC_FILTERS, SINC_K), dtype=np.float32)
+ sinc[:, : sinc_filters(sd).shape[1]] = sinc_filters(sd)
+ blob.add("sinc_w", sinc)
+
+ for i, tag in enumerate(("norm1", "norm2", "norm3")):
+ blob.add(f"{tag}_w", sd[f"sincnet.norm1d.{i}.weight"])
+ blob.add(f"{tag}_b", sd[f"sincnet.norm1d.{i}.bias"])
+
+ for src, tag in ((1, "conv2"), (2, "conv3")):
+ blob.add(f"{tag}_w", repack_conv(sd[f"sincnet.conv1d.{src}.weight"]))
+ blob.add(f"{tag}_b", sd[f"sincnet.conv1d.{src}.bias"])
+
+ for layer in range(4):
+ for tag, suffix in (("f", ""), ("b", "_reverse")):
+ key = f"lstm{layer}{tag}"
+ blob.add(f"{key}_ih", sd[f"lstm.weight_ih_l{layer}{suffix}"])
+ blob.add(f"{key}_hh", sd[f"lstm.weight_hh_l{layer}{suffix}"])
+ blob.add(
+ f"{key}_bias",
+ sd[f"lstm.bias_ih_l{layer}{suffix}"] + sd[f"lstm.bias_hh_l{layer}{suffix}"],
+ )
+
+ for i in range(2):
+ blob.add(f"lin{i}_w", sd[f"linear.{i}.weight"])
+ blob.add(f"lin{i}_b", sd[f"linear.{i}.bias"])
+
+ blob.add("cls_w", sd["classifier.weight"])
+ blob.add("cls_b", sd["classifier.bias"])
+ return blob
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument("outdir", nargs="?", default=".")
+ args = ap.parse_args()
+
+ outdir = Path(args.outdir)
+ sd = load_state_dict()
+ blob = build(sd)
+ data = blob.pack()
+
+ binpath = outdir / "pyseg_weights.bin"
+ binpath.write_bytes(data)
+
+ params = sum(t.size for _, t in blob.tensors)
+ print(f"{binpath}: {len(blob.tensors)} tensors, {params} floats, {len(data) / 1e6:.2f} MB")
+ for name, t in blob.tensors:
+ print(f" {name:16s} {str(t.shape):16s}")
+
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/make_golden.py b/tools/make_golden.py
new file mode 100644
index 0000000..109af1d
--- /dev/null
+++ b/tools/make_golden.py
@@ -0,0 +1,93 @@
+"""Converts the captured references into flat binary files the C tests read.
+
+Keeping the test fixtures as plain little-endian float32 means the C side needs
+no parser and no dependency, and the conversion is the only place the two
+representations have to agree.
+
+ python tools/make_golden.py chunks golden.npz build/golden.bin
+ python tools/make_golden.py slide audio.wav build/slide_golden.bin
+"""
+
+import argparse
+import struct
+import sys
+
+import numpy as np
+
+from model import NUM_CLASSES, NUM_FRAMES, NUM_SAMPLES, SAMPLE_RATE
+
+MAGIC_CHUNKS = b"PSGG"
+MAGIC_SLIDE = b"PSGS"
+
+
+def chunks(args) -> int:
+ """Per-window fixtures: waveform in, class probabilities out.
+
+ The torch reference emits log probabilities. They are exponentiated here
+ because that is what the engine returns, and because a difference of 2e-3
+ in a log probability of -17 is a difference of 4e-8 in the probability
+ itself: comparing in log space would set the tolerance by the least
+ significant outputs rather than the ones that decide a frame.
+ """
+ data = np.load(args.npz)
+ inputs = data["inputs"].astype(np.float32)
+ probs = np.exp(data["outputs"].astype(np.float64)).astype(np.float32)
+ n = inputs.shape[0]
+ assert inputs.shape == (n, NUM_SAMPLES)
+ assert probs.shape == (n, NUM_FRAMES, NUM_CLASSES)
+
+ with open(args.out, "wb") as f:
+ f.write(struct.pack("<4sIII", MAGIC_CHUNKS, n, NUM_SAMPLES, NUM_FRAMES))
+ f.write(inputs.tobytes())
+ f.write(np.ascontiguousarray(probs).tobytes())
+ print(f"wrote {args.out}: {n} windows")
+ return 0
+
+
+def slide(args) -> int:
+ """Whole-recording fixture: the aggregated tracks pyannote's Inference
+ produces, next to the samples that produced them."""
+ import soundfile as sf
+
+ from pipeline import aggregate_tracks
+
+ wav, rate = sf.read(args.audio, dtype="float32", always_2d=True)
+ if rate != SAMPLE_RATE:
+ raise SystemExit(f"{args.audio}: expected {SAMPLE_RATE} Hz, got {rate}")
+ samples = np.ascontiguousarray(wav[: args.limit, 0])
+
+ tracks = aggregate_tracks(samples, step=args.step)
+ with open(args.out, "wb") as f:
+ f.write(
+ struct.pack(
+ "<4sIId", MAGIC_SLIDE, len(samples), tracks.shape[0], args.step
+ )
+ )
+ f.write(samples.tobytes())
+ f.write(np.ascontiguousarray(tracks, dtype=np.float32).tobytes())
+ print(f"wrote {args.out}: {len(samples)} samples, {tracks.shape[0]} frames")
+ return 0
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ sub = ap.add_subparsers(dest="cmd", required=True)
+
+ c = sub.add_parser("chunks")
+ c.add_argument("npz")
+ c.add_argument("out")
+ c.set_defaults(func=chunks)
+
+ s = sub.add_parser("slide")
+ s.add_argument("audio")
+ s.add_argument("out")
+ s.add_argument("--step", type=float, default=1.0)
+ s.add_argument("--limit", type=int, default=45 * SAMPLE_RATE)
+ s.set_defaults(func=slide)
+
+ args = ap.parse_args()
+ return args.func(args)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/model.py b/tools/model.py
new file mode 100644
index 0000000..b6601e3
--- /dev/null
+++ b/tools/model.py
@@ -0,0 +1,137 @@
+"""Loading and structural description of pyannote/segmentation-3.0.
+
+The checkpoint is a PyTorch Lightning file whose pickle references pyannote
+classes, so reading it requires pyannote.audio to be importable. Everything
+downstream of this module works on plain numpy arrays.
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+REPO = "pyannote/segmentation-3.0"
+SNAPSHOT = (
+ Path.home()
+ / ".cache/huggingface/hub/models--pyannote--segmentation-3.0/snapshots"
+)
+
+SAMPLE_RATE = 16000
+DURATION = 10.0
+NUM_SAMPLES = 160000
+NUM_FRAMES = 589
+NUM_CLASSES = 7
+HIDDEN = 128
+NUM_LAYERS = 4
+
+# SincNet geometry: (kernel_size, stride) for conv, abs, pool, conv, pool, conv, pool.
+SINC_KERNEL = 251
+SINC_STRIDE = 10
+SINC_FILTERS = 80
+
+
+def checkpoint_path() -> Path:
+ """Path of the single snapshot of the model in the local Hugging Face cache."""
+ snaps = sorted(SNAPSHOT.glob("*/pytorch_model.bin"))
+ if not snaps:
+ raise FileNotFoundError(
+ f"{REPO} not found under {SNAPSHOT}; run \"hf download {REPO}\" first"
+ )
+ return snaps[-1]
+
+
+def load_state_dict() -> dict:
+ """Returns the checkpoint tensors as numpy arrays keyed by parameter name."""
+ import torch
+
+ ckpt = torch.load(checkpoint_path(), map_location="cpu", weights_only=False)
+ return {k: v.numpy().copy() for k, v in ckpt["state_dict"].items()}
+
+
+def sinc_filters(sd: dict) -> np.ndarray:
+ """Materialises the parametric sinc filterbank as a plain [80, 251] matrix.
+
+ asteroid_filterbanks builds the filters from the learned band edges every
+ forward pass, but the edges are frozen at inference time, so the result is a
+ constant that can be folded into the exported weights.
+ """
+ low_hz = sd["sincnet.conv1d.0.filterbank.low_hz_"].astype(np.float64)
+ band_hz = sd["sincnet.conv1d.0.filterbank.band_hz_"].astype(np.float64)
+ window = sd["sincnet.conv1d.0.filterbank.window_"].astype(np.float64)
+ n_ = sd["sincnet.conv1d.0.filterbank.n_"].astype(np.float64)
+
+ min_low_hz, min_band_hz = 50.0, 50.0
+ low = min_low_hz + np.abs(low_hz)
+ high = np.clip(low + min_band_hz + np.abs(band_hz), min_low_hz, SAMPLE_RATE / 2)
+ band = (high - low)[:, 0]
+
+ ft_low = low @ n_
+ ft_high = high @ n_
+
+ cos_left = ((np.sin(ft_high) - np.sin(ft_low)) / (n_ / 2)) * window
+ cos = np.concatenate(
+ [cos_left, 2 * band[:, None], np.flip(cos_left, axis=1)], axis=1
+ )
+ cos /= 2 * band[:, None]
+
+ sin_left = ((np.cos(ft_low) - np.cos(ft_high)) / (n_ / 2)) * window
+ sin = np.concatenate(
+ [sin_left, np.zeros_like(band[:, None]), -np.flip(sin_left, axis=1)], axis=1
+ )
+ sin /= 2 * band[:, None]
+
+ return np.concatenate([cos, sin], axis=0).astype(np.float32)
+
+
+def num_frames(num_samples: int) -> int:
+ """Output frame count of the SincNet stack for a given input length."""
+ geometry = [(SINC_KERNEL, SINC_STRIDE), (3, 3), (5, 1), (3, 3), (5, 1), (3, 3)]
+ n = num_samples
+ for kernel, stride in geometry:
+ n = 1 + (n - kernel) // stride
+ return n
+
+
+def receptive_field() -> tuple[int, int, int]:
+ """(size, step, start) of the output frame grid, in samples.
+
+ Frame f covers the 991 input samples starting at f * 270. The grid begins
+ exactly at sample 0 because the centre of the first frame sits half a
+ receptive field into the signal.
+ """
+ geometry = [(SINC_KERNEL, SINC_STRIDE), (3, 3), (5, 1), (3, 3), (5, 1), (3, 3)]
+
+ def rf_size(frames: int) -> int:
+ size = frames
+ for kernel, stride in reversed(geometry):
+ size = kernel + (size - 1) * stride
+ return size
+
+ def rf_centre(frame: int) -> int:
+ centre = frame
+ for kernel, stride in reversed(geometry):
+ centre = centre * stride + (kernel - 1) // 2
+ return centre
+
+ size = rf_size(1)
+ step = rf_size(2) - size
+ start = rf_centre(0) - (size - 1) // 2
+ return size, step, start
+
+
+def powerset_mapping(num_classes: int = 3, max_set_size: int = 2) -> np.ndarray:
+ """[num_powerset_classes, num_classes] membership matrix in pyannote order."""
+ from itertools import combinations
+
+ rows = []
+ for size in range(max_set_size + 1):
+ for members in combinations(range(num_classes), size):
+ row = np.zeros(num_classes, dtype=np.float32)
+ row[list(members)] = 1.0
+ rows.append(row)
+ return np.stack(rows)
+
+
+FRAME_SIZE, FRAME_STEP, FRAME_START = receptive_field()
+
+assert num_frames(NUM_SAMPLES) == NUM_FRAMES
+assert (FRAME_SIZE, FRAME_STEP, FRAME_START) == (991, 270, 0)
diff --git a/tools/pipeline.py b/tools/pipeline.py
new file mode 100644
index 0000000..c4f675d
--- /dev/null
+++ b/tools/pipeline.py
@@ -0,0 +1,169 @@
+"""Sliding-window aggregation, the reference for src/slide.c.
+
+pyannote's Inference cuts a recording into overlapping ten-second windows,
+converts each window's powerset output to per-speaker activity, and averages
+the windows with a Hamming taper. The taper lets a frame sitting at the edge of
+one window, where the LSTM has only seen context on one side, defer to the
+window that holds it in the middle.
+
+Run as a script it checks this implementation against pyannote's own Inference
+on real audio:
+
+ python tools/pipeline.py <audio.wav>
+"""
+
+import sys
+
+import numpy as np
+
+from model import (
+ FRAME_STEP,
+ NUM_FRAMES,
+ NUM_SAMPLES,
+ SAMPLE_RATE,
+ checkpoint_path,
+ powerset_mapping,
+)
+
+TRACK_SPEECH, TRACK_OVERLAP, TRACK_COUNT = 0, 1, 2
+NUM_TRACKS = 3
+
+
+def rint_div(n: int, d: int) -> int:
+ """Round n/d half to even, matching numpy.rint on the same ratio."""
+ q, r = divmod(n, d)
+ if 2 * r < d:
+ return q
+ if 2 * r > d:
+ return q + 1
+ return q + (q & 1)
+
+
+def window_starts(num_samples: int, step_samples: int) -> list[int]:
+ if num_samples < NUM_SAMPLES:
+ return [0]
+ whole = (num_samples - NUM_SAMPLES) // step_samples + 1
+ starts = [i * step_samples for i in range(whole)]
+ if (num_samples - NUM_SAMPLES) % step_samples > 0:
+ starts.append(whole * step_samples)
+ return starts
+
+
+def num_aggregated_frames(num_samples: int, step: float) -> int:
+ step_samples = int(step * SAMPLE_RATE + 0.5)
+ starts = window_starts(num_samples, step_samples)
+ frames = rint_div(NUM_SAMPLES + (len(starts) - 1) * step_samples, FRAME_STEP) + 1
+ padded = num_samples < NUM_SAMPLES or (num_samples - NUM_SAMPLES) % step_samples > 0
+ if padded:
+ frames = min(frames, num_samples // FRAME_STEP + 1)
+ return frames
+
+
+def powerset_windows(samples: np.ndarray, step: float, batch: int = 8) -> np.ndarray:
+ """[num_windows, NUM_FRAMES, 7] class probabilities from the torch model."""
+ import torch
+ from pyannote.audio import Model
+
+ torch.set_num_threads(1)
+ model = Model.from_pretrained(checkpoint_path())
+ model.eval()
+
+ step_samples = int(step * SAMPLE_RATE + 0.5)
+ starts = window_starts(len(samples), step_samples)
+ windows = np.zeros((len(starts), NUM_SAMPLES), dtype=np.float32)
+ for i, s in enumerate(starts):
+ chunk = samples[s : s + NUM_SAMPLES]
+ windows[i, : len(chunk)] = chunk
+
+ out = []
+ with torch.no_grad():
+ for i in range(0, len(windows), batch):
+ logp = model(torch.from_numpy(windows[i : i + batch])[:, None, :])
+ out.append(torch.exp(logp).numpy())
+ return np.concatenate(out)
+
+
+def window_tracks(probs: np.ndarray) -> np.ndarray:
+ """[num_windows, NUM_FRAMES, 3] speech / overlap / speaker-count votes.
+
+ The powerset output is decoded by taking the most likely class, which is
+ the hard decoding pyannote uses, so each window contributes integers rather
+ than probabilities; the averaging across windows is what makes the
+ aggregate continuous.
+ """
+ mapping = powerset_mapping()
+ active = mapping[probs.argmax(axis=-1)]
+ speakers = active.sum(axis=-1)
+ return np.stack(
+ [(speakers >= 1).astype(np.float32), (speakers >= 2).astype(np.float32), speakers],
+ axis=-1,
+ )
+
+
+def overlap_add(votes: np.ndarray, num_samples: int, step: float) -> np.ndarray:
+ """Hamming-weighted average of per-window tracks onto the frame grid."""
+ step_samples = int(step * SAMPLE_RATE + 0.5)
+ starts = window_starts(num_samples, step_samples)
+ frames = num_aggregated_frames(num_samples, step)
+
+ taper = np.hamming(NUM_FRAMES).astype(np.float32)[:, None]
+ total = np.zeros((frames, votes.shape[-1]), dtype=np.float32)
+ weight = np.zeros((frames, votes.shape[-1]), dtype=np.float32)
+
+ for i, start in enumerate(starts):
+ base = rint_div(start, FRAME_STEP)
+ n = min(NUM_FRAMES, frames - base)
+ if n <= 0:
+ continue
+ total[base : base + n] += votes[i, :n] * taper[:n]
+ weight[base : base + n] += taper[:n]
+
+ return np.where(weight > 1e-12, total / np.maximum(weight, 1e-12), 0.0)
+
+
+def aggregate_tracks(samples: np.ndarray, step: float = 1.0) -> np.ndarray:
+ return overlap_add(
+ window_tracks(powerset_windows(samples, step)), len(samples), step
+ )
+
+
+def main() -> int:
+ """Checks the speech track against pyannote's own VoiceActivityDetection
+ inference, which is the aggregation this file reimplements."""
+ import soundfile as sf
+ import torch
+ from pyannote.audio import Inference, Model
+
+ path = sys.argv[1] if len(sys.argv) > 1 else "testdata_aepyx.wav"
+ limit = int(sys.argv[2]) if len(sys.argv) > 2 else 45 * SAMPLE_RATE
+
+ wav, rate = sf.read(path, dtype="float32", always_2d=True)
+ samples = np.ascontiguousarray(wav[:limit, 0])
+ if rate != SAMPLE_RATE:
+ raise SystemExit(f"{path}: expected {SAMPLE_RATE} Hz")
+
+ torch.set_num_threads(1)
+ model = Model.from_pretrained(checkpoint_path())
+ inference = Inference(
+ model,
+ step=1.0,
+ pre_aggregation_hook=lambda s: np.max(s, axis=-1, keepdims=True),
+ )
+ want = inference(
+ {"waveform": torch.from_numpy(samples)[None, :], "sample_rate": SAMPLE_RATE}
+ ).data[:, 0]
+
+ got = aggregate_tracks(samples)[:, TRACK_SPEECH]
+
+ print(f"frames: pyannote {len(want)}, here {len(got)}")
+ n = min(len(want), len(got))
+ diff = np.abs(want[:n] - got[:n]).max()
+ print(f"max |speech score diff| over {n} frames: {diff:.3e}")
+
+ ok = len(want) == len(got) and diff <= 1e-5
+ print("AGGREGATION OK" if ok else "AGGREGATION MISMATCH")
+ return 0 if ok else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/reference.py b/tools/reference.py
new file mode 100644
index 0000000..1992f7f
--- /dev/null
+++ b/tools/reference.py
@@ -0,0 +1,192 @@
+"""Numpy forward pass for pyannote/segmentation-3.0.
+
+This is the executable specification the C engine is written against: every
+operator appears here in the order and with the exact arithmetic the checkpoint
+was trained with. Run it against the torch model to confirm the two agree:
+
+ .venv/bin/python tools/reference.py
+
+The stage outputs are returned as well, so a failing parity run can be bisected
+to a single stage instead of guessed at.
+"""
+
+import sys
+
+import numpy as np
+
+from model import (
+ HIDDEN,
+ NUM_FRAMES,
+ NUM_SAMPLES,
+ SINC_FILTERS,
+ load_state_dict,
+ sinc_filters,
+)
+
+EPS = 1e-5
+LEAKY = 0.01
+
+
+def instance_norm(x: np.ndarray, weight: np.ndarray, bias: np.ndarray) -> np.ndarray:
+ """InstanceNorm1d(affine=True) over [channels, time]; variance is biased."""
+ mean = x.mean(axis=-1, keepdims=True)
+ var = x.var(axis=-1, keepdims=True)
+ return (x - mean) / np.sqrt(var + EPS) * weight[:, None] + bias[:, None]
+
+
+def leaky_relu(x: np.ndarray) -> np.ndarray:
+ return np.where(x >= 0, x, LEAKY * x)
+
+
+def max_pool(x: np.ndarray, size: int = 3, stride: int = 3) -> np.ndarray:
+ """MaxPool1d over the time axis of a [channels, time] array."""
+ n = 1 + (x.shape[-1] - size) // stride
+ view = np.lib.stride_tricks.as_strided(
+ x,
+ shape=(x.shape[0], n, size),
+ strides=(x.strides[0], x.strides[1] * stride, x.strides[1]),
+ )
+ return view.max(axis=-1)
+
+
+def conv1d(x: np.ndarray, weight: np.ndarray, bias: np.ndarray, stride: int = 1):
+ """Valid 1D convolution of [in_ch, time] with [out_ch, in_ch, kernel]."""
+ in_ch, length = x.shape
+ out_ch, _, kernel = weight.shape
+ n = 1 + (length - kernel) // stride
+ # [in_ch, kernel, n] gather, contracted against the weight in one matmul.
+ cols = np.lib.stride_tricks.as_strided(
+ x,
+ shape=(in_ch, kernel, n),
+ strides=(x.strides[0], x.strides[1], x.strides[1] * stride),
+ ).reshape(in_ch * kernel, n)
+ return weight.reshape(out_ch, in_ch * kernel) @ cols + bias[:, None]
+
+
+def lstm_layer(x, w_ih, w_hh, bias, reverse: bool):
+ """One direction of a PyTorch LSTM layer over [time, features]."""
+ steps = x.shape[0]
+ h = np.zeros(HIDDEN, dtype=np.float32)
+ c = np.zeros(HIDDEN, dtype=np.float32)
+ pre = x @ w_ih.T + bias
+ out = np.empty((steps, HIDDEN), dtype=np.float32)
+ order = range(steps - 1, -1, -1) if reverse else range(steps)
+ for t in order:
+ g = pre[t] + h @ w_hh.T
+ i = sigmoid(g[0:HIDDEN])
+ f = sigmoid(g[HIDDEN : 2 * HIDDEN])
+ gg = np.tanh(g[2 * HIDDEN : 3 * HIDDEN])
+ o = sigmoid(g[3 * HIDDEN : 4 * HIDDEN])
+ c = f * c + i * gg
+ h = o * np.tanh(c)
+ out[t] = h
+ return out
+
+
+def sigmoid(x):
+ return 1.0 / (1.0 + np.exp(-x))
+
+
+def log_softmax(x):
+ m = x.max(axis=-1, keepdims=True)
+ z = x - m
+ return z - np.log(np.exp(z).sum(axis=-1, keepdims=True))
+
+
+class Reference:
+ def __init__(self, sd: dict):
+ self.sd = sd
+ self.sinc = sinc_filters(sd)[:, None, :]
+
+ def sincnet(self, wav: np.ndarray, stages: dict) -> np.ndarray:
+ sd = self.sd
+ x = wav[None, :]
+ x = instance_norm(x, sd["sincnet.wav_norm1d.weight"], sd["sincnet.wav_norm1d.bias"])
+ stages["wav_norm"] = x
+
+ x = conv1d(x, self.sinc, np.zeros(SINC_FILTERS, dtype=np.float32), stride=10)
+ x = np.abs(x)
+ stages["sinc"] = x
+ x = max_pool(x)
+ stages["pool1"] = x
+ x = leaky_relu(instance_norm(x, sd["sincnet.norm1d.0.weight"], sd["sincnet.norm1d.0.bias"]))
+ stages["block1"] = x
+
+ x = conv1d(x, sd["sincnet.conv1d.1.weight"], sd["sincnet.conv1d.1.bias"])
+ stages["conv2"] = x
+ x = max_pool(x)
+ x = leaky_relu(instance_norm(x, sd["sincnet.norm1d.1.weight"], sd["sincnet.norm1d.1.bias"]))
+ stages["block2"] = x
+
+ x = conv1d(x, sd["sincnet.conv1d.2.weight"], sd["sincnet.conv1d.2.bias"])
+ x = max_pool(x)
+ x = leaky_relu(instance_norm(x, sd["sincnet.norm1d.2.weight"], sd["sincnet.norm1d.2.bias"]))
+ stages["block3"] = x
+ return x
+
+ def forward(self, wav: np.ndarray, stages: dict | None = None) -> np.ndarray:
+ """[num_samples] float32 waveform -> [num_frames, 7] log probabilities."""
+ stages = {} if stages is None else stages
+ sd = self.sd
+
+ x = self.sincnet(wav, stages).T # [time, 60]
+
+ for layer in range(4):
+ suffix = f"l{layer}"
+ fwd = lstm_layer(
+ x,
+ sd[f"lstm.weight_ih_{suffix}"],
+ sd[f"lstm.weight_hh_{suffix}"],
+ sd[f"lstm.bias_ih_{suffix}"] + sd[f"lstm.bias_hh_{suffix}"],
+ reverse=False,
+ )
+ bwd = lstm_layer(
+ x,
+ sd[f"lstm.weight_ih_{suffix}_reverse"],
+ sd[f"lstm.weight_hh_{suffix}_reverse"],
+ sd[f"lstm.bias_ih_{suffix}_reverse"] + sd[f"lstm.bias_hh_{suffix}_reverse"],
+ reverse=True,
+ )
+ x = np.concatenate([fwd, bwd], axis=-1)
+ stages[f"lstm{layer}"] = x
+
+ for i in range(2):
+ x = leaky_relu(x @ sd[f"linear.{i}.weight"].T + sd[f"linear.{i}.bias"])
+ stages[f"linear{i}"] = x
+
+ logits = x @ sd["classifier.weight"].T + sd["classifier.bias"]
+ stages["logits"] = logits
+ return log_softmax(logits)
+
+
+def main() -> int:
+ import torch
+ from pyannote.audio import Model
+
+ from model import checkpoint_path
+
+ sd = load_state_dict()
+ ref = Reference(sd)
+
+ torch_model = Model.from_pretrained(checkpoint_path())
+ torch_model.eval()
+
+ rng = np.random.default_rng(0)
+ worst = 0.0
+ for trial in range(3):
+ wav = rng.standard_normal(NUM_SAMPLES).astype(np.float32) * 0.1
+ with torch.no_grad():
+ want = torch_model(torch.from_numpy(wav)[None, None, :]).numpy()[0]
+ got = ref.forward(wav)
+ assert got.shape == (NUM_FRAMES, 7), got.shape
+ diff = np.abs(got - want).max()
+ worst = max(worst, diff)
+ print(f"trial {trial}: max |log-prob diff| = {diff:.3e}")
+
+ ok = worst <= 2e-4
+ print(f"worst {worst:.3e} -> {'PARITY OK' if ok else 'PARITY FAILED'}")
+ return 0 if ok else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/verify_cli.py b/tools/verify_cli.py
new file mode 100644
index 0000000..15e7cef
--- /dev/null
+++ b/tools/verify_cli.py
@@ -0,0 +1,132 @@
+"""End-to-end check of the built binary against pyannote's own pipelines.
+
+The parity tests compare tensors; this compares what a user actually gets. It
+derives speech and overlapped-speech segments from pyannote for a recording,
+runs pyseg_cli over the same file, and reports both the segment boundaries
+and the fraction of the timeline the two disagree about, which is the number
+that matters for anything downstream.
+
+ python tools/verify_cli.py <audio.wav> [--limit SECONDS] [--step SECONDS]
+"""
+
+import argparse
+import subprocess
+import sys
+
+import numpy as np
+
+from model import SAMPLE_RATE, checkpoint_path
+
+BINARY = "./pyseg_cli"
+
+
+def run_cli(path: str, mode: str, step: float) -> list[tuple[float, float]]:
+ out = subprocess.run(
+ [BINARY, "--mode", mode, "--step", str(step), path],
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout
+ return [
+ (float(a), float(b))
+ for a, b in (line.split() for line in out.splitlines() if line.strip())
+ ]
+
+
+def run_pyannote(path: str, mode: str, step: float):
+ """Reference segments for one track.
+
+ Speech goes through pyannote's own VoiceActivityDetection pipeline. Overlap
+ is assembled here from the same parts, because the pipeline that used to
+ wrap them was dropped from pyannote.audio: take the second largest
+ per-speaker score of each frame, which for this model's hard multi-label
+ output is one exactly when at least two speakers are active, aggregate, and
+ binarize with the same thresholds.
+ """
+ import torch
+ from pyannote.audio import Inference, Model
+ from pyannote.audio.pipelines import VoiceActivityDetection
+ from pyannote.audio.utils.signal import Binarize
+
+ torch.set_num_threads(1)
+ model = Model.from_pretrained(checkpoint_path())
+
+ if mode == "speech":
+ pipeline = VoiceActivityDetection(segmentation=model, step=step)
+ pipeline.instantiate({"min_duration_on": 0.0, "min_duration_off": 0.0})
+ annotation = pipeline(path)
+ else:
+ inference = Inference(
+ model,
+ step=step,
+ pre_aggregation_hook=lambda s: np.partition(s, -2, axis=-1)[:, :, -2, np.newaxis],
+ )
+ binarize = Binarize(
+ onset=0.5, offset=0.5, min_duration_on=0.0, min_duration_off=0.0
+ )
+ annotation = binarize(inference(path))
+
+ return [(s.start, s.end) for s in annotation.get_timeline()]
+
+
+def timeline_mask(segments, duration: float, resolution: float = 0.01) -> np.ndarray:
+ n = int(duration / resolution) + 1
+ mask = np.zeros(n, dtype=bool)
+ for start, end in segments:
+ mask[int(start / resolution) : int(end / resolution) + 1] = True
+ return mask
+
+
+def compare(name: str, got, want, duration: float) -> bool:
+ a, b = timeline_mask(got, duration), timeline_mask(want, duration)
+ n = min(len(a), len(b))
+ disagree = np.count_nonzero(a[:n] != b[:n]) / n
+ covered = np.count_nonzero(b[:n]) / n
+
+ print(f"{name}: {len(got)} segments here, {len(want)} from pyannote")
+ print(f" reference covers {covered:6.2%} of the timeline")
+ print(f" disagreement {disagree:6.4%} of the timeline")
+
+ worst = 0.0
+ for (s0, e0), (s1, e1) in zip(got, want):
+ worst = max(worst, abs(s0 - s1), abs(e0 - e1))
+ if len(got) == len(want):
+ print(f" worst boundary shift {worst * 1e3:.1f} ms")
+
+ ok = disagree <= 1e-3
+ print(f" {'OK' if ok else 'MISMATCH'}")
+ return ok
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument("audio")
+ ap.add_argument("--limit", type=int, default=None, help="seconds of audio to use")
+ ap.add_argument("--step", type=float, default=1.0)
+ args = ap.parse_args()
+
+ import soundfile as sf
+
+ info = sf.info(args.audio)
+ if info.samplerate != SAMPLE_RATE:
+ raise SystemExit(f"{args.audio}: expected {SAMPLE_RATE} Hz")
+ duration = info.duration if args.limit is None else min(info.duration, args.limit)
+
+ path = args.audio
+ if args.limit is not None:
+ wav, rate = sf.read(args.audio, dtype="float32", always_2d=True)
+ path = "build/verify_clip.wav"
+ sf.write(path, wav[: args.limit * rate, :1], rate, subtype="PCM_16")
+
+ ok = True
+ for mode in ("speech", "overlap"):
+ got = run_cli(path, mode, args.step)
+ want = run_pyannote(path, mode, args.step)
+ ok &= compare(mode, got, want, duration)
+
+ print("VERIFY OK" if ok else "VERIFY FAILED")
+ return 0 if ok else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())