tilavet-aligner 0.1.0__tar.gz

tilavet_aligner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarık İsmet ALKAN — Tilavet
+
+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.

tilavet_aligner-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: tilavet-aligner
+Version: 0.1.0
+Summary: Monotonic / CTC forced-alignment helpers for the Tilavet Quran teleprompter pipeline.
+Author-email: Tilavet <web3alkan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tialkan/tilavet-aligner
+Project-URL: Documentation, https://github.com/tialkan/tilavet-aligner#readme
+Project-URL: Repository, https://github.com/tialkan/tilavet-aligner
+Project-URL: Issues, https://github.com/tialkan/tilavet-aligner/issues
+Project-URL: Companion, https://github.com/tialkan/tilavet-phonemizer
+Keywords: quran,alignment,forced-alignment,ctc,viterbi,phoneme,tajwid,arabic,speech-recognition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Natural Language :: Arabic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: posterior
+Requires-Dist: numpy>=1.24; extra == "posterior"
+Provides-Extra: phonemizer
+Requires-Dist: tilavet-phonemizer>=0.2.0; extra == "phonemizer"
+Provides-Extra: dev
+Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: tilavet-phonemizer>=0.2.0; extra == "dev"
+Dynamic: license-file
+
+# Tilavet Aligner
+
+Small MVP package for monotonic Quran phoneme alignment.
+
+It consumes `tilavet-phonemizer` alignment targets:
+
+```python
+target = Phonemizer().phonemize("رَيْبَ ۛ فِيهِ").to_alignment_dict()
+```
+
+and aligns frame-level phoneme log probabilities to that known target sequence.
+This package does not perform free ASR decoding.
+
+## MVP Modules
+
+- `contract.py`: validates the phonemizer alignment target JSON.
+- `posterior.py`: adapts sparse JSON, dense JSON, dense logits, and optional
+  `.npy` matrices to frame log-prob dictionaries.
+- `viterbi.py`: aligns frame log-probabilities to target phoneme symbols,
+  including optional blank-aware CTC mode.
+- `word_spans.py`: converts symbol frame spans to word-level timestamps.
+- `ctc.py`: vocabulary and frame normalization helpers.
+
+## Posterior Inputs
+
+Sparse frame dictionaries:
+
+```json
+[
+  {"a": -0.1, "b": -5.0},
+  {"a": -4.0, "b": -0.1}
+]
+```
+
+Dense matrix JSON or `.npy` input requires a vocabulary file whose order matches
+the posterior columns:
+
+```json
+["<blank>", "a", "b"]
+```
+
+CLI examples:
+
+```bash
+tilavet-align target.json sparse-frames.json
+tilavet-align target.json dense-logprobs.json --vocab-json vocab.json
+tilavet-align target.json dense-logits.npy --vocab-json vocab.json --from-logits
+tilavet-align target.json ctc-logprobs.json --ctc --blank-symbol "<blank>"
+```
+
+`--ctc` uses expanded states `[blank, s0, blank, s1, ...]`; blank frames do
+not expand word-level symbol spans.
+
+## Output Confidence
+
+Alignment output keeps the raw Viterbi `score` and adds normalized confidence
+fields:
+
+```json
+{
+  "score": -0.6,
+  "frame_count": 5,
+  "mean_log_prob": -0.12,
+  "confidence": 0.8869,
+  "words": [
+    {
+      "token": "ab",
+      "score": -0.2,
+      "scored_frames": 2,
+      "mean_log_prob": -0.1,
+      "confidence": 0.9048
+    }
+  ]
+}
+```
+
+In CTC mode, `frame_count` may include blank frames inside the timestamp span;
+`scored_frames` counts only frames assigned to the word's target symbols.
+
+## Synthetic End-to-End Demo
+
+With the sibling phonemizer source tree present:
+
+```bash
+PYTHONPATH=src python3 examples/synthetic_alignment.py \
+  --phonemizer-src "../Tilavet Phonemizer/src"
+```
+
+This runs:
+
+```text
+Arabic text -> phonemizer.to_alignment_dict() -> synthetic CTC posterior -> word timestamps
+```
+
+It is not an acoustic-model test; it is a package-boundary smoke test.
+
+## Development
+
+```bash
+python3 -m pytest -q
+python3 -m ruff check .
+```

tilavet_aligner-0.1.0/README.md

