Skip to content

Commit e86ade5

Browse files
authored
feat(api): add /v1/audio/diarization endpoint with sherpa-onnx + vibevoice.cpp (#9654)
* feat(api): add /v1/audio/diarization endpoint with sherpa-onnx + vibevoice.cpp Closes #1648. OpenAI-style multipart endpoint that returns "who spoke when". Single endpoint instead of the issue's three-endpoint sketch (refactor /vad, /vad/embedding, /diarization) — the typical client wants one call, and embeddings can land later as a sibling without breaking this surface. Response shape borrows from Pyannote/Deepgram: segments carry a normalised SPEAKER_NN id (zero-padded, stable across the response) plus the raw backend label, optional per-segment text when the backend bundles ASR, and a speakers summary in verbose_json. response_format also accepts rttm so consumers can pipe straight into pyannote.metrics / dscore. Backends: * vibevoice-cpp — Diarize() reuses the existing vv_capi_asr pass. vibevoice's ASR prompt asks the model to emit [{Start,End,Speaker,Content}] natively, so diarization is a by-product of the same pass; include_text=true preserves the transcript per segment, otherwise we drop it. * sherpa-onnx — wraps the upstream SherpaOnnxOfflineSpeakerDiarization C API (pyannote segmentation + speaker-embedding extractor + fast clustering). libsherpa-shim grew config builders, a SetClustering wrapper for per-call num_clusters/threshold overrides, and a segment_at accessor (purego can't read field arrays out of SherpaOnnxOfflineSpeakerDiarizationSegment[] directly). Plumbing: new Diarize gRPC RPC + DiarizeRequest / DiarizeSegment / DiarizeResponse messages, threaded through interface.go, base, server, client, embed. Default Base impl returns unimplemented. Capability surfaces all updated: FLAG_DIARIZATION usecase, FeatureAudioDiarization permission (default-on), RouteFeatureRegistry entries for /v1/audio/diarization and /audio/diarization, audio instruction-def description widened, CAP_DIARIZATION JS symbol, swagger regenerated, /api/instructions discovery map updated. Tests: * core/backend: speaker-label normalisation (first-seen → SPEAKER_NN, per-speaker totals, nil-safety, fallback to backend NumSpeakers when no segments). * core/http/endpoints/openai: RTTM rendering (file-id basename, negative duration clamping, fallback id). * tests/e2e: mock-backend grew a deterministic Diarize that emits raw labels "5","2","5" so the e2e suite verifies SPEAKER_NN remapping, verbose_json speakers summary + transcript pass-through (gated by include_text), RTTM bytes content-type, and rejection of unknown response_format. mock-diarize model config registered with known_usecases=[FLAG_DIARIZATION] to bypass the backend-name guard. Docs: new features/audio-diarization.md (request/response, RTTM example, sherpa-onnx + vibevoice setup), cross-link from audio-to-text.md, entry in whats-new.md. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-7 [Claude Code] * fix(diarization): correct sherpa-onnx symbol name + lint cleanup CI failures on #9654: * sherpa-onnx-grpc-{tts,transcription} and sherpa-onnx-realtime panicked at backend startup with `undefined symbol: SherpaOnnxDestroyOfflineSpeakerDiarizationResult`. Upstream's actual symbol is SherpaOnnxOfflineSpeakerDiarizationDestroyResult (Destroy in the middle, not the prefix); the rest of the diarization surface follows the same naming pattern. The mismatched name made purego.RegisterLibFunc fail at dlopen time and crashed the gRPC server before the BeforeAll could probe Health, taking down every sherpa-onnx test job — not just the diarization-related ones. * golangci-lint flagged 5 errcheck violations on new defer cleanups (os.RemoveAll / Close / conn.Close); wrap each in a `defer func() { _ = X() }()` closure (matches the pattern other LocalAI files use for new code, since pre-existing bare defers are grandfathered in via new-from-merge-base). * golangci-lint also flagged forbidigo violations: the new diarization_test.go files used testing.T-style `t.Errorf` / `t.Fatalf`, which are forbidden by the project's coding-style policy (.agents/coding-style.md). Convert both files to Ginkgo/Gomega Describe/It with Expect(...) — they get picked up by the existing TestBackend / TestOpenAI suites, no new suite plumbing needed. * modernize linter: tightened the diarization segment loop to `for i := range int(numSegments)` (Go 1.22+ idiom). Verified locally: golangci-lint with new-from-merge-base=origin/master reports 0 issues across all touched packages, and the four mocked diarization e2e specs in tests/e2e/mock_backend_test.go still pass. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-7 [Claude Code] * fix(vibevoice-cpp): convert non-WAV input via ffmpeg + raise ASR token budget Confirmed end-to-end against a real LocalAI instance with vibevoice-asr-q4_k loaded and the multi-speaker MP3 sample at vibevoice.cpp/samples/2p_argument.mp3: both /v1/audio/transcriptions and /v1/audio/diarization now succeed and return correctly attributed speaker turns for the full clip. Two latent issues surfaced once the diarization endpoint actually exercised the backend with a non-trivial input: 1. vv_capi_asr only accepts WAV via load_wav_24k_mono. The previous code passed the uploaded path straight through, so anything that wasn't already a 24 kHz mono s16le WAV failed at the C side with rc=-8 and the very unhelpful "vv_capi_asr failed". prepareWavInput shells out to ffmpeg ("-ar 24000 -ac 1 -acodec pcm_s16le") in a per-call temp dir, matching the rate the model was trained on; both AudioTranscription and Diarize now route through it. This is the same shape sherpa-onnx uses (utils.AudioToWav), but vibevoice needs 24 kHz rather than 16 kHz so we don't reuse that helper. 2. The C ABI's max_new_tokens defaults to 256 when 0 is passed. That's fine for a five-second clip but not for anything past ~10 s — vibevoice stops mid-JSON, the parse fails, and the caller sees a hard error. Pass a much larger budget (16 384 ≈ ~9 minutes of speech at the model's ~30 tok/s rate); generation stops at EOS so this is a cap rather than a target. 3. As a defensive belt-and-braces, mirror AudioTranscription's existing "fall back to a single segment if the model emits non-JSON text" pattern in Diarize, so partial / unusual model output never produces a 500. This kept the endpoint usable while diagnosing (1) and (2), and is the right behaviour to keep. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-7 [Claude Code] * fix(vibevoice-cpp): pass valid WAVs through directly so ffmpeg is not required at runtime Spotted by tests-e2e-backend (1.25.x): the previous fix forced every incoming audio file through `ffmpeg -ar 24000 ...`, which meant the backend container — which does not ship ffmpeg — failed even for the existing happy path where the caller already uploads a WAV. The container-side error was: rpc error: code = Unknown desc = vibevoice-cpp: ffmpeg convert to 24k mono wav: exec: "ffmpeg": executable file not found in $PATH Reading vibevoice.cpp's audio_io.cpp, `load_wav_24k_mono` uses drwav and already accepts any PCM/IEEE-float WAV at any sample rate, downmixes multi-channel input to mono, and resamples to 24 kHz internally. So the only inputs that genuinely need an external converter are non-WAV formats (MP3, OGG, FLAC, ...). Detect WAVs by RIFF/WAVE magic at bytes 0..3 / 8..11 and pass them straight through with a no-op cleanup; everything else still goes through ffmpeg with the same 24 kHz mono s16le target. The result: * Container builds without ffmpeg keep working for WAV uploads (the e2e-backends fixture is jfk.wav at 16 kHz mono s16le). * MP3 and other non-WAV inputs still get the new ffmpeg conversion path so the diarization endpoint stays useful. * If the caller uploads a non-WAV but ffmpeg isn't on PATH, the surfaced error is still descriptive enough to act on. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-7 [Claude Code] * fix(ci): make gcc-14 install in Dockerfile.golang best-effort for jammy bases The LocalVQE PR (bb033b1) made `gcc-14 g++-14` an unconditional apt install in backend/Dockerfile.golang and pointed update-alternatives at them. That works on the default `BASE_IMAGE=ubuntu:24.04` (noble has gcc-14 in main), but every Go backend that builds on `nvcr.io/nvidia/l4t-jetpack:r36.4.0` — jammy under the hood — now fails at the apt step: E: Unable to locate package gcc-14 This blocked unrelated jobs: backend-jobs(*-nvidia-l4t-arm64-{stablediffusion-ggml, sam3-cpp, whisper, acestep-cpp, qwen3-tts-cpp, vibevoice-cpp}). LocalVQE itself is only matrix-built on ubuntu:24.04 (CPU + Vulkan), so it doesn't actually need gcc-14 anywhere else. Make the gcc-14 install conditional on the package being available in the configured apt repos. On noble: identical behaviour to today (gcc-14 installed, update-alternatives points at it). On jammy: skip the gcc-14 stanza entirely and let build-essential's default gcc take over, which is what the other Go backends compile with anyway. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-7 [Claude Code] --------- Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
1 parent 1634eec commit e86ade5

35 files changed

Lines changed: 1932 additions & 6 deletions

backend/Dockerfile.golang

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,28 @@ ENV AMDGPU_TARGETS=${AMDGPU_TARGETS}
2121
ARG APT_MIRROR
2222
ARG APT_PORTS_MIRROR
2323

24+
# gcc-14 is the default on noble (ubuntu:24.04) but absent from jammy
25+
# (the L4T jetpack r36.4.0 base). LocalVQE specifically needs it; the
26+
# other Go backends compile fine with the default gcc shipped via
27+
# build-essential. So: try gcc-14 from the configured repos, fall back
28+
# gracefully when it's not available so jammy-based builds don't fail
29+
# at the apt step.
2430
RUN --mount=type=bind,source=.docker/apt-mirror.sh,target=/usr/local/sbin/apt-mirror \
2531
APT_MIRROR="${APT_MIRROR}" APT_PORTS_MIRROR="${APT_PORTS_MIRROR}" sh /usr/local/sbin/apt-mirror && \
2632
apt-get update && \
2733
apt-get install -y --no-install-recommends \
2834
build-essential \
29-
gcc-14 g++-14 \
3035
git ccache \
3136
ca-certificates \
3237
make cmake wget libopenblas-dev \
3338
curl unzip \
3439
libssl-dev && \
35-
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 100 \
36-
--slave /usr/bin/g++ g++ /usr/bin/g++-14 \
37-
--slave /usr/bin/gcov gcov /usr/bin/gcov-14 && \
40+
if apt-cache show gcc-14 >/dev/null 2>&1 && apt-cache show g++-14 >/dev/null 2>&1; then \
41+
apt-get install -y --no-install-recommends gcc-14 g++-14 && \
42+
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 100 \
43+
--slave /usr/bin/g++ g++ /usr/bin/g++-14 \
44+
--slave /usr/bin/gcov gcov /usr/bin/gcov-14; \
45+
fi && \
3846
apt-get clean && \
3947
rm -rf /var/lib/apt/lists/*
4048

backend/backend.proto

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ service Backend {
4141

4242
rpc VAD(VADRequest) returns (VADResponse) {}
4343

44+
rpc Diarize(DiarizeRequest) returns (DiarizeResponse) {}
45+
4446
rpc AudioEncode(AudioEncodeRequest) returns (AudioEncodeResult) {}
4547
rpc AudioDecode(AudioDecodeRequest) returns (AudioDecodeResult) {}
4648

@@ -416,6 +418,43 @@ message VADResponse {
416418
repeated VADSegment segments = 1;
417419
}
418420

421+
// --- Speaker diarization messages ---
422+
//
423+
// Pure speaker diarization: "who spoke when". Returns time-stamped segments
424+
// labelled with cluster IDs (the same string for the same speaker across
425+
// segments). Some backends (e.g. vibevoice.cpp) produce diarization as a
426+
// by-product of ASR and may also fill in `text` per segment; backends with a
427+
// dedicated diarization pipeline (e.g. sherpa-onnx pyannote) leave `text`
428+
// empty and emit only the segmentation.
429+
430+
message DiarizeRequest {
431+
string dst = 1; // path to audio file (HTTP layer materialises uploads to a temp file)
432+
uint32 threads = 2;
433+
string language = 3; // optional; only meaningful for transcription-bundling backends
434+
int32 num_speakers = 4; // exact speaker count if known (>0 forces); 0 = auto
435+
int32 min_speakers = 5; // hint when auto-detecting; 0 = unset
436+
int32 max_speakers = 6; // hint when auto-detecting; 0 = unset
437+
float clustering_threshold = 7; // distance threshold when num_speakers unknown; 0 = backend default
438+
float min_duration_on = 8; // discard segments shorter than this (seconds); 0 = backend default
439+
float min_duration_off = 9; // merge gaps shorter than this (seconds); 0 = backend default
440+
bool include_text = 10; // when the backend can emit per-segment transcript for free, ask it to populate `text`
441+
}
442+
443+
message DiarizeSegment {
444+
int32 id = 1;
445+
float start = 2; // seconds
446+
float end = 3; // seconds
447+
string speaker = 4; // backend-emitted speaker label (e.g. "0", "SPEAKER_00")
448+
string text = 5; // optional per-segment transcript (empty unless include_text and supported)
449+
}
450+
451+
message DiarizeResponse {
452+
repeated DiarizeSegment segments = 1;
453+
int32 num_speakers = 2; // count of distinct speaker labels in `segments`
454+
float duration = 3; // total audio duration in seconds (0 if unknown)
455+
string language = 4; // optional, when the backend bundles transcription
456+
}
457+
419458
message SoundGenerationRequest {
420459
string text = 1;
421460
string model = 2;

0 commit comments

Comments
 (0)