transcribe-cpp 0.3.1__tar.gz → 0.4.0__tar.gz

{transcribe_cpp-0.3.1 → transcribe_cpp-0.4.0}/.gitignore

@@ -59,6 +59,8 @@ __pycache__/
 
 # WER evaluation data + generated working reports.
 /samples/wer/
+# FLEURS language ID corpus (scripts/langid/ingest.py).
+/samples/langid/
 # Diarization eval corpora (AMI audio + fetched RTTMs); regenerable via
 # scripts/diar/ingest_ami.py + fetch_ami_forced_alignment.py. The committed
 # oracle case lives at samples/sortformer-2spk-mix.wav (outside samples/diar/).

{transcribe_cpp-0.3.1 → transcribe_cpp-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: transcribe-cpp
-Version: 0.3.1
+Version: 0.4.0
 Summary: Python bindings for transcribe.cpp
 Project-URL: Homepage, https://github.com/handy-computer/transcribe.cpp
 Project-URL: Repository, https://github.com/handy-computer/transcribe.cpp
@@ -21,9 +21,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9
-Requires-Dist: transcribe-cpp-native==0.3.1.*
+Requires-Dist: transcribe-cpp-native==0.4.0.*
 Provides-Extra: cu12
-Requires-Dist: transcribe-cpp-native-cu12==0.3.1.*; extra == 'cu12'
+Requires-Dist: transcribe-cpp-native-cu12==0.4.0.*; extra == 'cu12'
 Provides-Extra: test
 Requires-Dist: numpy; extra == 'test'
 Requires-Dist: pytest>=7; extra == 'test'
@@ -101,6 +101,72 @@ Long transcriptions can be cancelled from another thread with
 `session.cancel()` — the run raises `Aborted` with the partial transcript on
 `exc.partial_result` (same for `OutputTruncated`).
 
+### Diarization
+
+Models whose `model.roles` include `Role.DIARIZE` (Sortformer) answer "who
+spoke when" through a diarize session. `run()` returns `SpeakerSegment`
+rows (`speaker_id` in `1..model.diarize_info.max_speakers`), grouped by
+speaker. Locking, `Busy`, `cancel()` and `close()` work as on `Session`. A
+model without the role raises `UnsupportedRole`, as `model.session()` and
+`model.capabilities` do on a model without `Role.ASR` (Sortformer serves only
+`Role.DIARIZE`).
+
+```python
+with model.diarize_session() as diarizer:
+    turns = diarizer.run(pcm, family=transcribe_cpp.SortformerDiarizeOptions(
+        preset="very_high_latency"))
+    for turn in turns:
+        print(turn.speaker_id, turn.t0_ms, turn.t1_ms)
+```
+
+### Language ID
+
+Models whose `model.roles` include `Role.LANGID` (VoxLingua107 ECAPA-TDNN)
+identify the spoken language through a langid session. `run()` returns a
+`LangIdResult` with candidates ranked by `p`. Codes are the model's own labels
+(`"iw"`, `"jw"`; `model.langid_label_index("he")` resolves aliases), so match
+`result.code` against the ASR model's `capabilities.languages` yourself.
+`allowed=None` scores every label; `allowed_mass` is the unrestricted
+probability the allowed set captured. An empty `allowed` list raises
+`InvalidArgument`; clips under `model.langid_info.min_audio_ms` raise
+`InputTooShort`, and longer ones than `max_audio_ms` are scored on their first
+`max_audio_ms`. Every allowed label comes back as a candidate. Locking,
+`Busy`, `cancel()` and `close()` work as on `Session`.
+
+```python
+with model.langid_session() as lid:
+    result = lid.run(pcm, allowed=["en", "de", "fr"])
+    print(result.code, result.candidates[0].p, result.allowed_mass)
+```
+
+### Voice activity detection
+
+Models whose `model.roles` include `Role.VAD` (Silero VAD, GGUF or the
+whisper.cpp `.bin`) score speech probability per frame of
+`model.vad_info.frame_samples` samples through a VAD session. `run()` scores one
+clip and returns a `VadResult` with `probs` and speech `segments`
+(`start_sample`/`end_sample`; options default to Silero's
+`get_speech_timestamps`). `stream_feed()` streams audio of any chunk size and
+returns the probabilities of the frames each call completed (`first_frame` is
+the position of the first); `stream_flush()` scores the zero-padded remainder
+and ends the stream, `stream_reset()` drops it. The VAD stream does not take
+the model's ASR stream lease. Locking, `Busy`, `cancel()` and `close()` work as
+on `Session`.
+
+```python
+with model.vad_session() as vad:
+    for seg in vad.run(pcm, min_silence_ms=300).segments:
+        print(seg.start_sample, seg.end_sample)
+
+    frame = model.vad_info.frame_samples
+    probs = []
+    for chunk in chunks:
+        r = vad.stream_feed(chunk)
+        print(f"{len(r.probs)} frames from sample {r.first_frame * frame}")
+        probs.extend(r.probs)
+    probs.extend(vad.stream_flush().probs)
+```
+
 ## Backends
 
 `Model(backend=...)` applies a backend policy (`"auto"` uses the best
@@ -151,9 +217,10 @@ TRANSCRIBE_LIBRARY=../../build-shared/src/libtranscribe.dylib \
 
 ## Notes
 
-- One run/stream at a time per `Model` in 0.x: sessions share the model's
-  compute backend, so serialize runs across sessions (or load one model per
-  worker). See the `Model` docstring.
+- One compute call at a time per `Model`: the binding serializes calls across
+  all sessions of a model with a model-wide lock (load one model per worker
+  for parallelism). While a stream is active, other runs and stream begins on
+  that model raise `transcribe_cpp.Busy`. See the `Model` docstring.
 - Import package: `transcribe_cpp`
 - Distribution: `transcribe-cpp`
 - License: MIT

{transcribe_cpp-0.3.1 → transcribe_cpp-0.4.0}/README.md

@@ -70,6 +70,72 @@ Long transcriptions can be cancelled from another thread with
 `session.cancel()` — the run raises `Aborted` with the partial transcript on
 `exc.partial_result` (same for `OutputTruncated`).
 
+### Diarization
+
+Models whose `model.roles` include `Role.DIARIZE` (Sortformer) answer "who
+spoke when" through a diarize session. `run()` returns `SpeakerSegment`
+rows (`speaker_id` in `1..model.diarize_info.max_speakers`), grouped by
+speaker. Locking, `Busy`, `cancel()` and `close()` work as on `Session`. A
+model without the role raises `UnsupportedRole`, as `model.session()` and
+`model.capabilities` do on a model without `Role.ASR` (Sortformer serves only
+`Role.DIARIZE`).
+
+```python
+with model.diarize_session() as diarizer:
+    turns = diarizer.run(pcm, family=transcribe_cpp.SortformerDiarizeOptions(
+        preset="very_high_latency"))
+    for turn in turns:
+        print(turn.speaker_id, turn.t0_ms, turn.t1_ms)
+```
+
+### Language ID
+
+Models whose `model.roles` include `Role.LANGID` (VoxLingua107 ECAPA-TDNN)
+identify the spoken language through a langid session. `run()` returns a
+`LangIdResult` with candidates ranked by `p`. Codes are the model's own labels
+(`"iw"`, `"jw"`; `model.langid_label_index("he")` resolves aliases), so match
+`result.code` against the ASR model's `capabilities.languages` yourself.
+`allowed=None` scores every label; `allowed_mass` is the unrestricted
+probability the allowed set captured. An empty `allowed` list raises
+`InvalidArgument`; clips under `model.langid_info.min_audio_ms` raise
+`InputTooShort`, and longer ones than `max_audio_ms` are scored on their first
+`max_audio_ms`. Every allowed label comes back as a candidate. Locking,
+`Busy`, `cancel()` and `close()` work as on `Session`.
+
+```python
+with model.langid_session() as lid:
+    result = lid.run(pcm, allowed=["en", "de", "fr"])
+    print(result.code, result.candidates[0].p, result.allowed_mass)
+```
+
+### Voice activity detection
+
+Models whose `model.roles` include `Role.VAD` (Silero VAD, GGUF or the
+whisper.cpp `.bin`) score speech probability per frame of
+`model.vad_info.frame_samples` samples through a VAD session. `run()` scores one
+clip and returns a `VadResult` with `probs` and speech `segments`
+(`start_sample`/`end_sample`; options default to Silero's
+`get_speech_timestamps`). `stream_feed()` streams audio of any chunk size and
+returns the probabilities of the frames each call completed (`first_frame` is
+the position of the first); `stream_flush()` scores the zero-padded remainder
+and ends the stream, `stream_reset()` drops it. The VAD stream does not take
+the model's ASR stream lease. Locking, `Busy`, `cancel()` and `close()` work as
+on `Session`.
+
+```python
+with model.vad_session() as vad:
+    for seg in vad.run(pcm, min_silence_ms=300).segments:
+        print(seg.start_sample, seg.end_sample)
+
+    frame = model.vad_info.frame_samples
+    probs = []
+    for chunk in chunks:
+        r = vad.stream_feed(chunk)
+        print(f"{len(r.probs)} frames from sample {r.first_frame * frame}")
+        probs.extend(r.probs)
+    probs.extend(vad.stream_flush().probs)
+```
+
 ## Backends
 
 `Model(backend=...)` applies a backend policy (`"auto"` uses the best
@@ -120,9 +186,10 @@ TRANSCRIBE_LIBRARY=../../build-shared/src/libtranscribe.dylib \
 
 ## Notes
 
-- One run/stream at a time per `Model` in 0.x: sessions share the model's
-  compute backend, so serialize runs across sessions (or load one model per
-  worker). See the `Model` docstring.
+- One compute call at a time per `Model`: the binding serializes calls across
+  all sessions of a model with a model-wide lock (load one model per worker
+  for parallelism). While a stream is active, other runs and stream begins on
+  that model raise `transcribe_cpp.Busy`. See the `Model` docstring.
 - Import package: `transcribe_cpp`
 - Distribution: `transcribe-cpp`
 - License: MIT

{transcribe_cpp-0.3.1 → transcribe_cpp-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcribe-cpp"
-version = "0.3.1"
+version = "0.4.0"
 description = "Python bindings for transcribe.cpp"
 readme = "README.md"
 # 3.8 is EOL (2024-10); 3.9 is the floor. The binding is ctypes-only, so there
@@ -34,13 +34,13 @@ classifiers = [
 # packaging fix still resolves); the import-time version/header-hash check in
 # _library.py is the runtime backstop. check_version_sync.py gates this pin
 # against include/transcribe.h.
-dependencies = ["transcribe-cpp-native==0.3.1.*"]
+dependencies = ["transcribe-cpp-native==0.4.0.*"]
 
 [project.optional-dependencies]
 # Opt-in accelerator providers — ADDITIVE: they install alongside the default
 # provider and the best one wins at runtime. Same base-version pin contract
 # as the hard dependency (gated by check_version_sync.py).
-cu12 = ["transcribe-cpp-native-cu12==0.3.1.*"]
+cu12 = ["transcribe-cpp-native-cu12==0.4.0.*"]
 # Test-only deps. Run with: uv run --extra test pytest (from bindings/python).
 # numpy is here so the numpy PCM-input tests run in every lane instead of
 # silently skipping wherever numpy happens to be absent.