@@ -0,0 +1,102 @@
+# Tilavet Aligner
+
+Small MVP package for monotonic Quran phoneme alignment.
+
+It consumes `tilavet-phonemizer` alignment targets:
+
+```python
+target = Phonemizer().phonemize("رَيْبَ ۛ فِيهِ").to_alignment_dict()
+```
+
+and aligns frame-level phoneme log probabilities to that known target sequence.
+This package does not perform free ASR decoding.
+
+## MVP Modules
+
+- `contract.py`: validates the phonemizer alignment target JSON.
+- `posterior.py`: adapts sparse JSON, dense JSON, dense logits, and optional
+  `.npy` matrices to frame log-prob dictionaries.
+- `viterbi.py`: aligns frame log-probabilities to target phoneme symbols,
+  including optional blank-aware CTC mode.
+- `word_spans.py`: converts symbol frame spans to word-level timestamps.
+- `ctc.py`: vocabulary and frame normalization helpers.
+
+## Posterior Inputs
+
+Sparse frame dictionaries:
+
+```json
+[
+  {"a": -0.1, "b": -5.0},
+  {"a": -4.0, "b": -0.1}
+]
+```
+
+Dense matrix JSON or `.npy` input requires a vocabulary file whose order matches
+the posterior columns:
+
+```json
+["<blank>", "a", "b"]
+```
+
+CLI examples:
+
+```bash
+tilavet-align target.json sparse-frames.json
+tilavet-align target.json dense-logprobs.json --vocab-json vocab.json
+tilavet-align target.json dense-logits.npy --vocab-json vocab.json --from-logits
+tilavet-align target.json ctc-logprobs.json --ctc --blank-symbol "<blank>"
+```
+
+`--ctc` uses expanded states `[blank, s0, blank, s1, ...]`; blank frames do
+not expand word-level symbol spans.
+
+## Output Confidence
+
+Alignment output keeps the raw Viterbi `score` and adds normalized confidence
+fields:
+
+```json
+{
+  "score": -0.6,
+  "frame_count": 5,
+  "mean_log_prob": -0.12,
+  "confidence": 0.8869,
+  "words": [
+    {
+      "token": "ab",
+      "score": -0.2,
+      "scored_frames": 2,
+      "mean_log_prob": -0.1,
+      "confidence": 0.9048
+    }
+  ]
+}
+```
+
+In CTC mode, `frame_count` may include blank frames inside the timestamp span;
+`scored_frames` counts only frames assigned to the word's target symbols.
+
+## Synthetic End-to-End Demo
+
+With the sibling phonemizer source tree present:
+
+```bash
+PYTHONPATH=src python3 examples/synthetic_alignment.py \
+  --phonemizer-src "../Tilavet Phonemizer/src"
+```
+
+This runs:
+
+```text
+Arabic text -> phonemizer.to_alignment_dict() -> synthetic CTC posterior -> word timestamps
+```
+
+It is not an acoustic-model test; it is a package-boundary smoke test.
+
+## Development
+
+```bash
+python3 -m pytest -q
+python3 -m ruff check .
+```

