tinykw 1.0.0__py3-none-any.whl

tinykw/__init__.py

@@ -0,0 +1,17 @@
+from .wrapper import (
+    tkw_init,
+    tkw_add_keyword,
+    tkw_process_frame,
+    tkw_is_keyword_detected,
+    tkw_clear_keyword_flag,
+    AUDIO_FRAME_SIZE,
+)
+
+__all__ = [
+    "tkw_init",
+    "tkw_add_keyword",
+    "tkw_process_frame",
+    "tkw_is_keyword_detected",
+    "tkw_clear_keyword_flag",
+    "AUDIO_FRAME_SIZE"
+]

tinykw/wrapper.py

@@ -0,0 +1,160 @@
+import ctypes
+import platform
+from pathlib import Path
+
+def _load_library():
+    system = platform.system()
+    machine = platform.machine()
+    arch = {
+        "x86_64":  "x86_64",
+        "AMD64":   "x86_64",   
+        "arm64":   "arm64",
+        "aarch64": "arm64",
+    }.get(machine)
+
+    if arch is None:
+        raise OSError(f"Unsupported architecture: {machine}")
+    
+    lib_dir = Path(__file__).parent / "libs"
+    if system == "Darwin":
+        lib_path = lib_dir / f"macos-{arch}" / "libtinykw.dylib"
+    elif system == "Linux":
+        lib_path = lib_dir / f"linux-{arch}" / "libtinykw.so"
+    elif system == "Windows":
+        lib_path = lib_dir / f"windows-{arch}" / "libtinykw.dll"
+    else:
+        raise OSError(f"Unsupported platform: {system}")
+
+    if not lib_path.exists():
+        raise OSError(f"No native library found for {system}/{arch}.")
+    
+    return ctypes.CDLL(str(lib_path))
+
+_lib = _load_library()
+
+_lib.tkw_init.restype  = ctypes.c_int32
+_lib.tkw_init.argtypes = []
+
+_lib.tkw_add_keyword.restype  = ctypes.c_int32
+_lib.tkw_add_keyword.argtypes = [ctypes.POINTER(ctypes.c_uint8), 
+                                  ctypes.c_uint8, 
+                                  ctypes.POINTER(ctypes.c_uint32)]
+
+_lib.tkw_process_frame.restype  = ctypes.c_int32
+_lib.tkw_process_frame.argtypes = [ctypes.POINTER(ctypes.c_int16),
+                                    ctypes.c_size_t]
+
+_lib.tkw_is_keyword_detected.restype  = ctypes.c_int32
+_lib.tkw_is_keyword_detected.argtypes = [ctypes.c_uint32, 
+                                          ctypes.POINTER(ctypes.c_uint32)]
+
+_lib.tkw_clear_keyword_flag.restype  = ctypes.c_int32
+_lib.tkw_clear_keyword_flag.argtypes = [ctypes.c_uint32]
+
+_lib.tkw_status_string.restype = ctypes.c_char_p
+_lib.tkw_status_string.argtypes = [ctypes.c_int32]
+
+AUDIO_FRAME_SIZE = 480
+
+class tkwError(RuntimeError):
+    pass
+
+def _check_status(status: int):
+    if status != 0:
+        msg = _lib.tkw_status_string(status)
+        msg = msg.decode() if msg else f"Error code {status}"
+        raise tkwError(msg)
+
+def tkw_init() -> None:
+    """
+    Initialize or reset the library.
+
+    This should be called before any other API function. Calling tkw_init() multiple times is allowed 
+    and resets all internal state, including registered keywords and detection flags.
+    """
+    status = _lib.tkw_init()
+    _check_status(status)
+
+
+def tkw_add_keyword(data: list[int] | bytes, detection_threshold: float = 0.5) -> int:
+    """
+    Adds a keyword to the engine.
+
+    Args:
+        data: 48 bytes keyword encoding (can be obtained from https://voyelle.io/tinykw).
+        detection_threshold: value between 0 and 1. 
+            Controls how strict the engine is when deciding whether a detection is valid.
+            A high value makes the engine more conservative: only high-scoring detections are accepted (fewer false positives, but more missed detections).
+            A low value makes the engine more permissive: more detections are accepted (fewer misses, but more false positives).
+            This parameter may need tuning depending on the keyword, use case and environment. A good starting point is to set it mid-range at 0.5, and 
+            then eventually adjust it based on your tolerance for false positives vs missed detections.
+    
+    Returns:
+        id: the assigned keyword ID
+
+    Example:
+        data = [0x3f, 0x12, 0x00, ...]  # 48 bytes
+        id = tkw_add_keyword(data, 0.75)
+    """
+    if isinstance(data, bytes):
+        data = list(data)
+    if len(data) != 48:
+        raise ValueError(f"data must be exactly 48 bytes, got {len(data)}")
+    if not (0.0 <= detection_threshold <= 1.0):
+        raise ValueError("detection_threshold must be in [0.0, 1.0]")
+    detection_threshold = max(0, min(255, round(detection_threshold * 256)))
+    c_data = (ctypes.c_uint8 * 48)(*data)
+    out_id = ctypes.c_uint32()
+    status = _lib.tkw_add_keyword(c_data, 
+                                   ctypes.c_uint8(detection_threshold), 
+                                   ctypes.byref(out_id))
+    _check_status(status)
+    return out_id.value
+
+
+def tkw_process_frame(waveform) -> None:
+    """
+    Processes one frame of 16-bit PCM audio sampled at 16 kHz.
+
+    Args:
+        waveform: int16 numpy array or list of length tinykw.AUDIO_FRAME_SIZE.
+    """
+    if len(waveform) != AUDIO_FRAME_SIZE:
+        raise ValueError(
+            f"waveform must have length {AUDIO_FRAME_SIZE}, got {len(waveform)}"
+        )
+    if hasattr(waveform, "ctypes"):
+        ptr = waveform.ctypes.data_as(ctypes.POINTER(ctypes.c_int16))
+    else:
+        arr = (ctypes.c_int16 * len(waveform))(*waveform)
+        ptr = arr
+    status = _lib.tkw_process_frame(ptr, len(waveform))
+    _check_status(status)
+
+
+def tkw_is_keyword_detected(keyword_id: int) -> bool:
+    """
+   Reads the detection flag for a specific keyword.
+
+    Args:
+        id: keyword assigned ID.
+
+    Returns:
+        True if detected, False otherwise.
+        Detection remains set until cleared with tkw_clear_keyword_flag().
+    """
+    out = ctypes.c_uint32()
+    status = _lib.tkw_is_keyword_detected(ctypes.c_uint32(keyword_id), ctypes.byref(out))
+    _check_status(status)
+    return bool(out.value)
+
+
+def tkw_clear_keyword_flag(keyword_id: int) -> None:
+    """
+    Clear detection flag.
+
+    Args:
+        id: keyword id
+    """
+    status = _lib.tkw_clear_keyword_flag(ctypes.c_uint32(keyword_id))
+    _check_status(status)

