readalign 1.0.0__py3-none-any.whl

readalign/report.py

@@ -0,0 +1,153 @@
+"""Build readalign-report.json and the short summary the CLI prints.
+
+Everything a reader would want to check before trusting the output goes here: how much of the
+book got timed, where the alignment drifted, and which chapters got no overlay at all.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+
+from .align import CONFIDENT, AlignmentResult
+from .audio import AudioTrack
+from .epub import EpubPackage
+from .fs import ensure_directory, write_text
+
+REPORT_VERSION = 1
+
+
+@dataclass
+class DocStat:
+    """Per content document: how much of it ended up narrated."""
+
+    manifest_id: str
+    href: str
+    sentences: int
+    aligned: int
+    max_drift: float
+    start: float | None
+    end: float | None
+
+
+def _percentile(values: list[float], fraction: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    position = min(len(ordered) - 1, max(0, round(fraction * (len(ordered) - 1))))
+    return ordered[position]
+
+
+def document_stats(package: EpubPackage, result: AlignmentResult) -> list[DocStat]:
+    timed_by_doc: dict[int, list] = {}
+    for entry in result.timed:
+        timed_by_doc.setdefault(entry.sentence.doc_index, []).append(entry)
+    stats = []
+    for index, doc in enumerate(package.docs):
+        entries = timed_by_doc.get(index, [])
+        stats.append(
+            DocStat(
+                manifest_id=doc.manifest_id,
+                href=doc.href,
+                sentences=len(doc.sentences),
+                aligned=len(entries),
+                max_drift=round(max((entry.drift for entry in entries), default=0.0), 3),
+                start=round(min(entry.start for entry in entries), 3) if entries else None,
+                end=round(max(entry.end for entry in entries), 3) if entries else None,
+            )
+        )
+    return stats
+
+
+def build_report(
+    package: EpubPackage,
+    result: AlignmentResult,
+    tracks: list[AudioTrack],
+    stats: list[DocStat],
+    *,
+    output: str,
+    asr_info: dict,
+    drift_threshold: float,
+    warnings: list[str],
+    extras: dict | None = None,
+) -> dict:
+    drifts = [entry.drift for entry in result.timed]
+    total_sentences = sum(len(doc.sentences) for doc in package.docs)
+    max_drift = round(max(drifts, default=0.0), 3)
+    return {
+        "version": REPORT_VERSION,
+        "tool": "readalign",
+        "generated": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "input": {
+            "epub": os.path.abspath(package.source),
+            "title": package.title(),
+            "epub_version": package.version,
+            "audio_files": [os.path.basename(track.source) for track in tracks],
+            "audio_duration": round(sum(track.duration for track in tracks), 3),
+            "transcoded": [
+                os.path.basename(track.source) for track in tracks if track.transcoded
+            ],
+        },
+        "output": os.path.abspath(output),
+        "asr": asr_info,
+        "coverage": {
+            "sentences": total_sentences,
+            "aligned": len(result.timed),
+            "unaligned": total_sentences - len(result.timed),
+            "interpolated": sum(1 for entry in result.timed if entry.interpolated),
+            "low_confidence": sum(1 for entry in result.timed if entry.confidence < CONFIDENT),
+            "clamped_to_track_end": sum(1 for entry in result.timed if entry.clamped),
+            "trimmed_head": result.trimmed_head,
+            "trimmed_tail": result.trimmed_tail,
+            "token_match_rate": round(
+                result.matched_tokens / result.book_tokens if result.book_tokens else 0.0, 4
+            ),
+        },
+        "drift": {
+            "threshold": drift_threshold,
+            "max": max_drift,
+            "p95": round(_percentile(drifts, 0.95), 3),
+            "mean": round(sum(drifts) / len(drifts), 3) if drifts else 0.0,
+            "within_threshold": max_drift <= drift_threshold,
+        },
+        "documents": [stat.__dict__ for stat in stats],
+        "documents_without_overlay": [stat.href for stat in stats if stat.aligned == 0],
+        "unaligned_regions": result.unaligned_regions,
+        "warnings": warnings,
+        **(extras or {}),
+    }
+
+
+def write_report(path: str, report: dict) -> None:
+    directory = os.path.dirname(os.path.abspath(path))
+    ensure_directory(directory)
+    write_text(path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+
+
+def format_summary(report: dict) -> str:
+    coverage = report["coverage"]
+    drift = report["drift"]
+    missing = report["documents_without_overlay"]
+    lines = [
+        f"  sentences      {coverage['aligned']}/{coverage['sentences']} timed "
+        f"({coverage['aligned'] / max(coverage['sentences'], 1):.1%})",
+        f"  interpolated   {coverage['interpolated']}"
+        f"   low confidence {coverage['low_confidence']}",
+        f"  token match    {coverage['token_match_rate']:.1%}",
+        f"  drift          max {drift['max']:.2f}s, p95 {drift['p95']:.2f}s, "
+        f"threshold {drift['threshold']:.2f}s",
+    ]
+    if coverage["trimmed_head"] or coverage["trimmed_tail"]:
+        lines.append(
+            f"  untimed matter {coverage['trimmed_head']} sentences before the narration, "
+            f"{coverage['trimmed_tail']} after"
+        )
+    if missing:
+        rest = f" and {len(missing) - 5} more" if len(missing) > 5 else ""
+        shown = ", ".join(missing[:5]) + rest
+        lines.append(f"  no overlay     {len(missing)} document(s): {shown}")
+    for warning in report["warnings"]:
+        lines.append(f"  warning        {warning}")
+    return "\n".join(lines)

readalign/sentences.py

@@ -0,0 +1,78 @@
+"""Sentence boundary detection for prose, good enough to drive a read-along highlight.
+
+Deliberately dependency-free and conservative: a wrong split costs one mistimed highlight,
+so the rules favour leaving two sentences joined over cutting an abbreviation in half.
+"""
+
+from __future__ import annotations
+
+import re
+
+_ABBREVIATIONS = {
+    "mr", "mrs", "ms", "dr", "prof", "sr", "jr", "st", "rev", "hon", "gen", "col", "capt",
+    "lieut", "lt", "sgt", "maj", "messrs", "mme", "mlle", "esq", "no", "vol", "chap", "fig",
+    "pp", "ed", "vs", "etc", "viz", "cf", "ibid", "al", "inc", "ltd", "co", "dept", "univ",
+    "jan", "feb", "mar", "apr", "jun", "jul", "aug", "sep", "sept", "oct", "nov", "dec",
+    "i.e", "e.g", "a.m", "p.m", "u.s", "u.k",
+}
+
+_TERMINATOR = re.compile(r"[.!?…]")
+# Typographic quotes and dashes, deliberately: real ebooks are full of them.
+_CLOSERS = "\"')]}’”»›*"  # noqa: RUF001
+_OPENERS = "\"'([{‘“«‹—–-"  # noqa: RUF001
+_WORD_BEFORE = re.compile(r"([\w.]+)$", re.UNICODE)
+
+
+def _is_abbreviation(text: str, position: int) -> bool:
+    match = _WORD_BEFORE.search(text[:position])
+    if not match:
+        return False
+    word = match[1].rstrip(".").casefold()
+    if word in _ABBREVIATIONS:
+        return True
+    # A single letter followed by a period is an initial ("J. Smith"), not a sentence end.
+    return len(word) == 1 and word.isalpha()
+
+
+def split_sentences(text: str) -> list[tuple[int, int]]:
+    """Return ``(start, end)`` character ranges of the sentences in ``text``.
+
+    Ranges exclude the whitespace between sentences and cover the whole string otherwise,
+    so callers can map a range straight back onto the markup it came from.
+    """
+    if not text.strip():
+        return []
+    ranges: list[tuple[int, int]] = []
+    start = 0
+    position = 0
+    length = len(text)
+    while position < length:
+        char = text[position]
+        if not _TERMINATOR.match(char):
+            position += 1
+            continue
+        if char == "." and _is_abbreviation(text, position):
+            position += 1
+            continue
+        end = position + 1
+        while end < length and _TERMINATOR.match(text[end]):
+            end += 1
+        while end < length and text[end] in _CLOSERS:
+            end += 1
+        rest = text[end:]
+        if rest and not rest[0].isspace():
+            position = end
+            continue
+        following = rest.lstrip()
+        if following and not (following[0].isupper() or following[0] in _OPENERS):
+            position = end
+            continue
+        chunk = text[start:end]
+        if chunk.strip():
+            ranges.append((start + len(chunk) - len(chunk.lstrip()), end))
+        start = end
+        position = end
+    tail = text[start:]
+    if tail.strip():
+        ranges.append((start + len(tail) - len(tail.lstrip()), start + len(tail.rstrip())))
+    return ranges

readalign/sidecar.py

@@ -0,0 +1,142 @@
+"""Write the sidecars: WebVTT cues for players, and one flat align.json for tooling.
+
+The EPUB is self-contained, but the same timings are useful outside it. WebVTT is per audio
+file, because that is what a player loads next to a track, so a chapter spanning two files
+produces two cue files.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import posixpath
+from collections import defaultdict
+
+from .align import AlignmentResult, TimedSentence
+from .audio import AudioTrack
+from .fs import ensure_directory, write_text
+
+SIDECAR_VERSION = 1
+
+
+def vtt_timestamp(seconds: float) -> str:
+    """WebVTT needs HH:MM:SS.mmm, and unlike SMIL it wants the hours field zero-padded."""
+    milliseconds = max(0, round(seconds * 1000))
+    hours, rest = divmod(milliseconds, 3_600_000)
+    minutes, rest = divmod(rest, 60_000)
+    secs, millis = divmod(rest, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}.{millis:03d}"
+
+
+def _cue_text(text: str) -> str:
+    collapsed = " ".join(text.split())
+    return collapsed.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def build_vtt(entries: list[TimedSentence], track: AudioTrack, audio_name: str) -> str:
+    """One WebVTT file: cues in the audio file's own timeline, not the book's."""
+    lines = ["WEBVTT", "", f"NOTE audio {audio_name}", ""]
+    for entry in entries:
+        start = max(0.0, entry.start - track.offset)
+        end = max(start + 0.001, min(entry.end - track.offset, track.duration))
+        lines.append(entry.sentence.fragment_id)
+        lines.append(f"{vtt_timestamp(start)} --> {vtt_timestamp(end)}")
+        lines.append(_cue_text(entry.sentence.text))
+        lines.append("")
+    return "\n".join(lines)
+
+
+def build_align_json(
+    result: AlignmentResult,
+    tracks: dict[int, AudioTrack],
+    doc_hrefs: dict[int, str],
+    audio_hrefs: dict[int, str],
+    *,
+    title: str | None,
+) -> str:
+    """The whole alignment as one flat JSON document, in absolute book time."""
+    rows = []
+    for entry in result.timed:
+        track = tracks[entry.track_index]
+        rows.append(
+            {
+                "id": entry.sentence.fragment_id,
+                "document": doc_hrefs.get(entry.sentence.doc_index, ""),
+                "audio": audio_hrefs.get(entry.track_index, posixpath.basename(track.href)),
+                "start": round(entry.start, 3),
+                "end": round(entry.end, 3),
+                "clip_begin": round(max(0.0, entry.start - track.offset), 3),
+                "clip_end": round(max(0.0, entry.end - track.offset), 3),
+                "confidence": entry.confidence,
+                "interpolated": entry.interpolated,
+                "drift": round(entry.drift, 3),
+                "text": " ".join(entry.sentence.text.split()),
+            }
+        )
+    payload = {
+        "version": SIDECAR_VERSION,
+        "title": title,
+        "sentences": len(rows),
+        "audio": [
+            {
+                "index": index,
+                "href": audio_hrefs.get(index, posixpath.basename(track.href)),
+                "source": os.path.basename(track.source),
+                "offset": round(track.offset, 3),
+                "duration": round(track.duration, 3),
+            }
+            for index, track in sorted(tracks.items())
+        ],
+        "alignment": rows,
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _clear_previous(directory: str) -> None:
+    """Drop the sidecars of an earlier run: a re-run can name its files differently."""
+    for name in os.listdir(directory):
+        if name == "align.json" or name.endswith(".vtt"):
+            with contextlib.suppress(OSError):
+                os.unlink(os.path.join(directory, name))
+
+
+def write_sidecars(
+    directory: str,
+    result: AlignmentResult,
+    tracks: list[AudioTrack],
+    doc_hrefs: dict[int, str],
+    audio_hrefs: dict[int, str],
+    *,
+    title: str | None = None,
+) -> list[str]:
+    """Write align.json plus one WebVTT per (document, audio file) pair. Returns the paths."""
+    by_index = {track.index: track for track in tracks}
+    ensure_directory(directory, "sidecar directory")
+    _clear_previous(directory)
+
+    grouped: dict[tuple[int, int], list[TimedSentence]] = defaultdict(list)
+    for entry in result.timed:
+        grouped[(entry.sentence.doc_index, entry.track_index)].append(entry)
+
+    written: list[str] = []
+    multi_track = {
+        doc_index
+        for doc_index in {key[0] for key in grouped}
+        if len({key[1] for key in grouped if key[0] == doc_index}) > 1
+    }
+    for (doc_index, track_index), entries in sorted(grouped.items()):
+        track = by_index[track_index]
+        href = doc_hrefs.get(doc_index, f"doc{doc_index}")
+        stem = posixpath.splitext(posixpath.basename(href))[0]
+        name = f"{stem}.part{track_index:03d}.vtt" if doc_index in multi_track else f"{stem}.vtt"
+        path = os.path.join(directory, name)
+        audio_name = audio_hrefs.get(track_index, posixpath.basename(track.href))
+        write_text(path, build_vtt(entries, track, audio_name))
+        written.append(path)
+
+    path = os.path.join(directory, "align.json")
+    write_text(path, build_align_json(result, by_index, doc_hrefs, audio_hrefs, title=title))
+    written.append(path)
+    return written
+

readalign/smil.py

@@ -0,0 +1,77 @@
+"""Write one media overlay document per content document.
+
+Structure follows EPUB 3.3 section 9.2.2: a ``smil`` root at version 3.0, a ``body`` carrying
+``par`` elements, and nested ``seq`` wrappers mirroring the structures a reading system may let
+the user skip (a footnote, a page number) or escape out of (a table, a list, a figure).
+"""
+
+from __future__ import annotations
+
+import posixpath
+
+from lxml import etree
+
+from .align import TimedSentence
+from .audio import AudioTrack
+from .clock import format_clock
+
+SMIL_NS = "http://www.w3.org/ns/SMIL"
+EPUB_NS = "http://www.idpf.org/2007/ops"
+
+_NSMAP = {None: SMIL_NS, "epub": EPUB_NS}
+
+
+def relative_href(from_path: str, to_path: str) -> str:
+    """Path from one archive member to another, as a path-relative-scheme-less-URL string."""
+    relative = posixpath.relpath(to_path, posixpath.dirname(from_path))
+    return relative.replace("\\", "/")
+
+
+def build_smil(
+    smil_path: str,
+    doc_path: str,
+    entries: list[TimedSentence],
+    tracks: dict[int, AudioTrack],
+    audio_paths: dict[int, str],
+) -> bytes:
+    """Serialise the overlay for one content document."""
+    text_href = relative_href(smil_path, doc_path)
+    root = etree.Element(f"{{{SMIL_NS}}}smil", nsmap=_NSMAP)
+    root.set("version", "3.0")
+    body = etree.SubElement(root, f"{{{SMIL_NS}}}body")
+    body.set(f"{{{EPUB_NS}}}textref", text_href)
+
+    # Open seqs, innermost last. Nesting has to mirror the document for escapability to work,
+    # and entries arrive in document order, so a structure is left as soon as its ids stop matching.
+    open_seqs: list[tuple[str, etree._Element]] = []
+    for entry in entries:
+        chain = entry.sentence.structure
+        shared = 0
+        while (
+            shared < len(open_seqs)
+            and shared < len(chain)
+            and open_seqs[shared][0] == chain[shared].container_id
+        ):
+            shared += 1
+        del open_seqs[shared:]
+        for level in chain[shared:]:
+            parent = open_seqs[-1][1] if open_seqs else body
+            seq = etree.SubElement(parent, f"{{{SMIL_NS}}}seq")
+            seq.set(f"{{{EPUB_NS}}}textref", f"{text_href}#{level.container_id}")
+            seq.set(f"{{{EPUB_NS}}}type", level.epub_type)
+            open_seqs.append((level.container_id, seq))
+        container = open_seqs[-1][1] if open_seqs else body
+        par = etree.SubElement(container, f"{{{SMIL_NS}}}par")
+        text = etree.SubElement(par, f"{{{SMIL_NS}}}text")
+        text.set("src", f"{text_href}#{entry.sentence.fragment_id}")
+        track = tracks[entry.track_index]
+        audio = etree.SubElement(par, f"{{{SMIL_NS}}}audio")
+        audio.set("src", relative_href(smil_path, audio_paths[entry.track_index]))
+        audio.set("clipBegin", format_clock(entry.start - track.offset))
+        audio.set("clipEnd", format_clock(entry.end - track.offset))
+    return etree.tostring(root, xml_declaration=True, encoding="utf-8", pretty_print=True)
+
+
+def overlay_duration(entries: list[TimedSentence]) -> float:
+    """Playing time of an overlay: the sum of its clips, which is what media:duration means."""
+    return sum(max(0.0, entry.end - entry.start) for entry in entries)

readalign/textnorm.py

@@ -0,0 +1,158 @@
+"""Turn raw words from an ebook or an ASR transcript into comparable tokens.
+
+Both sides go through :func:`tokenize_word`, so the aligner only ever compares like with like:
+case folded, accent stripped, punctuation removed, numbers and roman numerals spelled out.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_UNITS = [
+    "zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+    "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+    "seventeen", "eighteen", "nineteen",
+]
+_TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"]
+_SCALES = [(1_000_000_000, "billion"), (1_000_000, "million"), (1_000, "thousand")]
+
+_ORDINALS = {
+    "one": "first",
+    "two": "second",
+    "three": "third",
+    "five": "fifth",
+    "eight": "eighth",
+    "nine": "ninth",
+    "twelve": "twelfth",
+}
+
+_ROMAN_VALUES = {"i": 1, "v": 5, "x": 10, "l": 50, "c": 100, "d": 500, "m": 1000}
+_ROMAN_RE = re.compile(r"^M{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$")
+_ORDINAL_SUFFIX_RE = re.compile(r"^(\d+)(?:st|nd|rd|th)$")
+_DIGITS_RE = re.compile(r"\d")
+
+
+def _small_number_words(value: int) -> list[str]:
+    if value < 20:
+        return [_UNITS[value]]
+    if value < 100:
+        tens, unit = divmod(value, 10)
+        words = [_TENS[tens]]
+        if unit:
+            words.append(_UNITS[unit])
+        return words
+    hundreds, rest = divmod(value, 100)
+    words = [_UNITS[hundreds], "hundred"]
+    if rest:
+        words.extend(_small_number_words(rest))
+    return words
+
+
+def number_words(value: int) -> list[str]:
+    """Spell an integer in English, e.g. 1207 -> ['one', 'thousand', 'two', 'hundred', 'seven']."""
+    if value < 0:
+        return ["minus", *number_words(-value)]
+    if value == 0:
+        return ["zero"]
+    words: list[str] = []
+    remainder = value
+    for scale, name in _SCALES:
+        count, remainder = divmod(remainder, scale)
+        if count:
+            words.extend([*number_words(count), name])
+    if remainder:
+        words.extend(_small_number_words(remainder))
+    return words
+
+
+def _year_words(value: int) -> list[str]:
+    """Read a four-digit year the way a narrator does: 1797 -> seventeen ninety seven."""
+    high, low = divmod(value, 100)
+    if low == 0:
+        return [*_small_number_words(high), "hundred"]
+    if low < 10:
+        return [*_small_number_words(high), "oh", _UNITS[low]]
+    return [*_small_number_words(high), *_small_number_words(low)]
+
+
+def _ordinal_words(value: int) -> list[str]:
+    words = number_words(value)
+    last = words[-1]
+    if last in _ORDINALS:
+        words[-1] = _ORDINALS[last]
+    elif last.endswith("y"):
+        words[-1] = last[:-1] + "ieth"
+    else:
+        words[-1] = last + "th"
+    return words
+
+
+def roman_value(token: str) -> int | None:
+    """Value of a canonical roman numeral, or None if the token is not one."""
+    lowered = token.lower()
+    if len(lowered) < 2 or not _ROMAN_RE.match(token.upper()):
+        return None
+    total = 0
+    previous = 0
+    for char in reversed(lowered):
+        value = _ROMAN_VALUES[char]
+        total += value if value >= previous else -value
+        previous = max(previous, value)
+    return total
+
+
+def _strip_accents(text: str) -> str:
+    decomposed = unicodedata.normalize("NFKD", text)
+    return "".join(char for char in decomposed if not unicodedata.combining(char))
+
+
+def tokenize_word(raw: str) -> list[str]:
+    """Normalise one whitespace-delimited word into zero or more comparison tokens."""
+    if not raw:
+        return []
+    # Roman numerals are only recognised as written in the source, before case folding,
+    # so that the pronoun "I" and ordinary lowercase words are never rewritten as numbers.
+    stripped = re.sub(r"[^\w]", "", _strip_accents(raw), flags=re.UNICODE)
+    if not stripped:
+        return []
+    if stripped.isupper():
+        value = roman_value(stripped)
+        if value is not None:
+            return number_words(value)
+    folded = stripped.casefold()
+    if _DIGITS_RE.search(folded):
+        return _number_tokens(folded)
+    return [folded] if folded else []
+
+
+def _number_tokens(folded: str) -> list[str]:
+    ordinal = _ORDINAL_SUFFIX_RE.match(folded)
+    if ordinal:
+        return _ordinal_words(int(ordinal[1]))
+    if folded.isdigit():
+        value = int(folded)
+        if len(folded) == 4 and 1100 <= value <= 2099:
+            return _year_words(value)
+        return number_words(value)
+    # Mixed letters and digits (a chapter label like "12a", a model number): split the runs.
+    tokens: list[str] = []
+    for part in re.findall(r"\d+|[^\d]+", folded):
+        tokens.extend(number_words(int(part)) if part.isdigit() else [part])
+    return tokens
+
+
+def tokenize_words(raw_words: list[str]) -> tuple[list[str], list[int]]:
+    """Tokenise a word list, returning the tokens and the source index each token came from."""
+    tokens: list[str] = []
+    origins: list[int] = []
+    for index, raw in enumerate(raw_words):
+        for token in tokenize_word(raw):
+            tokens.append(token)
+            origins.append(index)
+    return tokens, origins
+
+
+def split_raw_words(text: str) -> list[str]:
+    """Split running text into raw words on whitespace."""
+    return text.split()