phonomatch 0.1.0__py3-none-any.whl

phonomatch/__init__.py

@@ -0,0 +1,57 @@
+"""Record speech, transcribe it to IPA, and match it against known words."""
+
+from .application.analyzer import (
+    DEFAULT_MODEL_ID,
+    DEFAULT_MODEL_REVISION,
+)
+from .application.phonomatch import PhonoMatch, listen_and_match
+from .domain import (
+    DEFAULT_WORDS,
+    AnalysisResult,
+    CandidateScore,
+    MatchResult,
+    MatchSettings,
+    PhraseAnalysisResult,
+    WordAnalysisResult,
+    decide_match,
+    distance_ratio,
+    normalize_ipa,
+)
+from .exceptions import (
+    AudioRecordingError,
+    OptionalDependencyError,
+    PhonoMatchError,
+    RecognitionError,
+    UnsupportedPhoneError,
+)
+
+
+def load_model(*args: object, **kwargs: object) -> None:
+    """Load the optional speech-recognition model."""
+    from .application.analyzer import load_model as _load_model
+
+    _load_model(*args, **kwargs)
+
+
+__all__ = [
+    "DEFAULT_MODEL_ID",
+    "DEFAULT_MODEL_REVISION",
+    "DEFAULT_WORDS",
+    "AnalysisResult",
+    "AudioRecordingError",
+    "CandidateScore",
+    "MatchResult",
+    "MatchSettings",
+    "OptionalDependencyError",
+    "PhonoMatch",
+    "PhonoMatchError",
+    "PhraseAnalysisResult",
+    "RecognitionError",
+    "UnsupportedPhoneError",
+    "WordAnalysisResult",
+    "decide_match",
+    "distance_ratio",
+    "listen_and_match",
+    "load_model",
+    "normalize_ipa",
+]

phonomatch/application/__init__.py

@@ -0,0 +1,6 @@
+"""Application services and workflows for speech recognition and matching."""
+
+from .analyzer import Analyzer
+from .phonomatch import PhonoMatch
+
+__all__ = ["Analyzer", "PhonoMatch"]

phonomatch/application/analyzer.py

