readalign 1.1.0__tar.gz → 1.2.0__tar.gz

{readalign-1.1.0 → readalign-1.2.0}/.gitignore

@@ -1,20 +1,20 @@
-__pycache__/
-*.py[cod]
-*.egg-info/
-.eggs/
-build/
-dist/
-.venv/
-venv/
-.pytest_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-*.epub
-!examples/aesop/*.epub
-readalign-report.json
-*-sidecars/
-.readalign-cache/
-examples/output/
-.DS_Store
-Thumbs.db
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.epub
+!examples/aesop/*.epub
+readalign-report.json
+*-sidecars/
+.readalign-cache/
+examples/output/
+.DS_Store
+Thumbs.db

{readalign-1.1.0 → readalign-1.2.0}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.2.0 - 2026-10-22
+
+- New: `--report PATH` selects a separate JSON report for each batch build, with guards
+  against overwriting input audio, the input/output EPUB or generated sidecars.
+- Fixed: colliding overlay names and URL-special characters in EPUB resource paths.
+  Generated audio and CSS also avoid overwriting unrelated existing resources.
+- Fixed: transcript cache identity now hashes prepared audio bytes and includes chapter
+  boundaries and the effective language. Malformed cached words are ignored instead of crashing.
+- Fixed: EPUB, report and cache writes replace their destinations only after a complete write.
+- Fixed: work-directory audio aliases, invalid durations, chapter marks and beam sizes are
+  rejected; missing epubcheck paths fail before transcription.
+- Fixed: `check` rejects unmanifested audio, overlays pointing outside their associated document,
+  empty overlays, duplicate manifest ids and mismatched durations. Corrupt archives produce
+  readable errors; audio-probe scratch filenames never come from archive member names.
+- New: `--min-token-match FRACTION` optionally gates builds on the fraction of book tokens
+  matched to narration. Values range from 0 to 1; the default 0 preserves existing behaviour.
+  A failed gate exits 5 after writing the EPUB, report and enabled sidecars. Its threshold and
+  verdict are recorded under `token_match_gate`; drift and epubcheck failures retain precedence.
+- Fixed: chapters with identical basenames in different EPUB directories could overwrite each
+  other's WebVTT sidecars. Colliding names now gain a numeric suffix, including case-only
+  collisions on Windows, without changing filenames for non-colliding exports.
+- Fixed: the ebook overwrite guard now recognises symbolic links, hard links and path aliases.
+- Fixed: non-finite drift thresholds such as NaN and infinity are rejected before processing.
+
 ## 1.1.0 - 2026-10-04
 
 - New: `--verify [JAR]` runs epubcheck on the result right after the build, prints its verdict,

{readalign-1.1.0 → readalign-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readalign
-Version: 1.1.0
+Version: 1.2.0
 Summary: Turn an audiobook and the matching ebook you own into one EPUB 3 with Media Overlays.
 Project-URL: Homepage, https://github.com/Booyaka101/readalign
 Project-URL: Repository, https://github.com/Booyaka101/readalign
@@ -210,13 +210,23 @@ Drift is how far a sentence's start could be wrong, in seconds.
 `--drift-threshold` (default 2.5s) is a gate on the maximum, not the average. The EPUB is always
 written; exceeding the threshold only changes the exit code to 3 so a script can catch it.
 
+For batch builds, `--min-token-match 0.9` also requires at least 90% of the ebook's normalised
+tokens to match the narration. This optional gate defaults to 0 (disabled). A failed gate exits 5
+but keeps the EPUB, report and enabled sidecars for inspection. The report's `token_match_gate`
+records the threshold and verdict using the unrounded match fraction. Unnarrated front matter
+and abridgements lower this score, so choose a threshold appropriate to your books. This is a
+screening aid, not proof that every sentence is correctly timed. Drift and epubcheck failures
+take precedence over this gate when more than one check fails.
+
 ## How it works
 
 1. **ffprobe** reads every audio file. FLAC, WAV, ALAC and WMA are transcoded to AAC because
    EPUB 3 only takes MP3, MP4 audio and Opus; MP3, M4A/M4B and Opus are stream-copied, so no
    audio is re-encoded unless it has to be.
 2. **faster-whisper** transcribes with word timestamps. Transcripts are cached per file, keyed by
-   content and settings, so a second run over the same audiobook costs nothing.
+   a streamed SHA-256 of the prepared audio, chapter boundaries and recogniser settings.
+   A second run avoids transcription, but still prepares and hashes the audio. Older cache keys
+   are invalidated once; malformed entries are ignored and rebuilt.
 3. Both sides are normalised to comparable tokens: case folded, accents stripped, punctuation
    dropped, digits and roman numerals spelled out ("Chapter XVIII" and "chapter eighteen" become
    the same tokens).
@@ -240,9 +250,11 @@ written; exceeding the threshold only changes the exit code to 3 so a script can
 --audio PATH             a file, a directory of numbered files, or a glob
 --epub PATH              the matching DRM-free EPUB
 --out PATH               the EPUB to write
+--report PATH            JSON report path (default: readalign-report.json beside --out)
 --model NAME             faster-whisper model (default: large-v3-turbo)
 --language CODE          ISO code of the narration (default: detect)
 --drift-threshold SECS   exit 3 if any sentence drifts more than this (default: 2.5)
+--min-token-match N      exit 5 if matched book-token fraction is below N (0 to 1; default: 0)
 --sidecars/--no-sidecars write WebVTT and align.json next to the output (default: on)
 --dry-run                probe the inputs and print the plan, transcribe nothing
 --narrator NAME          value for the media:narrator metadata
@@ -311,6 +323,7 @@ against the reference Media Overlays title from the EPUB test suite at
 | 2 | the input is DRM-protected |
 | 3 | the EPUB was written but max drift exceeded `--drift-threshold` |
 | 4 | the EPUB was written but epubcheck reported problems (only with `--verify`) |
+| 5 | the EPUB was written but token match was below `--min-token-match` |
 | 130 | interrupted |
 
 Failures print one line, not a traceback.

{readalign-1.1.0 → readalign-1.2.0}/README.md

@@ -177,13 +177,23 @@ Drift is how far a sentence's start could be wrong, in seconds.
 `--drift-threshold` (default 2.5s) is a gate on the maximum, not the average. The EPUB is always
 written; exceeding the threshold only changes the exit code to 3 so a script can catch it.
 
+For batch builds, `--min-token-match 0.9` also requires at least 90% of the ebook's normalised
+tokens to match the narration. This optional gate defaults to 0 (disabled). A failed gate exits 5
+but keeps the EPUB, report and enabled sidecars for inspection. The report's `token_match_gate`
+records the threshold and verdict using the unrounded match fraction. Unnarrated front matter
+and abridgements lower this score, so choose a threshold appropriate to your books. This is a
+screening aid, not proof that every sentence is correctly timed. Drift and epubcheck failures
+take precedence over this gate when more than one check fails.
+
 ## How it works
 
 1. **ffprobe** reads every audio file. FLAC, WAV, ALAC and WMA are transcoded to AAC because
    EPUB 3 only takes MP3, MP4 audio and Opus; MP3, M4A/M4B and Opus are stream-copied, so no
    audio is re-encoded unless it has to be.
 2. **faster-whisper** transcribes with word timestamps. Transcripts are cached per file, keyed by
-   content and settings, so a second run over the same audiobook costs nothing.
+   a streamed SHA-256 of the prepared audio, chapter boundaries and recogniser settings.
+   A second run avoids transcription, but still prepares and hashes the audio. Older cache keys
+   are invalidated once; malformed entries are ignored and rebuilt.
 3. Both sides are normalised to comparable tokens: case folded, accents stripped, punctuation
    dropped, digits and roman numerals spelled out ("Chapter XVIII" and "chapter eighteen" become
    the same tokens).
@@ -207,9 +217,11 @@ written; exceeding the threshold only changes the exit code to 3 so a script can
 --audio PATH             a file, a directory of numbered files, or a glob
 --epub PATH              the matching DRM-free EPUB
 --out PATH               the EPUB to write
+--report PATH            JSON report path (default: readalign-report.json beside --out)
 --model NAME             faster-whisper model (default: large-v3-turbo)
 --language CODE          ISO code of the narration (default: detect)
 --drift-threshold SECS   exit 3 if any sentence drifts more than this (default: 2.5)
+--min-token-match N      exit 5 if matched book-token fraction is below N (0 to 1; default: 0)
 --sidecars/--no-sidecars write WebVTT and align.json next to the output (default: on)
 --dry-run                probe the inputs and print the plan, transcribe nothing
 --narrator NAME          value for the media:narrator metadata
@@ -278,6 +290,7 @@ against the reference Media Overlays title from the EPUB test suite at
 | 2 | the input is DRM-protected |
 | 3 | the EPUB was written but max drift exceeded `--drift-threshold` |
 | 4 | the EPUB was written but epubcheck reported problems (only with `--verify`) |
+| 5 | the EPUB was written but token match was below `--min-token-match` |
 | 130 | interrupted |
 
 Failures print one line, not a traceback.

{readalign-1.1.0 → readalign-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "readalign"
-version = "1.1.0"
+version = "1.2.0"
 description = "Turn an audiobook and the matching ebook you own into one EPUB 3 with Media Overlays."
 readme = "README.md"
 requires-python = ">=3.11"

{readalign-1.1.0 → readalign-1.2.0}/src/readalign/__init__.py

@@ -1,3 +1,3 @@
 """readalign: build an EPUB 3 with Media Overlays from an audiobook and the matching ebook."""
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"

{readalign-1.1.0 → readalign-1.2.0}/src/readalign/asr.py

@@ -10,6 +10,7 @@ import contextlib
 import glob
 import hashlib
 import json
+import math
 import os
 import site
 import time
@@ -17,6 +18,7 @@ from dataclasses import asdict, dataclass
 
 from .audio import AudioTrack, read_wav_segment
 from .errors import DependencyError
+from .fs import atomic_output
 
 _CUDA_READY = False
 
@@ -152,13 +154,17 @@ def _cache_key(
     track: AudioTrack, model: str, language: str | None, vad: bool, beam_size: int,
     window_seconds: float,
 ) -> str:
-    stat = os.stat(track.path)
-    payload = "|".join(
-        [os.path.basename(track.source), str(stat.st_size), f"{track.duration:.3f}",
-         model, language or "auto", str(vad), f"beam{beam_size}",
-         f"window{window_seconds:g}"]
-    )
-    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:20]
+    digest = hashlib.sha256()
+    # Size and duration are not identities: edited tracks can retain both.
+    with open(track.path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    settings = {"version": 2, "model": model, "language": language, "vad": vad,
+                "beam_size": beam_size, "window_seconds": window_seconds,
+                "duration": track.duration,
+                "chapters": [(chapter.start, chapter.end) for chapter in track.chapters]}
+    digest.update(json.dumps(settings, sort_keys=True).encode("utf-8"))
+    return digest.hexdigest()
 
 
 def _load_cached(cache_dir: str | None, key: str) -> tuple[list[Word], str | None] | None:
@@ -169,13 +175,26 @@ def _load_cached(cache_dir: str | None, key: str) -> tuple[list[Word], str | Non
     try:
         with open(path, encoding="utf-8") as handle:
             data = json.load(handle)
-    except (OSError, json.JSONDecodeError):
+    except (OSError, ValueError, UnicodeError):
         return None
     try:
         # Caches written before the language was recorded are a bare list of words.
-        if isinstance(data, list):
-            return [Word(**entry) for entry in data], None
-        return [Word(**entry) for entry in data["words"]], data.get("language")
+        if not isinstance(data, (dict, list)):
+            return None
+        rows = data if isinstance(data, list) else data["words"]
+        language = None if isinstance(data, list) else data.get("language")
+        if not isinstance(rows, list) or (language is not None and not isinstance(language, str)):
+            return None
+        words = [Word(**entry) for entry in rows]
+        for word in words:
+            if not isinstance(word.text, str) or not word.text.strip():
+                return None
+            values = (word.start, word.end, word.probability)
+            if any(type(value) not in (int, float) or not math.isfinite(value) for value in values):
+                return None
+            if word.start < 0 or word.end < word.start or not 0 <= word.probability <= 1:
+                return None
+        return words, language
     except (KeyError, TypeError):
         return None
 
@@ -188,7 +207,7 @@ def _store_cached(
     try:
         os.makedirs(cache_dir, exist_ok=True)
         path = os.path.join(cache_dir, f"{key}.json")
-        with open(path, "w", encoding="utf-8") as handle:
+        with atomic_output(path) as temporary, open(temporary, "w", encoding="utf-8") as handle:
             json.dump({"language": language, "words": [asdict(w) for w in words]}, handle)
     except OSError as exc:
         log(f"  warning: could not write the transcript cache: {exc}")
@@ -220,7 +239,7 @@ def transcribe_tracks(
 
     for track in tracks:
         key = (
-            _cache_key(track, model_name, language, vad, beam_size, window_seconds)
+            _cache_key(track, model_name, settings.language, vad, beam_size, window_seconds)
             if cache_dir
             else ""
         )

{readalign-1.1.0 → readalign-1.2.0}/src/readalign/audio.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import glob as globlib
 import json
+import math
 import os
 import re
 import shutil
@@ -19,6 +20,7 @@ from dataclasses import dataclass, field
 import numpy as np
 
 from .errors import DependencyError, DRMError, InputError
+from .fs import same_path
 
 AUDIO_EXTENSIONS = {
     ".mp3", ".m4a", ".m4b", ".mp4", ".flac", ".ogg", ".oga", ".opus", ".wav", ".aiff", ".aif",
@@ -117,9 +119,9 @@ def _duration_of(probe: dict, path: str) -> float:
         if value:
             try:
                 duration = float(value)
-            except ValueError:
+            except (TypeError, ValueError):
                 continue
-            if duration > 0:
+            if math.isfinite(duration) and duration > 0:
                 return duration
     raise InputError(f"{path} has no readable duration; is it a complete audio file?")
 
@@ -190,7 +192,7 @@ def _chapters_from(probe: dict) -> list[Chapter]:
             end = float(entry.get("end_time", 0.0))
         except (TypeError, ValueError):
             continue
-        if end <= start:
+        if not math.isfinite(start) or not math.isfinite(end) or start < 0 or end <= start:
             continue
         title = (entry.get("tags") or {}).get("title") or f"Chapter {len(chapters) + 1}"
         chapters.append(Chapter(start=start, end=end, title=title))
@@ -228,6 +230,8 @@ def prepare_tracks(sources: list[str], workdir: str, bitrate: str, log=print) ->
         _reject_drm(source, probe)
         suffix, media_type, transcode = _output_plan(source, probe)
         target = os.path.join(audio_dir, f"part{index:03d}{suffix}")
+        if any(same_path(target, original) for original in sources):
+            raise InputError(f"the work directory would overwrite source audio: {target}")
         label = f"[{index}/{len(sources)}] {os.path.basename(source)}"
         log(f"  {label} -> {'transcoding to AAC' if transcode else 'stream copy'}")
         command = ["ffmpeg", "-nostdin", "-v", "error", "-y", "-i", source,
@@ -265,6 +269,8 @@ def decode_wav(track: AudioTrack, workdir: str) -> str:
     wav_dir = os.path.join(workdir, "wav")
     os.makedirs(wav_dir, exist_ok=True)
     target = os.path.join(wav_dir, f"part{track.index:03d}.wav")
+    if same_path(target, track.source):
+        raise InputError(f"the work directory would overwrite source audio: {target}")
     result = _run(
         [
             "ffmpeg", "-nostdin", "-v", "error", "-y", "-i", track.path,

{readalign-1.1.0 → readalign-1.2.0}/src/readalign/cli.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import math
 import os
 import posixpath
 import shutil
@@ -15,10 +16,12 @@ import sys
 import tempfile
 import time
 import zipfile
+import zlib
 from urllib.parse import unquote
 
 from . import __version__
 from .errors import InputError, ReadAlignError
+from .fs import ensure_directory, same_path
 from .members import open_archive
 
 DEFAULT_MODEL = "large-v3-turbo"
@@ -46,6 +49,8 @@ def build_parser() -> argparse.ArgumentParser:
                        help="audio file, or a directory of numbered files, or a glob")
     build.add_argument("--epub", required=True, help="the matching DRM-free EPUB")
     build.add_argument("--out", required=True, help="path of the EPUB to write")
+    build.add_argument("--report", default=None, metavar="PATH",
+                       help="JSON report path (default: readalign-report.json beside --out)")
     build.add_argument("--model", default=DEFAULT_MODEL,
                        help=f"faster-whisper model (default: {DEFAULT_MODEL})")
     build.add_argument("--language", default=None,
@@ -53,6 +58,9 @@ def build_parser() -> argparse.ArgumentParser:
     build.add_argument("--drift-threshold", type=float, default=DEFAULT_DRIFT, metavar="SECONDS",
                        help="fail if any sentence drifts more than this "
                             f"(default: {DEFAULT_DRIFT})")
+    build.add_argument("--min-token-match", type=float, default=0.0, metavar="FRACTION",
+                       help="exit 5 if the matched book-token fraction is below this "
+                            "(0 to 1, default: 0, disabled)")
     sidecars = build.add_mutually_exclusive_group()
     sidecars.add_argument("--sidecars", dest="sidecars", action="store_true", default=True,
                           help="write WebVTT and align.json next to the output (default)")
@@ -134,13 +142,37 @@ def run_build(args) -> int:
     started = time.monotonic()
     warnings: list[str] = []
 
-    if args.drift_threshold <= 0:
-        raise InputError("--drift-threshold must be a positive number of seconds")
+    if not math.isfinite(args.drift_threshold) or args.drift_threshold <= 0:
+        raise InputError("--drift-threshold must be a finite positive number of seconds")
+    if not math.isfinite(args.min_token_match) or not 0 <= args.min_token_match <= 1:
+        raise InputError("--min-token-match must be a finite fraction between 0 and 1")
+    if args.beam_size < 1:
+        raise InputError("--beam-size must be a positive integer")
     out_path = os.path.abspath(args.out)
     if os.path.isdir(out_path):
         raise InputError(f"--out points at a directory: {out_path}")
-    if out_path == os.path.abspath(args.epub):
+    if same_path(out_path, args.epub):
         raise InputError("--out is the same file as --epub, which would overwrite your ebook")
+    report_path = os.path.abspath(args.report) if args.report else os.path.join(
+        os.path.dirname(out_path), "readalign-report.json"
+    )
+    if os.path.isdir(report_path):
+        raise InputError(f"--report points at a directory: {report_path}")
+    if same_path(report_path, args.epub) or same_path(report_path, out_path):
+        raise InputError("--report would overwrite the input or output EPUB")
+    directory = os.path.join(os.path.dirname(out_path),
+                             os.path.splitext(os.path.basename(out_path))[0] + "-sidecars")
+    if args.sidecars:
+        sidecar_root = os.path.normcase(os.path.realpath(directory))
+        report_real = os.path.normcase(os.path.realpath(report_path))
+        if report_real == sidecar_root or report_real.startswith(sidecar_root + os.sep):
+            raise InputError("--report must be outside the generated sidecar directory")
+
+    verification_tool = None
+    if args.verify and not args.dry_run:
+        from .verify import find_epubcheck
+
+        verification_tool = find_epubcheck(args.verify)
 
     require_ffmpeg()
     log(f"readalign {__version__}")
@@ -155,11 +187,18 @@ def run_build(args) -> int:
     log(f"  {len(package.docs)} content documents, {len(sentences)} sentences")
 
     sources = discover_inputs(args.audio)
+    for source in sources:
+        if same_path(out_path, source) or same_path(report_path, source):
+            raise InputError(f"an output path would overwrite source audio: {source}")
     log(f"preparing {len(sources)} audio file(s)")
     work_dir = args.work_dir or tempfile.mkdtemp(prefix="readalign-")
     temporary = args.work_dir is None
-    os.makedirs(work_dir, exist_ok=True)
+    ensure_directory(work_dir, "work directory")
     try:
+        for index in range(1, len(sources) + 1):
+            wav_path = os.path.join(work_dir, "wav", f"part{index:03d}.wav")
+            if any(same_path(wav_path, source) for source in [args.epub, *sources]):
+                raise InputError(f"the work directory would overwrite an input: {wav_path}")
         tracks = prepare_tracks(sources, work_dir, args.audio_bitrate, log=log)
         if args.dry_run:
             return _dry_run_plan(package, tracks, log)
@@ -217,11 +256,10 @@ def run_build(args) -> int:
 
         verification = None
         if args.verify:
-            from .verify import find_epubcheck, run_epubcheck
+            from .verify import run_epubcheck
 
-            tool = find_epubcheck(args.verify)
             log("verifying with epubcheck")
-            verification = run_epubcheck(out_path, tool, log=log)
+            verification = run_epubcheck(out_path, verification_tool, log=log)
 
         stats = document_stats(package, result)
         for doc in package.docs:
@@ -241,19 +279,19 @@ def run_build(args) -> int:
             drift_threshold=args.drift_threshold,
             warnings=warnings,
             extras={"elapsed_seconds": round(time.monotonic() - started, 1),
+                    "token_match_gate": {
+                        "threshold": args.min_token_match,
+                        "passed": (result.matched_tokens / result.book_tokens
+                                   if result.book_tokens else 0.0) >= args.min_token_match,
+                    },
                     "overlay_duration": summary["total_duration"],
                     **({"verify": verification} if verification is not None else {})},
         )
-        report_path = os.path.join(os.path.dirname(out_path) or ".", "readalign-report.json")
         write_report(report_path, report)
 
         if args.sidecars:
             from .sidecar import write_sidecars
 
-            directory = os.path.join(
-                os.path.dirname(out_path) or ".",
-                os.path.splitext(os.path.basename(out_path))[0] + "-sidecars",
-            )
             written = write_sidecars(
                 directory, result, tracks,
                 {index: doc.href for index, doc in enumerate(package.docs)},
@@ -275,17 +313,25 @@ def run_build(args) -> int:
         print(
             f"readalign: max drift {report['drift']['max']:.2f}s exceeds the "
             f"--drift-threshold of {args.drift_threshold:.2f}s. The EPUB was still written; "
-            f"check readalign-report.json for where it slipped.",
+            f"check {report_path} for where it slipped.",
             file=sys.stderr,
         )
         return 3
     if verification is not None and not verification["ok"]:
         print(
             "readalign: epubcheck reported problems with the output; the lines above are its "
-            "own. See the verify section of readalign-report.json.",
+            f"own. See the verify section of {report_path}.",
             file=sys.stderr,
         )
         return 4
+    if not report["token_match_gate"]["passed"]:
+        print(
+            f"readalign: token match {report['coverage']['token_match_rate']:.1%} is below "
+            f"--min-token-match {args.min_token_match:.1%}. The EPUB was still written; "
+            f"inspect {report_path} for unmatched regions.",
+            file=sys.stderr,
+        )
+        return 5
     return 0
 
 
@@ -304,7 +350,8 @@ def _open_package(archive, path: str):
     if "META-INF/container.xml" not in names:
         raise InputError(f"{path} has no META-INF/container.xml, so it is not an EPUB")
     try:
-        container = etree.fromstring(archive.read("META-INF/container.xml"))
+        container = etree.fromstring(archive.read("META-INF/container.xml"),
+                                     etree.XMLParser(resolve_entities=False))
     except etree.XMLSyntaxError as exc:
         raise InputError(
             f"{path}: META-INF/container.xml is not well-formed XML: {exc}"
@@ -316,7 +363,8 @@ def _open_package(archive, path: str):
     if opf_path not in names:
         raise InputError(f"{path} names a package document that is missing: {opf_path}")
     try:
-        return opf_path, etree.fromstring(archive.read(opf_path))
+        return opf_path, etree.fromstring(archive.read(opf_path),
+                                         etree.XMLParser(resolve_entities=False))
     except etree.XMLSyntaxError as exc:
         raise InputError(
             f"{path}: the package document {opf_path} is not well-formed XML: {exc}"
@@ -367,18 +415,19 @@ def _fragment_ids(
 def _probe_clip_ends(archive, max_clip_end: dict[str, float], errors: list[str],
                      warnings: list[str]) -> dict[str, float]:
     """Acceptance check: no clipEnd may sit past the real duration ffprobe reports."""
-    from .audio import ffprobe
+    from .audio import _duration_of, ffprobe
 
     durations: dict[str, float] = {}
     with tempfile.TemporaryDirectory(prefix="readalign-check-") as scratch:
-        for audio_path, clip_end in sorted(max_clip_end.items()):
-            extracted = os.path.join(scratch, posixpath.basename(audio_path))
+        for index, (audio_path, clip_end) in enumerate(sorted(max_clip_end.items())):
+            # Archive names are URL paths, not trusted OS filenames (especially on Windows).
+            extracted = os.path.join(scratch, f"audio-{index:04d}")
             with archive.open(audio_path) as source, open(extracted, "wb") as handle:
                 shutil.copyfileobj(source, handle, 1 << 20)
             try:
-                duration = float(ffprobe(extracted)["format"]["duration"])
+                duration = _duration_of(ffprobe(extracted), audio_path)
             except (ReadAlignError, KeyError, ValueError, TypeError) as exc:
-                warnings.append(f"could not probe {audio_path}: {exc}")
+                errors.append(f"could not probe {audio_path}: {exc}")
                 continue
             durations[audio_path] = round(duration, 3)
             if clip_end > duration + 0.05:
@@ -391,6 +440,13 @@ def _probe_clip_ends(archive, max_clip_end: dict[str, float], errors: list[str],
 
 def check_epub(path: str, *, probe_audio: bool = True) -> dict:
     """Validate the media overlays of an EPUB. Structural faults are reported, not raised."""
+    try:
+        return _check_epub(path, probe_audio=probe_audio)
+    except (zipfile.BadZipFile, zlib.error, NotImplementedError, RuntimeError) as exc:
+        raise InputError(f"{path} is not a readable EPUB: {exc}") from None
+
+
+def _check_epub(path: str, *, probe_audio: bool) -> dict:
     from lxml import etree
 
     from .clock import parse_clock
@@ -401,6 +457,8 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
     warnings: list[str] = []
     with open_archive(path) as archive:
         names = set(archive.namelist())
+        if len(names) != len(archive.namelist()):
+            errors.append("the archive contains duplicate member names")
         entries = archive.infolist()
         if not entries or entries[0].filename != "mimetype":
             errors.append("the first archive entry is not 'mimetype'")
@@ -411,6 +469,13 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
 
         opf_path, opf = _open_package(archive, path)
         items = {item.get("id"): item for item in opf.iter(f"{{{OPF_NS}}}item") if item.get("id")}
+        manifest_items = list(opf.iter(f"{{{OPF_NS}}}item"))
+        if len(items) != len(manifest_items):
+            errors.append("the manifest has missing or duplicate item ids")
+        manifested = {
+            _resolve(opf_path, item.get("href", "")): item.get("media-type", "")
+            for item in items.values()
+        }
         spine = [ref.get("idref") for ref in opf.iter(f"{{{OPF_NS}}}itemref") if ref.get("idref")]
         for idref in spine:
             if idref not in items:
@@ -448,12 +513,17 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
             if overlay_id not in durations:
                 warnings.append(f"overlay '{overlay_id}' has no media:duration metadata")
             try:
-                smil = etree.fromstring(archive.read(smil_path))
+                smil = etree.fromstring(archive.read(smil_path),
+                                         etree.XMLParser(resolve_entities=False))
             except etree.XMLSyntaxError as exc:
                 errors.append(f"{smil_path}: the overlay is not well-formed XML: {exc}")
                 continue
             overlay_clip = 0.0
-            for par in smil.iter(f"{{{SMIL_NS}}}par"):
+            overlay_pars = list(smil.iter(f"{{{SMIL_NS}}}par"))
+            if smil.tag != f"{{{SMIL_NS}}}smil" or not overlay_pars:
+                errors.append(f"{smil_path}: overlay has no SMIL par elements")
+            expected_document = _resolve(opf_path, item.get("href", ""))
+            for par in overlay_pars:
                 pars += 1
                 text = par.find(f"{{{SMIL_NS}}}text")
                 audio = par.find(f"{{{SMIL_NS}}}audio")
@@ -463,6 +533,10 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
                 src = text.get("src")
                 doc_path = _resolve(smil_path, src)
                 fragment = unquote(src.split("#", 1)[1]) if "#" in src else ""
+                if doc_path != expected_document:
+                    errors.append(f"{smil_path}: text points outside its associated document")
+                if manifested.get(doc_path) not in {"application/xhtml+xml", "image/svg+xml"}:
+                    errors.append(f"{smil_path}: text target is not a manifested content document")
                 if doc_path not in names:
                     errors.append(f"{smil_path}: text points at a missing document {doc_path}")
                 elif fragment:
@@ -473,6 +547,8 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
                     errors.append(f"{smil_path}: a par has no audio src")
                     continue
                 audio_path = _resolve(smil_path, audio.get("src"))
+                if not manifested.get(audio_path, "").startswith("audio/"):
+                    errors.append(f"{smil_path}: audio target is not a manifested audio file")
                 if audio_path not in names:
                     errors.append(f"{smil_path}: audio points at a missing file {audio_path}")
                     continue
@@ -489,7 +565,7 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
             clip_total += overlay_clip
             declared = durations.get(overlay_id)
             if declared is not None and abs(declared - overlay_clip) > 1.0:
-                warnings.append(
+                errors.append(
                     f"overlay '{overlay_id}' declares {declared:.3f}s but its clips total "
                     f"{overlay_clip:.3f}s"
                 )
@@ -503,6 +579,11 @@ def check_epub(path: str, *, probe_audio: bool = True) -> dict:
             errors.append("no spine document has a media-overlay attribute")
         if total_meta is None and overlays:
             warnings.append("the package has no unrefined media:duration for the whole book")
+        elif total_meta is not None and abs(total_meta - clip_total) > 1.0:
+            errors.append(
+                f"package media:duration declares {total_meta:.3f}s but its clips total "
+                f"{clip_total:.3f}s"
+            )
 
     return {
         "epub": os.path.abspath(path),