Skip to content

Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.

Whistle (#163)

Jakub Mrozbb665fc1e16a
diff --git a/llms.txt b/llms.txt
index 49c12d3..fea901d 100644
--- a/llms.txt
+++ b/llms.txt
@@ -234,6 +234,9 @@ Adapt by swapping the Literal values for your own and keeping the shapes: closed
- `needle run --checkpoint <base.safetensors> --query "..." --tools tools.json` - JAX reference inference from a checkpoint (dev path; normal inference is the Python `Needle` API above).
- `needle generate-data` / `needle finetune` / `needle build [checkpoint] [--lora adapter] [--layers N] [--platform <folder>] [--out <path>]` - the fine-tuning pipeline; fine-tuning runs at the full 20 layers, `build` merges the adapter, slices the `--layers` rung (default 20), exports at 4 bits, and fetches the published `needle3.cact` on every run (without an adapter at full depth it ships that published 2-bit archive as is). `--platform` also downloads that platform's engine and header and makes `--out` a folder holding them plus `needle3.cact`.
- `needle playground` - the browser UI locally (hosted at https://cactuscompute.com/needle).
+- `needle whistle playground [clip.wav] [--language en] [--keywords "Siobhan, Krzysztof"] [--word-timestamps] [--weights whistle.cact]` - Whistle speech to text in the terminal: press Enter to speak, Enter again to stop, or pass a WAV file; `/language`, `/keywords`, `/timestamps` and `/file` change the settings between recordings. Needs the `[whistle]` extra. The Whistle engine and `whistle.cact` are fetched from `Cactus-Compute/whistle` on first use; `NEEDLE_WHISTLE_LIB_PATH` and `NEEDLE_WHISTLE_WEIGHTS` point at local ones.
+- `needle whistle compare [clip.wav] [--weights whistle.cact]` - the same English speech through Whistle, Whisper tiny and base (openai-whisper) and Moonshine tiny v2 (moonshine-voice), one line per model with its weight size, time to first token, decode tokens per second, total time and transcript; `/file` runs a WAV between recordings. Whistle's timing comes from the engine's own JSON. Needs the `[whistle,whistle-compare]` extras.
+- `needle whistle fetch [--platform-tag <tag>] [--out <dir>]` / `needle whistle download whistle | <platform> [--out <dir>]` - the Whistle counterparts of `needle fetch` and `needle download`: pre-download the Whistle engine library, the `whistle.cact` weights, or a platform folder with the `whistle` binary, `libwhistle.a` and `whistle.h`.
- `needle fetch [--platform-tag <tag>] [--out <dir>]` - pre-download the inference engine for this machine (or another platform) into the cache; prints the path. For air-gapped devices, also see `NEEDLE3_LIB_PATH` and `HF_HUB_OFFLINE` at https://cactuscompute.com/blog/needle-python-docs.
- `needle platform finetune | generate | jobs | models | files | billing` - the hosted platform from the CLI (section above).
- `needle download needle3 | needle3.safetensors | model-<id> | <org>/<repo>[/<file>.cact] | <platform> [--out <dir>]` - pull the base Needle 3 archive, a checkpoint to fine-tune, a platform-trained model by id (`--depth N` for one size), a published `.cact` (single-archive repos need only `<org>/<repo>`), or pass a platform folder name (`macos-arm64`, `linux-x86_64`, `wasm`, `wasm-component`, ...) to fetch that platform's engine files into `<out>/<platform>/`. Native runners are marked executable; `wasm-component` contains the WASI Preview 2 component and WIT contract.
diff --git a/needle/__init__.py b/needle/__init__.py
index fcf84b7..d1ea2c7 100644
--- a/needle/__init__.py
+++ b/needle/__init__.py
@@ -11,9 +11,10 @@ import warnings
from .agent.tools import Field, build_schema, pydantic_schema, tool, _is_pydantic_model
from ._telemetry import track as _track
from ._worker import FineTuneWorker
+from .whistle import Whistle
__version__ = "3.0.1"
-__all__ = ["Needle", "ExtractionValidationError", "tool", "Field", "extract",
+__all__ = ["Needle", "Whistle", "ExtractionValidationError", "tool", "Field", "extract",
"__version__"]
@@ -80,8 +81,8 @@ def _confidence_head_present(path):
def _library_path(generation=2):
from .agent import fetch
- generation = int(generation)
- override = os.environ.get(f"NEEDLE{generation}_LIB_PATH")
+ generation = fetch._engine(generation)
+ override = os.environ.get(fetch.lib_path_env(generation))
if generation == 2 and not override:
# NEEDLE_LIB_PATH predates multi-generation dispatch and therefore
# names the Needle 2 engine. Never route a v3 archive through it.
@@ -89,9 +90,9 @@ def _library_path(generation=2):
if override:
return override
here = os.path.dirname(os.path.abspath(__file__))
- lib_name = fetch._lib_name()
+ lib_name = fetch.lib_name(generation)
stem, suffix = os.path.splitext(lib_name)
- local_names = [f"{stem}{generation}{suffix}"]
+ local_names = [lib_name if generation in fetch.NAMED_ENGINES else f"{stem}{generation}{suffix}"]
if generation == 2:
# Wheels published before the split shipped Needle 2 as libneedle.*.
local_names.append(lib_name)
@@ -100,9 +101,8 @@ def _library_path(generation=2):
if os.path.exists(local):
return local
version = fetch.engine_version(generation)
- cache = os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",
- f"v{generation}", version)
- cached = os.path.join(cache, fetch._lib_name())
+ cache = fetch.cache_dir(generation)
+ cached = os.path.join(cache, lib_name)
if os.path.exists(cached):
return cached
os.makedirs(cache, exist_ok=True)
diff --git a/needle/agent/fetch.py b/needle/agent/fetch.py
index 5e03d54..44c79fa 100644
--- a/needle/agent/fetch.py
+++ b/needle/agent/fetch.py
@@ -4,19 +4,34 @@ import sysconfig
import sys
import zipfile
+WHISTLE = "whistle"
+NEEDLE3_WHISTLE = "needle3_whistle"
+
ENGINE_REPOS = {
2: "Cactus-Compute/needle2",
3: "Cactus-Compute/needle3",
+ NEEDLE3_WHISTLE: "Cactus-Compute/needle3",
+ WHISTLE: "Cactus-Compute/whistle",
}
ENGINE_VERSIONS = {
2: "2.0.4",
3: "3.0.3",
+ NEEDLE3_WHISTLE: "3.0.0",
+ WHISTLE: "1.0.0",
}
BASE_WEIGHTS = {
2: "needle2.cact",
3: "needle3.cact",
+ NEEDLE3_WHISTLE: "needle3.cact",
+ WHISTLE: "whistle.cact",
+}
+# Engines named instead of numbered: one library per name, beside the generations.
+LIB_PATH_ENVS = {
+ NEEDLE3_WHISTLE: "NEEDLE3_WHISTLE_LIB_PATH",
+ WHISTLE: "NEEDLE_WHISTLE_LIB_PATH",
}
+NAMED_ENGINES = tuple(LIB_PATH_ENVS)
CHECKPOINT_PREFIX = "checkpoints"
# Backwards-compatible aliases for callers that explicitly fetch Needle 2.
@@ -50,6 +65,20 @@ def _lib_name():
return "libneedle.so"
+def _engine(generation):
+ """The key of an engine in the tables above: a Needle generation, or a named engine."""
+ return generation if generation in ENGINE_VERSIONS and not isinstance(generation, int) else int(generation)
+
+
+def lib_name(generation=2, tag=None):
+ name = _lib_name_for(tag) if tag else _lib_name()
+ return name.replace("needle", generation) if generation in NAMED_ENGINES else name
+
+
+def lib_path_env(generation=2):
+ return LIB_PATH_ENVS.get(generation) or f"NEEDLE{generation}_LIB_PATH"
+
+
def _is_musl():
"""True on a musl system (Alpine and friends).
@@ -100,8 +129,9 @@ def other_libc_tag():
return None
-def engine_wheel(version, tag):
- return "python/cactus_needle-{}-py3-none-{}.whl".format(version, tag)
+def engine_wheel(version, tag, generation=2):
+ name = generation if generation in NAMED_ENGINES else "needle"
+ return "{}python/cactus_{}-{}-py3-none-{}.whl".format(repo_prefix(generation), name, version, tag)
def unpublished_engine_wheels():
@@ -113,27 +143,32 @@ def unpublished_engine_wheels():
"""
from huggingface_hub import list_repo_files
- missing = []
- for generation in sorted(ENGINE_VERSIONS):
+ missing, listings = [], {}
+ for generation in ENGINE_VERSIONS:
repo = ENGINE_REPOS[generation]
- present = set(list_repo_files(repo))
+ if repo not in listings:
+ # A repo that is private or not created yet holds none of its wheels.
+ try:
+ listings[repo] = set(list_repo_files(repo))
+ except Exception:
+ listings[repo] = set()
for tag in WHEEL_TAGS:
- wheel = engine_wheel(ENGINE_VERSIONS[generation], tag)
- if wheel not in present:
+ wheel = engine_wheel(ENGINE_VERSIONS[generation], tag, generation)
+ if wheel not in listings[repo]:
missing.append(repo + "/" + wheel)
return missing
def engine_repo(generation=2):
try:
- return ENGINE_REPOS[int(generation)]
+ return ENGINE_REPOS[_engine(generation)]
except (KeyError, TypeError, ValueError) as exc:
raise ValueError(f"unsupported Needle generation: {generation}") from exc
def engine_version(generation=2):
try:
- return ENGINE_VERSIONS[int(generation)]
+ return ENGINE_VERSIONS[_engine(generation)]
except (KeyError, TypeError, ValueError) as exc:
raise ValueError(f"unsupported Needle generation: {generation}") from exc
@@ -155,7 +190,8 @@ def download_platform(name, out_dir, generation=2, dest=None):
repo = engine_repo(generation)
_register_download(generation)
- files = [f for f in list_repo_files(repo) if f.startswith(name + "/")]
+ prefix = repo_prefix(generation)
+ files = [f for f in list_repo_files(repo) if f.startswith(prefix + name + "/")]
if name not in PLATFORMS or not files:
raise FileNotFoundError(f"{name} is not a published platform folder in {repo}")
dest = dest or os.path.join(out_dir, name)
@@ -165,7 +201,7 @@ def download_platform(name, out_dir, generation=2, dest=None):
cached = hf_hub_download(repo_id=repo, filename=f, repo_type="model")
target = os.path.join(dest, os.path.basename(f))
shutil.copyfile(cached, target)
- if os.path.basename(target) in ("needle", "needle.exe"):
+ if os.path.splitext(os.path.basename(target))[0] in ("needle",) + NAMED_ENGINES:
os.chmod(target, os.stat(target).st_mode | stat.S_IXUSR
| stat.S_IXGRP | stat.S_IXOTH)
out.append(target)
@@ -174,14 +210,20 @@ def download_platform(name, out_dir, generation=2, dest=None):
def base_weights(generation=2):
try:
- return BASE_WEIGHTS[int(generation)]
+ return BASE_WEIGHTS[_engine(generation)]
except (KeyError, TypeError, ValueError) as exc:
raise ValueError(f"unsupported Needle generation: {generation}") from exc
+def repo_prefix(generation=2):
+ """Where an engine lives inside its repo. needle3_whistle shares needle3's."""
+ return generation + "/" if generation == NEEDLE3_WHISTLE else ""
+
+
def cache_dir(generation=2):
+ folder = generation if generation in NAMED_ENGINES else f"v{int(generation)}"
return os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",
- f"v{int(generation)}", engine_version(generation))
+ folder, engine_version(generation))
def fetch_weights(generation=2, dest_dir=None, force=False):
@@ -240,10 +282,10 @@ def fetch_library(version=None, dest_dir=None, tag=None, generation=2):
tag = tag or _platform_tag()
repo = engine_repo(generation)
_register_download(generation)
- path = hf_hub_download(repo_id=repo, filename=engine_wheel(version, tag), repo_type="model")
- lib = _lib_name_for(tag)
+ path = hf_hub_download(repo_id=repo, filename=engine_wheel(version, tag, generation), repo_type="model")
+ lib = lib_name(generation, tag)
stem, suffix = os.path.splitext(lib)
- member = f"{stem}{generation}{suffix}" if int(generation) >= 3 else lib
+ member = lib if generation in NAMED_ENGINES or int(generation) < 3 else f"{stem}{generation}{suffix}"
os.makedirs(dest_dir, exist_ok=True)
with zipfile.ZipFile(path) as archive:
data = archive.read("needle/" + member)
diff --git a/needle/cli.py b/needle/cli.py
index 7b12429..7ab4000 100644
--- a/needle/cli.py
+++ b/needle/cli.py
@@ -14,6 +14,7 @@ HELP = """usage: needle <command> [options]
download needle3 | needle3.safetensors | <platform> | model-<id> | <org>/<repo>[/<file>.cact]
fetch fetch the engine library for this platform
playground serve the browser playground
+ whistle speech to text: playground | compare | fetch | download
needle <command> --help for the options of one command.
Check the readme for the rest."""
@@ -39,6 +40,8 @@ def _download_target(spec):
name = spec[:-5] if spec.endswith(".cact") else spec
if name in ("needle2", "needle3"):
return "base", int(name[-1])
+ if name == fetch.WHISTLE:
+ return "base", name
if spec.endswith(".safetensors"):
return "checkpoint", spec
raise SystemExit(
@@ -262,6 +265,34 @@ def main():
p.add_argument("--port", type=int, default=7860)
p.add_argument("--host", type=str, default="127.0.0.1")
+ from .whistle import LANGUAGES
+ p = sub.add_parser("whistle")
+ verbs = p.add_subparsers(dest="verb")
+ v = verbs.add_parser("playground")
+ v.add_argument("audio", type=str, nargs="?", default=None,
+ help="A WAV file to transcribe once (default: press Enter to speak)")
+ v.add_argument("--language", type=str, default=None, choices=LANGUAGES,
+ help="Force the language (default: detect it)")
+ v.add_argument("--keywords", type=str, default="",
+ help="Words and phrases to favour, comma separated")
+ v.add_argument("--word-timestamps", action="store_true",
+ help="Show each word's start, end and probability")
+ v.add_argument("--weights", type=str, default=None,
+ help="whistle.cact to load (default: the published weights)")
+ v = verbs.add_parser("compare")
+ v.add_argument("audio", type=str, nargs="?", default=None,
+ help="A WAV file to run through every model once (default: press Enter to speak)")
+ v.add_argument("--weights", type=str, default=None,
+ help="whistle.cact to load (default: the published weights)")
+ v = verbs.add_parser("fetch")
+ v.add_argument("--out", type=str, default=None,
+ help="Directory to place the engine (default: the cache)")
+ v.add_argument("--platform-tag", type=str, default=None,
+ help="Fetch the build for another device, e.g. manylinux2014_aarch64")
+ v = verbs.add_parser("download")
+ v.add_argument("spec", type=str, help="whistle (the weights) or a platform folder (e.g. macos-arm64)")
+ v.add_argument("--out", type=str, default=".", help="Directory to place the files")
+
args = parser.parse_args()
if not args.command:
@@ -272,6 +303,9 @@ def main():
track("cli:" + args.command,
{"generation": getattr(args, "generation", 2)})
+ if args.command == "whistle" and args.verb in ("fetch", "download"):
+ args.command, args.generation = args.verb, "whistle"
+
if args.command == "run":
from .model.run import main as run_main
run_main(args)
@@ -292,20 +326,24 @@ def main():
if kind == "platform":
paths = fetch.download_platform(target, args.out,
generation=args.generation)
- if args.generation >= 3:
+ if args.generation != 2:
paths.append(fetch.fetch_weights(args.generation, os.path.join(args.out, target)))
for path in paths:
print(f" {'file':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")
runner = next((p for p in paths
- if os.path.basename(p) in ("needle", "needle.exe")), None)
+ if os.path.basename(p) in ("needle", "needle.exe", "whistle", "whistle.exe")), None)
if runner:
- weights = f" --model {fetch.base_weights(args.generation)}" if args.generation >= 3 else ""
- print(f" {'next':<9} {runner}{weights} --tools tools.json --serve")
+ weights = f" --model {fetch.base_weights(args.generation)}" if args.generation != 2 else ""
+ use = "--audio clip.wav" if args.generation == fetch.WHISTLE else "--tools tools.json --serve"
+ print(f" {'next':<9} {runner}{weights} {use}")
elif kind == "base":
os.makedirs(args.out, exist_ok=True)
path = fetch.fetch_weights(target, args.out)
print(f" {'weights':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")
- print(f" {'next':<9} needle.Needle(weights={path!r}, tools=[...])")
+ if target == fetch.WHISTLE:
+ print(f" {'next':<9} needle.Whistle(weights={path!r})")
+ else:
+ print(f" {'next':<9} needle.Needle(weights={path!r}, tools=[...])")
elif kind == "hosted":
from .platform import Platform
for path in Platform().download(target, args.out, depth=args.depth):
@@ -336,17 +374,24 @@ def main():
from .agent import fetch
generation = args.generation
version = fetch.engine_version(generation)
- dest = args.out or os.path.join(os.path.expanduser("~"), ".cache",
- "cactus-needle", f"v{generation}", version)
+ dest = args.out or fetch.cache_dir(generation)
os.makedirs(dest, exist_ok=True)
path = fetch.fetch_library(version, dest, tag=args.platform_tag,
generation=generation)
print(f" {'engine':<9} {path}")
- print(f" {'deploy':<9} copy to ~/.cache/cactus-needle/v{generation}/{version}/ "
- f"on the device, or point NEEDLE{generation}_LIB_PATH at the file")
+ print(f" {'deploy':<9} copy to {fetch.cache_dir(generation)}/ "
+ f"on the device, or point {fetch.lib_path_env(generation)} at the file")
elif args.command == "platform":
from .platform import main as platform_main
platform_main(args)
elif args.command == "playground":
from .playground.server import main as playground_main
playground_main(args)
+ elif args.command == "whistle":
+ if args.verb == "playground":
+ from .whistle.playground import main as whistle_main
+ elif args.verb == "compare":
+ from .whistle.compare import main as whistle_main
+ else:
+ raise SystemExit("needle whistle playground | compare | fetch | download")
+ whistle_main(args)
diff --git a/needle/whistle/__init__.py b/needle/whistle/__init__.py
new file mode 100644
index 0000000..bc4be7c
--- /dev/null
+++ b/needle/whistle/__init__.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import array
+import ctypes
+import json
+import os
+import sys
+import wave
+
+SAMPLE_RATE = 16000
+LANGUAGES = ("en", "de", "fr", "es", "it", "nl", "pl")
+
+_handle = None
+_loaded = None
+
+
+def _weights_path():
+ from .. import _base_weights_path
+ from ..agent import fetch
+
+ return os.environ.get("NEEDLE_WHISTLE_WEIGHTS") or _base_weights_path(fetch.WHISTLE)
+
+
+def _lib():
+ global _handle
+ if _handle is None:
+ from .. import _load_cdll
+ from ..agent import fetch
+
+ lib = _load_cdll(fetch.WHISTLE)
+ samples = ctypes.POINTER(ctypes.c_float)
+ lib.whistle_load.argtypes = [ctypes.c_char_p, ctypes.c_uint64]
+ lib.whistle_load.restype = ctypes.c_int
+ lib.whistle_transcribe.argtypes = [samples, ctypes.c_int, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int,
+ ctypes.c_char_p, ctypes.c_int]
+ lib.whistle_transcribe.restype = ctypes.c_int
+ lib.whistle_embed.argtypes = [samples, ctypes.c_int, samples, ctypes.c_int]
+ lib.whistle_embed.restype = ctypes.c_int
+ lib.whistle_last_error.argtypes = []
+ lib.whistle_last_error.restype = ctypes.c_char_p
+ _handle = lib
+ return _handle
+
+
+def _read_wav(path):
+ with wave.open(path, "rb") as source:
+ channels, width, rate = source.getnchannels(), source.getsampwidth(), source.getframerate()
+ raw = source.readframes(source.getnframes())
+ if width == 3:
+ values = [int.from_bytes(raw[i:i + 3], "little", signed=True) for i in range(0, len(raw), 3)]
+ else:
+ values = array.array({1: "B", 2: "h", 4: "i"}[width])
+ values.frombytes(raw)
+ if sys.byteorder == "big":
+ values.byteswap()
+ offset, scale = (128, 128.0) if width == 1 else (0, float(1 << (8 * width - 1)))
+ scale *= channels
+ mono = [(sum(frame) - offset * channels) / scale for frame in zip(*(values[c::channels] for c in range(channels)))]
+ if rate == SAMPLE_RATE or not mono:
+ return mono
+ try:
+ import numpy
+ import soxr
+ except ImportError:
+ raise RuntimeError(f"resampling {rate} Hz audio to {SAMPLE_RATE} Hz needs soxr: pip install cactus-needle[whistle]") from None
+ return soxr.resample(numpy.asarray(mono, numpy.float32), rate, SAMPLE_RATE, quality="HQ")
+
+
+def _samples(audio):
+ if isinstance(audio, (str, os.PathLike)):
+ audio = _read_wav(os.fspath(audio))
+ data = array.array("f")
+ if isinstance(audio, (bytes, bytearray)):
+ data.frombytes(audio)
+ elif isinstance(audio, array.array) and audio.typecode == "f":
+ data = audio
+ elif hasattr(audio, "tobytes") and getattr(audio, "dtype", None) is not None:
+ data.frombytes(audio.astype("float32", copy=False).tobytes())
+ else:
+ data.extend(audio)
+ return (ctypes.c_float * len(data)).from_buffer(data) if len(data) else (ctypes.c_float * 1)(), len(data)
+
+
+class Whistle:
+ """Speech-to-text in English, German, French, Spanish, Italian, Dutch and Polish.
+
+ Audio is a WAV file path or 16 kHz mono float samples in [-1, 1], at most 30 s.
+ One model is loaded per process; it is not thread-safe.
+ """
+
+ def __init__(self, weights=None, buffer_size=1 << 18):
+ self.weights = os.fspath(weights) if weights is not None else _weights_path()
+ self._buffer = ctypes.create_string_buffer(buffer_size)
+ self._bind()
+
+ def _bind(self):
+ global _loaded
+ lib = _lib()
+ if _loaded == self.weights:
+ return lib
+ with open(self.weights, "rb") as handle:
+ data = handle.read()
+ if lib.whistle_load(data, len(data)) < 0:
+ _loaded = None
+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))
+ _loaded = self.weights
+ return lib
+
+ def transcribe(self, audio, language=None, keywords=None, word_timestamps=False) -> dict:
+ """Returns {"text", "language", "ttft_ms", "decode_tps"}, plus "words" with start, end and probability when word_timestamps is set.
+
+ language is one of LANGUAGES, or None to detect it. keywords are words or phrases for keyword biasing.
+ """
+ lib = self._bind()
+ samples, count = _samples(audio)
+ if keywords is not None and not isinstance(keywords, str):
+ keywords = "\n".join(keywords)
+ code = lib.whistle_transcribe(samples, count, language.encode("utf-8") if language else None,
+ keywords.encode("utf-8") if keywords else None, int(bool(word_timestamps)),
+ self._buffer, len(self._buffer))
+ if code < 0:
+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))
+ return json.loads(self._buffer.value.decode("utf-8", "replace"))
+
+ def embed(self, audio) -> list[float]:
+ """The encoder output, one row of floats per 80 ms frame, flattened."""
+ lib = self._bind()
+ samples, count = _samples(audio)
+ size = lib.whistle_embed(samples, count, None, 0)
+ if size < 0:
+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))
+ output = (ctypes.c_float * size)()
+ if lib.whistle_embed(samples, count, output, size) != size:
+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))
+ return list(output)
diff --git a/needle/whistle/compare.py b/needle/whistle/compare.py
new file mode 100644
index 0000000..c975260
--- /dev/null
+++ b/needle/whistle/compare.py
@@ -0,0 +1,106 @@
+import os
+import time
+
+from .playground import audio_path, prompt, record, status
+
+HELP = """ Enter speak, Enter again to stop
+ /file clip.wav run a file through every model
+ /quit leave"""
+INSTALL = 'pip install "cactus-needle[whistle,whistle-compare]"'
+
+
+def rate(marks):
+ return (len(marks) - 1) / (marks[-1] - marks[0]) if len(marks) > 1 and marks[-1] > marks[0] else 0.0
+
+
+def load_whistle(weights):
+ from . import Whistle
+
+ whistle = Whistle(weights=weights)
+
+ def transcribe(audio):
+ result = whistle.transcribe(audio, language="en")
+ return result["text"], result["ttft_ms"] / 1000, result["decode_tps"]
+
+ return os.path.getsize(whistle.weights), transcribe
+
+
+def load_whisper(size):
+ import whisper
+
+ model = whisper.load_model(size, device="cpu")
+ cache = os.path.join(os.getenv("XDG_CACHE_HOME", os.path.join(os.path.expanduser("~"), ".cache")), "whisper")
+ marks = []
+ model.decoder.register_forward_hook(lambda *_: marks.append(time.perf_counter()))
+
+ def transcribe(audio):
+ marks.clear()
+ started = time.perf_counter()
+ text = model.transcribe(audio, language="en", fp16=False)["text"].strip()
+ return text, marks[0] - started, rate(marks)
+
+ return os.path.getsize(os.path.join(cache, f"{size}.pt")), transcribe
+
+
+def load_moonshine():
+ import moonshine_voice
+
+ from . import SAMPLE_RATE
+
+ path, arch = moonshine_voice.get_model_for_language("en", moonshine_voice.ModelArch.TINY_STREAMING)
+ model = moonshine_voice.Transcriber(model_path=path, model_arch=arch)
+
+ def transcribe(audio):
+ lines = model.transcribe_without_streaming(audio.tolist(), SAMPLE_RATE).lines
+ return " ".join(line.text.strip() for line in lines).strip(), None, None
+
+ return sum(os.path.getsize(os.path.join(path, f)) for f in os.listdir(path)), transcribe
+
+
+def compare(models, audio):
+ for name, size, transcribe in models:
+ started = time.perf_counter()
+ text, ttft, tokens = transcribe(audio)
+ print(status(name, size, ttft, tokens, time.perf_counter() - started), " ", text or "(no speech)")
+
+
+def main(args):
+ from . import SAMPLE_RATE, _read_wav
+
+ try:
+ import moonshine_voice # noqa: F401
+ import numpy
+ import whisper # noqa: F401
+ except ImportError as error:
+ raise SystemExit(f"{error.name} is not installed: {INSTALL}")
+ print("whistle compare: downloading and initializing the models...", flush=True)
+ models = [
+ ("whistle", *load_whistle(args.weights)),
+ ("whisper tiny", *load_whisper("tiny")),
+ ("whisper base", *load_whisper("base")),
+ ("moonshine tiny v2", *load_moonshine()),
+ ]
+ beat = numpy.arange(SAMPLE_RATE) * (numpy.pi / SAMPLE_RATE)
+ warmup = (numpy.sin(440 * beat) * numpy.abs(numpy.sin(3 * beat))).astype(numpy.float32)
+ for _, _, transcribe in models:
+ transcribe(warmup)
+ if args.audio:
+ return compare(models, numpy.asarray(_read_wav(args.audio), numpy.float32))
+ print(HELP)
+ while True:
+ line = prompt()
+ command, _, rest = line.partition(" ")
+ if command == "/quit":
+ return
+ if command == "/file":
+ try:
+ compare(models, numpy.asarray(_read_wav(audio_path(rest)), numpy.float32))
+ except OSError as error:
+ print(f" {error}")
+ elif line == "":
+ try:
+ compare(models, numpy.asarray(record(), numpy.float32))
+ except RuntimeError as error:
+ print(f" {error}")
+ else:
+ print(HELP)
diff --git a/needle/whistle/playground.py b/needle/whistle/playground.py
new file mode 100644
index 0000000..ea283b4
--- /dev/null
+++ b/needle/whistle/playground.py
@@ -0,0 +1,115 @@
+import os
+import time
+
+HELP = """ Enter speak, Enter again to stop
+ /language de force a language (en de fr es it nl pl), bare to detect it
+ /keywords Siobhan, Krzysztof
+ /timestamps toggle word times
+ /file clip.wav transcribe a file
+ /quit leave"""
+CLEAR_ABOVE = "\x1b[1A\x1b[2K"
+LIMIT_SECONDS = 30
+
+
+def audio_path(rest):
+ """The path in a /file line, as a terminal hands it over: quoted, or with escaped spaces."""
+ path = rest.strip()
+ if len(path) > 1 and path[0] == path[-1] and path[0] in "'\"":
+ return path[1:-1]
+ return path.replace("\\ ", " ")
+
+
+def status(name, size, ttft, tokens, total):
+ ttft = f"{ttft * 1000:.0f} ms" if ttft is not None else "-"
+ tokens = f"{tokens:.0f} tok/s" if tokens is not None else "-"
+ spent = f"{total:.1f} s" if total >= 10 else f"{total * 1000:.0f} ms"
+ return f" {name:<18}{size / 1e6:>4.0f} MB ttft {ttft:>6} decode {tokens:>10} total {spent:>7}"
+
+
+def record():
+ from . import SAMPLE_RATE
+
+ try:
+ import numpy
+ import sounddevice
+ import soxr
+ except ImportError as error:
+ raise RuntimeError(f'{error.name} is not installed: pip install "cactus-needle[whistle]"') from None
+ chunks = []
+ try:
+ rate = int(sounddevice.query_devices(kind="input")["default_samplerate"])
+ with sounddevice.InputStream(samplerate=rate, channels=1, dtype="float32", callback=lambda data, *_: chunks.append(data.copy())):
+ print(CLEAR_ABOVE + "● recording, Enter to stop", end="", flush=True)
+ try:
+ input()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ except sounddevice.PortAudioError as error:
+ raise RuntimeError(f"no microphone: {error}") from None
+ print(CLEAR_ABOVE, end="", flush=True)
+ heard = numpy.concatenate(chunks)[:, 0] if chunks else numpy.zeros(0, numpy.float32)
+ audio = heard[:LIMIT_SECONDS * rate]
+ if len(audio) < len(heard):
+ print(f" keeping the first {LIMIT_SECONDS} s")
+ return audio if rate == SAMPLE_RATE else soxr.resample(audio, rate, SAMPLE_RATE, quality="HQ")
+
+
+def prompt():
+ try:
+ return input("› ").strip()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ return "/quit"
+
+
+def transcribe(whistle, audio, state):
+ started = time.perf_counter()
+ try:
+ result = whistle.transcribe(audio, language=state["language"], keywords=state["keywords"], word_timestamps=state["timestamps"])
+ except (RuntimeError, OSError, EOFError) as error:
+ print(f" {error}")
+ return
+ total = time.perf_counter() - started
+ print(result["text"] or "(no speech)")
+ for word in result.get("words", []):
+ print(f" {word['start']:6.2f} - {word['end']:5.2f} {word['word']:<20} {word['probability']:.2f}")
+ print(status("whistle", os.path.getsize(whistle.weights), result["ttft_ms"] / 1000, result["decode_tps"], total),
+ " ", result["language"] or "no speech")
+
+
+def main(args):
+ from . import LANGUAGES, Whistle
+
+ state = {"language": args.language, "keywords": [k.strip() for k in args.keywords.split(",") if k.strip()], "timestamps": args.word_timestamps}
+ print("whistle playground: downloading and initializing the model...", flush=True)
+ whistle = Whistle(weights=args.weights)
+ if args.audio:
+ return transcribe(whistle, args.audio, state)
+ print(HELP)
+ while True:
+ line = prompt()
+ command, _, rest = line.partition(" ")
+ if command == "/quit":
+ return
+ if command == "/language":
+ language = rest.strip()
+ if language and language not in LANGUAGES:
+ print(" language is one of", " ".join(LANGUAGES))
+ continue
+ state["language"] = language or None
+ print(" language", state["language"] or "detected")
+ elif command in ("/keywords", "/keyword"):
+ state["keywords"] = [k.strip() for k in rest.split(",") if k.strip()]
+ print(" keywords", ", ".join(state["keywords"]) or "none")
+ elif command == "/timestamps":
+ state["timestamps"] = not state["timestamps"]
+ print(" word timestamps", "on" if state["timestamps"] else "off")
+ elif command == "/file":
+ transcribe(whistle, audio_path(rest), state)
+ elif line == "":
+ try:
+ transcribe(whistle, record(), state)
+ except RuntimeError as error:
+ print(f" {error}")
+ else:
+ print(HELP)
diff --git a/pyproject.toml b/pyproject.toml
index a6cefce..3cee9c7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,8 @@ metal = [
"jaxlib==0.4.38",
"jax-metal"
]
+whistle = ["numpy", "soxr", "sounddevice"]
+whistle-compare = ["openai-whisper", "moonshine-voice"]
test = ["pytest", "pydantic"]
[project.scripts]
diff --git a/setup b/setup
index 3b0b0af..61c8446 100755
--- a/setup
+++ b/setup
@@ -31,7 +31,7 @@ source "$VENV_DIR/bin/activate"
if [ "$UV_INSTALL" = "pip install" ]; then
pip install --upgrade pip -q
fi
-$UV_INSTALL -e ".[train]" -q
+$UV_INSTALL -e ".[train,whistle]" -q
if command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi >/dev/null 2>&1; then
echo "NVIDIA GPU detected; installing gpu extras..."
diff --git a/setup.bat b/setup.bat
index 788ca6d..c63f598 100644
--- a/setup.bat
+++ b/setup.bat
@@ -19,6 +19,6 @@ if not exist "%VENV_DIR%\Scripts\python.exe" %PYTHON_CMD% -m venv "%VENV_DIR%"
call "%VENV_DIR%\Scripts\activate.bat"
python -m pip install --upgrade pip -q
-python -m pip install -e ".[train]" -q
+python -m pip install -e ".[train,whistle]" -q
needle --help
diff --git a/tests/conftest.py b/tests/conftest.py
index da63a86..8d8bfad 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -13,24 +13,22 @@ def _engine_available(generation=3):
import needle
from needle.agent import fetch
- override = os.environ.get(f"NEEDLE{generation}_LIB_PATH")
+ override = os.environ.get(fetch.lib_path_env(generation))
if generation == 2 and not override:
override = os.environ.get("NEEDLE_LIB_PATH")
if override:
return os.path.exists(override)
here = os.path.dirname(needle.__file__)
- name = fetch._lib_name()
+ name = fetch.lib_name(generation)
stem, suffix = os.path.splitext(name)
- local_names = [f"{stem}{generation}{suffix}"]
+ local_names = [name if generation == fetch.WHISTLE else f"{stem}{generation}{suffix}"]
if generation == 2:
local_names.append(name)
if any(os.path.exists(os.path.join(here, local)) for local in local_names):
return True
- cache = os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",
- f"v{generation}", fetch.engine_version(generation), name)
- return os.path.exists(cache)
+ return os.path.exists(os.path.join(fetch.cache_dir(generation), name))
except Exception:
return False
diff --git a/tests/test_fetch.py b/tests/test_fetch.py
index 5e59cca..0d76862 100644
--- a/tests/test_fetch.py
+++ b/tests/test_fetch.py
@@ -108,11 +108,11 @@ def test_component_platform_is_downloadable():
def test_unpublished_engine_wheels_lists_every_missing_tag(monkeypatch):
from needle.agent import fetch
- published = {
- repo: {fetch.engine_wheel(version, tag) for tag in fetch.WHEEL_TAGS}
- for repo, version in ((fetch.ENGINE_REPOS[2], fetch.ENGINE_VERSIONS[2]),
- (fetch.ENGINE_REPOS[3], fetch.ENGINE_VERSIONS[3]))
- }
+ published = {}
+ for generation, version in fetch.ENGINE_VERSIONS.items():
+ # needle3 hosts both its own engine and needle3_whistle, so the sets merge.
+ published.setdefault(fetch.ENGINE_REPOS[generation], set()).update(
+ fetch.engine_wheel(version, tag, generation) for tag in fetch.WHEEL_TAGS)
monkeypatch.setattr("huggingface_hub.list_repo_files",
lambda repo: sorted(published[repo]) + ["needle3.cact"])
assert fetch.unpublished_engine_wheels() == []
@@ -122,6 +122,29 @@ def test_unpublished_engine_wheels_lists_every_missing_tag(monkeypatch):
published[repo3].remove(dropped)
assert fetch.unpublished_engine_wheels() == [repo3 + "/" + dropped]
+ audio = fetch.engine_wheel(fetch.ENGINE_VERSIONS[fetch.NEEDLE3_WHISTLE], "win_arm64", fetch.NEEDLE3_WHISTLE)
+ published[repo3].remove(audio)
+ assert fetch.unpublished_engine_wheels() == [repo3 + "/" + dropped, repo3 + "/" + audio]
+ published[repo3].add(audio)
+
+ whistle = fetch.ENGINE_REPOS[fetch.WHISTLE]
+ published[whistle].clear()
+ missing = fetch.unpublished_engine_wheels()
+ assert len(missing) == 1 + len(fetch.WHEEL_TAGS)
+ assert missing[-1] == f"{whistle}/python/cactus_whistle-{fetch.ENGINE_VERSIONS[fetch.WHISTLE]}-py3-none-win_arm64.whl"
+
+
+def test_a_repo_that_cannot_be_listed_holds_none_of_its_wheels(monkeypatch):
+ """The whistle repo is private until release; the gate must report, not raise."""
+ from needle.agent import fetch
+
+ def refuse(repo):
+ raise OSError("401 private repo")
+
+ monkeypatch.setattr("huggingface_hub.list_repo_files", refuse)
+ missing = fetch.unpublished_engine_wheels()
+ assert len(missing) == len(fetch.ENGINE_VERSIONS) * len(fetch.WHEEL_TAGS)
+
def test_release_gate_runs_before_the_publish_step():
from pathlib import Path
diff --git a/tests/test_whistle.py b/tests/test_whistle.py
new file mode 100644
index 0000000..d98e625
--- /dev/null
+++ b/tests/test_whistle.py
@@ -0,0 +1,382 @@
+import array
+import math
+import os
+import struct
+import sys
+import wave
+
+import pytest
+
+from conftest import _engine_available
+
+
+def _whistle_weights():
+ from needle.agent import fetch
+
+ return os.environ.get("NEEDLE_WHISTLE_WEIGHTS") or os.path.join(fetch.cache_dir(fetch.WHISTLE), fetch.base_weights(fetch.WHISTLE))
+
+
+requires_whistle = pytest.mark.skipif(not (_engine_available("whistle") and os.path.exists(_whistle_weights())),
+ reason="Whistle engine or whistle.cact not installed (auto-fetched from HF on first real use)")
+
+
+def test_engine_and_weights_resolve_like_needle(tmp_path, monkeypatch):
+ import zipfile
+ import needle
+ from needle import whistle
+ from needle.agent import fetch
+
+ monkeypatch.setattr(os.path, "expanduser", lambda path: str(tmp_path))
+ monkeypatch.setattr(needle, "__file__", str(tmp_path / "package" / "__init__.py"))
+ monkeypatch.setattr(fetch, "_register_download", lambda generation: None)
+ monkeypatch.delenv("NEEDLE_WHISTLE_WEIGHTS", raising=False)
+ monkeypatch.setenv("NEEDLE_WHISTLE_LIB_PATH", "/opt/libwhistle.so")
+ assert needle._library_path(fetch.WHISTLE) == "/opt/libwhistle.so"
+ monkeypatch.delenv("NEEDLE_WHISTLE_LIB_PATH")
+
+ lib = fetch.lib_name(fetch.WHISTLE)
+ wheel, weights, fetched = tmp_path / "engine.whl", tmp_path / "published.cact", []
+ with zipfile.ZipFile(wheel, "w") as archive:
+ archive.writestr("needle/" + lib, b"engine")
+ weights.write_bytes(b"weights")
+ monkeypatch.setattr("huggingface_hub.hf_hub_download",
+ lambda **kwargs: fetched.append((kwargs["repo_id"], kwargs["filename"])) or str(weights if kwargs["filename"].endswith(".cact") else wheel))
+ cache = tmp_path / ".cache" / "cactus-needle" / "whistle" / fetch.ENGINE_VERSIONS[fetch.WHISTLE]
+ assert lib.startswith("libwhistle.") and needle._library_path(fetch.WHISTLE) == str(cache / lib) and (cache / lib).read_bytes() == b"engine"
+ assert whistle._weights_path() == str(cache / "whistle.cact") and (cache / "whistle.cact").read_bytes() == b"weights"
+ assert fetched == [("Cactus-Compute/whistle", f"python/cactus_whistle-{fetch.ENGINE_VERSIONS[fetch.WHISTLE]}-py3-none-{fetch._platform_tag()}.whl"),
+ ("Cactus-Compute/whistle", "whistle.cact")]
+ assert needle._library_path(fetch.WHISTLE) and whistle._weights_path() and len(fetched) == 2
+ monkeypatch.setenv("NEEDLE_WHISTLE_WEIGHTS", "/opt/whistle.cact")
+ assert whistle._weights_path() == "/opt/whistle.cact"
+
+
+def test_cli_fetches_the_whistle_engine_and_weights(tmp_path, monkeypatch, capsys):
+ import sys
+ import needle._telemetry
+ import needle.cli
+ from needle.agent import fetch
+
+ calls = []
+ monkeypatch.setattr(needle._telemetry, "track", lambda *a, **k: None)
+ monkeypatch.setattr(fetch, "fetch_library", lambda version, dest, tag=None, generation=2: calls.append((version, tag, generation)) or os.path.join(dest, "libwhistle.so"))
+ monkeypatch.setattr(fetch, "fetch_weights", lambda generation, dest: calls.append((generation, dest)) or __file__)
+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "fetch", "--out", str(tmp_path), "--platform-tag", "manylinux2014_aarch64"])
+ needle.cli.main()
+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "download", "whistle", "--out", str(tmp_path)])
+ needle.cli.main()
+ assert calls == [(fetch.ENGINE_VERSIONS[fetch.WHISTLE], "manylinux2014_aarch64", fetch.WHISTLE), (fetch.WHISTLE, str(tmp_path))]
+ out = capsys.readouterr().out
+ assert "NEEDLE_WHISTLE_LIB_PATH" in out and "needle.Whistle(weights=" in out
+
+
+def _tone(seconds, rate=16000):
+ return [0.3 * math.sin(2 * math.pi * 220 * i / rate) for i in range(int(seconds * rate))]
+
+
+def _write_wav(path, samples, rate, channels=1, width=2):
+ peak = (1 << (8 * width - 1)) - 1
+ with wave.open(str(path), "wb") as out:
+ out.setnchannels(channels)
+ out.setsampwidth(width)
+ out.setframerate(rate)
+ for value in samples:
+ level = int(value * peak)
+ frame = bytes([level + 128]) if width == 1 else level.to_bytes(width, "little", signed=True)
+ out.writeframes(frame * channels)
+
+
[email protected]("rate,channels,width", [(16000, 1, 2), (8000, 1, 2), (44100, 2, 2), (16000, 1, 1), (22050, 2, 3), (48000, 1, 4)])
+def test_wav_files_become_16k_mono_floats(tmp_path, rate, channels, width):
+ from needle.whistle import _read_wav
+
+ if rate != 16000:
+ pytest.importorskip("soxr")
+ path = tmp_path / "tone.wav"
+ _write_wav(path, _tone(0.5, rate), rate, channels, width)
+ samples = _read_wav(str(path))
+ assert abs(len(samples) - 8000) <= 1
+ assert 0.28 < max(samples) < 0.31 and -0.31 < min(samples) < -0.28
+ crossings = sum(1 for a, b in zip(samples, samples[1:]) if a < 0 <= b)
+ assert 108 <= crossings <= 111
+
+
+def test_samples_accept_lists_arrays_and_float32_bytes():
+ from needle.whistle import _samples
+
+ values = [0.0, 0.5, -0.25]
+ inputs = [values, array.array("f", values), struct.pack("<3f", *values), (v for v in values)]
+ numpy = pytest.importorskip("numpy")
+ inputs.append(numpy.array(values, numpy.float64))
+ for audio in inputs:
+ buffer, count = _samples(audio)
+ assert count == 3 and list(buffer) == values
+ assert _samples([])[1] == 0
+
+
+@requires_whistle
+def test_silence_is_an_empty_transcript():
+ from needle import Whistle
+
+ result = Whistle().transcribe([0.0] * 16000, word_timestamps=True)
+ assert result == {"text": "", "language": "", "words": [], "ttft_ms": 0.0, "decode_tps": 0.0}
+
+
+@requires_whistle
+def test_transcribe_returns_text_language_and_timed_words(tmp_path):
+ from needle import Whistle
+ from needle.whistle import LANGUAGES
+
+ whistle = Whistle()
+ sound = [v * (0.2 + 0.8 * abs(math.sin(math.pi * 3 * i / 16000))) for i, v in enumerate(_tone(3))]
+ plain = whistle.transcribe(sound)
+ assert set(plain) == {"text", "language", "ttft_ms", "decode_tps"} and plain["language"] in LANGUAGES + ("",)
+ assert (plain["ttft_ms"] > 0) == bool(plain["language"]) and plain["decode_tps"] >= 0
+ path = tmp_path / "sound.wav"
+ _write_wav(path, sound, 16000)
+ timed = whistle.transcribe(path, language="en", keywords=["Siobhan", "Krzysztof"], word_timestamps=True)
+ assert timed["language"] == "en" and isinstance(timed["text"], str)
+ starts = [word["start"] for word in timed["words"]]
+ assert starts == sorted(starts)
+ assert all(0 <= word["start"] <= word["end"] <= 3.01 and 0 <= word["probability"] <= 1 for word in timed["words"])
+
+
+@requires_whistle
+def test_embed_and_the_30_second_limit():
+ from needle import Whistle
+
+ whistle = Whistle()
+ embedding = whistle.embed(_tone(1))
+ assert len(embedding) > 0 and all(isinstance(v, float) for v in embedding[:8])
+ with pytest.raises(RuntimeError, match="30 s"):
+ whistle.transcribe([0.0] * (30 * 16000 + 1))
+
+
+@requires_whistle
+def test_missing_weights_fail_clearly(tmp_path):
+ from needle import Whistle
+
+ broken = tmp_path / "broken.cact"
+ broken.write_bytes(b"not a model at all")
+ with pytest.raises(RuntimeError):
+ Whistle(weights=broken)
+ whistle = Whistle()
+ assert os.path.getsize(whistle.weights) > 0 and whistle.transcribe([0.0] * 16000)["text"] == ""
+
+
+class _Whistle:
+ weights = __file__
+
+ def __init__(self, result):
+ self.result = result
+ self.calls = []
+
+ def transcribe(self, audio, **options):
+ self.calls.append((audio, options))
+ return self.result
+
+
+class _Microphone:
+ PortAudioError = OSError
+
+ def __init__(self, rate, seconds):
+ self.rate, self.seconds, self.opened = rate, seconds, None
+
+ def query_devices(self, kind):
+ return {"default_samplerate": float(self.rate)}
+
+ def InputStream(self, **options):
+ import numpy
+
+ microphone = self
+
+ class Stream:
+ def __enter__(self):
+ microphone.opened = options
+ options["callback"](numpy.full((microphone.rate * microphone.seconds, 1), 0.25, numpy.float32), None, None, None)
+
+ def __exit__(self, *_):
+ return False
+
+ return Stream()
+
+
+def test_record_resamples_the_microphone_to_16_khz_and_keeps_30_s(monkeypatch, capsys):
+ numpy = pytest.importorskip("numpy")
+ pytest.importorskip("soxr")
+ from needle.whistle.playground import record
+
+ microphone = _Microphone(48000, 1)
+ monkeypatch.setitem(sys.modules, "sounddevice", microphone)
+ monkeypatch.setattr("builtins.input", lambda *_: "")
+ audio = record()
+ assert microphone.opened["samplerate"] == 48000 and microphone.opened["channels"] == 1
+ assert audio.dtype == numpy.float32 and len(audio) == 16000 and abs(float(audio[8000]) - 0.25) < 0.01
+ assert "recording, Enter to stop" in capsys.readouterr().out
+ monkeypatch.setitem(sys.modules, "sounddevice", _Microphone(16000, 31))
+ assert len(record()) == 30 * 16000
+ assert "keeping the first 30 s" in capsys.readouterr().out
+
+
+def test_record_says_what_is_missing(monkeypatch):
+ from needle.whistle.playground import record
+
+ monkeypatch.setitem(sys.modules, "sounddevice", None)
+ with pytest.raises(RuntimeError, match=r"cactus-needle\[whistle\]"):
+ record()
+
+
+def test_rate_counts_steps_after_the_first_mark():
+ from needle.whistle.compare import rate
+
+ assert rate([1.0, 1.5, 2.0]) == 2.0
+ assert rate([1.0]) == 0.0 and rate([]) == 0.0 and rate([2.0, 2.0]) == 0.0
+
+
+def test_compare_prints_one_line_per_model_with_dashes_for_missing_timing(capsys):
+ from needle.whistle.compare import compare
+
+ models = [("whistle", 17e6, lambda audio: ("hello there", 0.013, 1264.0)),
+ ("moonshine tiny v2", 45e6, lambda audio: ("", None, None))]
+ compare(models, [0.0] * 16000)
+ lines = capsys.readouterr().out.splitlines()
+ assert len(lines) == 2
+ assert lines[0].startswith(" whistle 17 MB ttft 13 ms decode 1264 tok/s total")
+ assert lines[0].endswith("ms hello there")
+ assert lines[1].startswith(" moonshine tiny v2 45 MB ttft - decode - total")
+ assert lines[1].endswith("ms (no speech)")
+
+
+def test_playground_and_compare_share_one_status_line():
+ from needle.whistle.playground import status
+
+ assert status("whistle", 17e6, 0.0137, 1264.4, 0.048) == " whistle 17 MB ttft 14 ms decode 1264 tok/s total 48 ms"
+ assert status("moonshine tiny v2", 145e6, None, None, 0.21) == " moonshine tiny v2 145 MB ttft - decode - total 210 ms"
+
+
+def test_status_reads_a_slow_run_in_seconds():
+ from needle.whistle.playground import status
+
+ assert status("whistle", 17e6, 0.0137, 1264.4, 12.5).endswith("total 12.5 s")
+ assert status("whistle", 17e6, 0.0137, 1264.4, 9.9).endswith("total 9900 ms")
+
+
+def test_audio_path_takes_a_path_as_a_terminal_hands_it_over():
+ from needle.whistle.playground import audio_path
+
+ assert audio_path(" clip.wav ") == "clip.wav"
+ assert audio_path('"my clips/a b.wav"') == "my clips/a b.wav"
+ assert audio_path("'my clips/a b.wav'") == "my clips/a b.wav"
+ assert audio_path("my\\ clips/a\\ b.wav") == "my clips/a b.wav"
+
+
+def test_playground_prints_text_words_and_timing(capsys):
+ from needle.whistle.playground import transcribe
+
+ whistle = _Whistle({"text": "hello there", "language": "en", "ttft_ms": 12.6, "decode_tps": 900.4,
+ "words": [{"word": "hello", "start": 0.1, "end": 0.4, "probability": 0.98}]})
+ transcribe(whistle, "clip.wav", {"language": "en", "keywords": ["Siobhan"], "timestamps": True})
+ out = capsys.readouterr().out.splitlines()
+ assert whistle.calls == [("clip.wav", {"language": "en", "keywords": ["Siobhan"], "word_timestamps": True})]
+ assert out[0] == "hello there"
+ assert out[1].split() == ["0.10", "-", "0.40", "hello", "0.98"]
+ assert out[2].startswith(" whistle ") and "ttft 13 ms decode 900 tok/s total" in out[2] and out[2].endswith("ms en")
+
+
+def test_playground_reports_engine_errors_instead_of_raising(capsys):
+ from needle.whistle.playground import transcribe
+
+ class Broken:
+ def transcribe(self, audio, **options):
+ raise RuntimeError("audio limit is 30 s")
+
+ transcribe(Broken(), "long.wav", {"language": None, "keywords": [], "timestamps": False})
+ assert capsys.readouterr().out == " audio limit is 30 s\n"
+
+
+def test_playground_keeps_the_language_when_the_code_is_not_one_of_ours(monkeypatch, capsys):
+ from needle.whistle import playground
+
+ lines = iter(["/language de", "/language EN", "/language", "/quit"])
+ monkeypatch.setattr(playground, "prompt", lambda: next(lines))
+ monkeypatch.setattr("needle.whistle.Whistle", lambda weights=None: _Whistle({}))
+ playground.main(type("Args", (), {"audio": None, "language": None, "keywords": "",
+ "word_timestamps": False, "weights": None})())
+ out = capsys.readouterr().out
+ assert "language de" in out and "language is one of en de fr es it nl pl" in out and "language detected" in out
+
+
+def test_compare_runs_a_file_the_same_way_the_playground_does(monkeypatch, capsys):
+ pytest.importorskip("numpy")
+ from needle.whistle import compare as whistle_compare
+
+ seen, read = [], []
+ monkeypatch.setattr(whistle_compare, "compare", lambda models, audio: seen.append(len(audio)))
+ monkeypatch.setattr("needle.whistle._read_wav", lambda path: read.append(path) or [0.0] * 16000)
+ lines = iter(['/file "my clips/a b.wav"', "/quit"])
+ monkeypatch.setattr(whistle_compare, "prompt", lambda: next(lines))
+ monkeypatch.setattr(whistle_compare, "load_whistle", lambda weights: (17e6, lambda audio: ("", None, None)))
+ monkeypatch.setattr(whistle_compare, "load_whisper", lambda size: (76e6, lambda audio: ("", None, None)))
+ monkeypatch.setattr(whistle_compare, "load_moonshine", lambda: (45e6, lambda audio: ("", None, None)))
+ whistle_compare.main(type("Args", (), {"audio": None, "weights": None})())
+ assert read == ["my clips/a b.wav"] and seen == [16000]
+
+
+def test_compare_needs_its_extra(monkeypatch):
+ from needle.whistle import compare as whistle_compare
+
+ monkeypatch.setitem(sys.modules, "whisper", None)
+ with pytest.raises(SystemExit, match=r"cactus-needle\[whistle,whistle-compare\]"):
+ whistle_compare.main(type("Args", (), {"audio": None, "weights": None})())
+
+
+def test_cli_routes_the_whistle_commands(monkeypatch):
+ import needle._telemetry
+ import needle.cli
+ import needle.whistle.playground
+ import needle.whistle.compare
+
+ seen = []
+ monkeypatch.setattr(needle._telemetry, "track", lambda *a, **k: None)
+ monkeypatch.setattr(needle.whistle.playground, "main", lambda args: seen.append(("playground", args)))
+ monkeypatch.setattr(needle.whistle.compare, "main", lambda args: seen.append(("compare", args)))
+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "playground", "clip.wav", "--language", "de", "--keywords", "Siobhan, Krzysztof", "--word-timestamps"])
+ needle.cli.main()
+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "compare", "--weights", "w.cact"])
+ needle.cli.main()
+ assert [s[0] for s in seen] == ["playground", "compare"]
+ assert (seen[0][1].audio, seen[0][1].language, seen[0][1].keywords, seen[0][1].word_timestamps) == ("clip.wav", "de", "Siobhan, Krzysztof", True)
+ assert (seen[1][1].audio, seen[1][1].weights) == (None, "w.cact")
+ monkeypatch.setattr(sys, "argv", ["needle", "whistle"])
+ with pytest.raises(SystemExit, match="needle whistle playground \\| compare \\| fetch \\| download"):
+ needle.cli.main()
+
+
+def test_needle3_whistle_resolves_inside_the_needle3_repo(tmp_path, monkeypatch):
+ """The combined engine shares needle3's repo, so every path it fetches is prefixed."""
+ import zipfile
+ import needle
+ from needle.agent import fetch
+
+ audio = fetch.NEEDLE3_WHISTLE
+ assert fetch.engine_repo(audio) == fetch.engine_repo(3)
+ assert fetch.engine_version(audio) == "3.0.0"
+ assert fetch.lib_name(audio) == fetch.lib_name(3).replace("needle", audio)
+ assert fetch.engine_wheel("3.0.0", "win_arm64", audio).startswith(audio + "/python/")
+ assert fetch.engine_wheel("3.0.3", "win_arm64", 3).startswith("python/")
+
+ monkeypatch.setattr(os.path, "expanduser", lambda path: str(tmp_path))
+ monkeypatch.setattr(needle, "__file__", str(tmp_path / "package" / "__init__.py"))
+ monkeypatch.setattr(fetch, "_register_download", lambda generation: None)
+ monkeypatch.setenv(fetch.lib_path_env(audio), "/opt/libneedle3_whistle.so")
+ assert needle._library_path(audio) == "/opt/libneedle3_whistle.so"
+ monkeypatch.delenv(fetch.lib_path_env(audio))
+
+ wheel, fetched = tmp_path / "engine.whl", []
+ with zipfile.ZipFile(wheel, "w") as archive:
+ archive.writestr("needle/" + fetch.lib_name(audio), b"engine")
+ monkeypatch.setattr("huggingface_hub.hf_hub_download",
+ lambda **kwargs: fetched.append(kwargs["filename"]) or str(wheel))
+ resolved = needle._library_path(audio)
+ assert resolved == str(tmp_path / ".cache" / "cactus-needle" / audio / "3.0.0" / fetch.lib_name(audio))
+ assert fetched == [fetch.engine_wheel("3.0.0", fetch._platform_tag(), audio)]