@@ -0,0 +1,145 @@
+"""High-level orchestration API for sound analysis."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Optional
+
+from ..domain.config import DEFAULT_SETTINGS, MatchSettings
+from ..domain.matching import decide_match
+from ..domain.models import AnalysisResult, PhraseAnalysisResult, WordAnalysisResult
+from ..exceptions import OptionalDependencyError
+from ..infrastructure.phonetics import (
+    Vocabulary,
+    phonetic_distance,
+    phonetic_maximum_distance,
+)
+
+DEFAULT_MODEL_ID = "onnx-community/wav2vec2-lv-60-espeak-cv-ft-ONNX"
+DEFAULT_MODEL_REVISION = "c69750f5043e5e1f8a71ab95dd3b98338c280c92"
+
+
+def _recognition_module() -> Any:
+    """Load speech recognition only when a recognition API is used."""
+    try:
+        from ..infrastructure import recognition
+    except ModuleNotFoundError as exc:
+        if exc.name in {"numpy", "scipy", "onnxruntime", "huggingface_hub"}:
+            raise OptionalDependencyError("recognition") from exc
+        raise
+    return recognition
+
+
+def speech_to_ipa(*args: object, **kwargs: object) -> str:
+    """Lazily dispatch to the optional speech-recognition integration."""
+    return str(_recognition_module().speech_to_ipa(*args, **kwargs))
+
+
+def speech_to_phrase(*args: object, **kwargs: object) -> Any:
+    """Lazily dispatch to the optional phrase-recognition integration."""
+    return _recognition_module().speech_to_phrase(*args, **kwargs)
+
+
+def load_model(*args: object, **kwargs: object) -> None:
+    """Lazily load the optional speech-recognition model."""
+    _recognition_module().load_model(*args, **kwargs)
+
+
+def unload_models() -> None:
+    """Lazily release optional cached speech-recognition models."""
+    _recognition_module().unload_models()
+
+
+class Analyzer:
+    """Transcribe recordings and match them against an IPA vocabulary."""
+
+    def __init__(
+        self,
+        vocabulary: Vocabulary,
+        settings: MatchSettings = DEFAULT_SETTINGS,
+        *,
+        model_id: str = DEFAULT_MODEL_ID,
+        model_revision: Optional[str] = DEFAULT_MODEL_REVISION,
+    ) -> None:
+        self._vocabulary = vocabulary
+        self._settings = settings
+        self._model_id = model_id
+        self._model_revision = model_revision
+
+    @property
+    def words(self) -> Mapping[str, str]:
+        """Return a defensive copy of the analyzer vocabulary."""
+        return dict(self._vocabulary.words)
+
+    def analyze_file(self, wav_path: str | Path) -> AnalysisResult:
+        """Transcribe and match an existing WAV file."""
+        started_at = time.perf_counter()
+        ipa = speech_to_ipa(
+            wav_path,
+            self._vocabulary.phones,
+            model_id=self._model_id,
+            model_revision=self._model_revision,
+        )
+        result = self.match_ipa(ipa)
+        return AnalysisResult(
+            recognized_ipa=result.recognized_ipa,
+            match=result.match,
+            recognition_seconds=time.perf_counter() - started_at,
+        )
+
+    def analyze_phrase_file(
+        self,
+        wav_path: str | Path,
+        *,
+        beam_size: int = 64,
+        max_words: int = 12,
+    ) -> PhraseAnalysisResult:
+        """Decode and independently match vocabulary words in a WAV file."""
+        started_at = time.perf_counter()
+        transcription = speech_to_phrase(
+            wav_path,
+            self._vocabulary,
+            model_id=self._model_id,
+            model_revision=self._model_revision,
+            beam_size=beam_size,
+            max_words=max_words,
+        )
+        word_results = tuple(
+            WordAnalysisResult(
+                recognized_ipa=word.ipa,
+                match=self.match_ipa(word.ipa).match,
+                start_seconds=word.start_seconds,
+                end_seconds=word.end_seconds,
+            )
+            for word in transcription.words
+        )
+        return PhraseAnalysisResult(
+            words=word_results,
+            sequence_confidence=transcription.confidence,
+            sequence_accepted=(
+                transcription.confidence >= self._settings.min_confidence
+            ),
+            alternative_words=transcription.alternative,
+            recognition_seconds=time.perf_counter() - started_at,
+        )
+
+    def load_model(self) -> None:
+        """Load the speech model now so later recognition avoids startup delay."""
+        load_model(self._model_id, self._model_revision)
+
+    def unload_model(self) -> None:
+        """Release the cached speech model and request Python memory cleanup."""
+        unload_models()
+
+    def match_ipa(self, ipa: str) -> AnalysisResult:
+        """Match an existing IPA transcription without recording audio."""
+        match = decide_match(
+            ipa,
+            self._vocabulary.words,
+            phonetic_distance,
+            maximum_distance_function=phonetic_maximum_distance,
+            settings=self._settings,
+        )
+        return AnalysisResult(recognized_ipa=ipa, match=match)

phonomatch/application/phonomatch.py

@@ -0,0 +1,133 @@
+"""The public façade for recording, recognition, and pronunciation matching."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from contextlib import AbstractContextManager
+from pathlib import Path
+from typing import Optional
+
+from ..domain.config import DEFAULT_SETTINGS, MatchSettings
+from ..domain.models import AnalysisResult, PhraseAnalysisResult
+from ..infrastructure.audio import recorded_audio
+from ..infrastructure.phonetics import Vocabulary
+from .analyzer import DEFAULT_MODEL_ID, DEFAULT_MODEL_REVISION, Analyzer
+
+Recording = Callable[[float], AbstractContextManager[Path]]
+
+
+class PhonoMatch:
+    """Coordinate microphone capture with pronunciation analysis."""
+
+    def __init__(
+        self,
+        words: Mapping[str, str] | None = None,
+        settings: MatchSettings = DEFAULT_SETTINGS,
+        *,
+        default_words: bool = False,
+        model_id: str = DEFAULT_MODEL_ID,
+        model_revision: Optional[str] = DEFAULT_MODEL_REVISION,
+        record: Recording = recorded_audio,
+    ) -> None:
+        self._analyzer = Analyzer(
+            self._create_vocabulary(words, default_words=default_words),
+            settings,
+            model_id=model_id,
+            model_revision=model_revision,
+        )
+        self._record = record
+
+    @staticmethod
+    def _create_vocabulary(
+        words: Mapping[str, str] | None, *, default_words: bool
+    ) -> Vocabulary:
+        if words is None:
+            if not default_words:
+                raise ValueError(
+                    "a word list is required; pass words={'word': 'ipa'} or set "
+                    "default_words=True"
+                )
+            from ..domain.config import DEFAULT_WORDS
+
+            return Vocabulary.from_words(DEFAULT_WORDS)
+        if default_words:
+            raise ValueError("pass either words or default_words=True, not both")
+        return Vocabulary.from_words(words)
+
+    @property
+    def words(self) -> Mapping[str, str]:
+        """Return a defensive copy of the configured vocabulary."""
+        return self._analyzer.words
+
+    def load_model(self) -> None:
+        """Load the speech model now so later recognition avoids startup delay."""
+        self._analyzer.load_model()
+
+    def unload_model(self) -> None:
+        """Release the cached speech model."""
+        self._analyzer.unload_model()
+
+    def match_ipa(self, ipa: str) -> AnalysisResult:
+        """Match an existing IPA transcription."""
+        return self._analyzer.match_ipa(ipa)
+
+    def analyze_file(self, wav_path: str | Path) -> AnalysisResult:
+        """Analyze an existing WAV file."""
+        return self._analyzer.analyze_file(wav_path)
+
+    def analyze_phrase_file(
+        self,
+        wav_path: str | Path,
+        *,
+        beam_size: int = 64,
+        max_words: int = 12,
+    ) -> PhraseAnalysisResult:
+        """Analyze an existing WAV file as a vocabulary word sequence."""
+        return self._analyzer.analyze_phrase_file(
+            wav_path, beam_size=beam_size, max_words=max_words
+        )
+
+    def record_and_analyze_word(
+        self,
+        *,
+        seconds: float = 2.0,
+        on_recording_complete: Optional[Callable[[], None]] = None,
+    ) -> AnalysisResult:
+        """Capture one utterance, then analyze its temporary WAV file."""
+        self.load_model()
+        with self._record(seconds) as wav_path:
+            if on_recording_complete is not None:
+                on_recording_complete()
+            return self.analyze_file(wav_path)
+
+    def record_and_analyze_phrase(
+        self,
+        *,
+        seconds: float = 4.0,
+        beam_size: int = 64,
+        max_words: int = 12,
+        on_recording_complete: Optional[Callable[[], None]] = None,
+    ) -> PhraseAnalysisResult:
+        """Capture an utterance, then decode it as a vocabulary word sequence."""
+        self.load_model()
+        with self._record(seconds) as wav_path:
+            if on_recording_complete is not None:
+                on_recording_complete()
+            return self.analyze_phrase_file(
+                wav_path,
+                beam_size=beam_size,
+                max_words=max_words,
+            )
+
+
+def listen_and_match(
+    words: Mapping[str, str] | None = None,
+    *,
+    seconds: float = 2.0,
+    settings: MatchSettings = DEFAULT_SETTINGS,
+    default_words: bool = False,
+) -> AnalysisResult:
+    """Backward-compatible convenience workflow for one live utterance."""
+    return PhonoMatch(
+        words, settings, default_words=default_words
+    ).record_and_analyze_word(seconds=seconds)

