wfloat 2.0.0__py3-none-win_amd64.whl

wfloat/_stt_assets.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Optional
+from urllib.parse import urlparse
+
+from ._assets import SttModelAssets
+from ._download import download_file, verify_checksum
+
+
+@dataclass(frozen=True)
+class CachedSttAssets:
+    model_name: str
+    family: str
+    cache_dir: Path
+    files: Mapping[str, Path]
+
+    def require(self, key: str) -> Path:
+        path = self.files.get(key)
+        if path is None:
+            raise ValueError(f"Missing required STT asset: {key}")
+        return path
+
+
+def _normalize_model_dir_name(model_name: str) -> str:
+    return model_name.replace("/", "--").replace(" ", "-")
+
+
+def _is_url(value: str) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in {"http", "https", "file"}
+
+
+def _copy_local_file(source: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(str(source), str(destination))
+
+
+def _materialize_asset(
+    source: str | Path,
+    destination: Path,
+    *,
+    expected_checksum: Optional[str],
+    force_download: bool,
+) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    if not force_download and destination.is_file():
+        if expected_checksum is None or verify_checksum(destination, expected_checksum):
+            return destination
+
+    if isinstance(source, Path):
+        _copy_local_file(source, destination)
+    else:
+        source_str = str(source)
+        if _is_url(source_str):
+            download_file(source_str, destination, expected_checksum=expected_checksum)
+        else:
+            _copy_local_file(Path(source_str), destination)
+
+    if expected_checksum is not None and not verify_checksum(destination, expected_checksum):
+        raise RuntimeError(f"Cached STT asset checksum mismatch for {destination}.")
+
+    return destination
+
+
+def cache_stt_assets(
+    model_name: str,
+    *,
+    family: str,
+    sources: Mapping[str, str | Path | None],
+    checksums: Optional[Mapping[str, str]] = None,
+    cache_dir: Path,
+    force_download: bool = False,
+) -> CachedSttAssets:
+    model_dir = cache_dir / "models" / _normalize_model_dir_name(model_name)
+    model_dir.mkdir(parents=True, exist_ok=True)
+    checksums = checksums or {}
+
+    files: dict[str, Path] = {}
+    for key, source in sources.items():
+        if source is None:
+            continue
+
+        source_value = Path(source) if isinstance(source, Path) else str(source)
+        filename = Path(urlparse(str(source_value)).path).name or Path(str(source_value)).name
+        if not filename:
+            raise ValueError(f"Could not derive filename for STT asset {key}.")
+
+        destination = model_dir / filename
+        files[key] = _materialize_asset(
+            source_value,
+            destination,
+            expected_checksum=checksums.get(key),
+            force_download=force_download,
+        )
+
+    return CachedSttAssets(
+        model_name=model_name,
+        family=family,
+        cache_dir=cache_dir,
+        files=files,
+    )
+
+
+def cache_stt_model_assets(
+    model_name: str,
+    assets: SttModelAssets,
+    *,
+    cache_dir: Path,
+    force_download: bool = False,
+) -> CachedSttAssets:
+    return cache_stt_assets(
+        model_name,
+        family=assets.family,
+        sources={
+            "model": assets.model,
+            "tokens": assets.tokens,
+            "preprocessor": assets.preprocessor,
+            "encoder": assets.encoder,
+            "decoder": assets.decoder,
+            "joiner": assets.joiner,
+            "uncached_decoder": assets.uncached_decoder,
+            "cached_decoder": assets.cached_decoder,
+        },
+        checksums={
+            key: value
+            for key, value in {
+                "model": assets.model_checksum,
+                "tokens": assets.tokens_checksum,
+                "preprocessor": assets.preprocessor_checksum,
+                "encoder": assets.encoder_checksum,
+                "decoder": assets.decoder_checksum,
+                "joiner": assets.joiner_checksum,
+                "uncached_decoder": assets.uncached_decoder_checksum,
+                "cached_decoder": assets.cached_decoder_checksum,
+            }.items()
+            if value is not None
+        },
+        cache_dir=cache_dir,
+        force_download=force_download,
+    )

wfloat/_stt_load.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ._assets import fetch_stt_assets
+from ._cache import get_default_cache_dir
+from ._core import create_core_stt
+from ._stt import SttModel
+from ._stt_assets import cache_stt_model_assets
+
+
+def load_stt_model(
+    model_name: str,
+    *,
+    cache_dir: Optional[Path] = None,
+    force_download: bool = False,
+    language: Optional[str] = None,
+    task: Optional[str] = None,
+    enable_token_timestamps: bool = False,
+    enable_segment_timestamps: bool = False,
+) -> SttModel:
+    resolved_cache_dir = Path(cache_dir) if cache_dir is not None else get_default_cache_dir()
+    assets = fetch_stt_assets(model_name)
+    cached = cache_stt_model_assets(
+        model_name,
+        assets,
+        cache_dir=resolved_cache_dir,
+        force_download=force_download,
+    )
+    family = assets.family
+
+    native_stt = create_core_stt(
+        model_name=model_name,
+        family=family,
+        model_path=cached.files.get("model"),
+        tokens_path=cached.require("tokens"),
+        preprocessor_path=cached.files.get("preprocessor"),
+        encoder_path=cached.files.get("encoder"),
+        decoder_path=cached.files.get("decoder"),
+        joiner_path=cached.files.get("joiner"),
+        uncached_decoder_path=cached.files.get("uncached_decoder"),
+        cached_decoder_path=cached.files.get("cached_decoder"),
+        language=language,
+        task=task,
+        enable_token_timestamps=enable_token_timestamps,
+        enable_segment_timestamps=enable_segment_timestamps,
+    )
+    return SttModel(model_id=model_name, _native_stt=native_stt)
+
+
+def load_whisper_tiny_en(
+    *,
+    cache_dir: Optional[Path] = None,
+    force_download: bool = False,
+) -> SttModel:
+    return load_stt_model(
+        "openai/whisper-tiny-en",
+        cache_dir=cache_dir,
+        force_download=force_download,
+        language="en",
+        task="transcribe",
+    )
+
+
+def load_moonshine_tiny_en(
+    *,
+    cache_dir: Optional[Path] = None,
+    force_download: bool = False,
+) -> SttModel:
+    return load_stt_model(
+        "UsefulSensors/moonshine-tiny",
+        cache_dir=cache_dir,
+        force_download=force_download,
+    )

wfloat/_vad.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import math
+import wave
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Sequence
+
+from ._results import Audio, VadDetectionResult, VadSegment
+
+DEFAULT_VAD_SAMPLE_RATE = 16000
+
+
+def _coerce_audio_samples(audio: bytes | Sequence[float]) -> list[float]:
+    if isinstance(audio, (bytes, bytearray, memoryview)):
+        raise TypeError(
+            "Raw PCM bytes are not supported yet. Pass a float sequence or a WAV path."
+        )
+
+    samples = [float(sample) for sample in audio]
+    if any(not math.isfinite(sample) for sample in samples):
+        raise ValueError("audio samples must be finite numbers.")
+    return samples
+
+
+def _load_wav_audio(path: Path) -> tuple[list[float], int]:
+    with wave.open(str(path), "rb") as wav_file:
+        channels = wav_file.getnchannels()
+        sample_width = wav_file.getsampwidth()
+        sample_rate = wav_file.getframerate()
+        frame_count = wav_file.getnframes()
+
+        if channels != 1:
+            raise ValueError("Only mono WAV files are supported.")
+        if sample_width != 2:
+            raise ValueError("Only 16-bit PCM WAV files are supported.")
+
+        frames = wav_file.readframes(frame_count)
+
+    samples: list[float] = []
+    for index in range(0, len(frames), 2):
+        sample = int.from_bytes(frames[index : index + 2], "little", signed=True)
+        samples.append(float(sample) / 32768.0)
+
+    return samples, sample_rate
+
+
+@dataclass
+class VadModel:
+    model_id: str
+    family: str
+    _native_vad: object
+    sample_rate: int = DEFAULT_VAD_SAMPLE_RATE
+
+    @property
+    def window_size(self) -> int:
+        return 256 if self.family.lower().replace("_", "-") in {"ten-vad", "tenvad"} else 512
+
+    def detect(
+        self,
+        *,
+        audio: bytes | Sequence[float] | str | Path,
+        sample_rate: Optional[int] = None,
+    ) -> VadDetectionResult:
+        if isinstance(audio, (str, Path)):
+            samples, resolved_sample_rate = _load_wav_audio(Path(audio))
+        else:
+            if sample_rate is None or sample_rate <= 0:
+                raise ValueError("sample_rate is required for in-memory audio.")
+            samples = _coerce_audio_samples(audio)
+            resolved_sample_rate = int(sample_rate)
+
+        if resolved_sample_rate != self.sample_rate:
+            raise ValueError(
+                f"VAD expects {self.sample_rate} Hz mono audio; got {resolved_sample_rate} Hz."
+            )
+
+        if not hasattr(self._native_vad, "accept_waveform"):
+            raise RuntimeError("Native VAD backend does not support accept_waveform().")
+
+        self._native_vad.reset()
+        window_size = self.window_size
+        for offset in range(0, len(samples), window_size):
+            self._native_vad.accept_waveform(samples[offset : offset + window_size])
+        self._native_vad.flush()
+
+        segments: list[VadSegment] = []
+        speech_sample_count = 0
+        while not self._native_vad.empty():
+            native_segment = self._native_vad.front
+            segment_samples = [float(sample) for sample in native_segment.samples]
+            start_sample = int(native_segment.start)
+            sample_count = len(segment_samples)
+            speech_sample_count += sample_count
+            duration_sec = sample_count / float(self.sample_rate)
+            start_sec = start_sample / float(self.sample_rate)
+            segments.append(
+                VadSegment(
+                    start_sec=start_sec,
+                    duration_sec=duration_sec,
+                    end_sec=start_sec + duration_sec,
+                    start_sample=start_sample,
+                    sample_count=sample_count,
+                    sample_rate=self.sample_rate,
+                    audio=Audio(samples=segment_samples, sample_rate=self.sample_rate),
+                )
+            )
+            self._native_vad.pop()
+
+        speech_ratio = (
+            min(max(speech_sample_count / float(len(samples)), 0.0), 1.0)
+            if samples
+            else 0.0
+        )
+        return VadDetectionResult(
+            model_id=self.model_id,
+            segments=segments,
+            speech_ratio=speech_ratio,
+        )

wfloat/_vad_assets.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Optional
+from urllib.parse import urlparse
+
+from ._assets import VadModelAssets
+from ._download import download_file, verify_checksum
+
+
+@dataclass(frozen=True)
+class CachedVadAssets:
+    model_name: str
+    family: str
+    cache_dir: Path
+    files: Mapping[str, Path]
+
+    def require(self, key: str) -> Path:
+        path = self.files.get(key)
+        if path is None:
+            raise ValueError(f"Missing required VAD asset: {key}")
+        return path
+
+
+def _normalize_model_dir_name(model_name: str) -> str:
+    return model_name.replace("/", "--").replace(" ", "-")
+
+
+def _is_url(value: str) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in {"http", "https", "file"}
+
+
+def _copy_local_file(source: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(str(source), str(destination))
+
+
+def _materialize_asset(
+    source: str | Path,
+    destination: Path,
+    *,
+    expected_checksum: Optional[str],
+    force_download: bool,
+) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    if not force_download and destination.is_file():
+        if expected_checksum is None or verify_checksum(destination, expected_checksum):
+            return destination
+
+    if isinstance(source, Path):
+        _copy_local_file(source, destination)
+    else:
+        source_str = str(source)
+        if _is_url(source_str):
+            download_file(source_str, destination, expected_checksum=expected_checksum)
+        else:
+            _copy_local_file(Path(source_str), destination)
+
+    if expected_checksum is not None and not verify_checksum(destination, expected_checksum):
+        raise RuntimeError(f"Cached VAD asset checksum mismatch for {destination}.")
+
+    return destination
+
+
+def cache_vad_assets(
+    model_name: str,
+    *,
+    family: str,
+    sources: Mapping[str, str | Path | None],
+    checksums: Optional[Mapping[str, str]] = None,
+    cache_dir: Path,
+    force_download: bool = False,
+) -> CachedVadAssets:
+    model_dir = cache_dir / "models" / _normalize_model_dir_name(model_name)
+    model_dir.mkdir(parents=True, exist_ok=True)
+    checksums = checksums or {}
+
+    files: dict[str, Path] = {}
+    for key, source in sources.items():
+        if source is None:
+            continue
+
+        source_value = Path(source) if isinstance(source, Path) else str(source)
+        filename = Path(urlparse(str(source_value)).path).name or Path(str(source_value)).name
+        if not filename:
+            raise ValueError(f"Could not derive filename for VAD asset {key}.")
+
+        destination = model_dir / filename
+        files[key] = _materialize_asset(
+            source_value,
+            destination,
+            expected_checksum=checksums.get(key),
+            force_download=force_download,
+        )
+
+    return CachedVadAssets(
+        model_name=model_name,
+        family=family,
+        cache_dir=cache_dir,
+        files=files,
+    )
+
+
+def cache_vad_model_assets(
+    model_name: str,
+    assets: VadModelAssets,
+    *,
+    cache_dir: Path,
+    force_download: bool = False,
+) -> CachedVadAssets:
+    return cache_vad_assets(
+        model_name,
+        family=assets.family,
+        sources={
+            "model": assets.model,
+        },
+        checksums={
+            key: value
+            for key, value in {
+                "model": assets.model_checksum,
+            }.items()
+            if value is not None
+        },
+        cache_dir=cache_dir,
+        force_download=force_download,
+    )

wfloat/_vad_load.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ._assets import fetch_vad_assets
+from ._cache import get_default_cache_dir
+from ._core import create_core_vad
+from ._vad import DEFAULT_VAD_SAMPLE_RATE, VadModel
+from ._vad_assets import cache_vad_model_assets
+
+DEFAULT_VAD_THRESHOLD = 0.5
+DEFAULT_VAD_MIN_SILENCE_DURATION_SEC = 0.5
+DEFAULT_VAD_MIN_SPEECH_DURATION_SEC = 0.25
+DEFAULT_VAD_MAX_SPEECH_DURATION_SEC = 20.0
+DEFAULT_VAD_BUFFER_SIZE_IN_SECONDS = 30.0
+
+
+def _finite_float_or_default(value: Optional[float], default: float) -> float:
+    if value is None:
+        return default
+    resolved = float(value)
+    if not resolved == resolved or resolved in {float("inf"), float("-inf")}:
+        raise ValueError("VAD timing and threshold options must be finite numbers.")
+    return resolved
+
+
+def load_vad_model(
+    model_name: str,
+    *,
+    cache_dir: Optional[Path] = None,
+    force_download: bool = False,
+    threshold: Optional[float] = None,
+    min_silence_duration_sec: Optional[float] = None,
+    min_speech_duration_sec: Optional[float] = None,
+    max_speech_duration_sec: Optional[float] = None,
+    buffer_size_in_seconds: Optional[float] = None,
+) -> VadModel:
+    resolved_cache_dir = Path(cache_dir) if cache_dir is not None else get_default_cache_dir()
+    assets = fetch_vad_assets(model_name)
+    cached = cache_vad_model_assets(
+        model_name,
+        assets,
+        cache_dir=resolved_cache_dir,
+        force_download=force_download,
+    )
+    family = assets.family
+
+    native_vad = create_core_vad(
+        model_name=model_name,
+        family=family,
+        model_path=cached.require("model"),
+        threshold=_finite_float_or_default(threshold, DEFAULT_VAD_THRESHOLD),
+        min_silence_duration_sec=_finite_float_or_default(
+            min_silence_duration_sec,
+            DEFAULT_VAD_MIN_SILENCE_DURATION_SEC,
+        ),
+        min_speech_duration_sec=_finite_float_or_default(
+            min_speech_duration_sec,
+            DEFAULT_VAD_MIN_SPEECH_DURATION_SEC,
+        ),
+        max_speech_duration_sec=_finite_float_or_default(
+            max_speech_duration_sec,
+            DEFAULT_VAD_MAX_SPEECH_DURATION_SEC,
+        ),
+        sample_rate=DEFAULT_VAD_SAMPLE_RATE,
+        buffer_size_in_seconds=_finite_float_or_default(
+            buffer_size_in_seconds,
+            DEFAULT_VAD_BUFFER_SIZE_IN_SECONDS,
+        ),
+    )
+    return VadModel(
+        model_id=model_name,
+        family=family,
+        _native_vad=native_vad,
+        sample_rate=DEFAULT_VAD_SAMPLE_RATE,
+    )
+
+
+def load_silero_vad(
+    *,
+    cache_dir: Optional[Path] = None,
+    force_download: bool = False,
+    threshold: Optional[float] = None,
+    min_silence_duration_sec: Optional[float] = None,
+    min_speech_duration_sec: Optional[float] = None,
+    max_speech_duration_sec: Optional[float] = None,
+) -> VadModel:
+    return load_vad_model(
+        "snakers4/silero-vad",
+        cache_dir=cache_dir,
+        force_download=force_download,
+        threshold=threshold,
+        min_silence_duration_sec=min_silence_duration_sec,
+        min_speech_duration_sec=min_speech_duration_sec,
+        max_speech_duration_sec=max_speech_duration_sec,
+    )

wfloat/_version.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"