fix(bindings): expose FoxNose speaker turns

Author: crispasr integration

.github/workflows/regression.yml

@@ -44,6 +44,8 @@ on:
   pull_request:
     paths:
       - 'tests/regression/**'
+      - 'tests/test_python_diarize_turns.py'
+      - 'python/crispasr/**'
       - '.github/workflows/regression.yml'
 
 permissions:
@@ -98,6 +100,10 @@ jobs:
         run: |
           python -m pytest tests/test_python_chat.py -v || \
           python -m unittest tests/test_python_chat.py -v
+      - name: Run Python diarization ABI tests
+        run: |
+          python -m pytest tests/test_python_diarize_turns.py -v || \
+          python tests/test_python_diarize_turns.py -v
       # Perf-regression compare logic (docs/perf-sweep/PLAN.md TODO-4). Model-free —
       # guards the hard/soft-gate logic used by the nightly perf snapshot step below.
       - name: Run perf-baseline compare unit tests

PLAN.md

@@ -618,14 +618,13 @@ verified locally on `samples/multispeaker.wav` + wespeaker-resnet34-lm, where
 the fixture does exercise a segment covering two speakers. Same pair of
 levels on the Rust side in `crispasr/tests/integration.rs`.
 
-**Not done, and deliberately: the other bindings.** Go, Python, Java, Ruby,
-Dart and JS still expose only `crispasr_diarize_segments_abi`. Nothing there
-is broken — the new symbol is additive — but a caller on those surfaces still
-cannot split a segment. Extending them is a mechanical follow-up (each has a
-hand-written mirror; the new turn struct is its own 24-byte POD, NOT an
-append to the opts struct). `tests/test_binding_parity.py`'s curated symbol
-list is unchanged for the same reason: adding the symbol there would fail
-until the Python binding declares it.
+Follow-up completed 2026-09-06: Go, Python, and Dart now size and retry the
+turn buffer and expose typed turn results; Java declares both calls on its
+low-level JNA surface. The Python audit also found and repaired a separate
+ABI bug: its options mirror had remained at 24 bytes after FoxNose extended
+the native append-only struct to 48 bytes. JavaScript and Ruby have no public
+standalone diarization API today (their unused C declarations were previously
+mistaken for binding support), so there is no turn-returning surface to extend.
 
 ## CLAIMED 2026-08-19 — Issue #375 Canary streaming regression
 

bindings/java/src/main/java/io/github/ggerganov/whispercpp/CrispasrSession.java