phonomatch/domain/__init__.py

@@ -0,0 +1,26 @@
+"""Pure domain models, configuration, normalization, and matching rules."""
+
+from .config import DEFAULT_SETTINGS, DEFAULT_WORDS, MatchSettings
+from .ipa import normalize_ipa
+from .matching import decide_match, distance_ratio
+from .models import (
+    AnalysisResult,
+    CandidateScore,
+    MatchResult,
+    PhraseAnalysisResult,
+    WordAnalysisResult,
+)
+
+__all__ = [
+    "DEFAULT_SETTINGS",
+    "DEFAULT_WORDS",
+    "AnalysisResult",
+    "CandidateScore",
+    "MatchResult",
+    "MatchSettings",
+    "PhraseAnalysisResult",
+    "WordAnalysisResult",
+    "decide_match",
+    "distance_ratio",
+    "normalize_ipa",
+]

phonomatch/domain/config.py

@@ -0,0 +1,56 @@
+"""Domain defaults and validated matching configuration."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+DEFAULT_WORDS: Mapping[str, str] = MappingProxyType(
+    {
+        "naku": "naku",
+        "selim": "selim",
+        "tova": "tova",
+        "grun": "ɡrun",
+        "shaki": "ʃaki",
+        "flabkiver": "flæbˈkɪvər",
+        "dracarys": "draˈkarys",
+        "lykiri": "lyˈkiri",
+        "dohaeras": "dohaeˈra:s",
+        "umbas": "ˈʊmbæs",
+        "rybas": "ˈriːbəs",
+        "mazis": "mˈæ.ziz",
+        "naejot": "ˈnaeɟot",
+        "soves": "ˈsuːvɛs",
+        "vezos": "ˈˈveːzos",
+        "kepus": "ˈkɛpus",
+        "sovetes": "soˈvetes",
+        "drakaryssy": "drakaˈryssy",
+    }
+)
+
+
+@dataclass(frozen=True)
+class MatchSettings:
+    """Thresholds used to accept or reject the best phonetic candidate."""
+
+    temperature: float = 0.035
+    max_distance_ratio: float = 0.1
+    min_relative_margin: float = 0.20
+    min_confidence: float = 0.80
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.temperature) or self.temperature <= 0:
+            raise ValueError("temperature must be a finite value greater than zero")
+        for name in (
+            "max_distance_ratio",
+            "min_relative_margin",
+            "min_confidence",
+        ):
+            value = getattr(self, name)
+            if not math.isfinite(value) or not 0 <= value <= 1:
+                raise ValueError(f"{name} must be a finite value between zero and one")
+
+
+DEFAULT_SETTINGS = MatchSettings()

phonomatch/domain/ipa.py

@@ -0,0 +1,25 @@
+"""Pure IPA text normalization shared by recognition and matching."""
+
+import unicodedata
+
+# These are notation aliases, not merely similar sounds. Distinct phonemes such
+# as /r/ and /ɾ/ deliberately remain separate.
+_IPA_EQUIVALENTS = str.maketrans(
+    {
+        "g": "ɡ",
+        ":": "ː",
+        "꞉": "ː",
+        "'": "ʼ",
+        "‘": "ʼ",
+        "’": "ʼ",
+        "ʹ": "ʼ",
+        "′": "ʼ",
+        "͜": "͡",
+    }
+)
+
+
+def normalize_ipa(ipa: str) -> str:
+    """Remove separators and canonicalize equivalent IPA notation."""
+    compact = "".join(ipa.split()).translate(_IPA_EQUIVALENTS)
+    return unicodedata.normalize("NFC", compact)

phonomatch/domain/matching.py

@@ -0,0 +1,109 @@
+"""Domain functions for ranking and accepting phonetic candidates."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Mapping
+
+from .config import DEFAULT_SETTINGS, MatchSettings
+from .ipa import normalize_ipa
+from .models import CandidateScore, Decision, MatchResult
+
+DistanceFunction = Callable[[str, str], float]
+
+
+def distance_ratio(cost: float, maximum_cost: float) -> float:
+    """Express an edit cost as a fraction of its theoretical maximum."""
+    if cost < 0 or not math.isfinite(cost):
+        raise ValueError("distance function must return a finite non-negative value")
+    if maximum_cost < 0 or not math.isfinite(maximum_cost):
+        raise ValueError(
+            "maximum distance function must return a finite non-negative value"
+        )
+    if maximum_cost == 0:
+        return 0.0 if cost == 0 else math.inf
+    if cost > maximum_cost:
+        raise ValueError("distance cost cannot exceed its stated maximum")
+    return cost / maximum_cost
+
+
+def unit_edit_maximum(ipa_a: str, ipa_b: str) -> float:
+    """Return the delete-all/insert-all bound for unit-cost edit distance."""
+    return float(len(ipa_a) + len(ipa_b))
+
+
+def decide_match(
+    query: str,
+    candidates: Mapping[str, str],
+    distance_function: DistanceFunction,
+    *,
+    maximum_distance_function: DistanceFunction = unit_edit_maximum,
+    settings: MatchSettings = DEFAULT_SETTINGS,
+) -> MatchResult:
+    """Rank IPA candidates and reject distant or ambiguous results."""
+    if not candidates:
+        raise ValueError("at least one candidate is required")
+
+    normalized_query = normalize_ipa(query)
+    raw_scores: list[tuple[str, str, float, float, float]] = []
+    for word, ipa in candidates.items():
+        normalized_ipa = normalize_ipa(ipa)
+        raw_distance = distance_function(normalized_query, normalized_ipa)
+        ratio = distance_ratio(
+            raw_distance,
+            maximum_distance_function(normalized_query, normalized_ipa),
+        )
+        raw_scores.append(
+            (
+                word,
+                normalized_ipa,
+                raw_distance,
+                ratio,
+                -ratio / settings.temperature,
+            )
+        )
+
+    # Ratios make candidate ranking comparable across different word lengths.
+    raw_scores.sort(key=lambda score: score[3])
+    highest_log_score = max(score[4] for score in raw_scores)
+    denominator = sum(math.exp(score[4] - highest_log_score) for score in raw_scores)
+    scores = [
+        CandidateScore(
+            word=word,
+            ipa=ipa,
+            raw_distance=raw_distance,
+            distance_ratio=ratio,
+            confidence=math.exp(log_score - highest_log_score) / denominator,
+        )
+        for word, ipa, raw_distance, ratio, log_score in raw_scores
+    ]
+
+    best = scores[0]
+    second = scores[1] if len(scores) > 1 else None
+    relative_margin = _relative_margin(best, second, distance_function)
+    accepted = (
+        best.distance_ratio <= settings.max_distance_ratio
+        and relative_margin >= settings.min_relative_margin
+        and best.confidence >= settings.min_confidence
+    )
+    decision: Decision = "likely_match" if accepted else "ambiguous_or_unknown"
+    return MatchResult(decision, best, second, relative_margin)
+
+
+def _relative_margin(
+    best: CandidateScore,
+    second: CandidateScore | None,
+    distance_function: DistanceFunction,
+) -> float:
+    if second is None:
+        return math.inf
+
+    candidate_distance = distance_function(best.ipa, second.ipa)
+    if not math.isfinite(candidate_distance) or candidate_distance < 0:
+        raise ValueError("distance function must return a finite non-negative value")
+    if candidate_distance == 0:
+        # Identical pronunciations cannot be distinguished from audio alone.
+        return 0.0
+
+    margin = (second.raw_distance - best.raw_distance) / candidate_distance
+    return max(-1.0, min(1.0, margin))