tilavet_aligner-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tilavet-aligner"
+version = "0.1.0"
+description = "Monotonic / CTC forced-alignment helpers for the Tilavet Quran teleprompter pipeline."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Tilavet", email = "web3alkan@gmail.com" }]
+license = { text = "MIT" }
+keywords = [
+    "quran",
+    "alignment",
+    "forced-alignment",
+    "ctc",
+    "viterbi",
+    "phoneme",
+    "tajwid",
+    "arabic",
+    "speech-recognition",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+    "Natural Language :: Arabic",
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/tialkan/tilavet-aligner"
+Documentation = "https://github.com/tialkan/tilavet-aligner#readme"
+Repository = "https://github.com/tialkan/tilavet-aligner"
+Issues = "https://github.com/tialkan/tilavet-aligner/issues"
+Companion = "https://github.com/tialkan/tilavet-phonemizer"
+
+[project.scripts]
+tilavet-align = "tilavet_aligner.cli:main"
+
+[project.optional-dependencies]
+posterior = [
+    "numpy>=1.24",
+]
+phonemizer = [
+    "tilavet-phonemizer>=0.2.0",
+]
+dev = [
+    "numpy>=1.24",
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "tilavet-phonemizer>=0.2.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]

tilavet_aligner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tilavet_aligner-0.1.0/src/tilavet_aligner/__init__.py

@@ -0,0 +1,43 @@
+"""Tilavet Quran phoneme alignment helpers."""
+
+from .contract import AlignmentTarget, ContractError, PauseMarker, WordTarget, parse_target
+from .ctc import build_vocabulary, normalize_frames, symbol_to_index
+from .posterior import (
+    PosteriorError,
+    dense_to_frames,
+    frames_from_payload,
+    load_frames_json,
+    load_npy_frames,
+    load_vocabulary_json,
+)
+from .viterbi import SymbolFrame, ViterbiResult, align_ctc_frames, align_frames
+from .word_spans import AlignmentResult, PauseHint, WordAlignment, pause_hints, word_alignments
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AlignmentResult",
+    "AlignmentTarget",
+    "ContractError",
+    "PauseHint",
+    "PauseMarker",
+    "PosteriorError",
+    "SymbolFrame",
+    "ViterbiResult",
+    "WordAlignment",
+    "WordTarget",
+    "__version__",
+    "align_ctc_frames",
+    "align_frames",
+    "build_vocabulary",
+    "dense_to_frames",
+    "frames_from_payload",
+    "load_frames_json",
+    "load_npy_frames",
+    "load_vocabulary_json",
+    "normalize_frames",
+    "parse_target",
+    "pause_hints",
+    "symbol_to_index",
+    "word_alignments",
+]

tilavet_aligner-0.1.0/src/tilavet_aligner/cli.py

@@ -0,0 +1,92 @@
+"""CLI for aligning a target JSON file to frame log-probabilities."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Mapping
+from typing import Any, Optional
+
+from .contract import parse_target
+from .posterior import load_frames_json, load_npy_frames, load_vocabulary_json
+from .viterbi import align_ctc_frames, align_frames
+from .word_spans import alignment_result
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tilavet-align",
+        description="Align frame log-probabilities to a known Tilavet phoneme target.",
+    )
+    parser.add_argument("target_json", help="Path to a to_alignment_dict() JSON payload.")
+    parser.add_argument(
+        "posterior",
+        help="Path to sparse frame JSON, dense matrix JSON, or dense .npy posterior.",
+    )
+    parser.add_argument(
+        "--vocab-json",
+        help="Vocabulary JSON for dense matrix / .npy input.",
+    )
+    parser.add_argument(
+        "--from-logits",
+        action="store_true",
+        help="Treat dense matrix rows as logits and apply log-softmax.",
+    )
+    parser.add_argument(
+        "--ctc",
+        action="store_true",
+        help="Use blank-aware CTC alignment instead of simple monotonic Viterbi.",
+    )
+    parser.add_argument(
+        "--blank-symbol",
+        default="<blank>",
+        help="CTC blank symbol name. Default: <blank>.",
+    )
+    parser.add_argument(
+        "--hop-seconds",
+        type=float,
+        default=0.04,
+        help="Frame hop duration in seconds. Default: 0.04.",
+    )
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    with open(args.target_json, "r", encoding="utf-8") as handle:
+        target_payload = json.load(handle)
+
+    target = parse_target(_require_mapping(target_payload, "target_json"))
+    vocabulary = load_vocabulary_json(args.vocab_json) if args.vocab_json else None
+    if args.posterior.endswith(".npy"):
+        if vocabulary is None:
+            raise SystemExit("--vocab-json is required for .npy posterior input")
+        frames = load_npy_frames(
+            args.posterior,
+            vocabulary=vocabulary,
+            from_logits=args.from_logits,
+        )
+    else:
+        frames = load_frames_json(
+            args.posterior,
+            vocabulary=vocabulary,
+            from_logits=args.from_logits,
+        )
+    if args.ctc:
+        viterbi = align_ctc_frames(frames, target.symbols, blank=args.blank_symbol)
+    else:
+        viterbi = align_frames(frames, target.symbols)
+    result = alignment_result(target, viterbi, hop_seconds=args.hop_seconds)
+    print(json.dumps(result.to_dict(), ensure_ascii=False))
+
+
+def _require_mapping(value: Any, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise SystemExit(f"{label} must be a JSON object")
+    return value
+
+
+if __name__ == "__main__":
+    main()

tilavet_aligner-0.1.0/src/tilavet_aligner/contract.py

@@ -0,0 +1,155 @@
+"""Target contract consumed from tilavet-phonemizer."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+class ContractError(ValueError):
+    """Raised when an alignment target does not match the expected contract."""
+
+
+@dataclass(frozen=True)
+class WordTarget:
+    """A source token span over the cleaned target symbol sequence."""
+
+    token: str
+    start: int
+    end: int
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], symbol_count: int) -> "WordTarget":
+        token = _require_str(data, "token")
+        start = _require_int(data, "start")
+        end = _require_int(data, "end")
+        if not 0 <= start < end <= symbol_count:
+            raise ContractError(
+                f"invalid word span for {token!r}: {start}..{end} "
+                f"outside 0..{symbol_count}"
+            )
+        return cls(token=token, start=start, end=end)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"token": self.token, "start": self.start, "end": self.end}
+
+
+@dataclass(frozen=True)
+class PauseMarker:
+    """A pause insertion point over the cleaned target symbol sequence."""
+
+    raw_index: int
+    target_index: int
+    symbol: str = "PAUSE"
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], symbol_count: int) -> "PauseMarker":
+        raw_index = _require_int(data, "raw_index")
+        target_index = _require_int(data, "target_index")
+        symbol = str(data.get("symbol", "PAUSE"))
+        if not 0 <= target_index <= symbol_count:
+            raise ContractError(
+                f"pause target_index {target_index} outside 0..{symbol_count}"
+            )
+        if raw_index < 0:
+            raise ContractError(f"pause raw_index must be non-negative: {raw_index}")
+        return cls(raw_index=raw_index, target_index=target_index, symbol=symbol)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "raw_index": self.raw_index,
+            "target_index": self.target_index,
+            "symbol": self.symbol,
+        }
+
+
+@dataclass(frozen=True)
+class AlignmentTarget:
+    """Clean phoneme target plus word spans and pause metadata."""
+
+    symbols: tuple[str, ...]
+    words: tuple[WordTarget, ...]
+    pauses: tuple[PauseMarker, ...]
+    text: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "symbols": list(self.symbols),
+            "text": self.text,
+            "words": [word.to_dict() for word in self.words],
+            "pauses": [pause.to_dict() for pause in self.pauses],
+        }
+
+
+def parse_target(data: Mapping[str, Any], allow_pause_symbol: bool = False) -> AlignmentTarget:
+    """Validate and normalize a `PhonemizationResult.to_alignment_dict()` payload."""
+
+    symbols = _require_symbol_list(data.get("symbols"), allow_pause_symbol)
+    expected_text = " ".join(symbols)
+    text = str(data.get("text", expected_text))
+    if text != expected_text:
+        raise ContractError(f"text mismatch: expected {expected_text!r}, got {text!r}")
+
+    word_items = data.get("words", [])
+    if not _is_sequence(word_items):
+        raise ContractError("words must be a list")
+    words = tuple(
+        WordTarget.from_mapping(_require_mapping(item, "word"), len(symbols))
+        for item in word_items
+    )
+
+    pause_items = data.get("pauses", [])
+    if not _is_sequence(pause_items):
+        raise ContractError("pauses must be a list")
+    pauses = tuple(
+        PauseMarker.from_mapping(_require_mapping(item, "pause"), len(symbols))
+        for item in pause_items
+    )
+
+    return AlignmentTarget(
+        symbols=tuple(symbols),
+        text=text,
+        words=words,
+        pauses=pauses,
+    )
+
+
+def _require_symbol_list(value: Any, allow_pause_symbol: bool) -> list[str]:
+    if not _is_sequence(value):
+        raise ContractError("symbols must be a list of strings")
+
+    symbols: list[str] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, str):
+            raise ContractError(f"symbols[{index}] must be a string")
+        if item == "":
+            raise ContractError(f"symbols[{index}] must not be empty")
+        if item == "PAUSE" and not allow_pause_symbol:
+            raise ContractError("PAUSE must be metadata, not a target symbol")
+        symbols.append(item)
+    return symbols
+
+
+def _require_str(data: Mapping[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str):
+        raise ContractError(f"{key} must be a string")
+    return value
+
+
+def _require_int(data: Mapping[str, Any], key: str) -> int:
+    value = data.get(key)
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ContractError(f"{key} must be an integer")
+    return value
+
+
+def _require_mapping(value: Any, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ContractError(f"{label} must be an object")
+    return value
+
+
+def _is_sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))