@@ -315,6 +315,9 @@ int     crispasr_pyannote_cache_apply_abi(Pointer cache, long sliceT0Cs,
         // Diarization
         int crispasr_diarize_segments_abi(float[] leftPcm, float[] rightPcm, int nSamples,
                                           int isStereo, Pointer segs, int nSegs, Pointer opts);
+        int crispasr_diarize_segments_turns_abi(float[] leftPcm, float[] rightPcm, int nSamples,
+                                                int isStereo, Pointer segs, int nSegs, Pointer opts,
+                                                Pointer outTurns, int turnsCap, IntByReference outNTurns);
 
         // Text-LID
         int crispasr_text_detect_language(String text, String modelPath, int nThreads,

docs/bindings.md

@@ -173,7 +173,8 @@ exposes them as struct/class members on its segment type.
 
 ```python
 from crispasr import (
-    Session, diarize_segments, detect_language_pcm,
+    Session, diarize_segments, diarize_segments_with_turns,
+    detect_language_pcm,
     align_words, cache_ensure_file, registry_default_bundle,
     # Diarize pipeline primitives (#107):
     SpeakerEmbedder, PyannoteCache, agglomerative_cluster,
@@ -188,6 +189,10 @@ segs = sess.transcribe_vad(pcm, "silero-v6.2.0.bin")  # stitched VAD pass
 # Run each shared post-step standalone
 lang = detect_language_pcm(pcm, model_path="ggml-tiny.bin")
 diarize_segments(my_segs, pcm, method=DiarizeMethod.VAD_TURNS)
+ok, turns = diarize_segments_with_turns(
+    my_segs, pcm, method=DiarizeMethod.FOXNOSE,
+    foxnose_embedder_path="wespeaker-resnet34-lm.gguf",
+)
 words = align_words("canary-ctc-aligner.gguf", "hello world", pcm)
 
 # Inspect the canonical bundle used by `-m auto` (no quant suffix).

docs/diarization-speakers.md

@@ -298,8 +298,11 @@ for them and you get the audio's own boundaries, independent of your grid:
 | C ABI | `crispasr_diarize_segments_turns_abi(...)` (0.8.30+) |
 | Rust | `crispasr::diarize_segments_with_turns(...) -> Result<Vec<DiarizeTurn>, String>` |
 | Go | `whisper.DiarizeSegmentsWithTurns(...) ([]DiarizeTurn, error)` |
+| Python | `diarize_segments_with_turns(...) -> (bool, list[DiarizeTurn])` |
+| Dart | `diarizeSegments(..., outTurns: turns)` |
+| Java/JNA | `Lib.crispasr_diarize_segments_turns_abi(...)` |
 
-All four are additive: the segments come back labelled exactly as they would
+All surfaces are additive: the segments come back labelled exactly as they would
 without the turns, and every other method reports zero turns rather than an
 error. Turn timestamps are on the **same absolute timeline as your segments**
 (the ABI adds `slice_t0_cs` back on the way out), so they compare directly.
@@ -316,12 +319,14 @@ Its turn buffer is caller-allocated: pass `out_n_turns` to learn the count,
 `out_turns` + `n_turns_cap` to receive them, and expect `2` when the buffer
 was short — the segments are still labelled, `*out_n_turns` holds the required
 capacity, and a retry costs a second full pass because the ABI keeps no state
-between calls. The Rust and Go wrappers size the buffer from the audio length
+between calls. The Rust, Go, Python, and Dart wrappers size the buffer from
+the audio length
 (one slot per 0.5 s, above FoxNose's 0.6 s embedding hop) and retry once on
 `2`, so their callers never see any of that.
 
-Java, JavaScript and Ruby wrap `crispasr_diarize_segments_abi` but not yet the
-turns symbol; nothing is broken there, they simply cannot reach the turns.
+Java exposes both calls at its low-level JNA surface. JavaScript and Ruby do
+not currently expose standalone diarization; their unused native declarations
+are not public binding APIs.
 
 ## pyannote segmentation: chunked inference and the powerset layout (#326)
 

flutter/crispasr/lib/src/crispasr.dart

@@ -217,6 +217,17 @@ class DiarizeSegment {
   DiarizeSegment({required this.t0, required this.t1, this.speaker = -1});
 }
 
+/// One audio-derived speaker turn returned by FoxNose.
+///
+/// Times are seconds on the same absolute timeline as [DiarizeSegment].
+class DiarizeTurn {
+  final double t0;
+  final double t1;
+  final int speaker;
+  const DiarizeTurn(
+      {required this.t0, required this.t1, required this.speaker});
+}
+
 enum DiarizeMethod {
   /// Stereo only. |L| vs |R| energy per segment, 1.1× margin.
   energy,
@@ -258,6 +269,10 @@ enum DiarizeMethod {
 /// WeSpeaker embedder GGUF; [minSpeakers] / [maxSpeakers] bound the
 /// automatic speaker-count estimation (0 keeps the library defaults 1 / 8)
 /// and [numSpeakers] > 0 pins the count and skips estimation.
+///
+/// When [outTurns] is supplied, the function calls the CrispASR 0.8.30+
+/// turn-returning ABI and replaces that list with FoxNose's audio-derived
+/// turns. Other methods leave it empty.
 bool diarizeSegments({
   required List<DiarizeSegment> segs,
   required Float32List left,
@@ -271,8 +286,10 @@ bool diarizeSegments({
   int minSpeakers = 0,
   int maxSpeakers = 0,
   int numSpeakers = 0,
+  List<DiarizeTurn>? outTurns,
   DynamicLibrary? lib,
 }) {
+  outTurns?.clear();
   if (segs.isEmpty || left.isEmpty) return true;
   lib ??= DynamicLibrary.open(CrispASR.defaultLibName());
 
@@ -329,13 +346,68 @@ bool diarizeSegments({
   (optsPtr + 40).cast<Int32>().value = numSpeakers;
   (optsPtr + 44).cast<Int32>().value = 0;
 
-  final fn = lib.lookupFunction<
-      Int32 Function(Pointer<Float>, Pointer<Float>, Int32, Int32,
-          Pointer<Uint8>, Int32, Pointer<Uint8>),
-      int Function(Pointer<Float>, Pointer<Float>, int, int, Pointer<Uint8>,
-          int, Pointer<Uint8>)>('crispasr_diarize_segments_abi');
-  final rc =
-      fn(leftPtr, rightPtr, n, isStereo ? 1 : 0, segsPtr, segs.length, optsPtr);
+  var rc = 0;
+  if (outTurns == null) {
+    final fn = lib.lookupFunction<
+        Int32 Function(Pointer<Float>, Pointer<Float>, Int32, Int32,
+            Pointer<Uint8>, Int32, Pointer<Uint8>),
+        int Function(Pointer<Float>, Pointer<Float>, int, int, Pointer<Uint8>,
+            int, Pointer<Uint8>)>('crispasr_diarize_segments_abi');
+    rc = fn(
+        leftPtr, rightPtr, n, isStereo ? 1 : 0, segsPtr, segs.length, optsPtr);
+  } else {
+    final fn = lib.lookupFunction<
+        Int32 Function(
+            Pointer<Float>,
+            Pointer<Float>,
+            Int32,
+            Int32,
+            Pointer<Uint8>,
+            Int32,
+            Pointer<Uint8>,
+            Pointer<Uint8>,
+            Int32,
+            Pointer<Int32>),
+        int Function(
+            Pointer<Float>,
+            Pointer<Float>,
+            int,
+            int,
+            Pointer<Uint8>,
+            int,
+            Pointer<Uint8>,
+            Pointer<Uint8>,
+            int,
+            Pointer<Int32>)>('crispasr_diarize_segments_turns_abi');
+    var turnCap = ((n + 7999) ~/ 8000) + segs.length + 16;
+    for (var attempt = 0; attempt < 2; attempt++) {
+      final turnsPtr = calloc<Uint8>(turnCap * 24);
+      final nTurnsPtr = calloc<Int32>();
+      rc = fn(leftPtr, rightPtr, n, isStereo ? 1 : 0, segsPtr, segs.length,
+          optsPtr, turnsPtr, turnCap, nTurnsPtr);
+      final required = nTurnsPtr.value;
+      if (rc == 2 && attempt == 0 && required > turnCap) {
+        calloc.free(turnsPtr);
+        calloc.free(nTurnsPtr);
+        turnCap = required;
+        continue;
+      }
+      if (rc == 0) {
+        final count = required < turnCap ? required : turnCap;
+        for (var i = 0; i < count; i++) {
+          final base = turnsPtr + i * 24;
+          outTurns.add(DiarizeTurn(
+            t0: base.cast<Int64>().value / 100.0,
+            t1: (base + 8).cast<Int64>().value / 100.0,
+            speaker: (base + 16).cast<Int32>().value,
+          ));
+        }
+      }
+      calloc.free(turnsPtr);
+      calloc.free(nTurnsPtr);
+      break;
+    }
+  }
 
   if (rc == 0) {
     for (var i = 0; i < segs.length; i++) {

flutter/crispasr/test/bindings_smoke_test.dart

@@ -7,8 +7,10 @@
 
 import 'dart:ffi';
 import 'dart:io';
+import 'dart:typed_data';
 
-import 'package:crispasr/crispasr.dart' show DiarizeMethod, LidMethod;
+import 'package:crispasr/crispasr.dart'
+    show DiarizeMethod, DiarizeSegment, DiarizeTurn, LidMethod, diarizeSegments;
 import 'package:ffi/ffi.dart';
 import 'package:test/test.dart';
 
@@ -300,6 +302,7 @@ void main() {
       'crispasr_params_set_max_tokens',
       'crispasr_text_detect_language',
       'crispasr_enhance_audio_rnnoise',
+      'crispasr_diarize_segments_turns_abi',
     ]) {
       expect(() => lib.lookup(s), returnsNormally,
           reason: 'missing C-ABI symbol: $s');
@@ -339,4 +342,23 @@ void main() {
         reason: 'extending DiarizeMethod without bumping the C-side enum '
             'will silently drop the new variant');
   });
+
+  test('turn-returning diarize ABI labels segments and reports no energy turns',
+      () {
+    final segs = [DiarizeSegment(t0: 0, t1: 1)];
+    final turns = <DiarizeTurn>[];
+    final ok = diarizeSegments(
+      segs: segs,
+      left: Float32List.fromList(List.filled(16000, 0.5)),
+      right: Float32List(16000),
+      isStereo: true,
+      method: DiarizeMethod.energy,
+      outTurns: turns,
+      lib: lib,
+    );
+    expect(ok, isTrue);
+    expect(segs.single.speaker, 0);
+    expect(turns, isEmpty,
+        reason: 'only FoxNose derives audio-level speaker turns');
+  });
 }

python/README.md

@@ -65,7 +65,9 @@ for seg in s.transcribe_pcm(pcm_f32, sample_rate=16000):
 - `Session` — unified API across all backends compiled into `libcrispasr`
 - `ChatSession` — text → text chat over a GGUF chat model: one-shot and streaming generation, prompt-token counting, and cancellation through an abort predicate
 - `align_words(...)` — word-level CTC alignment
-- `diarize_segments(...)` — speaker diarization (energy / xcorr / vad-turns / pyannote)
+- `diarize_segments(...)` — speaker diarization (energy / xcorr / vad-turns / pyannote / FoxNose)
+- `diarize_segments_with_turns(...)` — label segments and return FoxNose's
+  finer audio-derived speaker turns
 - `SpeakerEmbedder(spec)` — pluggable embedder ("auto"/"titanet", "indextts"/"ecapa", or a `.gguf` path)
 - `PyannoteCache(pcm, model)` — pre-computed pyannote-seg posteriors for cross-slice consistency
 - `agglomerative_cluster(embeddings, ...)` — single-linkage cosine clustering for globally stable speaker IDs

python/crispasr/__init__.py

@@ -8,6 +8,7 @@
     CrispASR,
     DiarizeMethod,
     DiarizeSegment,
+    DiarizeTurn,
     KokoroResolved,
     LidMethod,
     LidResult,
@@ -28,6 +29,7 @@
     cache_ensure_file,
     detect_language_pcm,
     diarize_segments,
+    diarize_segments_with_turns,
     kokoro_resolve_for_lang,
     list_known_models,
     mic_default_device_name,
@@ -47,6 +49,7 @@
     "CrispASR",
     "DiarizeMethod",
     "DiarizeSegment",
+    "DiarizeTurn",
     "KokoroResolved",
     "LidMethod",
     "LidResult",
@@ -67,6 +70,7 @@
     "cache_ensure_file",
     "detect_language_pcm",
     "diarize_segments",
+    "diarize_segments_with_turns",
     "kokoro_resolve_for_lang",
     "list_known_models",
     "mic_default_device_name",