phonomatch/domain/models.py

@@ -0,0 +1,77 @@
+"""Result models returned by the analyzer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+Decision = Literal["likely_match", "ambiguous_or_unknown"]
+
+
+@dataclass(frozen=True)
+class CandidateScore:
+    """The score assigned to one vocabulary entry."""
+
+    word: str
+    ipa: str
+    raw_distance: float
+    distance_ratio: float
+    confidence: float
+
+
+@dataclass(frozen=True)
+class MatchResult:
+    """The matching decision and its strongest candidates."""
+
+    decision: Decision
+    best_candidate: CandidateScore
+    second_candidate: Optional[CandidateScore]
+    relative_margin: float
+
+    @property
+    def accepted(self) -> bool:
+        return self.decision == "likely_match"
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    """An IPA transcription together with its vocabulary match."""
+
+    recognized_ipa: str
+    match: MatchResult
+    recognition_seconds: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class WordAnalysisResult:
+    """An independently matched word within a phrase."""
+
+    recognized_ipa: str
+    match: MatchResult
+    start_seconds: float
+    end_seconds: float
+
+
+@dataclass(frozen=True)
+class PhraseAnalysisResult:
+    """A sequence of independently matched vocabulary words."""
+
+    words: tuple[WordAnalysisResult, ...]
+    sequence_confidence: float
+    sequence_accepted: bool
+    alternative_words: Optional[tuple[str, ...]] = None
+    recognition_seconds: Optional[float] = None
+
+    @property
+    def recognized_ipa(self) -> str:
+        """Return the per-word transcriptions separated by spaces."""
+        return " ".join(word.recognized_ipa for word in self.words)
+
+    @property
+    def accepted(self) -> bool:
+        """Return whether every independently scored word was accepted."""
+        return (
+            self.sequence_accepted
+            and bool(self.words)
+            and all(word.match.accepted for word in self.words)
+        )

phonomatch/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by phonomatch integrations."""
+
+
+class PhonoMatchError(Exception):
+    """Base class for expected phonomatch failures."""
+
+
+class OptionalDependencyError(PhonoMatchError):
+    """Raised when an operation needs an optional installation extra."""
+
+    def __init__(self, extra: str) -> None:
+        super().__init__(
+            f"this feature requires the {extra!r} extra; install it with "
+            f"python -m pip install 'phonomatch[{extra}]'"
+        )
+
+
+class AudioRecordingError(PhonoMatchError):
+    """Raised when microphone capture fails."""
+
+
+class RecognitionError(PhonoMatchError):
+    """Raised when Wav2Vec2Phoneme cannot transcribe a recording."""
+
+
+class UnsupportedPhoneError(RecognitionError):
+    """Raised when a vocabulary phone is unavailable in Wav2Vec2Phoneme."""

phonomatch/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Adapters for audio capture, speech recognition, and phonetic tooling."""