tilavet_aligner-0.1.0/src/tilavet_aligner/ctc.py

@@ -0,0 +1,51 @@
+"""Small CTC vocabulary helpers for the MVP aligner."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+
+def build_vocabulary(symbols: Sequence[str], blank: str = "<blank>") -> list[str]:
+    """Return `[blank] + unique symbols` while preserving first occurrence order."""
+
+    if not blank:
+        raise ValueError("blank symbol must be non-empty")
+
+    vocabulary = [blank]
+    seen = {blank}
+    for symbol in symbols:
+        if not symbol:
+            raise ValueError("symbols must be non-empty")
+        if symbol not in seen:
+            vocabulary.append(symbol)
+            seen.add(symbol)
+    return vocabulary
+
+
+def symbol_to_index(vocabulary: Sequence[str]) -> dict[str, int]:
+    """Build a stable symbol -> index map and reject duplicates."""
+
+    mapping: dict[str, int] = {}
+    for index, symbol in enumerate(vocabulary):
+        if symbol in mapping:
+            raise ValueError(f"duplicate vocabulary symbol: {symbol!r}")
+        mapping[symbol] = index
+    return mapping
+
+
+def normalize_frames(
+    frames: Sequence[Mapping[str, float]],
+    vocabulary: Sequence[str],
+    missing_log_prob: float = -1.0e9,
+) -> list[dict[str, float]]:
+    """Project sparse frame log-prob dictionaries onto a fixed vocabulary."""
+
+    normalized: list[dict[str, float]] = []
+    for frame in frames:
+        normalized.append(
+            {
+                symbol: float(frame.get(symbol, missing_log_prob))
+                for symbol in vocabulary
+            }
+        )
+    return normalized