naptrap 0.1.0__py3-none-any.whl

naptrap/__init__.py

@@ -0,0 +1,15 @@
+"""naptrap: local, text-defined wake word and keyword detection."""
+
+from .artifacts import ArtifactError
+from .audio import load_wav
+from .google import GoogleSpeechEmbedding
+from .models import PhonMatchNet
+from .registry import available_models, load_model, register_model
+from .text import G2PTextEncoder, normalize_keyword
+from .types import Keyword, KeywordModel, Prediction
+
+__version__ = "0.1.0"
+__all__ = [
+    "ArtifactError", "G2PTextEncoder", "GoogleSpeechEmbedding", "Keyword", "KeywordModel", "PhonMatchNet",
+    "Prediction", "available_models", "load_model", "load_wav", "normalize_keyword", "register_model",
+]

naptrap/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

naptrap/artifacts.py

@@ -0,0 +1,49 @@
+"""Load and verify a model artifact directory: ``config.json`` + ``model.safetensors``."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, Tuple
+
+import torch
+
+WEIGHTS = "model.safetensors"
+
+
+class ArtifactError(ValueError):
+    """A model artifact is missing, has the wrong format or fails its checksum."""
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def read_config(directory: str | Path, expected_format: str) -> Tuple[Path, Dict[str, Any]]:
+    root = Path(directory).expanduser().resolve()
+    try:
+        config = json.loads((root / "config.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ArtifactError(f"Cannot read config.json in {root}") from error
+    if not isinstance(config, dict) or config.get("format") != expected_format:
+        raise ArtifactError(f"{root} is not a {expected_format} artifact")
+    return root, config
+
+
+def load_artifact(directory: str | Path, expected_format: str) -> Tuple[Dict[str, Any], Dict[str, torch.Tensor]]:
+    """Return ``(config, state_dict)`` after checking format and weight checksum."""
+    from safetensors.torch import load_file
+
+    root, config = read_config(directory, expected_format)
+    path = root / WEIGHTS
+    if not path.is_file():
+        raise ArtifactError(f"Missing {WEIGHTS} in {root}")
+    expected = config.get("sha256", {}).get(WEIGHTS)
+    if not isinstance(expected, str) or sha256(path) != expected:
+        raise ArtifactError(f"{WEIGHTS} checksum mismatch in {root}")
+    return config, load_file(str(path), device="cpu")

naptrap/audio.py

@@ -0,0 +1,24 @@
+"""Minimal WAV reading without NumPy or audio libraries."""
+
+from __future__ import annotations
+
+import array
+import sys
+import wave
+from pathlib import Path
+
+import torch
+
+from .features import SAMPLE_RATE
+
+
+def load_wav(path: str | Path) -> torch.Tensor:
+    """Read a mono 16 kHz 16-bit PCM WAV file as float32 samples in [-1, 1)."""
+    with wave.open(str(Path(path).expanduser()), "rb") as stream:
+        if stream.getnchannels() != 1 or stream.getsampwidth() != 2 or stream.getframerate() != SAMPLE_RATE:
+            raise ValueError("Expected a mono, 16-bit PCM, 16 kHz WAV file; convert it first, "
+                             "e.g. ffmpeg -i in.wav -ac 1 -ar 16000 -sample_fmt s16 out.wav")
+        samples = array.array("h", stream.readframes(stream.getnframes()))
+    if sys.byteorder == "big":
+        samples.byteswap()
+    return torch.tensor(samples, dtype=torch.float32) / 32768

naptrap/cli.py

@@ -0,0 +1,35 @@
+"""Command-line interface: ``naptrap detect AUDIO.wav "keyword"``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .audio import load_wav
+from .registry import available_models, load_model
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="naptrap", description="Text-defined keyword detection for short clips.")
+    parser.add_argument("--version", action="version", version=f"naptrap {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    detect = commands.add_parser("detect", help="score one 0.5-2 s mono 16 kHz 16-bit WAV clip against a keyword")
+    detect.add_argument("audio", type=Path)
+    detect.add_argument("keyword")
+    detect.add_argument("--model", choices=available_models(), default="phonmatchnet")
+    detect.add_argument("--far", type=float, default=0.01, help="calibrated operating point (default 0.01)")
+    detect.add_argument("--model-dir", type=Path, help="local model directory (default: download)")
+    detect.add_argument("--google-dir", type=Path, help="local Google speech embedding directory")
+    detect.add_argument("--g2p-dir", type=Path, help="local G2P decoder directory")
+    args = parser.parse_args(argv)
+    try:
+        model = load_model(args.model, model_dir=args.model_dir, google_dir=args.google_dir, g2p_dir=args.g2p_dir)
+        result = model.detect(load_wav(args.audio), args.keyword, far=args.far)
+    except (ImportError, OSError, ValueError, RuntimeError) as error:
+        parser.exit(2, f"naptrap: {error}\n")
+    json.dump(result.to_dict(), sys.stdout, indent=2)
+    print()
+    return 0 if result.accepted else 1

naptrap/features.py

@@ -0,0 +1,69 @@
+"""Input validation and the 40-bin log-mel frontend used by PhonMatchNet."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+from torch import nn
+
+SAMPLE_RATE = 16000
+MIN_SAMPLES = SAMPLE_RATE // 2
+MAX_SAMPLES = SAMPLE_RATE * 2
+
+
+def feature_tensor(value: Any, name: str, width: int, minimum: int, maximum: int) -> torch.Tensor:
+    """Accept ``[time, width]`` or ``[1, time, width]`` float32 and return ``[1, time, width]`` on CPU."""
+    try:
+        tensor = torch.as_tensor(value)
+    except (TypeError, ValueError, RuntimeError) as error:
+        raise ValueError(f"{name} must be a float32 feature array") from error
+    if tensor.dtype != torch.float32:
+        raise ValueError(f"{name} must have dtype float32")
+    if tensor.ndim == 2:
+        tensor = tensor.unsqueeze(0)
+    if tensor.ndim != 3 or tensor.shape[0] != 1 or tensor.shape[2] != width:
+        raise ValueError(f"{name} must have shape [time,{width}] or [1,time,{width}]")
+    if not minimum <= tensor.shape[1] <= maximum:
+        raise ValueError(f"{name} time length must be between {minimum} and {maximum}")
+    tensor = tensor.detach().to(device="cpu").contiguous()
+    if not torch.isfinite(tensor).all():
+        raise ValueError(f"{name} must contain finite values")
+    return tensor
+
+
+def waveform_tensor(value: Any, sample_rate: int) -> torch.Tensor:
+    """Validate one mono 16 kHz clip of 0.5-2 s, float32 scaled into [-1, 1]."""
+    if sample_rate != SAMPLE_RATE:
+        raise ValueError("Audio must be mono 16 kHz; resample before inference")
+    try:
+        wave = torch.as_tensor(value)
+    except (TypeError, ValueError, RuntimeError) as error:
+        raise ValueError("waveform must be a float32 array") from error
+    if wave.dtype != torch.float32 or wave.ndim != 1:
+        raise ValueError("waveform must be a one-dimensional float32 array scaled into [-1, 1]")
+    if not MIN_SAMPLES <= wave.numel() <= MAX_SAMPLES:
+        raise ValueError("Clip duration must be 0.5-2 seconds (8,000-32,000 samples at 16 kHz)")
+    wave = wave.detach().to(device="cpu").contiguous()
+    if not torch.isfinite(wave).all() or wave.abs().max() > 1:
+        raise ValueError("waveform must contain finite samples in [-1, 1]")
+    return wave
+
+
+class KeywordMel(nn.Module):
+    """Log10 power mel spectrogram: 400-sample window, 160 hop, 512 FFT, 40 bins.
+
+    The mel matrix and window are stored with the trained weights.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.register_buffer("mel_matrix", torch.zeros(257, 40))
+        self.register_buffer("window", torch.zeros(400))
+
+    @torch.inference_mode()
+    def forward(self, wave: torch.Tensor) -> torch.Tensor:
+        spectrum = torch.stft(wave, n_fft=512, hop_length=160, win_length=400,
+                              window=self.window, center=True, pad_mode="reflect", return_complex=True)
+        features = torch.log10(spectrum.abs().square().transpose(0, 1) @ self.mel_matrix + 1e-7)
+        return features[:(wave.numel() + 159) // 160].unsqueeze(0)

naptrap/google.py

@@ -0,0 +1,96 @@
+"""PyTorch port of Google's speech_embedding/1 (Apache-2.0) feature extractor.
+
+The converted weights, mel matrix and window come from the original TensorFlow
+model unchanged; this module never imports TensorFlow or NumPy.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+from .artifacts import ArtifactError, load_artifact
+from .features import SAMPLE_RATE, waveform_tensor
+
+FORMAT = "naptrap-google-speech-embedding-v1"
+PARENT_SHA256 = "0f626c42009c1eb916401b7b2800229a211e43100115bc591b9afbf1b60da27f"
+
+
+class GoogleSpeechEmbedding(nn.Module):
+    """16 kHz clip -> ``[floor(samples / 1280), 96]`` speech embeddings.
+
+    The clip is left-padded with 11,120 zeros and not trimmed, matching how the
+    keyword models were trained.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.register_buffer("window", torch.zeros(400))
+        self.register_buffer("mel_matrix", torch.zeros(257, 32))
+        self.initial = nn.Conv2d(1, 24, (3, 3), padding=(0, 1), bias=False)
+        self.norms = nn.ModuleList([nn.BatchNorm2d(24, eps=.001)])
+        self.convs = nn.ModuleList()
+        channels = 24
+        for index in range(18):
+            target = {2: 48, 6: 72, 10: 96}.get(index, channels)
+            frequency = index % 2 == 0
+            self.convs.append(nn.Conv2d(channels, target, (1, 3) if frequency else (3, 1),
+                                        padding=(0, 1) if frequency else 0, bias=False))
+            self.norms.append(nn.BatchNorm2d(target, eps=.001))
+            channels = target
+        self.output = nn.Conv2d(96, 96, (3, 1), bias=False)
+        self._loaded = False
+        self.requires_grad_(False)
+        self.eval()
+
+    def train(self, mode=True):
+        # A frozen pretrained feature extractor; BatchNorm stays in inference mode.
+        return super().train(False)
+
+    @classmethod
+    def from_pretrained(cls, directory: str | Path) -> "GoogleSpeechEmbedding":
+        config, state = load_artifact(directory, FORMAT)
+        if config.get("source", {}).get("archive_sha256") != PARENT_SHA256:
+            raise ArtifactError("Google speech embedding was converted from an unexpected source archive")
+        model = cls()
+        model.load_state_dict(state, strict=True)
+        model._loaded = True
+        return model.eval()
+
+    @staticmethod
+    def activation(value):
+        # Original graph: max(max(0.2*x,x),-0.4), after inference BatchNorm.
+        return F.leaky_relu(value, negative_slope=.2).clamp(min=-.4)
+
+    def log_mel(self, waveform):
+        padded = F.pad(waveform, (11120, 0))
+        # TensorFlow STFT windows start at frame zero: no centered FFT window.
+        frames = padded.unfold(0, 400, 160) * self.window
+        magnitude = torch.fft.rfft(frames, n=512, dim=-1).abs()
+        return torch.log(magnitude @ self.mel_matrix + .001)
+
+    def encode_log_mel(self, features):
+        value = features.unsqueeze(0).unsqueeze(0)
+        value = self.activation(self.norms[0](F.relu(self.initial(value))))
+        for index, conv in enumerate(self.convs):
+            value = self.activation(self.norms[index + 1](conv(value)))
+            if index in (1, 9, 17):
+                value = F.max_pool2d(value, kernel_size=(2, 2), stride=(2, 2))
+            elif index in (5, 13):
+                # The fixed 32-bin input gives even frequency widths here, so the
+                # original SAME pooling at index 5 adds no padding.
+                value = F.max_pool2d(value, kernel_size=(1, 2), stride=(1, 2))
+        return self.output(value)[0, :, :, 0].transpose(0, 1)
+
+    @torch.inference_mode()
+    def forward(self, waveform, sample_rate=SAMPLE_RATE):
+        if not self._loaded:
+            raise RuntimeError("Load pretrained weights with GoogleSpeechEmbedding.from_pretrained()")
+        wave = waveform_tensor(waveform, sample_rate).to(self.window.device)
+        result = self.encode_log_mel(self.log_mel(wave))
+        if result.shape != (wave.numel() // 1280, 96) or not torch.isfinite(result).all():
+            raise RuntimeError("Google speech embedding produced an invalid output")
+        return result

naptrap/hub.py

@@ -0,0 +1,21 @@
+"""Optional Hugging Face Hub downloads (``pip install 'naptrap[hub]'``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_REVISION = "v1"
+_FILES = ["config.json", "model.safetensors", "README.md", "LICENSE", "NOTICE"]
+
+
+def download(repo_id: str, revision: str = DEFAULT_REVISION, cache_dir: Optional[str] = None) -> Path:
+    """Download one model repository's inference files and return its local directory."""
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError as error:
+        raise ImportError(
+            "Downloading models requires huggingface_hub: pip install 'naptrap[hub]'. "
+            "Alternatively, download the model directories yourself and pass their paths."
+        ) from error
+    return Path(snapshot_download(repo_id, revision=revision, cache_dir=cache_dir, allow_patterns=_FILES))

naptrap/models/__init__.py

@@ -0,0 +1,5 @@
+"""Naptrap model implementations."""
+
+from .phonmatchnet import PhonMatchNet
+
+__all__ = ["PhonMatchNet"]

naptrap/models/network.py

@@ -0,0 +1,61 @@
+"""PhonMatchNet network for single-clip inference.
+
+Architecture after PhonMatchNet (Lee et al., Interspeech 2023) and NCSOFT's
+BSD-3-Clause PyTorch implementation; see licenses/PhonMatchNet-BSD-3-Clause.txt.
+Tensors hold one unpadded clip, so time axes are the valid lengths.
+"""
+
+import math
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+from ..features import KeywordMel
+
+
+class _Norm(nn.Module):
+    def __init__(self):
+        super().__init__()
+        # Nested name kept so weight keys match the trained checkpoint.
+        self.bn = nn.BatchNorm1d(128)
+
+
+class _Audio(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.frontend = KeywordMel()
+        self.conv1 = nn.Conv1d(40, 128, 3, stride=2, padding=1)
+        self.bn1 = _Norm()
+        self.conv2 = nn.Conv1d(128, 128, 3, padding=1)
+        self.bn2 = _Norm()
+
+
+class PhonMatchNetwork(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.audio = _Audio()
+        self.google_upsample = nn.ConvTranspose1d(96, 128, 5, stride=4)
+        self.text_projection = nn.Linear(256, 128)
+        self.attention = nn.MultiheadAttention(128, 1, batch_first=True)
+        self.utterance_gru = nn.GRU(128, 128, batch_first=True)
+        self.utterance_head = nn.Linear(128, 1)
+        self.requires_grad_(False)
+        self.eval()
+
+    def train(self, mode=True):
+        return super().train(False)
+
+    def forward(self, keyword_mel, google, text):
+        value = F.relu(self.audio.bn1.bn(self.audio.conv1(keyword_mel.transpose(1, 2))))
+        value = F.relu(self.audio.bn2.bn(self.audio.conv2(value))).transpose(1, 2)
+        pretrained = F.leaky_relu(self.google_upsample(google.transpose(1, 2))).transpose(1, 2)
+        pretrained = F.pad(pretrained, (0, 0, 0, value.shape[1]))[:, :value.shape[1]]
+        textual = F.leaky_relu(self.text_projection(text))
+        joint = torch.cat([value + pretrained, textual], dim=1)
+        q, k, v = F.linear(joint, self.attention.in_proj_weight, self.attention.in_proj_bias).chunk(3, dim=-1)
+        logits = (q / math.sqrt(128.)) @ k.transpose(1, 2)
+        mask = torch.triu(torch.ones((joint.shape[1], joint.shape[1]), dtype=torch.bool, device=joint.device), diagonal=1)
+        attended = self.attention.out_proj(torch.softmax(logits.masked_fill(mask, float("-inf")), dim=-1) @ v)
+        _, hidden = self.utterance_gru(attended)
+        return self.utterance_head(hidden[-1]).squeeze(-1)

naptrap/models/phonmatchnet.py

@@ -0,0 +1,128 @@
+"""PhonMatchNet text-defined keyword detection."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any, Dict, Mapping, Optional, Union
+
+import torch
+
+from ..artifacts import WEIGHTS, ArtifactError, load_artifact, read_config, sha256
+from ..features import SAMPLE_RATE, feature_tensor, waveform_tensor
+from ..google import FORMAT as GOOGLE_FORMAT, GoogleSpeechEmbedding
+from ..hub import DEFAULT_REVISION, download
+from ..text import FORMAT as G2P_FORMAT, G2PTextEncoder, normalize_keyword
+from ..types import Keyword, Prediction
+from .network import PhonMatchNetwork
+
+FORMAT = "naptrap-phonmatchnet-v1"
+DEFAULT_REPO = "androiddrew/naptrap-phonmatchnet-en"
+PathLike = Union[str, Path]
+
+
+class PhonMatchNet:
+    """Content-only (C-KWS) detection: was this keyword spoken in the clip?
+
+    Inputs are one mono 16 kHz clip of 0.5-2 seconds and an English keyword.
+    The keyword is converted to G2P decoder features, and the audio to 40-bin
+    log-mels plus Google speech embeddings. The model has no speaker
+    enrollment: it does not check who is speaking.
+    """
+
+    name = "phonmatchnet"
+    task = "C-KWS"
+
+    def __init__(self, model_dir: PathLike, google_dir: PathLike, g2p_dir: PathLike):
+        config, state = load_artifact(model_dir, FORMAT)
+        try:
+            self._thresholds = {float(far): float(value) for far, value in config["thresholds"].items()}
+        except (KeyError, TypeError, ValueError, AttributeError) as error:
+            raise ArtifactError("config.json has no valid thresholds") from error
+        if not self._thresholds or not all(math.isfinite(v) for v in self._thresholds.values()):
+            raise ArtifactError("config.json has no valid thresholds")
+        self.config = config
+        self._check_companion("google", google_dir, GOOGLE_FORMAT)
+        self._check_companion("g2p", g2p_dir, G2P_FORMAT)
+        self._model = PhonMatchNetwork()
+        self._model.load_state_dict(state, strict=True)
+        self._frontend = self._model.audio.frontend
+        self.google_encoder = GoogleSpeechEmbedding.from_pretrained(google_dir)
+        self.text_encoder = G2PTextEncoder.from_pretrained(g2p_dir)
+
+    @classmethod
+    def from_pretrained(cls, model_dir: Optional[PathLike] = None, *, google_dir: Optional[PathLike] = None,
+                        g2p_dir: Optional[PathLike] = None, revision: Optional[str] = None,
+                        cache_dir: Optional[str] = None) -> "PhonMatchNet":
+        """Load from local directories, downloading any that are not given.
+
+        Downloads need ``pip install 'naptrap[hub]'``. ``revision`` applies to
+        the PhonMatchNet repository; companion encoders use the revisions
+        pinned in its ``config.json``.
+        """
+        if model_dir is None:
+            model_dir = download(DEFAULT_REPO, revision or DEFAULT_REVISION, cache_dir)
+        _, config = read_config(model_dir, FORMAT)
+        requires = config.get("requires", {})
+        if google_dir is None:
+            google_dir = download(requires["google"]["repo_id"], requires["google"]["revision"], cache_dir)
+        if g2p_dir is None:
+            g2p_dir = download(requires["g2p"]["repo_id"], requires["g2p"]["revision"], cache_dir)
+        return cls(model_dir, google_dir, g2p_dir)
+
+    def _check_companion(self, key: str, directory: PathLike, expected_format: str) -> None:
+        required = self.config.get("requires", {}).get(key, {})
+        root, _ = read_config(directory, expected_format)
+        if required.get("sha256") and sha256(root / WEIGHTS) != required["sha256"]:
+            raise ArtifactError(f"{root} is not the {key} encoder this model was trained with")
+
+    @property
+    def thresholds(self) -> Dict[float, float]:
+        """Available operating points: development target FAR -> score threshold."""
+        return dict(self._thresholds)
+
+    def keyword(self, text: str) -> Keyword:
+        """Precompute a keyword's text features; reuse the result across clips."""
+        return Keyword(normalize_keyword(text), self.text_encoder(text))
+
+    @torch.inference_mode()
+    def detect(self, waveform: Any, keyword: Union[str, Keyword], *, sample_rate: int = SAMPLE_RATE,
+               far: float = 0.01) -> Prediction:
+        """Score one clip against a keyword string or a :meth:`keyword` result.
+
+        ``waveform`` is a 1-D float32 tensor or array of 0.5-2 s mono 16 kHz
+        audio scaled into [-1, 1]. ``far`` selects an operating point from
+        :attr:`thresholds`.
+        """
+        if not isinstance(keyword, Keyword):
+            keyword = self.keyword(keyword)
+        wave = waveform_tensor(waveform, sample_rate)
+        features = {
+            "keyword_mel": self._frontend(wave),
+            "google": self.google_encoder(wave, sample_rate=sample_rate),
+            "text": keyword.features,
+        }
+        return self.predict(features, far=far)
+
+    @torch.inference_mode()
+    def predict(self, features: Mapping[str, Any], *, far: float = 0.01) -> Prediction:
+        """Score precomputed ``keyword_mel`` [T,40], ``google`` [G,96] and ``text`` [P,256] features."""
+        if far not in self._thresholds:
+            choices = ", ".join(str(v) for v in sorted(self._thresholds))
+            raise ValueError(f"far must be one of the calibrated operating points: {choices}")
+        missing = {"keyword_mel", "google", "text"} - set(features.keys())
+        if missing:
+            raise ValueError("Missing features: " + ", ".join(sorted(missing)))
+        mel = feature_tensor(features["keyword_mel"], "keyword_mel", 40, 50, 200)
+        google = feature_tensor(features["google"], "google", 96, 6, 25)
+        text = feature_tensor(features["text"], "text", 256, 1, 128)
+        if not 8 * google.shape[1] <= mel.shape[1] <= 8 * google.shape[1] + 8:
+            raise ValueError("keyword_mel and google features describe different clip lengths")
+        logits = self._model(mel, google, text)
+        if logits.shape != (1,) or not torch.isfinite(logits).all():
+            raise RuntimeError("Model returned an invalid keyword logit")
+        score = float(logits.sigmoid()[0])
+        threshold = self._thresholds[far]
+        return Prediction(model=self.name, task=self.task, score=score, threshold=threshold,
+                          accepted=score >= threshold, target_far=far,
+                          details={"keyword_logit": float(logits[0])})

naptrap/registry.py

@@ -0,0 +1,42 @@
+"""Model registry: maps a family name to the function that loads it."""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Tuple
+
+from .types import KeywordModel
+
+
+def _phonmatchnet(**kwargs) -> KeywordModel:
+    from .models.phonmatchnet import PhonMatchNet
+    return PhonMatchNet.from_pretrained(**kwargs)
+
+
+_FACTORIES: Dict[str, Callable[..., KeywordModel]] = {"phonmatchnet": _phonmatchnet}
+
+
+def available_models() -> Tuple[str, ...]:
+    return tuple(sorted(_FACTORIES))
+
+
+def register_model(name: str, factory: Callable[..., KeywordModel]) -> None:
+    """Register an additional model family under a new lowercase name."""
+    if not isinstance(name, str) or not name or name != name.strip().lower():
+        raise ValueError("Model names must be nonempty, lowercase and whitespace-trimmed")
+    if not callable(factory):
+        raise TypeError("A model factory must be callable")
+    if name in _FACTORIES:
+        raise ValueError("Model is already registered: " + name)
+    _FACTORIES[name] = factory
+
+
+def load_model(name: str = "phonmatchnet", **kwargs) -> KeywordModel:
+    """Load a registered model family; keyword arguments go to its loader.
+
+    For ``phonmatchnet`` see :meth:`naptrap.PhonMatchNet.from_pretrained`.
+    """
+    try:
+        factory = _FACTORIES[name]
+    except KeyError as error:
+        raise ValueError(f"Unknown model {name!r}; available: {', '.join(available_models())}") from error
+    return factory(**kwargs)

naptrap/text.py

@@ -0,0 +1,106 @@
+"""Keyword text features: a PyTorch port of the g2p_en neural decoder states.
+
+PhonMatchNet consumes the hidden states of the g2p_en grapheme-to-phoneme
+decoder (Kyubyong Park & Jongseok Kim, Apache-2.0), not phoneme strings. Each
+word is encoded with the grapheme GRU, then decoded greedily; every emitted
+decoder state becomes one 256-D feature row, and words are separated by the
+decoder's padding embedding. This mirrors ``G2p.embedding()`` from the
+PhonMatchNet repository without NumPy, NLTK or dictionary lookups.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+import torch
+from torch import nn
+
+from .artifacts import load_artifact
+
+FORMAT = "naptrap-g2p-en-decoder-v1"
+GRAPHEMES = ["<pad>", "<unk>", "</s>"] + list("abcdefghijklmnopqrstuvwxyz")
+_START, _END, _MAX_STEPS = 2, 3, 20
+_TOKENS = re.compile(r"[a-z]+(?:'[a-z]+)*|[0-9]+")
+
+
+def normalize_keyword(text: str) -> str:
+    """Lowercase, strip accents and punctuation; the policy used during training."""
+    if not isinstance(text, str):
+        raise TypeError("keyword must be a string")
+    text = unicodedata.normalize("NFKD", text.replace("’", "'"))
+    text = "".join(c for c in text if not unicodedata.combining(c)).lower()
+    words = _TOKENS.findall(text)
+    if any(word.isdigit() for word in words):
+        raise ValueError("Spell out numbers in the keyword, e.g. 'route sixty six'")
+    if not words:
+        raise ValueError("keyword contains no English letters")
+    return " ".join(words)
+
+
+class _GRUCell(nn.Module):
+    def __init__(self, size: int):
+        super().__init__()
+        self.w_ih = nn.Parameter(torch.zeros(3 * size, size))
+        self.w_hh = nn.Parameter(torch.zeros(3 * size, size))
+        self.b_ih = nn.Parameter(torch.zeros(3 * size))
+        self.b_hh = nn.Parameter(torch.zeros(3 * size))
+
+    def forward(self, x: torch.Tensor, h: torch.Tensor) -> torch.Tensor:
+        # Same gate order and arithmetic as g2p_en's NumPy grucell (r, z | n).
+        ih = x @ self.w_ih.T + self.b_ih
+        hh = h @ self.w_hh.T + self.b_hh
+        split = ih.shape[-1] * 2 // 3
+        r, z = torch.sigmoid(ih[:, :split] + hh[:, :split]).chunk(2, dim=-1)
+        n = torch.tanh(ih[:, split:] + r * hh[:, split:])
+        return (1 - z) * n + z * h
+
+
+class G2PTextEncoder(nn.Module):
+    """Keyword string -> ``[positions, 256]`` float32 decoder features."""
+
+    def __init__(self, size: int = 256, phonemes: int = 74):
+        super().__init__()
+        self.size = size
+        self.enc_emb = nn.Parameter(torch.zeros(len(GRAPHEMES), size))
+        self.encoder = _GRUCell(size)
+        self.dec_emb = nn.Parameter(torch.zeros(phonemes, size))
+        self.decoder = _GRUCell(size)
+        self.fc_w = nn.Parameter(torch.zeros(phonemes, size))
+        self.fc_b = nn.Parameter(torch.zeros(phonemes))
+        self._index = {g: i for i, g in enumerate(GRAPHEMES)}
+        self.requires_grad_(False)
+        self.eval()
+
+    @classmethod
+    def from_pretrained(cls, directory: str | Path) -> "G2PTextEncoder":
+        config, state = load_artifact(directory, FORMAT)
+        model = cls(size=int(config["hidden_size"]), phonemes=int(config["phonemes"]))
+        model.load_state_dict(state, strict=True)
+        return model
+
+    def _word(self, word: str) -> torch.Tensor:
+        unknown = self._index["<unk>"]
+        ids = [self._index.get(c, unknown) for c in word] + [self._index["</s>"]]
+        h = torch.zeros(1, self.size)
+        for index in ids:
+            h = self.encoder(self.enc_emb[index:index + 1], h)
+        token, states = _START, []
+        for _ in range(_MAX_STEPS):
+            h = self.decoder(self.dec_emb[token:token + 1], h)
+            token = int((h @ self.fc_w.T + self.fc_b).argmax())
+            if token == _END:
+                break
+            states.append(h)
+        return torch.cat(states) if states else h.new_zeros(0, self.size)
+
+    @torch.inference_mode()
+    def forward(self, keyword: str) -> torch.Tensor:
+        rows = []
+        for word in normalize_keyword(keyword).split():
+            rows += [self._word(word), self.dec_emb[0:1]]
+        features = torch.cat(rows[:-1])
+        if features.shape[0] < 1:
+            raise ValueError("keyword produced no phonetic features")
+        return features.contiguous()

naptrap/types.py

@@ -0,0 +1,61 @@
+"""Common result and model interfaces for naptrap backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Protocol
+
+import torch
+
+
+
+@dataclass(frozen=True)
+class Keyword:
+    """A keyword's normalized text and its precomputed text features."""
+
+    text: str
+    features: torch.Tensor = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class Prediction:
+    """One clip's keyword decision at a fixed operating point.
+
+    ``score`` is model specific; for PhonMatchNet it is the keyword-match
+    probability. ``target_far`` names the calibration target the threshold was
+    fitted for on development data. It is not a guaranteed false-accept rate on
+    other audio.
+    """
+
+    model: str
+    task: str
+    score: float
+    threshold: float
+    accepted: bool
+    target_far: float
+    details: Mapping[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "task": self.task,
+            "score": self.score,
+            "threshold": self.threshold,
+            "accepted": self.accepted,
+            "target_far": self.target_far,
+            "details": dict(self.details),
+        }
+
+
+class KeywordModel(Protocol):
+    """Interface every backend implements; inputs are documented per backend."""
+
+    def keyword(self, text: str) -> Keyword:
+        ...
+
+    def detect(self, waveform: Any, keyword: "str | Keyword", *, sample_rate: int = 16000,
+               far: float = 0.01) -> Prediction:
+        ...
+
+    def predict(self, features: Mapping[str, Any], *, far: float = 0.01) -> Prediction:
+        ...

naptrap-0.1.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: naptrap
+Version: 0.1.0
+Summary: Local, text-defined wake word and keyword detection in PyTorch
+Author-email: Drew Bednar <drew@runcible.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/androiddrew/naptrap
+Project-URL: Issues, https://github.com/androiddrew/naptrap/issues
+Project-URL: Models, https://huggingface.co/androiddrew/naptrap-phonmatchnet-en
+Keywords: wake word,keyword spotting,speech,phonmatchnet,pytorch,kws
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: licenses/PhonMatchNet-BSD-3-Clause.txt
+Requires-Dist: torch>=1.13
+Requires-Dist: safetensors>=0.4
+Provides-Extra: hub
+Requires-Dist: huggingface_hub>=0.20; extra == "hub"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Dynamic: license-file
+
+# naptrap
+
+**Local, text-defined wake word detection in PyTorch.** Type a keyword, give
+naptrap a short audio clip, and it tells you whether the keyword was spoken.
+New wake words need no recordings or training.
+
+```python
+from naptrap import load_model, load_wav
+
+model = load_model("phonmatchnet")             # downloads the model on first use
+result = model.detect(load_wav("clip.wav"), "hey computer")
+
+print(result.score)     # keyword-match probability, 0-1
+print(result.accepted)  # score >= the model's calibrated threshold
+```
+
+The first model is an independently trained
+[PhonMatchNet](https://huggingface.co/androiddrew/naptrap-phonmatchnet-en)
+(Lee & Cho, Interspeech 2023) for English. Inference runs on the CPU with
+**PyTorch as the only heavy dependency**. There is no TensorFlow, NumPy,
+torchaudio or NLTK, and no cloud API.
+
+## Install
+
+```bash
+pip install "naptrap[hub]"
+```
+
+Python 3.9+ and PyTorch 1.13+ are required. If you want a CPU-only or
+CUDA-specific PyTorch build, install it first; see
+[pytorch.org](https://pytorch.org/get-started/locally/). The `hub` extra adds
+`huggingface_hub` for automatic model downloads. Without it, `pip install
+naptrap` works with model directories you download yourself.
+
+## Models
+
+`load_model("phonmatchnet")` fetches three Hugging Face repositories (about
+6 MB in total), pinned to revision `v1`, and caches them locally:
+
+| Repository | Role | License |
+|---|---|---|
+| [`androiddrew/naptrap-phonmatchnet-en`](https://huggingface.co/androiddrew/naptrap-phonmatchnet-en) | keyword matcher | Apache-2.0 |
+| [`androiddrew/google-speech-embedding-pytorch`](https://huggingface.co/androiddrew/google-speech-embedding-pytorch) | frozen audio encoder | Apache-2.0 |
+| [`androiddrew/g2p-en-decoder-pytorch`](https://huggingface.co/androiddrew/g2p-en-decoder-pytorch) | frozen keyword text encoder | Apache-2.0 |
+
+To work offline, download them once and pass the directories:
+
+```bash
+hf download androiddrew/naptrap-phonmatchnet-en --revision v1 --local-dir models/phonmatchnet
+hf download androiddrew/google-speech-embedding-pytorch --revision v1 --local-dir models/google
+hf download androiddrew/g2p-en-decoder-pytorch --revision v1 --local-dir models/g2p
+```
+
+```python
+model = load_model("phonmatchnet", model_dir="models/phonmatchnet",
+                   google_dir="models/google", g2p_dir="models/g2p")
+```
+
+Every weight file is checked against the SHA-256 recorded in its `config.json`.
+The keyword model also pins the exact encoders it was trained with.
+
+## Usage
+
+### Audio
+
+`detect()` scores **one mono 16 kHz clip of 0.5–2 seconds**, given as a 1-D
+float32 tensor or array with values in [-1, 1]. `load_wav()` reads 16-bit PCM
+WAV files using only the standard library. Convert other files first:
+
+```bash
+ffmpeg -i input.m4a -ac 1 -ar 16000 -sample_fmt s16 clip.wav
+```
+
+naptrap does not resample, trim or rescale audio for you.
+
+### Reusing a keyword
+
+Converting the keyword text is cheap, but if you score many clips against the
+same keyword you can do it once:
+
+```python
+wake = model.keyword("hey computer")
+for clip in clips:
+    if model.detect(clip, wake).accepted:
+        ...
+```
+
+Keywords are English words; accents and punctuation are removed. Spell out
+numbers ("route sixty six").
+
+### Operating points and thresholds
+
+```python
+model.thresholds                                # {0.01: 0.7149..., 0.1: 0.0025...}
+model.detect(clip, "hey computer", far=0.1)     # more sensitive
+```
+
+Each threshold was fitted on held-out development speakers to target a
+per-clip false-accept rate (FAR) of 1% or 10%. **These targets do not hold on
+other audio.** On phonetically confusable phrases, the 1% threshold accepted
+31% of negatives. For a real product, record some positive and negative clips
+in your setting and choose your own threshold on `result.score`. See the
+[model card](https://huggingface.co/androiddrew/naptrap-phonmatchnet-en) for
+the evaluation.
+
+### Command line
+
+```bash
+naptrap detect clip.wav "hey computer"
+naptrap detect clip.wav "hey computer" --far 0.1 --model-dir models/phonmatchnet \
+    --google-dir models/google --g2p-dir models/g2p
+```
+
+The command prints the prediction as JSON. It exits with 0 if the keyword was
+accepted, 1 if it was rejected and 2 on error. `python -m naptrap` works the
+same way.
+
+### Precomputed features
+
+`model.predict({"keyword_mel": ..., "google": ..., "text": ...})` scores
+features you computed yourself: `[T, 40]`, `[T/8, 96]` and `[P, 256]` float32.
+The encoders are exposed as `naptrap.GoogleSpeechEmbedding` and
+`naptrap.G2PTextEncoder`.
+
+## Limitations
+
+- **Single clips, not a streaming listener (yet).** To watch a microphone you
+  must window the audio yourself, e.g. 1.5 s windows every 0.25 s, and add
+  your own debouncing.
+- **English only**, trained on read audiobook speech (LibriSpeech). Expect
+  lower accuracy with noise, far-field microphones, accents or children.
+- **No speaker verification.** Anyone saying the keyword triggers it.
+- Similar-sounding phrases are often confused.
+- CPU inference is the supported path; other devices have not been validated.
+- Not for security or safety-critical use.
+
+## Adding model families
+
+Backends implement `keyword()`, `detect()` and `predict()`, and return a
+`Prediction`. Register a loader under a new name:
+
+```python
+from naptrap import register_model, load_model
+
+register_model("my-model", MyModel.from_pretrained)
+model = load_model("my-model", model_dir="...")
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+# Also run the real-model tests against downloaded model directories:
+NAPTRAP_TEST_MODELS=path/to/models pytest
+```
+
+`NAPTRAP_TEST_MODELS` must point at a directory holding the three model
+repositories in subdirectories named `naptrap-phonmatchnet-en`,
+`google-speech-embedding-pytorch` and `g2p-en-decoder-pytorch`.
+
+## License and attribution
+
+naptrap is licensed under the [Apache License 2.0](LICENSE). The network
+follows the PhonMatchNet design and NCSOFT's BSD-3-Clause reference code (see
+[NOTICE](NOTICE) and [licenses/](licenses/)). The PhonMatchNet weights were
+trained independently. **naptrap is not affiliated with or endorsed by NCSOFT
+or the PhonMatchNet authors.** See
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for every component.
+
+If naptrap's PhonMatchNet model is useful in your research, please cite:
+
+```bibtex
+@inproceedings{lee23phonmatchnet,
+  title     = {PhonMatchNet: Phoneme-Guided Zero-Shot Keyword Spotting for User-Defined Keywords},
+  author    = {Lee, Yong-Hyeok and Cho, Namhyun},
+  booktitle = {Proc. INTERSPEECH 2023},
+  pages     = {3964--3968},
+  year      = {2023}
+}
+```

naptrap-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+naptrap/__init__.py,sha256=e9ngGAehjTutdhti-MQeGeikdp5MykvZ-RVxSiKO3kw,628
+naptrap/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+naptrap/artifacts.py,sha256=0YjP9o8_MVeqO9AsjNtuOMjVaoHDhG70LKQ8QJR-TKQ,1811
+naptrap/audio.py,sha256=YTVwSxfJy-wVCM0g8EAdoN_daYFrDsShABUfPyTlqRs,897
+naptrap/cli.py,sha256=vziRdOX42RuSdmAKBqiQ2tPoCTTWHSWPRuXxmVUhVec,1706
+naptrap/features.py,sha256=PRgf00IyGQ3NiRklJgkbs25tHqbaOBK2fwzlrbHLnDk,3047
+naptrap/google.py,sha256=h0bdBqclqetX1FcHNRkOzNkKbJfup1d7pNX7Ru9O9RE,4197
+naptrap/hub.py,sha256=3AYHrbudtJjk-Wn96JxZiVEj3AhCmiToGkfcb4UYPL8,896
+naptrap/registry.py,sha256=OqkA_CBnYGmcAhmxC0XwKqOiVFcwFXUMD6s-Xahj4i4,1475
+naptrap/text.py,sha256=lW0tbqmb66CykRZ64tAzsyF_mmgNB0T6vddlq76J43U,4313
+naptrap/types.py,sha256=eMzr2ZgUZyjKmUPo9yREdBY2n4E-p65Ja3e6MSopOEU,1690
+naptrap/models/__init__.py,sha256=xPIbVlXQtopgkj6c-NkA7yH6mYHN6bY59gHTSZk6AhI,105
+naptrap/models/network.py,sha256=_m6rxZZoHMoyG1oRfHKvSKkaqfcKiQBTuWkrhRo8arE,2466
+naptrap/models/phonmatchnet.py,sha256=wZUzaG0AKVjRWtKV1uHR6x2LYRorZS6xYUD3WAPMebo,6437
+naptrap-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+naptrap-0.1.0.dist-info/licenses/NOTICE,sha256=Hw8PSK2Ue5e7MgQC4zkDuAjsseiP4vdmCh5L-df9sK4,879
+naptrap-0.1.0.dist-info/licenses/licenses/PhonMatchNet-BSD-3-Clause.txt,sha256=K5PxNqW-JnzVVahI3K4TI1MXxBQgVWxu8K-8zxhcgMA,1534
+naptrap-0.1.0.dist-info/METADATA,sha256=c8zA_g3UjqSaRUoh9lFVfywKc7oWuxTA3ESyYfcWOxs,7952
+naptrap-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+naptrap-0.1.0.dist-info/entry_points.txt,sha256=cqZp15lOsP1ZtVBj1UehLR0G0V2MmCQdqfGY7K_9794,45
+naptrap-0.1.0.dist-info/top_level.txt,sha256=mTShbwf71nvzi8nL6YoBXsUFxtatajbl_wkKrwfYgng,8
+naptrap-0.1.0.dist-info/RECORD,,

naptrap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

naptrap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+naptrap = naptrap.cli:main

naptrap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

naptrap-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,19 @@
+naptrap
+Copyright 2026 Drew Bednar
+
+This product is licensed under the Apache License, Version 2.0 (LICENSE).
+
+src/naptrap/models/network.py implements the PhonMatchNet architecture
+(Yong-Hyeok Lee and Namhyun Cho, Interspeech 2023) after NCSOFT's
+BSD-3-Clause PyTorch implementation, https://github.com/ncsoft/PhonMatchNet.
+NCSOFT's copyright notice and license: licenses/PhonMatchNet-BSD-3-Clause.txt.
+naptrap is not affiliated with or endorsed by NCSOFT or the PhonMatchNet authors.
+
+src/naptrap/text.py reimplements the decoder-state "embedding" computation of
+g2p_en by Kyubyong Park and Jongseok Kim (Apache-2.0),
+https://github.com/Kyubyong/g2p.
+
+src/naptrap/google.py reimplements Google's speech_embedding/1 model
+(Apache-2.0) in PyTorch. naptrap is not affiliated with or endorsed by Google.
+
+Model weights are not included in this package; see THIRD_PARTY_NOTICES.md.

naptrap-0.1.0.dist-info/licenses/licenses/PhonMatchNet-BSD-3-Clause.txt

@@ -0,0 +1,28 @@
+© 2024 NCSOFT Corporation. All Rights Reserved.
+
+BSD 3-Clause "New" or "Revised" License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

naptrap-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+naptrap