ovkit 0.1.2__tar.gz → 0.2.0__tar.gz

{ovkit-0.1.2 → ovkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ovkit
-Version: 0.1.2
+Version: 0.2.0
 Summary: A simple Python inference API for OpenVINO: one import, one Model class, clean Results — with AUTO/NPU, async, and INT8.
 Project-URL: Homepage, https://github.com/leeyunjai82/ovkit
 Project-URL: Documentation, https://leeyunjai82.github.io/ovkit/
@@ -69,14 +69,36 @@ ready models — with `AUTO`/`NPU`/`GPU` devices, async throughput, and INT8.
 ```python
 from ovkit import Model
 
-r = Model("detect")("image.jpg")[0]   # download -> convert -> cache -> run
-r.save("out.jpg")                     # boxes drawn; r.boxes.xyxy / .conf / .cls
+r = Model("detect", "image.jpg")      # download -> convert -> cache -> run
+print(r)                              # 2x person, car
+r.save("out.jpg")                     # the boxes drawn on the photo
+```
+
+One call fits every input — and Korean names work too:
+
+```python
+r = Model("얼굴분석", "group.jpg")      # == Model("face_analyze", ...)
+for row in r.found:                    # [{'name': '사람', 'name_en': 'person',
+    print(row["name"], row["pos"])     #   'score': 0.93, 'box': [...], 'pos': '왼쪽 위'}]
+
+for r in Model("track", 0):            # webcam / video / "mic" -> a stream
+    print(r, r.elapsed_ms, r.device)   # 2x person (#1, #4) 14.2 GPU
+```
+
+The same call also runs whole **capabilities** — several models chained into one
+answer, so you never have to crop, chain and stitch by hand:
+
+```python
+r = Model("face_analyze", "group.jpg")
+print(r)                # 2 faces: age 31 · male 98% · happy 92%, age 27 · female 95% · neutral 88%
 ```
 
 Or without writing Python at all:
 
 ```bash
+ovkit gui                             # a window: pick a capability, point it at your webcam
 ovkit run detect image.jpg            # prints results, saves image_out.jpg
+ovkit capabilities                    # what Model(name) can answer
 ```
 
 ## Install
@@ -94,9 +116,45 @@ python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\act
 pip install -e ".[dev]"
 ```
 
+## Capabilities
+
+A capability name gives you the answer, not the plumbing. Each one chains a
+detector with the models that describe what it found — same `Model(...)` call,
+same `Results`, and it takes the same sources (path, ndarray, folder, video,
+camera index).
+
+| `Model(...)` | Answers | Chains |
+| ------------ | ------- | ------ |
+| `scene` | `2 people (1 happy) · a laptop and a cup · floor 47%` | detection + segmentation + faces |
+| `face_analyze` | `2 faces: age 31 · male 98% · happy 92%, ...` | face detection + age/gender + emotion (+ head pose, landmarks) |
+| `person_analyze` | `3 people: male 0.98 · long pants 0.95 · bag 0.71, ...` | person detection + attributes |
+| `vehicle_analyze` | `2 vehicles: type: car (0.98) · color: black (0.83), ...` | vehicle detection + type/colour |
+| `read_text` | `'STOP AHEAD'` — every word, in reading order | text detection + text recognition |
+| `read_plate` | `2 vehicles: black car — 12GA3456, ...` | plate detection + text recognition + vehicle attributes |
+| `track` | `2x person (#1, #4)` — ids stable across frames | detection + IoU association |
+| `drowsiness` | `EYES CLOSED 1.4s — drowsy` | face + landmarks + eye state + head pose, **over time** |
+| `gesture` | `thumb up 0.94` | sign-language model over a rolling 8-frame clip |
+| `gaze` | `1 face: looking right and slightly up` | face detection + landmarks + head pose + gaze |
+| `attention` | `1 person looking at: laptop` | gaze + object detection (ray-cast into the boxes) |
+| `anonymize` | the picture with every face pixelated | face (and plate) detection + redaction |
+| `face_match` | `('yunjai', 0.81)` — who this is | embedding + cosine matching against your gallery |
+
+```python
+from ovkit import Model, list_pipelines
+
+list_pipelines()                                    # every capability, described
+Model("read_text")("sign.jpg")[0].text              # 'STOP AHEAD'
+Model("track")(0)                                   # webcam, ids kept across frames
+Model("face_analyze", attributes=("age_gender",))   # configure what runs
+```
+
+Aliases: `ocr`, `anpr`, `blur`, `driver`, `describe`, `faces`, `people`, `vehicle`, `tracking`, `reid`.
+`ovkit capabilities` prints the list; **`ovkit gui` opens a window** where you can
+click through them against your webcam or a picture.
+
 ## Supported tasks
 
-Every task below runs end-to-end through the same 3 lines — swap the alias:
+Every single-model task below runs end-to-end through the same 3 lines — swap the alias:
 
 | Task | Alias | Output | Example |
 | ---- | ----- | ------ | ------- |
@@ -106,6 +164,7 @@ Every task below runs end-to-end through the same 3 lines — swap the alias:
 | Pose / landmarks | `pose`, `face_landmarks` | `r.keypoints` | [pose.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/pose.py) |
 | Face analysis | `age_gender`, `emotion`, `head_pose`, `face_reid` | `r.text` (e.g. `"age 31 · male 98%"`) | [face_analysis.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/face_analysis.py) |
 | OCR | `text_recognition` | `r.text` | [ocr.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/ocr.py) |
+| Tracking / matching | `track`, `face_match` | `r.track_ids` · `(label, score)` | [track.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/track.py) / [face_match.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/face_match.py) |
 | Super-resolution | `super_resolution` | upscaled image via `r.plot()` | [super_resolution.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/super_resolution.py) |
 | LLM / STT (GenAI) | `llm`, `stt` | generated text | [llm.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/llm.py) / [stt.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/stt.py) |
 | NLP / audio / time series | `qa`, `translation`, `noise_suppression`, `time_series` | tensors via `model.infer()` | [denoise_audio.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/denoise_audio.py) |
@@ -174,7 +233,10 @@ control for any model: `model.infer({name: tensor})` with `model.inputs`.
 | `r.boxes` | `xyxy`, `xywh`, `conf`, `cls` |
 | `r.masks` / `r.keypoints` / `r.probs` | masks · `[x,y,conf]` · `top1`/`top5` |
 | `r.text` | decoded text (OCR, face attributes) |
+| `r.labels` / `r.track_ids` | per-box label a pipeline wrote · per-box track id |
 | `r.tensors` | raw `{name: ndarray}` |
+| `r.summary()` | the whole result as one readable line |
+| `r.crop(i)` / `r.to_dict()` / `r.to_json()` | cut a box out · plain Python · JSON |
 | `r.plot()` / `r.save(path)` | annotated image (or the model's output image) |
 
 </details>

{ovkit-0.1.2 → ovkit-0.2.0}/README.md

@@ -24,14 +24,36 @@ ready models — with `AUTO`/`NPU`/`GPU` devices, async throughput, and INT8.
 ```python
 from ovkit import Model
 
-r = Model("detect")("image.jpg")[0]   # download -> convert -> cache -> run
-r.save("out.jpg")                     # boxes drawn; r.boxes.xyxy / .conf / .cls
+r = Model("detect", "image.jpg")      # download -> convert -> cache -> run
+print(r)                              # 2x person, car
+r.save("out.jpg")                     # the boxes drawn on the photo
+```
+
+One call fits every input — and Korean names work too:
+
+```python
+r = Model("얼굴분석", "group.jpg")      # == Model("face_analyze", ...)
+for row in r.found:                    # [{'name': '사람', 'name_en': 'person',
+    print(row["name"], row["pos"])     #   'score': 0.93, 'box': [...], 'pos': '왼쪽 위'}]
+
+for r in Model("track", 0):            # webcam / video / "mic" -> a stream
+    print(r, r.elapsed_ms, r.device)   # 2x person (#1, #4) 14.2 GPU
+```
+
+The same call also runs whole **capabilities** — several models chained into one
+answer, so you never have to crop, chain and stitch by hand:
+
+```python
+r = Model("face_analyze", "group.jpg")
+print(r)                # 2 faces: age 31 · male 98% · happy 92%, age 27 · female 95% · neutral 88%
 ```
 
 Or without writing Python at all:
 
 ```bash
+ovkit gui                             # a window: pick a capability, point it at your webcam
 ovkit run detect image.jpg            # prints results, saves image_out.jpg
+ovkit capabilities                    # what Model(name) can answer
 ```
 
 ## Install
@@ -49,9 +71,45 @@ python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\act
 pip install -e ".[dev]"
 ```
 
+## Capabilities
+
+A capability name gives you the answer, not the plumbing. Each one chains a
+detector with the models that describe what it found — same `Model(...)` call,
+same `Results`, and it takes the same sources (path, ndarray, folder, video,
+camera index).
+
+| `Model(...)` | Answers | Chains |
+| ------------ | ------- | ------ |
+| `scene` | `2 people (1 happy) · a laptop and a cup · floor 47%` | detection + segmentation + faces |
+| `face_analyze` | `2 faces: age 31 · male 98% · happy 92%, ...` | face detection + age/gender + emotion (+ head pose, landmarks) |
+| `person_analyze` | `3 people: male 0.98 · long pants 0.95 · bag 0.71, ...` | person detection + attributes |
+| `vehicle_analyze` | `2 vehicles: type: car (0.98) · color: black (0.83), ...` | vehicle detection + type/colour |
+| `read_text` | `'STOP AHEAD'` — every word, in reading order | text detection + text recognition |
+| `read_plate` | `2 vehicles: black car — 12GA3456, ...` | plate detection + text recognition + vehicle attributes |
+| `track` | `2x person (#1, #4)` — ids stable across frames | detection + IoU association |
+| `drowsiness` | `EYES CLOSED 1.4s — drowsy` | face + landmarks + eye state + head pose, **over time** |
+| `gesture` | `thumb up 0.94` | sign-language model over a rolling 8-frame clip |
+| `gaze` | `1 face: looking right and slightly up` | face detection + landmarks + head pose + gaze |
+| `attention` | `1 person looking at: laptop` | gaze + object detection (ray-cast into the boxes) |
+| `anonymize` | the picture with every face pixelated | face (and plate) detection + redaction |
+| `face_match` | `('yunjai', 0.81)` — who this is | embedding + cosine matching against your gallery |
+
+```python
+from ovkit import Model, list_pipelines
+
+list_pipelines()                                    # every capability, described
+Model("read_text")("sign.jpg")[0].text              # 'STOP AHEAD'
+Model("track")(0)                                   # webcam, ids kept across frames
+Model("face_analyze", attributes=("age_gender",))   # configure what runs
+```
+
+Aliases: `ocr`, `anpr`, `blur`, `driver`, `describe`, `faces`, `people`, `vehicle`, `tracking`, `reid`.
+`ovkit capabilities` prints the list; **`ovkit gui` opens a window** where you can
+click through them against your webcam or a picture.
+
 ## Supported tasks
 
-Every task below runs end-to-end through the same 3 lines — swap the alias:
+Every single-model task below runs end-to-end through the same 3 lines — swap the alias:
 
 | Task | Alias | Output | Example |
 | ---- | ----- | ------ | ------- |
@@ -61,6 +119,7 @@ Every task below runs end-to-end through the same 3 lines — swap the alias:
 | Pose / landmarks | `pose`, `face_landmarks` | `r.keypoints` | [pose.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/pose.py) |
 | Face analysis | `age_gender`, `emotion`, `head_pose`, `face_reid` | `r.text` (e.g. `"age 31 · male 98%"`) | [face_analysis.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/face_analysis.py) |
 | OCR | `text_recognition` | `r.text` | [ocr.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/ocr.py) |
+| Tracking / matching | `track`, `face_match` | `r.track_ids` · `(label, score)` | [track.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/track.py) / [face_match.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/face_match.py) |
 | Super-resolution | `super_resolution` | upscaled image via `r.plot()` | [super_resolution.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/super_resolution.py) |
 | LLM / STT (GenAI) | `llm`, `stt` | generated text | [llm.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/llm.py) / [stt.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/stt.py) |
 | NLP / audio / time series | `qa`, `translation`, `noise_suppression`, `time_series` | tensors via `model.infer()` | [denoise_audio.py](https://github.com/leeyunjai82/ovkit/blob/main/examples/denoise_audio.py) |
@@ -129,7 +188,10 @@ control for any model: `model.infer({name: tensor})` with `model.inputs`.
 | `r.boxes` | `xyxy`, `xywh`, `conf`, `cls` |
 | `r.masks` / `r.keypoints` / `r.probs` | masks · `[x,y,conf]` · `top1`/`top5` |
 | `r.text` | decoded text (OCR, face attributes) |
+| `r.labels` / `r.track_ids` | per-box label a pipeline wrote · per-box track id |
 | `r.tensors` | raw `{name: ndarray}` |
+| `r.summary()` | the whole result as one readable line |
+| `r.crop(i)` / `r.to_dict()` / `r.to_json()` | cut a box out · plain Python · JSON |
 | `r.plot()` / `r.save(path)` | annotated image (or the model's output image) |
 
 </details>

{ovkit-0.1.2 → ovkit-0.2.0}/examples/README.md

@@ -16,6 +16,7 @@ pip install -r examples/requirements.txt # fastapi / uvicorn (web demos only)
 | [`classify.py`](classify.py) | `classify` | top-5 classes |
 | [`ocr.py`](ocr.py) | `text_recognition` | decoded text |
 | [`super_resolution.py`](super_resolution.py) | `super_resolution` | upscaled image |
+| [`background_matting.py`](background_matting.py) | `background_matting_mobilenetv2` | cut the subject out (needs frame + empty-scene photo) |
 
 ```bash
 python examples/detect.py photo.jpg      # each is ~15 lines — read the source

{ovkit-0.1.2 → ovkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ovkit"
-version = "0.1.2"
+version = "0.2.0"
 description = "A simple Python inference API for OpenVINO: one import, one Model class, clean Results — with AUTO/NPU, async, and INT8."
 readme = "README.md"
 requires-python = ">=3.10"

{ovkit-0.1.2 → ovkit-0.2.0}/src/ovkit/__init__.py

@@ -3,14 +3,23 @@
 One import, one :class:`Model` class, a callable object, and clean
 :class:`Results` — plus OpenVINO's strengths (AUTO/NPU devices, async, INT8).
 
-Example
--------
+One model
+---------
 >>> from ovkit import Model
 >>> model = Model("rtdetr_r50")          # name -> auto download/convert/cache
 >>> results = model("img.jpg", conf=0.25)
 >>> for r in results:
-...     print(r.boxes.xyxy, r.boxes.conf, r.boxes.cls)
+...     print(r.summary())               # '2x person, car'
 ...     r.save("out.jpg")
+
+Several models, one answer
+--------------------------
+>>> from ovkit import Model
+>>> for r in Model("face_analyze")("group.jpg"):
+...     print(r.summary())               # '2 faces: age 31 · male 98% · happy 92%, ...'
+
+A capability name composes the models the answer needs — detection plus
+whatever describes what was found. :func:`list_pipelines` shows them all.
 """
 
 from __future__ import annotations
@@ -29,11 +38,14 @@ from .core.errors import (
 from .core.model import Model
 from .core.registry import list_models
 from .core.results import Boxes, Keypoints, Masks, Probs, Results
+from .pipelines import Pipeline, list_pipelines
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "Model",
+    "Pipeline",
+    "list_pipelines",
     "Results",
     "Boxes",
     "Masks",

{ovkit-0.1.2 → ovkit-0.2.0}/src/ovkit/__main__.py

@@ -1,4 +1,4 @@
-"""``ovkit`` command-line interface: ``run``, ``list``, ``info``, ``download``, ``devices``."""
+"""``ovkit`` command-line interface: ``gui``, ``run``, ``list``, ``info``, ``download``, ``devices``."""
 
 from __future__ import annotations
 
@@ -41,6 +41,19 @@ def _cmd_list(_: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_capabilities(_: argparse.Namespace) -> int:
+    """What ``Model(name)`` can answer beyond a single network."""
+    from .pipelines import ALIASES, list_pipelines
+
+    print("capabilities — Model(name) chains the models the answer needs:\n")
+    for name, description in list_pipelines().items():
+        print(f"  {name:16s} {description}")
+    print("\naliases:")
+    for alias, target in sorted(ALIASES.items()):
+        print(f"  {alias:16s} -> {target}")
+    return 0
+
+
 def _cmd_info(args: argparse.Namespace) -> int:
     entry = resolve(args.name)
     if entry is None:
@@ -96,25 +109,12 @@ def _cmd_run(args: argparse.Namespace) -> int:
         return 0
 
     for r in results:
-        parts = [f"task={r.task}"]
-        if r.text:
-            parts.append(f'text="{r.text}"')
+        print(r.summary())
         if r.boxes is not None:
-            parts.append(f"{len(r.boxes)} boxes")
             for x1, y1, x2, y2, c, cl in r.boxes.data[:20]:
                 print(
                     f"  {r.name_for(int(cl)):16s} {c:.2f} [{int(x1)},{int(y1)},{int(x2)},{int(y2)}]"
                 )
-        if r.probs is not None:
-            top = ", ".join(
-                f"{r.name_for(int(i))} {r.probs.data[int(i)]:.2f}" for i in r.probs.top5
-            )
-            parts.append(f"top-5: {top}")
-        if r.masks is not None:
-            parts.append(f"masks {tuple(r.masks.data.shape)}")
-        if r.keypoints is not None:
-            parts.append(f"keypoints {tuple(r.keypoints.data.shape)}")
-        print(" | ".join(parts))
 
     save = args.save
     if save is None and results and Path(str(args.source)).is_file():
@@ -125,15 +125,30 @@ def _cmd_run(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_gui(args: argparse.Namespace) -> int:
+    """Open the desktop window: ``ovkit gui``."""
+    from .gui import main as gui_main
+
+    return gui_main(device=args.device, camera=args.camera)
+
+
 def main(argv: list[str] | None = None) -> int:
     """CLI entry point. Returns a process exit code."""
     parser = argparse.ArgumentParser(prog="ovkit", description="ovkit model utilities")
     parser.add_argument("--version", action="version", version=f"ovkit {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
+    p_gui = sub.add_parser("gui", help="open the desktop window (easiest way to try ovkit)")
+    p_gui.add_argument("--device", default="AUTO", help="AUTO | CPU | GPU | NPU")
+    p_gui.add_argument("--camera", type=int, default=0, help="camera index for the webcam button")
+    p_gui.set_defaults(func=_cmd_gui)
+
     p_list = sub.add_parser("list", help="list registered models")
     p_list.set_defaults(func=_cmd_list)
 
+    p_caps = sub.add_parser("capabilities", help="list composed capabilities (Model(name))")
+    p_caps.set_defaults(func=_cmd_capabilities)
+
     p_info = sub.add_parser("info", help="show details for a model")
     p_info.add_argument("name")
     p_info.set_defaults(func=_cmd_info)

ovkit-0.2.0/src/ovkit/audio/__init__.py

@@ -0,0 +1,13 @@
+"""Audio I/O helpers: read a file into the array a model actually wants.
+
+Models want float32 mono at a fixed sample rate; files are int16 stereo at
+whatever rate the recorder used. These helpers close that gap so callers never
+have to touch :mod:`wave` or write their own resampler.
+"""
+
+from __future__ import annotations
+
+from .ops import read_audio, read_wav, resample, to_mono, write_wav
+from .plot import waveform
+
+__all__ = ["read_audio", "read_wav", "resample", "to_mono", "waveform", "write_wav"]

ovkit-0.2.0/src/ovkit/audio/ops.py

@@ -0,0 +1,108 @@
+"""Read, convert and write audio as plain float32 numpy arrays."""
+
+from __future__ import annotations
+
+import io
+import wave
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ..core.errors import OVKitError
+
+#: Sample formats ``wave`` reports, mapped to (numpy dtype, full-scale value).
+_PCM = {1: (np.int8, 128.0), 2: (np.int16, 32768.0), 4: (np.int32, 2147483648.0)}
+
+
+def to_mono(audio: np.ndarray) -> np.ndarray:
+    """Average an ``(N, channels)`` array down to a 1-D mono signal."""
+    arr = np.asarray(audio, dtype=np.float32)
+    return arr.mean(axis=1) if arr.ndim == 2 and arr.shape[1] > 1 else arr.reshape(-1)
+
+
+def resample(audio: np.ndarray, sr: int, target_sr: int) -> np.ndarray:
+    """Resample a 1-D signal to ``target_sr`` by linear interpolation.
+
+    Linear interpolation is not a studio-grade resampler, but it is exact when
+    the rates match, needs no extra dependency, and is well within the tolerance
+    of the classifiers and ASR models ovkit serves.
+    """
+    arr = np.asarray(audio, dtype=np.float32).reshape(-1)
+    if sr == target_sr or arr.size == 0:
+        return arr
+    n_out = int(round(arr.size * target_sr / float(sr)))
+    if n_out <= 1:
+        return arr[:1].copy()
+    src = np.linspace(0.0, arr.size - 1, num=n_out, dtype=np.float32)
+    return np.interp(src, np.arange(arr.size, dtype=np.float32), arr).astype(np.float32)
+
+
+def read_audio(path: str | Path, target_sr: int | None = None) -> tuple[np.ndarray, int]:
+    """Read an audio file as ``(float32 mono in [-1, 1], sample_rate)``.
+
+    ``.wav`` is read with the standard library. Other formats are read through
+    ``soundfile`` when it is installed; otherwise the error says what to do
+    rather than failing deep inside a decoder. ``target_sr`` resamples the
+    result (and is what most models need, e.g. 16 kHz for speech).
+    """
+    src = Path(path)
+    if src.suffix.lower() == ".wav":
+        audio, sr = read_wav(src)
+    else:
+        audio, sr = _read_soundfile(src)
+    if target_sr:
+        audio = resample(audio, sr, target_sr)
+        sr = target_sr
+    return audio, sr
+
+
+def read_wav(source: Any, target_sr: int | None = None) -> tuple[np.ndarray, int]:
+    """Read WAV from a path or an open/byte stream — any depth, any channels.
+
+    Uploads arrive as bytes and recordings arrive as stereo; both go through
+    here so callers never re-implement PCM decoding.
+    """
+    if isinstance(source, bytes):
+        source = io.BytesIO(source)
+    with wave.open(source if hasattr(source, "read") else str(source), "rb") as wf:
+        sr, width, channels = wf.getframerate(), wf.getsampwidth(), wf.getnchannels()
+        raw = wf.readframes(wf.getnframes())
+    if width not in _PCM:
+        raise OVKitError(
+            f"{width * 8}-bit WAV is not supported (8/16/32-bit PCM is). "
+            f"Re-encode it, e.g. ffmpeg -i in.wav -acodec pcm_s16le out.wav"
+        )
+    dtype, full_scale = _PCM[width]
+    samples = np.frombuffer(raw, dtype=dtype).astype(np.float32) / full_scale
+    if channels > 1:
+        samples = samples[: samples.size // channels * channels].reshape(-1, channels)
+    audio = to_mono(samples)
+    if target_sr:
+        return resample(audio, sr, target_sr), target_sr
+    return audio, sr
+
+
+def _read_soundfile(path: Path) -> tuple[np.ndarray, int]:
+    try:
+        import soundfile as sf
+    except ImportError as exc:
+        raise OVKitError(
+            f"Reading '{path.suffix}' needs an extra decoder. Either convert to WAV "
+            f"(ffmpeg -i {path.name} -ar 16000 -ac 1 out.wav) or install one: "
+            f"pip install soundfile"
+        ) from exc
+    audio, sr = sf.read(str(path), dtype="float32", always_2d=True)
+    return to_mono(audio), int(sr)
+
+
+def write_wav(path: str | Path, audio: np.ndarray, sr: int) -> Path:
+    """Write a float32 mono signal to a 16-bit PCM ``.wav`` and return the path."""
+    arr = np.clip(np.asarray(audio, dtype=np.float32).reshape(-1), -1.0, 1.0)
+    pcm = (arr * 32767.0).astype(np.int16)
+    with wave.open(str(path), "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(int(sr))
+        wf.writeframes(pcm.tobytes())
+    return Path(path)

ovkit-0.2.0/src/ovkit/audio/plot.py

@@ -0,0 +1,47 @@
+"""Draw a waveform, so an audio result has something to show."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def waveform(
+    audio: np.ndarray,
+    sr: int = 16_000,
+    width: int = 720,
+    height: int = 200,
+    color: tuple[int, int, int] = (200, 190, 120),
+) -> np.ndarray:
+    """Render a mono signal as a BGR image.
+
+    Audio results carry this as their image so ``plot()``, ``save()`` and the
+    web demo work the same way they do for a picture.
+    """
+    import cv2
+
+    img = np.full((height, width, 3), 24, np.uint8)
+    samples = np.asarray(audio, np.float32).reshape(-1)
+    mid = height // 2
+    cv2.line(img, (0, mid), (width, mid), (60, 60, 60), 1)
+    if samples.size:
+        # One vertical bar per column: the min/max of the samples it covers.
+        edges = np.linspace(0, samples.size, width + 1).astype(int)
+        peak = max(float(np.abs(samples).max()), 1e-6)
+        for x in range(width):
+            chunk = samples[edges[x] : max(edges[x + 1], edges[x] + 1)]
+            if not chunk.size:
+                continue
+            lo, hi = float(chunk.min()) / peak, float(chunk.max()) / peak
+            cv2.line(img, (x, mid - int(hi * mid * 0.9)), (x, mid - int(lo * mid * 0.9)), color, 1)
+    seconds = samples.size / float(sr or 1)
+    cv2.putText(
+        img,
+        f"{seconds:.1f}s @ {sr} Hz",
+        (8, height - 8),
+        cv2.FONT_HERSHEY_SIMPLEX,
+        0.45,
+        (140, 140, 140),
+        1,
+        cv2.LINE_AA,
+    )
+    return img

{ovkit-0.1.2 → ovkit-0.2.0}/src/ovkit/core/backend.py

@@ -32,6 +32,39 @@ def available_devices() -> list[str]:
     return list(core().available_devices)
 
 
+def _friendlier_compile_error(exc: Exception, model: str | Path | Any) -> Exception:
+    """Turn OpenVINO's nested compile errors into something actionable.
+
+    The most common one by far is IR whose ``.bin`` never arrived (a mirror
+    upload that dropped the weights, or an interrupted download). OpenVINO
+    reports it as "Empty weights data in bin file", buried under two layers of
+    "Exception from ...", which tells a user nothing about what to do.
+    """
+    from .errors import OVKitError
+
+    text = str(exc)
+    if "Empty weights data" not in text and "bin file" not in text:
+        return exc
+    if not isinstance(model, (str, Path)):
+        return exc
+    xml = Path(str(model))
+    if xml.suffix != ".xml":
+        return exc
+    bin_path = xml.with_suffix(".bin")
+    if not bin_path.exists():
+        state = "is missing"
+    elif bin_path.stat().st_size < 1024:
+        state = f"is only {bin_path.stat().st_size} bytes"
+    else:
+        return exc  # weights look fine — a different problem, keep the original
+    return OVKitError(
+        f"The weights file for this model {state}: {bin_path}\n"
+        f"An OpenVINO IR needs both model.xml and model.bin. Delete the cached "
+        f"copy and download it again; if it keeps happening, the mirrored model "
+        f"itself is incomplete and needs re-uploading."
+    )
+
+
 class Backend:
     """A compiled model bound to a device, with sync and async inference.
 
@@ -47,7 +80,10 @@ class Backend:
         self.device = device
         c = core()
         src = str(model) if isinstance(model, (str, Path)) else model
-        self.compiled = c.compile_model(src, device)
+        try:
+            self.compiled = c.compile_model(src, device)
+        except Exception as exc:
+            raise _friendlier_compile_error(exc, model) from exc
         self.inputs = self.compiled.inputs
         self.outputs = self.compiled.outputs
 
@@ -97,6 +133,15 @@ class Backend:
             return np.repeat(arr, 3, axis=1)
         return arr
 
+    @property
+    def actual_device(self) -> str:
+        """The device inference actually runs on (AUTO resolves to a real one)."""
+        try:
+            devices = self.compiled.get_property("EXECUTION_DEVICES")
+            return ",".join(devices) if devices else self.device
+        except Exception:
+            return self.device
+
     def output_signatures(self) -> list[tuple[str, tuple[int, ...]]]:
         """Return ``(name, shape)`` for each output (``-1`` for dynamic dims)."""
         sigs: list[tuple[str, tuple[int, ...]]] = []