phonomatch 0.1.0__tar.gz

phonomatch-0.1.0/LICENSE

@@ -0,0 +1,203 @@
+Copyright 2026 Aleksa Dejanovic
+
+                                 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.

phonomatch-0.1.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: phonomatch
+Version: 0.1.0
+Summary: Record speech, transcribe it to IPA, and match it against a word list
+Keywords: audio,ctc,ipa,phonetics,speech-recognition,wav2vec2
+Author: Aleksa Dejanovic
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Dist: panphon==0.22.2
+Requires-Dist: phonomatch[microphone] ; extra == 'all'
+Requires-Dist: phonomatch[recognition] ; extra == 'microphone'
+Requires-Dist: sounddevice>=0.5.5 ; extra == 'microphone'
+Requires-Dist: numpy>=1.26,<3 ; extra == 'recognition'
+Requires-Dist: huggingface-hub>=0.30,<2 ; extra == 'recognition'
+Requires-Dist: onnxruntime>=1.20,<1.24 ; python_full_version < '3.11' and extra == 'recognition'
+Requires-Dist: onnxruntime>=1.20,<1.30 ; python_full_version >= '3.11' and extra == 'recognition'
+Requires-Dist: scipy>=1.10,<2 ; extra == 'recognition'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/aleksa-dejanovic/phonomatch
+Project-URL: Repository, https://github.com/aleksa-dejanovic/phonomatch
+Project-URL: Issues, https://github.com/aleksa-dejanovic/phonomatch/issues
+Provides-Extra: all
+Provides-Extra: microphone
+Provides-Extra: recognition
+Description-Content-Type: text/markdown
+
+# PhonoMatch
+
+PhonoMatch records a short utterance, recognizes its phones with Meta's
+Wav2Vec2Phoneme model, and compares the resulting IPA transcription with a
+configurable vocabulary using PanPhon's weighted feature edit distance.
+
+It can recognize either one word or a phrase containing an arbitrary sequence
+of configured words. Phrase mode uses lexicon-constrained CTC beam search to
+infer word boundaries without requiring pauses, then aligns and evaluates each
+word independently.
+
+The application runs locally. It restricts CTC decoding to the phones in the
+configured vocabulary and rejects results that are too distant, insufficiently
+separated from the runner-up, or not confident enough.
+
+## Requirements
+
+- Python 3.10 or newer
+- A microphone and PortAudio for live recording
+- Approximately 200 MB of disk space for the default quantized ONNX model
+
+## Platform support
+
+PhonoMatch supports Linux, macOS, and Windows. Microphone access must be
+permitted for the terminal or Python environment that runs the command.
+
+On Linux, install PortAudio with your system package manager before installing
+PhonoMatch. For Debian or Ubuntu:
+
+```console
+sudo apt install libportaudio2
+```
+
+When installed with `pip`, the `sounddevice` dependency supplies PortAudio on
+macOS and Windows. If macOS cannot find the library, install it with Homebrew:
+
+```console
+brew install portaudio
+```
+
+If Windows cannot detect an input device, first check its microphone privacy
+settings and confirm that the selected input device works in another
+application.
+
+PanPhon reads IPA data as UTF-8. On Windows, enable Python UTF-8 mode before
+running PhonoMatch if your system locale does not already use UTF-8:
+
+```console
+set PYTHONUTF8=1
+phonomatch --default-words
+```
+
+In PowerShell, use `$env:PYTHONUTF8 = "1"` instead of `set`.
+
+## Install
+
+Install from PyPI:
+
+```console
+python -m pip install "phonomatch[all]"
+```
+
+For IPA-only matching, install `phonomatch` without extras. To analyze existing
+WAV files or use the recognition HTTP endpoints, install
+`phonomatch[recognition]`. Microphone recording requires
+`phonomatch[microphone]`; `phonomatch[all]` is an alias for that complete,
+interactive installation.
+
+PhonoMatch uses ONNX Runtime for CPU speech inference. It has no PyTorch,
+CUDA, or Transformers runtime dependency.
+
+Then confirm the command is available:
+
+```console
+phonomatch --help
+```
+
+## Quick start
+
+Try the built-in demonstration vocabulary by recording a two-second utterance:
+
+```console
+phonomatch --default-words
+```
+
+When prompted, say one of the built-in words (for example, `naku`, `selim`, or
+`grun`). To use your own vocabulary, create a JSON object mapping display words
+to IPA pronunciations, then pass its path with `--words`:
+
+```json
+{"grun": "ɡrun", "shaki": "ʃaki"}
+```
+
+```console
+phonomatch --words vocabulary.json
+```
+
+The command reports the recognized IPA, its best vocabulary candidates, and
+whether the distance, separation, and confidence checks passed. A successful
+result begins like this (the recognized IPA and scores depend on the recording):
+
+```text
+PHONOMATCH
+================================================
+Heard    /ɡrun/
+Result   ✓ LIKELY MATCH
+```
+
+For a development checkout, use [`uv`](https://docs.astral.sh/uv/):
+
+```console
+uv sync
+uv run phonomatch --default-words
+```
+
+Use `uv sync --locked` in production and CI so dependency resolution cannot
+change after review.
+
+The first run downloads the quantized ONNX conversion of
+`facebook/wav2vec2-lv-60-espeak-cv-ft`, pinned at revision
+`c69750f5043e5e1f8a71ab95dd3b98338c280c92`. Later runs reuse the local Hugging
+Face cache, so model contents and licensing cannot drift silently. The ONNX
+model (`model_q4f16.onnx`) is approximately 197 MB, compared with the former
+1.2 GiB PyTorch checkpoint.
+
+## How recognition works
+
+Speech recognition now runs the model directly with ONNX Runtime. Audio is
+resampled and normalized exactly as Wav2Vec2 expects, ONNX Runtime produces CTC
+logits as NumPy arrays, and PhonoMatch's existing vocabulary-constrained
+decoder consumes those arrays. The project intentionally uses a small local CTC
+vocabulary decoder instead of importing Transformers just for token decoding.
+
+The default model ID points to the ONNX conversion. To use a local model
+directory, pass a directory containing `vocab.json` and
+`onnx/model_q4f16.onnx` as the model ID. The conversion is pinned to a commit;
+updating it should include regression testing of both single-word and phrase
+recognition against representative audio.
+
+ONNX Runtime uses up to eight CPU threads per recognition session by default.
+Override this for a dedicated low-latency machine or a shared server with
+`PHONOMATCH_ONNX_THREADS`, for example:
+
+```console
+PHONOMATCH_ONNX_THREADS=4 phonomatch --default-words
+```
+
+The console loads the model before recording begins, announces when recording
+ends and recognition starts, and reports the recognition and matching time.
+Keeping the loaded analyzer instance alive also keeps the model resident for
+subsequent requests.
+
+## Privacy and network access
+
+PhonoMatch records audio from the selected microphone and processes it locally.
+It does not upload recorded audio to a PhonoMatch service or any other remote
+service. The first use of the default model requires network access to download
+the pinned model files from Hugging Face; later uses read them from the local
+cache. You can instead configure a compatible local model path to avoid that
+download.
+
+Useful CLI options:
+
+```console
+phonomatch --default-words --seconds 3
+phonomatch --words vocabulary.json --phrase --seconds 5
+phonomatch --words vocabulary.json --phrase --beam-size 96 --max-words 8
+phonomatch --words vocabulary.json --max-distance 0.08
+phonomatch --words vocabulary.json --color never
+phonomatch --help
+```
+
+Supply a vocabulary as a JSON object mapping words to IPA pronunciations, for
+example `{"grun": "ɡrun", "shaki": "ʃaki"}`. The built-in vocabulary is only
+available when explicitly enabled with `--default-words` or `default_words=True`
+in the Python API.
+
+Exit codes are `0` for an accepted match, `2` for an ambiguous or unknown
+utterance, and `1` for an operational error.
+
+## Local HTTP service
+
+Run PhonoMatch as a localhost-only microservice:
+
+```console
+phonomatch --default-words --server
+```
+
+The model is loaded once at startup, then requests reuse it. The default bind
+address is `127.0.0.1:8765`; use `--host` and `--port` to change it. Use a
+non-loopback host only on a trusted network: this deliberately small service
+does not include authentication or TLS.
+
+To let a client release model memory during periods of inactivity, start with
+`--enable-model-lifecycle`. This opt-in switch exposes `POST /v1/model/unload`,
+which releases the cached ONNX session and runs Python garbage collection. On
+Linux systems with glibc, it also asks the native allocator to return unused
+heap pages to the OS. `POST /v1/model/load` loads the model again. Model files remain on disk,
+so reloading normally does not download them. Lifecycle operations wait for any
+in-flight recognition request to finish before changing the model cache.
+
+With lifecycle endpoints enabled, load or release the in-process model cache:
+
+```console
+curl -X POST http://127.0.0.1:8765/v1/model/unload
+curl -X POST http://127.0.0.1:8765/v1/model/load
+```
+
+Send a 16-bit PCM WAV body to `POST /v1/recognize` for a single-word result:
+
+```console
+curl --data-binary @recording.wav \
+  -H 'Content-Type: audio/wav' \
+  http://127.0.0.1:8765/v1/recognize
+```
+
+For lexicon-constrained phrase recognition, post the same audio to
+`/v1/recognize/phrase`. Responses are JSON forms of the Python result models,
+with an additional top-level `accepted` boolean. `GET /health` returns
+`{"status":"ok"}`. Requests must include `Content-Length`, use `audio/wav`,
+and are limited to 32 MiB. Audio is stored in a temporary file only while that
+request is being processed, then removed.
+
+## Python API
+
+```python
+from phonomatch import MatchSettings, PhonoMatch
+
+words = {
+    "grun": "ɡrun",
+    "shaki": "ʃaki",
+}
+
+analyzer = PhonoMatch(
+    words,
+    MatchSettings(max_distance_ratio=0.10),
+)
+
+# Record, recognize, and match.
+
+result = analyzer.record_and_analyze_word(seconds=2)
+
+# Recognize an existing 16-bit PCM WAV file and match it.
+result = analyzer.analyze_file("recording.wav")
+
+# Decode a sequence of vocabulary words and match each word independently.
+phrase = analyzer.analyze_phrase_file(
+    "phrase.wav",
+    beam_size=64,
+    max_words=12,
+)
+
+for word in phrase.words:
+    print(
+        word.match.best_candidate.word,
+        word.start_seconds,
+        word.end_seconds,
+        word.match.accepted,
+    )
+
+# Record and recognize a phrase. The default recording duration is four seconds.
+phrase = analyzer.record_and_analyze_phrase(seconds=4)
+
+# Match an existing IPA transcription without loading the speech model.
+result = analyzer.match_ipa("gɾun")
+
+print(result.recognized_ipa)
+print(result.match.decision)
+print(result.match.best_candidate.word)
+```
+
+`PhonoMatch` is the public façade for the recording and analysis workflows.
+Its focused `Analyzer` service performs IPA and WAV analysis. `listen_and_match`
+remains available from the package root as a convenience function. Phrase
+acceptance requires both an unambiguous word sequence and successful
+independent matching of every aligned word.
+
+### Phrase decoding
+
+Phrase mode operates directly on the model's frame-level CTC probabilities.
+Every configured IPA pronunciation is converted to the model's phone tokens
+and inserted into a trie. Beam search can finish a word at a terminal trie node
+and immediately begin any vocabulary word, so boundaries do not depend on
+silence in the recording.
+
+The winning token sequence is Viterbi-aligned back to the model frames. Each
+word receives an approximate start and end time, a recognized IPA segment, and
+the same distance, relative-separation, and confidence checks used by
+single-word recognition. The phrase is rejected when its runner-up sequence is
+too competitive or any individual word fails.
+
+`--beam-size` trades decoding speed and memory for a wider hypothesis search.
+`--max-words` bounds phrase length and prevents unreasonably long segmentations.
+These options only affect phrase mode.
+
+You can use a compatible local or Hugging Face model identifier:
+
+```python
+analyzer = PhonoMatch(
+    words,
+    model_id="/path/to/local/model",
+    model_revision=None,
+)
+```
+
+PhonoMatch loads ONNX artifacts directly; it does not load Transformers models.
+The local directory or Hugging Face repository must contain `vocab.json` and
+`onnx/model_q4f16.onnx`. The vocabulary must map the normalized IPA phone tokens
+used by your configured words to model token IDs. The ONNX graph must accept the
+Wav2Vec2 waveform input and return CTC logits in the same format as the default
+model.
+
+Expected operational exceptions inherit from `PhonoMatchError`:
+
+- `AudioRecordingError`
+- `RecognitionError`
+- `UnsupportedPhoneError`
+
+## Matching
+
+The default acceptance rules are:
+
+| Check | Default | Meaning |
+| --- | ---: | --- |
+| Maximum distance | 10% | Best match may consume at most 10% of its theoretical maximum edit cost |
+| Relative separation | 20% | Best candidate must be sufficiently favored over the runner-up given their mutual distance |
+| Confidence | 80% | Best candidate must dominate the complete vocabulary |
+
+All checks must pass. Confidence is relative to the configured vocabulary; it
+does not replace the absolute distance check.
+
+The vocabulary is `DEFAULT_WORDS` in `src/phonomatch/domain/config.py`.
+The decoder inventory is derived automatically from it. Unsupported model
+phones produce a clear error instead of silently degrading recognition.
+
+## Development
+
+```console
+uv sync --group dev
+./scripts/check.sh
+```
+
+The script verifies patch whitespace, lockfile consistency, formatting, lint,
+strict typing, unit tests, and both distribution formats. Build artifacts are
+created in a temporary directory and removed automatically.
+
+Apply automatic formatting and safe lint fixes with:
+
+```console
+uv run ruff format .
+uv run ruff check . --fix
+```
+
+Unit tests do not download the Wav2Vec2 model. A real-model smoke test requires
+network access on its first run and can be performed with the installed CLI.
+
+## License
+
+PhonoMatch is licensed under the [Apache License 2.0](LICENSE).
+
+## Contributing
+
+Contributions and bug reports are welcome. Please run `./scripts/check.sh`
+before opening a pull request, and use the
+[issue tracker](https://github.com/aleksa-dejanovic/phonomatch/issues) for bugs
+and feature requests.