swanada 1.0.0__py3-none-any.whl

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/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")

swanada/cli.py

@@ -0,0 +1,203 @@
+"""Command-line interface for Swanada (Multilingual Speech-to-Text)."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Any, Dict, List, Optional
+
+from .audio import load_audio
+from .core import Swanada
+from .engine import TranscriptionResult
+from .vocab import SUPPORTED_LANGUAGES
+
+
+def parse_cli_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="swanada",
+        description="Swanada (स्वनद) — 16 kHz Multilingual Indic Speech-to-Text CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  swanada audio.wav -l sa\n"
+            "  swanada speech.wav -l hi --json -o output.json\n"
+            "  cat stream.wav | swanada -l kn --stream\n"
+        ),
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        default=None,
+        help="Input WAV audio file path or '-' for stdin pipe (default: stdin if piped)",
+    )
+    parser.add_argument(
+        "-l",
+        "--language",
+        "--lang",
+        dest="language",
+        default="sa",
+        help="Target language code: sa | en | hi | kn | mr | bn | ta | te | ml | gu | pa | or (default: sa)",
+    )
+    parser.add_argument(
+        "-m",
+        "--model-dir",
+        "--model",
+        dest="model_dir",
+        default=None,
+        help="Path to custom model directory containing ONNX weights and vocabularies",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        "--out",
+        dest="output",
+        type=Path,
+        default=None,
+        help="Output file path (default: stdout)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Emit structured JSON with text, durationMs, inferenceMs, rtf, and tokens",
+    )
+    parser.add_argument(
+        "--stream",
+        action="store_true",
+        dest="stream_mode",
+        help="Simulate real-time chunked streaming transcription (320ms / 5120 sample quanta)",
+    )
+    parser.add_argument(
+        "--threads",
+        type=int,
+        default=4,
+        dest="threads",
+        help="Number of inference execution threads (default: 4)",
+    )
+    parser.add_argument(
+        "--iast",
+        action="store_true",
+        dest="iast_mode",
+        help="Transliterate Classical Sanskrit output to Roman IAST with Vedic accents",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version="swanada 1.0.0",
+        help="Display version information and exit",
+    )
+    return parser.parse_args(argv)
+
+
+def result_to_dict(result: TranscriptionResult, mode: str = "batch", text_override: Optional[str] = None) -> Dict[str, Any]:
+    transcript_text = text_override if text_override is not None else result.text
+    return {
+        "text": transcript_text,
+        "language": result.language,
+        "durationMs": float(result.duration_ms),
+        "duration_ms": float(result.duration_ms),
+        "inferenceMs": float(result.inference_ms),
+        "inference_ms": float(result.inference_ms),
+        "rtf": round(float(result.rtf), 4),
+        "tokens": list(result.tokens),
+        "mode": mode,
+    }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parse_cli_args(argv)
+
+    lang = args.language.lower().strip()
+    if lang not in SUPPORTED_LANGUAGES:
+        sys.stderr.write(
+            f"Error: Unsupported language '{lang}'. Supported languages: {', '.join(sorted(SUPPORTED_LANGUAGES))}\n"
+        )
+        return 1
+
+    # Resolve audio source
+    input_arg = args.input
+    raw_audio_bytes: Optional[bytes] = None
+    input_file_path: Optional[Path] = None
+
+    if input_arg == "-" or (input_arg is None and not sys.stdin.isatty()):
+        try:
+            raw_audio_bytes = sys.stdin.buffer.read()
+            if not raw_audio_bytes:
+                sys.stderr.write("Error: Empty standard input received.\n")
+                return 1
+        except Exception as e:
+            sys.stderr.write(f"Error reading from stdin: {e}\n")
+            return 1
+    elif input_arg:
+        input_file_path = Path(input_arg)
+        if not input_file_path.exists():
+            sys.stderr.write(f"Error: Input file not found: {input_file_path}\n")
+            return 1
+    else:
+        sys.stderr.write("Error: Missing input audio. Provide <input.wav> or pipe via stdin.\n")
+        sys.stderr.write("Usage: swanada -l <lang> [-m <model_dir>] [-o <output.txt>] [--json] [--stream] <input.wav>\n")
+        return 1
+
+    # Initialize Engine
+    try:
+        model_dir = Path(args.model_dir) if args.model_dir else None
+        stt = Swanada.create(language=lang, model_dir=model_dir, num_threads=args.threads)
+    except Exception as e:
+        sys.stderr.write(f"Error initializing Swanada engine: {e}\n")
+        return 2
+
+    # Process Audio
+    try:
+        if raw_audio_bytes is not None:
+            pcm = load_audio(raw_audio_bytes, target_sr=16000)
+        else:
+            assert input_file_path is not None
+            pcm = load_audio(input_file_path, target_sr=16000)
+
+        if args.stream_mode:
+            stream_session = stt.stream(chunk_size_samples=5120)
+            chunk_size = 5120
+            total_samples = len(pcm)
+            for offset in range(0, total_samples, chunk_size):
+                chunk = pcm[offset : offset + chunk_size]
+                stream_session.push(chunk)
+            result = stream_session.finish()
+            mode = "streaming"
+        else:
+            result = stt.transcribe(pcm)
+            mode = "batch"
+
+        final_text = result.text
+        if args.iast_mode and lang == "sa" and final_text:
+            final_text = Swanada.transliterate_iast(final_text)
+
+    except Exception as e:
+        sys.stderr.write(f"Error during transcription: {e}\n")
+        return 2
+
+    # Format Output
+    if args.json_output:
+        res_dict = result_to_dict(result, mode=mode, text_override=final_text)
+        output_payload = json.dumps(res_dict, ensure_ascii=False, indent=2) + "\n"
+    else:
+        output_payload = final_text + "\n"
+
+    # Route Output
+    if args.output:
+        try:
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            args.output.write_text(output_payload, encoding="utf-8")
+        except Exception as e:
+            sys.stderr.write(f"Error writing to output file {args.output}: {e}\n")
+            return 1
+    else:
+        sys.stdout.write(output_payload)
+        sys.stdout.flush()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

swanada/core.py

@@ -0,0 +1,117 @@
+"""High-level Swanada Speech-to-Text Interface."""
+
+from pathlib import Path
+from typing import Optional, Union
+import numpy as np
+
+from .audio import load_audio
+from .engine import AcousticEngine, TranscriptionResult
+from .vocab import REGISTRY, transliterate_iast
+
+
+def _find_model_asset(filename: str, model_dir: Optional[Union[str, Path]] = None, subfolder: str = "") -> Optional[Path]:
+    candidates = []
+    if model_dir:
+        md = Path(model_dir)
+        if subfolder:
+            candidates.append(md / subfolder / filename)
+        candidates.append(md / filename)
+        # In case model_dir is e.g. models/onnx, check parent
+        if subfolder:
+            candidates.append(md.parent / subfolder / filename)
+        candidates.append(md.parent / filename)
+
+    # Standard repository locations
+    repo_models = Path(__file__).resolve().parents[3] / "models"
+    if subfolder:
+        candidates.append(repo_models / subfolder / filename)
+    candidates.append(repo_models / filename)
+
+    for c in candidates:
+        if c.exists():
+            return c
+    return None
+
+
+class Swanada:
+    """Swanada Speech-to-Text Transcriber.
+
+    Zero server dependencies. Client-side inference via ONNX.
+    """
+
+    def __init__(
+        self,
+        language: str = "sa",
+        model_dir: Optional[Union[str, Path]] = None,
+        num_threads: int = 4,
+        preprocessor_mode: str = "analytical",
+    ):
+        self.language = language
+
+        meta = REGISTRY.get(language)
+        model_name = meta.model_filename if meta else f"swanada_{language}_ctc_int8.onnx"
+        vocab_name = meta.vocab_filename if meta else f"{language}_vocab.json"
+
+        model_path = _find_model_asset(model_name, model_dir, "onnx")
+        if model_path is None and language == "sa":
+            model_path = _find_model_asset("sushrota_sanskrit_ctc_int8.onnx", model_dir, "onnx")
+
+        vocab_path = _find_model_asset(vocab_name, model_dir, "vocabularies")
+        if vocab_path is None and language == "sa":
+            vocab_path = _find_model_asset("sanskrit_vocab.json", model_dir, "vocabularies")
+
+        preprocessor_path = _find_model_asset("preprocessor.onnx", model_dir)
+
+        self.engine = AcousticEngine(
+            model_path=model_path,
+            vocab_path=vocab_path,
+            preprocessor_path=preprocessor_path,
+            language=language,
+            num_threads=num_threads,
+            preprocessor_mode=preprocessor_mode,
+        )
+
+    @staticmethod
+    def transliterate_iast(text: str) -> str:
+        """Transliterate Classical Sanskrit Devanagari text to Roman IAST with Vedic pitch accents."""
+        return transliterate_iast(text)
+
+    @classmethod
+    def create(
+        cls,
+        language: str = "sa",
+        model_dir: Optional[Union[str, Path]] = None,
+        num_threads: int = 4,
+        preprocessor_mode: str = "analytical",
+    ) -> "Swanada":
+        """Factory constructor matching TypeScript API."""
+        return cls(
+            language=language,
+            model_dir=model_dir,
+            num_threads=num_threads,
+            preprocessor_mode=preprocessor_mode,
+        )
+
+    def transcribe(
+        self,
+        audio: Union[str, Path, bytes, np.ndarray],
+        sample_rate: int = 16000,
+    ) -> TranscriptionResult:
+        """Transcribe audio input to normalized text."""
+        return self.engine.transcribe(audio, sample_rate=sample_rate)
+
+    def stream(
+        self,
+        chunk_size_samples: int = 5120,
+        left_context_samples: int = 30720,
+        max_buffer_samples: int = 61440,
+    ) -> "SwanadaStream":
+        """Creates a streaming audio transcription pipeline."""
+        from .streaming import SwanadaStream
+        return SwanadaStream(
+            self.engine,
+            chunk_size_samples=chunk_size_samples,
+            left_context_samples=left_context_samples,
+            max_buffer_samples=max_buffer_samples,
+        )
+