swanada 1.0.0__tar.gz

swanada-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth HM <hemanth@h3manth.com> (https://h3manth.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. 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.

swanada-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: swanada
+Version: 1.0.0
+Summary: Swanada (स्वनद): In-browser, Node.js, and Python 16 kHz Multilingual Speech-to-Text for Classical Sanskrit, Indian English & 10 Indic languages via ONNX/WASM.
+Author-email: Hemanth HM <hemanth@h3manth.com>
+License-Expression: MIT
+Project-URL: Homepage, https://hemanth.github.io/swanada/
+Project-URL: Repository, https://github.com/hemanth/swanada
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: neural
+Requires-Dist: onnxruntime>=1.18.0; extra == "neural"
+Requires-Dist: soundfile>=0.12.1; extra == "neural"
+Requires-Dist: scipy>=1.11.0; extra == "neural"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# swanada (स्वनद)
+
+In-browser, Node.js, and Python 16,000 Hz multilingual speech-to-text (STT) for Classical Sanskrit (`sa`), Indian English (`en`), and ten Indic languages (`hi`, `kn`, `mr`, `bn`, `ta`, `te`, `ml`, `gu`, `pa`, `or`) powered by 17-layer Conformer-CTC INT8 models running 100% client-side via ONNX/WASM with zero cloud or server dependencies.
+
+```bash
+npm install swanada
+```
+
+```bash
+pip install swanada
+```
+
+## Quick Start (JavaScript / TypeScript)
+
+```typescript
+import { Swanada } from 'swanada';
+
+// Initialize transcriber for Classical Sanskrit
+const transcriber = await Swanada.create({
+  language: 'sa',
+  executionProvider: 'wasm',
+  numThreads: 4,
+});
+
+// Transcribe audio Float32Array PCM or WAV ArrayBuffer
+const result = await transcriber.transcribe(audioPcmFloat32);
+console.log(`Transcript (${result.language}):`, result.text);
+console.log(`Duration: ${result.durationMs}ms | Latency: ${result.inferenceMs}ms | RTF: ${result.rtf}`);
+
+// Classical Sanskrit to Roman IAST transliteration
+const iast = Swanada.transliterateIast(result.text);
+console.log('IAST Transliteration:', iast);
+
+await transcriber.release();
+```
+
+## Quick Start (Python)
+
+```python
+from swanada import Swanada
+
+stt = Swanada.create(language="kn")  # Kannada
+result = stt.transcribe("speech_16k.wav")
+
+print("Transcript:", result.text)
+print(f"Duration: {result.duration_ms:.1f}ms | Latency: {result.inference_ms:.1f}ms | RTF: {result.rtf:.3f}")
+```
+
+## CLI Usage
+
+Dual-runtime command-line interface with identical flags:
+
+```bash
+# Node.js CLI
+npx swanada speech.wav -l sa
+npx swanada recitation.wav -l sa --json -o output.json
+cat stream.wav | npx swanada -l hi --stream
+
+# Python CLI
+swanada speech.wav -l kn
+cat stream.wav | swanada -l ta --stream
+```
+
+### Unified CLI Flags
+- `-l, --language <lang>`: Language code (default: `sa`). Supported: `sa, en, hi, kn, mr, bn, ta, te, ml, gu, pa, or`.
+- `-m, --model-dir <dir>`: Optional custom models directory.
+- `-o, --output <file>`: Output text file (default: stdout).
+- `--json`: Emit structured JSON with text, durationMs, inferenceMs, rtf, and tokens.
+- `--stream`: Simulate chunk-by-chunk streaming transcription (320 ms quanta).
+- `--iast`: Transliterate Classical Sanskrit output to Roman IAST with Vedic accents.
+- `-h, --help`: Show help and usage summary.
+- `-v, --version`: Show version (`swanada 1.0.0`).
+
+## Benchmarks
+
+Evaluated across 480 held-out 16 kHz utterances (40 per language, `B = 1,000` bootstrap 95% CIs), 1,200 unseen `google/fleurs` + wild test clips, and 72 streaming sessions (100 ms chunks):
+
+| Language | Code | Held-Out CER (95% CI) | Held-Out WER | Unseen Fleurs CER |
+| :--- | :---: | :---: | :---: | :---: |
+| Classical Sanskrit | `sa` | `5.24% [3.47%, 7.28%]` | `27.77%` | `17.10%` |
+| Indian English | `en` | `5.70% [4.41%, 7.00%]` | `16.94%` | `15.61%` |
+| Hindi | `hi` | `3.44% [2.34%, 4.53%]` | `12.64%` | `5.52%` |
+| Kannada | `kn` | `6.03% [4.65%, 7.58%]` | `35.70%` | `5.11%` |
+| Marathi | `mr` | `7.31% [4.30%, 10.50%]` | `27.52%` | `7.37%` |
+| Bengali | `bn` | `7.76% [6.07%, 9.54%]` | `40.66%` | `5.71%` |
+| Tamil | `ta` | `8.01% [6.28%, 9.86%]` | `38.46%` | `10.88%` |
+| Telugu | `te` | `5.54% [4.01%, 7.16%]` | `30.62%` | `9.05%` |
+| Malayalam | `ml` | `7.78% [5.58%, 10.13%]` | `40.27%` | `6.42%` |
+| Gujarati | `gu` | `5.32% [3.42%, 7.73%]` | `23.17%` | `6.69%` |
+| Punjabi | `pa` | `7.71% [4.69%, 11.34%]` | `29.47%` | `9.59%` |
+| Odia | `or` | `8.94% [6.25%, 12.46%]` | `37.55%` | `8.95%` |
+| **Overall (12 Langs)** | — | **`6.57% [5.94%, 7.22%]`** | **`30.06%`** | **`9.00%`** |
+
+Shared 178 MB INT8 Conformer encoder + 515 KB per-language CTC projection heads run at `0.0325x` CPU RTF, `~8-11 ms` streaming chunk latency, and `0.00%` committed prefix churn.
+
+## Live Playground
+
+- h3manth.com AI Experiments Studio: [https://h3manth.com/ai/swanada/](https://h3manth.com/ai/swanada/)
+- GitHub Pages Web Studio: [https://hemanth.github.io/swanada/](https://hemanth.github.io/swanada/)
+
+## Model Weights & Hugging Face Hub
+
+Quantized INT8 model weights are hosted on Hugging Face Hub:
+- Repository: [https://huggingface.co/gnumanth/swanada](https://huggingface.co/gnumanth/swanada)
+
+## License
+
+MIT © [Hemanth HM](https://h3manth.com)

swanada-1.0.0/README.md

@@ -0,0 +1,108 @@
+# swanada (स्वनद)
+
+In-browser, Node.js, and Python 16,000 Hz multilingual speech-to-text (STT) for Classical Sanskrit (`sa`), Indian English (`en`), and ten Indic languages (`hi`, `kn`, `mr`, `bn`, `ta`, `te`, `ml`, `gu`, `pa`, `or`) powered by 17-layer Conformer-CTC INT8 models running 100% client-side via ONNX/WASM with zero cloud or server dependencies.
+
+```bash
+npm install swanada
+```
+
+```bash
+pip install swanada
+```
+
+## Quick Start (JavaScript / TypeScript)
+
+```typescript
+import { Swanada } from 'swanada';
+
+// Initialize transcriber for Classical Sanskrit
+const transcriber = await Swanada.create({
+  language: 'sa',
+  executionProvider: 'wasm',
+  numThreads: 4,
+});
+
+// Transcribe audio Float32Array PCM or WAV ArrayBuffer
+const result = await transcriber.transcribe(audioPcmFloat32);
+console.log(`Transcript (${result.language}):`, result.text);
+console.log(`Duration: ${result.durationMs}ms | Latency: ${result.inferenceMs}ms | RTF: ${result.rtf}`);
+
+// Classical Sanskrit to Roman IAST transliteration
+const iast = Swanada.transliterateIast(result.text);
+console.log('IAST Transliteration:', iast);
+
+await transcriber.release();
+```
+
+## Quick Start (Python)
+
+```python
+from swanada import Swanada
+
+stt = Swanada.create(language="kn")  # Kannada
+result = stt.transcribe("speech_16k.wav")
+
+print("Transcript:", result.text)
+print(f"Duration: {result.duration_ms:.1f}ms | Latency: {result.inference_ms:.1f}ms | RTF: {result.rtf:.3f}")
+```
+
+## CLI Usage
+
+Dual-runtime command-line interface with identical flags:
+
+```bash
+# Node.js CLI
+npx swanada speech.wav -l sa
+npx swanada recitation.wav -l sa --json -o output.json
+cat stream.wav | npx swanada -l hi --stream
+
+# Python CLI
+swanada speech.wav -l kn
+cat stream.wav | swanada -l ta --stream
+```
+
+### Unified CLI Flags
+- `-l, --language <lang>`: Language code (default: `sa`). Supported: `sa, en, hi, kn, mr, bn, ta, te, ml, gu, pa, or`.
+- `-m, --model-dir <dir>`: Optional custom models directory.
+- `-o, --output <file>`: Output text file (default: stdout).
+- `--json`: Emit structured JSON with text, durationMs, inferenceMs, rtf, and tokens.
+- `--stream`: Simulate chunk-by-chunk streaming transcription (320 ms quanta).
+- `--iast`: Transliterate Classical Sanskrit output to Roman IAST with Vedic accents.
+- `-h, --help`: Show help and usage summary.
+- `-v, --version`: Show version (`swanada 1.0.0`).
+
+## Benchmarks
+
+Evaluated across 480 held-out 16 kHz utterances (40 per language, `B = 1,000` bootstrap 95% CIs), 1,200 unseen `google/fleurs` + wild test clips, and 72 streaming sessions (100 ms chunks):
+
+| Language | Code | Held-Out CER (95% CI) | Held-Out WER | Unseen Fleurs CER |
+| :--- | :---: | :---: | :---: | :---: |
+| Classical Sanskrit | `sa` | `5.24% [3.47%, 7.28%]` | `27.77%` | `17.10%` |
+| Indian English | `en` | `5.70% [4.41%, 7.00%]` | `16.94%` | `15.61%` |
+| Hindi | `hi` | `3.44% [2.34%, 4.53%]` | `12.64%` | `5.52%` |
+| Kannada | `kn` | `6.03% [4.65%, 7.58%]` | `35.70%` | `5.11%` |
+| Marathi | `mr` | `7.31% [4.30%, 10.50%]` | `27.52%` | `7.37%` |
+| Bengali | `bn` | `7.76% [6.07%, 9.54%]` | `40.66%` | `5.71%` |
+| Tamil | `ta` | `8.01% [6.28%, 9.86%]` | `38.46%` | `10.88%` |
+| Telugu | `te` | `5.54% [4.01%, 7.16%]` | `30.62%` | `9.05%` |
+| Malayalam | `ml` | `7.78% [5.58%, 10.13%]` | `40.27%` | `6.42%` |
+| Gujarati | `gu` | `5.32% [3.42%, 7.73%]` | `23.17%` | `6.69%` |
+| Punjabi | `pa` | `7.71% [4.69%, 11.34%]` | `29.47%` | `9.59%` |
+| Odia | `or` | `8.94% [6.25%, 12.46%]` | `37.55%` | `8.95%` |
+| **Overall (12 Langs)** | — | **`6.57% [5.94%, 7.22%]`** | **`30.06%`** | **`9.00%`** |
+
+Shared 178 MB INT8 Conformer encoder + 515 KB per-language CTC projection heads run at `0.0325x` CPU RTF, `~8-11 ms` streaming chunk latency, and `0.00%` committed prefix churn.
+
+## Live Playground
+
+- h3manth.com AI Experiments Studio: [https://h3manth.com/ai/swanada/](https://h3manth.com/ai/swanada/)
+- GitHub Pages Web Studio: [https://hemanth.github.io/swanada/](https://hemanth.github.io/swanada/)
+
+## Model Weights & Hugging Face Hub
+
+Quantized INT8 model weights are hosted on Hugging Face Hub:
+- Repository: [https://huggingface.co/gnumanth/swanada](https://huggingface.co/gnumanth/swanada)
+
+## License
+
+MIT © [Hemanth HM](https://h3manth.com)

swanada-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swanada"
+version = "1.0.0"
+description = "Swanada (स्वनद): In-browser, Node.js, and Python 16 kHz Multilingual Speech-to-Text for Classical Sanskrit, Indian English & 10 Indic languages via ONNX/WASM."
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "Hemanth HM", email = "hemanth@h3manth.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+  "numpy>=1.24.0",
+]
+
+[project.urls]
+Homepage = "https://hemanth.github.io/swanada/"
+Repository = "https://github.com/hemanth/swanada"
+
+[project.scripts]
+swanada = "swanada.cli:main"
+
+[project.optional-dependencies]
+neural = [
+  "onnxruntime>=1.18.0",
+  "soundfile>=0.12.1",
+  "scipy>=1.11.0",
+]
+dev = [
+  "pytest>=8.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["python/src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["python/src"]
+testpaths = ["tests"]
+markers = [
+  "tier1: Tier 1 feature coverage tests",
+  "tier2: Tier 2 boundary and corner case tests",
+  "tier3: Tier 3 cross-feature integration tests",
+  "tier4: Tier 4 real-world speech and benchmark tests",
+  "m1: Milestone 1 tests",
+  "m2: Milestone 2 tests",
+  "m3: Milestone 3 tests",
+  "m4: Milestone 4 tests",
+  "m5: Milestone 5 tests",
+  "f01: Feature 1 Audio Ingestion & Resampling",
+  "f02: Feature 2 Deterministic Log-Mel Frontend",
+  "f03: Feature 3 Core In-Browser ONNX/WASM Engine",
+  "f04: Feature 4 Linear-Time CTC Greedy Decoder",
+  "f05: Feature 5 Multilingual Vocabulary Registry",
+  "f06: Feature 6 Classical Sanskrit CTC Model",
+  "f07: Feature 7 Indic Languages CTC Heads",
+  "f08: Feature 8 Indian English Acoustic Head",
+  "f09: Feature 9 Streaming AudioWorklet Processor",
+  "f10: Feature 10 Background STT Web Worker",
+  "f11: Feature 11 RTF < 1.0 Protocol",
+  "f12: Feature 12 Offline CacheStorage Persistence",
+  "f13: Feature 13 JS/TS Package Parity",
+  "f14: Feature 14 Node.js Runtime Support",
+  "f15: Feature 15 Standalone Python Package",
+  "f16: Feature 16 Cross-Platform CLI Tools",
+  "f17: Feature 17 Tactile Studio Browser Playground",
+  "f18: Feature 18 Local Static Server",
+  "f19: Feature 19 Automated Browser Test Harness",
+  "f20: Feature 20 Held-Out Speech Audio Test Suite",
+  "f21: Feature 21 Empirical Accuracy & Latency Benchmarks",
+  "f22: Feature 22 Adversarial Hardening & Zero Regressions",
+]

swanada-1.0.0/python/src/swanada/__init__.py

@@ -0,0 +1,102 @@
+"""Swanada: In-browser & multi-runtime 16 kHz Multilingual Speech-to-Text."""
+
+__version__ = "1.0.0"
+
+from .audio import (
+    load_audio,
+    resample_audio,
+    parse_wav,
+    save_wav,
+)
+from .frontend import (
+    extract_log_mel_features,
+    extract_log_mel_onnx,
+    create_mel_filterbank,
+    create_padded_hann_window,
+    hz_to_mel,
+    mel_to_hz,
+)
+from .normalizer import (
+    dedup_marks,
+    repair_brahmic_orthography,
+    normalize_indic_text,
+    assemble_text,
+    join_subwords,
+)
+from .denoise import (
+    DenoiseTelemetry,
+    enhance_speech_with_telemetry,
+    denoise_pcm_16k,
+)
+from .decoder import (
+    decode_ctc,
+    decode_ctc_tokens,
+    is_special_token,
+    CTCDecodeResult,
+    CTCGreedyDecoder,
+)
+from .engine import (
+    AcousticEngine,
+    TranscriptionResult,
+)
+from .core import (
+    Swanada,
+)
+from .vocab import (
+    REGISTRY,
+    Vocabulary,
+    LanguageMeta,
+    detect_script,
+    devanagari_to_iast,
+    transliterate_iast,
+    SUPPORTED_LANGUAGES,
+    BLANK_TOKEN_ID,
+    UNK_TOKEN_ID,
+)
+from .streaming import (
+    StreamingCTCDecoder,
+    StreamingTranscript,
+    SwanadaStream,
+)
+
+__all__ = [
+    "__version__",
+    "Swanada",
+    "SwanadaStream",
+    "StreamingCTCDecoder",
+    "StreamingTranscript",
+    "TranscriptionResult",
+    "AcousticEngine",
+    "REGISTRY",
+    "Vocabulary",
+    "LanguageMeta",
+    "detect_script",
+    "devanagari_to_iast",
+    "transliterate_iast",
+    "SUPPORTED_LANGUAGES",
+    "BLANK_TOKEN_ID",
+    "UNK_TOKEN_ID",
+    "load_audio",
+    "resample_audio",
+    "parse_wav",
+    "save_wav",
+    "extract_log_mel_features",
+    "extract_log_mel_onnx",
+    "create_mel_filterbank",
+    "create_padded_hann_window",
+    "hz_to_mel",
+    "mel_to_hz",
+    "dedup_marks",
+    "repair_brahmic_orthography",
+    "normalize_indic_text",
+    "assemble_text",
+    "join_subwords",
+    "DenoiseTelemetry",
+    "enhance_speech_with_telemetry",
+    "denoise_pcm_16k",
+    "decode_ctc",
+    "decode_ctc_tokens",
+    "is_special_token",
+    "CTCDecodeResult",
+    "CTCGreedyDecoder",
+]

swanada-1.0.0/python/src/swanada/audio.py

@@ -0,0 +1,89 @@
+"""Audio loading, resampling, and WAV serialization for Swanada."""
+
+import io
+import math
+from pathlib import Path
+from typing import Tuple, Union
+import numpy as np
+
+
+def resample_audio(
+    wav: np.ndarray,
+    src_sr: int,
+    target_sr: int = 16000,
+) -> np.ndarray:
+    """Resample audio signal to target sample rate.
+
+    Uses polyphase FIR resampling (scipy.signal.resample_poly) with GCD reduction,
+    falling back to linear interpolation if scipy is unavailable.
+    """
+    if src_sr == target_sr:
+        return wav.astype(np.float32)
+
+    if len(wav) == 0:
+        return np.zeros(0, dtype=np.float32)
+
+    try:
+        import scipy.signal
+        g = math.gcd(target_sr, src_sr)
+        up = target_sr // g
+        down = src_sr // g
+        resampled = scipy.signal.resample_poly(wav, up, down)
+        return resampled.astype(np.float32)
+    except Exception:
+        num_samples = max(1, int(round(len(wav) * target_sr / src_sr)))
+        t_in = np.arange(len(wav))
+        t_out = np.linspace(0, len(wav) - 1, num_samples)
+        return np.interp(t_out, t_in, wav).astype(np.float32)
+
+
+def load_audio(
+    source: Union[str, Path, bytes, np.ndarray],
+    target_sr: int = 16000,
+) -> np.ndarray:
+    """Load audio from file path, bytes, or ndarray, converting to 16 kHz mono Float32."""
+    sr = target_sr
+
+    if isinstance(source, (str, Path)):
+        import soundfile as sf
+        wav, sr = sf.read(str(source), dtype="float32")
+    elif isinstance(source, (bytes, bytearray)):
+        import soundfile as sf
+        wav, sr = sf.read(io.BytesIO(source), dtype="float32")
+    elif isinstance(source, np.ndarray):
+        wav = source.astype(np.float32)
+    else:
+        raise TypeError(f"Unsupported audio input type: {type(source)}")
+
+    # Downmix multi-channel to mono
+    if wav.ndim > 1:
+        wav = np.mean(wav, axis=1 if wav.shape[1] < wav.shape[0] else 0)
+
+    # Scale integer PCM if unnormalized
+    if np.issubdtype(wav.dtype, np.integer):
+        wav = wav.astype(np.float32) / 32768.0
+
+    # Resample if sample rate differs
+    if sr != target_sr:
+        wav = resample_audio(wav, sr, target_sr)
+
+    return wav.astype(np.float32)
+
+
+def parse_wav(data: bytes) -> Tuple[np.ndarray, int]:
+    """Parse raw WAV byte stream into mono Float32 array and sample rate."""
+    import soundfile as sf
+    wav, sr = sf.read(io.BytesIO(data), dtype="float32")
+    if wav.ndim > 1:
+        wav = np.mean(wav, axis=1)
+    return wav.astype(np.float32), sr
+
+
+def save_wav(
+    path: Union[str, Path],
+    pcm: np.ndarray,
+    sample_rate: int = 16000,
+) -> None:
+    """Save Float32 audio as 16-bit PCM WAV."""
+    import soundfile as sf
+    sf.write(str(path), pcm.astype(np.float32), sample_rate, subtype="PCM_16")