tinykw-1.0.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: tinykw
+Version: 1.0.0
+Summary: Python binding for TinyKW
+Project-URL: Homepage, https://voyelle.io/tinykw
+Project-URL: Repository, https://github.com/voyelle-io/tinykw.git
+Keywords: keyword spotting,wake word
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: scipy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+Python binding for TinyKW.
+
+## Installation
+
+`pip install tinykw`
+
+## Usage
+
+```python
+import tinykw
+
+tinykw.tkw_init()
+
+kw_id = tinykw.tkw_add_keyword(keyword_bytes, detection_threshold)
+# ... 
+tinykw.tkw_process_frame(samples)
+# ...
+if tinykw.tkw_is_keyword_detected(kw_id):
+    tinykw.tkw_clear_keyword_flag(kw_id)
+```
+
+See [examples/python](../examples/python/) for full usage.
+
+## License
+
+TinyKW is free for non-commercial use, including research, education, prototyping, and evaluation.
+Please see [LICENSE](LICENSE) for details. For commercial enquiries, please contact [contact@voyelle.io](mailto:contact@voyelle.io).

tinykw-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tinykw/__init__.py,sha256=g0FqZFzbzrH9hxScfGhcbOxX0VdUCP-mvpYGd21Gdv0,324
+tinykw/wrapper.py,sha256=j6nAJEXNsg3d5yWAHyleN2PiJ1szJkSQ89Geu_52NTg,5462
+tinykw/libs/linux-arm64/libtinykw.so,sha256=LCaP360L8dQgtRaaKmvDgi6wplBUKUwnTWMPP9Fy9n8,317648
+tinykw/libs/linux-x86_64/libtinykw.so,sha256=Nd__IvAJUGpRKksI215YOcuWFpXTZQCf4bPkQRp_QjQ,320960
+tinykw/libs/macos-arm64/libtinykw.dylib,sha256=CHTl5oMmw_p6jMLc2r0pdfjGre9Z_1k2tQFCxIC_DiY,362192
+tinykw/libs/macos-x86_64/libtinykw.dylib,sha256=fU7W6ZoK7jeWA9_UwHjBSb7HUaifDAPi2bWbKTRDHhw,332752
+tinykw/libs/windows-arm64/libtinykw.dll,sha256=H6p-88X6cC3uAiL2w0fWGygzleoQopi5IpDbaIPlS1w,326144
+tinykw/libs/windows-x86_64/libtinykw.dll,sha256=CcDElE8NXxw3YNedr6CjRirCXD8UDg3PpjqmNGk-LGA,333824
+tinykw-1.0.0.dist-info/licenses/LICENSE,sha256=7TQoAJLKq41XnHkEUzq-U4nuBdjTxR6d-I67YwT9dcA,1499
+tinykw-1.0.0.dist-info/METADATA,sha256=WXk9FZ9iGnUTcZ8l0AkHwAXUd9Bkv8yLe87uqBdKSdo,1105
+tinykw-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tinykw-1.0.0.dist-info/top_level.txt,sha256=5-pvJSN5r_PM_tAxf0v6m24ZAJlEufMinzHYJbjbLUQ,7
+tinykw-1.0.0.dist-info/RECORD,,

tinykw-1.0.0.dist-info/WHEEL

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

tinykw-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2026 TinyKW
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of this software and associated documentation files
+(the "Software") to use, reproduce, and distribute the Software in binary form
+for non-commercial purposes only, including internal evaluation,
+research, prototyping, and educational use, provided that this license notice is 
+retained in all copies or distributions.
+
+Commercial use of the Software is prohibited without a separate written
+commercial license from the copyright holder. For purposes of this license, 
+"commercial use" means use of the Software in or for a product, service, or 
+activity that generates revenue or other commercial benefit, including use 
+in products or services that are sold, licensed, hosted, subscription-based, 
+or monetized in any form.
+
+You may not:
+- reverse engineer, decompile, or disassemble the Software except where
+  such restriction is prohibited by applicable law;
+- remove or alter copyright or license notices.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

tinykw-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tinykw