readalign 1.1.0__tar.gz → 1.3.0__tar.gz

{readalign-1.1.0 → readalign-1.3.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.3.0}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.3.0 - 2026-10-25
+
+- Fixed: work-directory audio/WAV paths cannot overwrite the input ebook, output EPUB or
+  report. Inputs must stay outside the generated sidecar directory when sidecars are enabled.
+- Fixed: chapter-derived subtitle names cannot escape the sidecar directory through Windows
+  separators or use reserved device names. Sanitized names still receive collision handling.
+- Added a real surround-AAC to stereo-MP3 regression checking retained chapter marks and
+  unchanged source bytes.
+- New: `--audio-format mp3` stream-copies existing MP3 sources and transcodes other codecs
+  to MP3 for readers with AAC/Opus decoder limitations. The default `auto` retains the existing
+  behavior. Timing uses the prepared audio and the report records the selected format.
+- Fixed: streamed audiobook entries now declare their size before ZIP writing so large files
+  select ZIP64 headers instead of failing at the end of the write. Small entries retain their
+  existing archive format.
+- Added long-book packaging regressions and evidence-linked reader guidance distinguishing
+  codec support, large-track loading, sentence highlighting and narration-position restoration.
+
+## 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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readalign
-Version: 1.1.0
+Version: 1.3.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
@@ -251,6 +263,7 @@ written; exceeding the threshold only changes the exit code to 3 so a script can
 --beam-size N            whisper beam size (default: 5)
 --no-vad                 disable the voice-activity filter
 --audio-bitrate RATE     bitrate when audio has to be transcoded (default: 96k)
+--audio-format auto|mp3  preserve supported codecs (default: auto), or use MP3 for compatibility
 --verify [JAR]           validate the result with epubcheck after writing it (needs Java);
                          pass its jar path, or leave the value off to search PATH,
                          EPUBCHECK_HOME and JAVA_HOME for one
@@ -264,6 +277,29 @@ Multiple files are ordered by natural sort, so `part2.mp3` comes before `part10.
 file covering the whole book is fine, and so is a chapter split over several files; readalign
 works from a continuous timeline and does not assume one file per chapter.
 
+For a reader that cannot decode AAC or Opus, select MP3 output:
+
+The `--audio-format` option requires readalign 1.3.0 or later.
+
+```
+readalign build --audio book.m4b --epub book.epub --out read-along.epub --audio-format mp3
+```
+
+Existing MP3 sources are stream-copied. Other codecs are re-encoded with ffmpeg's `libmp3lame`
+encoder at `--audio-bitrate` (default 96k). Re-encoding takes time and can reduce quality; it
+does not change your source files. Timings are measured against the prepared MP3, not the
+original AAC/Opus track. Changing the prepared audio also changes the transcript cache key,
+so the first build in this mode may need to transcribe again. The report records the requested
+`audio_format` and which source files were transcoded. This option does not fix reader resume
+bugs or split a long track into chapters.
+
+Use a dedicated `--work-dir`: its `audio/partNNN.mp3`, `.m4a`, `.opus` and
+`wav/partNNN.wav` paths are reserved for generated files. Builds refuse aliases of the input
+ebook, source audio, output EPUB or report at those paths before preparing audio. The generated
+`<output-name>-sidecars/` directory must also be separate from your inputs and report; previous
+`align.json` and `.vtt` files there are replaced on a rerun. Chapter-derived VTT filenames are
+sanitized for safe local paths, while `align.json` retains the original document hrefs.
+
 ### The optional refine pass
 
 `pip install 'readalign[refine]'` adds torch and torchaudio, and `--refine` then runs a CTC
@@ -292,13 +328,50 @@ it, and any run that uses it records the restriction in the report's warnings.
 
 ## Reader support
 
-Media Overlays are part of EPUB 3, but support is uneven. Readium-based readers (Thorium Reader
-on desktop, Colibrio-based web readers) and Apple Books implement them. Kindle does not read EPUB
-overlays at all, and several popular mobile readers ignore the `media-overlay` attribute and just
-show the book. If a reader shows the text but plays no audio, it does not support overlays; the
-file is still a valid EPUB and still readable.
-
-readalign's output is validated against epubcheck 5.2.1, and `readalign check` is validated
+Media Overlays are part of EPUB 3, but support is uneven. Text rendering, audio decoding,
+sentence highlighting and saving the narration position are separate capabilities. A silent
+book can mean an unsupported codec or a reader bug, not just missing overlay support.
+
+### Compatibility evidence (October 25, 2026)
+
+This is a record of available evidence, **not a personally tested reader certification table**.
+Reader fixes merged upstream may not yet be in the version you have installed.
+
+| Reader / platform | Evidence and limits |
+| --- | --- |
+| Calibre and Thorium, reporter's PC | A [Readest reporter](https://github.com/readest/readest/issues/6989) says their large narrated EPUB plays in both. Versions and complete seek/reopen behavior were not recorded. |
+| Readest, web and desktop | [#7004](https://github.com/readest/readest/pull/7004) fixes loading a large stored audio entry without copying it all into memory. Upstream tested a 921 MB shared MP3, including an eight-hour seek. This is upstream testing, not a readalign reader test. |
+| Readest, Android and iOS | [#7010](https://github.com/readest/readest/pull/7010) and [#7019](https://github.com/readest/readest/pull/7019) extend direct audio access to native players. Upstream tests are described in those PRs; they do not establish playback of every readalign book. |
+| Readest, Linux app | The maintainer [reports no AAC decoder](https://github.com/readest/readest/issues/6989#issuecomment-6357568308). Try `--audio-format mp3`; updating for large-track fixes alone does not resolve that codec limitation. |
+| Episteme, Android | An [independent readalign-output user](https://github.com/Aryan-Raj3112/episteme/issues/579) reports narration restarting at the beginning of a long section after reopening. The same book highlights sentences correctly on PC. No readalign-side fix is established. |
+| Apple Books and other readers | Overlay support alone is not proof of long-track seeking or saved narration position. These behaviors have not been verified here. |
+| Kindle | EPUB Media Overlays are not supported. |
+
+### Long books and playback troubleshooting
+
+1. Run `readalign check read-along.epub` and, if available, epubcheck. A clean result checks
+   package structure and clip bounds, not whether a specific reader plays or resumes correctly.
+2. Check the reader version and audio codec. MP3 output is an option for AAC/Opus decoder
+   limitations; an EPUB can be valid while a reader cannot decode its narration.
+3. For large books, use a reader version containing its large-track fixes. readalign stores
+   prepared MP3/M4A/Opus entries without ZIP compression so readers can seek directly. A reader
+   may still extract or copy the whole track before playback. One overlay per content document
+   does not mean the audio is split into separate files. If you already own chapter-sized
+   narration files, pass their directory; they are naturally sorted.
+4. Test a later chapter, cross a chapter boundary, pause/resume, then close and reopen the book.
+   Saving the text position is not the same as saving the narration sentence and audio offset.
+   Re-encoding to MP3 is not a guaranteed workaround for narration-position loss.
+5. Compare the same EPUB in another overlay-capable reader. If only one reader fails, include
+   that comparison when reporting it rather than assuming the EPUB generation is defective.
+
+When reporting a problem, include readalign's version, reader version, OS/device, audio format,
+approximate track duration/size, the chapter and sentence where it happens, and whether it is
+startup, seeking, highlighting or reopening that fails. Include the output of `readalign check`
+and a short public-domain reproduction if possible. Reports and sidecars can contain local paths
+and quoted book text: inspect them before sharing. Do not upload a copyrighted book or narration
+unless you have permission.
+
+readalign's sample output is validated against epubcheck 5.2.1, and `readalign check` is validated
 against the reference Media Overlays title from the EPUB test suite at
 <https://epubtest.org/test-books>.
 
@@ -311,6 +384,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.
@@ -325,9 +399,12 @@ python -m pytest tests -q
 python -m ruff check .
 ```
 
-The suite runs in about a second and needs neither a GPU nor network access; it builds its own
+The suite needs neither a GPU nor network access; it builds its own
 EPUBs and synthesises word timings. A few cases need ffmpeg and skip without it, and one is
 skipped unless `READALIGN_MO_TESTBOOK` points at a copy of the epubtest.org Media Overlays book.
+Long-book packaging tests cover shared 16-hour timelines, separate-track clock resets, stored
+audio entries and ZIP64 selection using a lowered size threshold. Synthetic timings and a lowered
+threshold do not substitute for a real multi-gigabyte book or reader playback test.
 
 ## Distribution
 

{readalign-1.1.0 → readalign-1.3.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
@@ -218,6 +230,7 @@ written; exceeding the threshold only changes the exit code to 3 so a script can
 --beam-size N            whisper beam size (default: 5)
 --no-vad                 disable the voice-activity filter
 --audio-bitrate RATE     bitrate when audio has to be transcoded (default: 96k)
+--audio-format auto|mp3  preserve supported codecs (default: auto), or use MP3 for compatibility
 --verify [JAR]           validate the result with epubcheck after writing it (needs Java);
                          pass its jar path, or leave the value off to search PATH,
                          EPUBCHECK_HOME and JAVA_HOME for one
@@ -231,6 +244,29 @@ Multiple files are ordered by natural sort, so `part2.mp3` comes before `part10.
 file covering the whole book is fine, and so is a chapter split over several files; readalign
 works from a continuous timeline and does not assume one file per chapter.
 
+For a reader that cannot decode AAC or Opus, select MP3 output:
+
+The `--audio-format` option requires readalign 1.3.0 or later.
+
+```
+readalign build --audio book.m4b --epub book.epub --out read-along.epub --audio-format mp3
+```
+
+Existing MP3 sources are stream-copied. Other codecs are re-encoded with ffmpeg's `libmp3lame`
+encoder at `--audio-bitrate` (default 96k). Re-encoding takes time and can reduce quality; it
+does not change your source files. Timings are measured against the prepared MP3, not the
+original AAC/Opus track. Changing the prepared audio also changes the transcript cache key,
+so the first build in this mode may need to transcribe again. The report records the requested
+`audio_format` and which source files were transcoded. This option does not fix reader resume
+bugs or split a long track into chapters.
+
+Use a dedicated `--work-dir`: its `audio/partNNN.mp3`, `.m4a`, `.opus` and
+`wav/partNNN.wav` paths are reserved for generated files. Builds refuse aliases of the input
+ebook, source audio, output EPUB or report at those paths before preparing audio. The generated
+`<output-name>-sidecars/` directory must also be separate from your inputs and report; previous
+`align.json` and `.vtt` files there are replaced on a rerun. Chapter-derived VTT filenames are
+sanitized for safe local paths, while `align.json` retains the original document hrefs.
+
 ### The optional refine pass
 
 `pip install 'readalign[refine]'` adds torch and torchaudio, and `--refine` then runs a CTC
@@ -259,13 +295,50 @@ it, and any run that uses it records the restriction in the report's warnings.
 
 ## Reader support
 
-Media Overlays are part of EPUB 3, but support is uneven. Readium-based readers (Thorium Reader
-on desktop, Colibrio-based web readers) and Apple Books implement them. Kindle does not read EPUB
-overlays at all, and several popular mobile readers ignore the `media-overlay` attribute and just
-show the book. If a reader shows the text but plays no audio, it does not support overlays; the
-file is still a valid EPUB and still readable.
-
-readalign's output is validated against epubcheck 5.2.1, and `readalign check` is validated
+Media Overlays are part of EPUB 3, but support is uneven. Text rendering, audio decoding,
+sentence highlighting and saving the narration position are separate capabilities. A silent
+book can mean an unsupported codec or a reader bug, not just missing overlay support.
+
+### Compatibility evidence (October 25, 2026)
+
+This is a record of available evidence, **not a personally tested reader certification table**.
+Reader fixes merged upstream may not yet be in the version you have installed.
+
+| Reader / platform | Evidence and limits |
+| --- | --- |
+| Calibre and Thorium, reporter's PC | A [Readest reporter](https://github.com/readest/readest/issues/6989) says their large narrated EPUB plays in both. Versions and complete seek/reopen behavior were not recorded. |
+| Readest, web and desktop | [#7004](https://github.com/readest/readest/pull/7004) fixes loading a large stored audio entry without copying it all into memory. Upstream tested a 921 MB shared MP3, including an eight-hour seek. This is upstream testing, not a readalign reader test. |
+| Readest, Android and iOS | [#7010](https://github.com/readest/readest/pull/7010) and [#7019](https://github.com/readest/readest/pull/7019) extend direct audio access to native players. Upstream tests are described in those PRs; they do not establish playback of every readalign book. |
+| Readest, Linux app | The maintainer [reports no AAC decoder](https://github.com/readest/readest/issues/6989#issuecomment-6357568308). Try `--audio-format mp3`; updating for large-track fixes alone does not resolve that codec limitation. |
+| Episteme, Android | An [independent readalign-output user](https://github.com/Aryan-Raj3112/episteme/issues/579) reports narration restarting at the beginning of a long section after reopening. The same book highlights sentences correctly on PC. No readalign-side fix is established. |
+| Apple Books and other readers | Overlay support alone is not proof of long-track seeking or saved narration position. These behaviors have not been verified here. |
+| Kindle | EPUB Media Overlays are not supported. |
+
+### Long books and playback troubleshooting
+
+1. Run `readalign check read-along.epub` and, if available, epubcheck. A clean result checks
+   package structure and clip bounds, not whether a specific reader plays or resumes correctly.
+2. Check the reader version and audio codec. MP3 output is an option for AAC/Opus decoder
+   limitations; an EPUB can be valid while a reader cannot decode its narration.
+3. For large books, use a reader version containing its large-track fixes. readalign stores
+   prepared MP3/M4A/Opus entries without ZIP compression so readers can seek directly. A reader
+   may still extract or copy the whole track before playback. One overlay per content document
+   does not mean the audio is split into separate files. If you already own chapter-sized
+   narration files, pass their directory; they are naturally sorted.
+4. Test a later chapter, cross a chapter boundary, pause/resume, then close and reopen the book.
+   Saving the text position is not the same as saving the narration sentence and audio offset.
+   Re-encoding to MP3 is not a guaranteed workaround for narration-position loss.
+5. Compare the same EPUB in another overlay-capable reader. If only one reader fails, include
+   that comparison when reporting it rather than assuming the EPUB generation is defective.
+
+When reporting a problem, include readalign's version, reader version, OS/device, audio format,
+approximate track duration/size, the chapter and sentence where it happens, and whether it is
+startup, seeking, highlighting or reopening that fails. Include the output of `readalign check`
+and a short public-domain reproduction if possible. Reports and sidecars can contain local paths
+and quoted book text: inspect them before sharing. Do not upload a copyrighted book or narration
+unless you have permission.
+
+readalign's sample output is validated against epubcheck 5.2.1, and `readalign check` is validated
 against the reference Media Overlays title from the EPUB test suite at
 <https://epubtest.org/test-books>.
 
@@ -278,6 +351,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.
@@ -292,9 +366,12 @@ python -m pytest tests -q
 python -m ruff check .
 ```
 
-The suite runs in about a second and needs neither a GPU nor network access; it builds its own
+The suite needs neither a GPU nor network access; it builds its own
 EPUBs and synthesises word timings. A few cases need ffmpeg and skip without it, and one is
 skipped unless `READALIGN_MO_TESTBOOK` points at a copy of the epubtest.org Media Overlays book.
+Long-book packaging tests cover shared 16-hour timelines, separate-track clock resets, stored
+audio entries and ZIP64 selection using a lowered size threshold. Synthetic timings and a lowered
+threshold do not substitute for a real multi-gigabyte book or reader playback test.
 
 ## Distribution
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "readalign"
-version = "1.1.0"
+version = "1.3.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.3.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.3.0"

{readalign-1.1.0 → readalign-1.3.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.3.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,17 +192,19 @@ 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))
     return chapters
 
 
-def _output_plan(path: str, probe: dict) -> tuple[str, str, bool]:
+def _output_plan(path: str, probe: dict, audio_format: str = "auto") -> tuple[str, str, bool]:
     """Pick the extension, media type and whether a transcode is needed for a source file."""
     stream = _audio_stream(probe, path)
     codec = (stream.get("codec_name") or "").lower()
+    if audio_format == "mp3":
+        return ".mp3", "audio/mpeg", codec != "mp3"
     names = (probe.get("format", {}).get("format_name") or "").split(",")
     container = {name.strip() for name in names}
     if codec == "mp3":
@@ -212,13 +216,17 @@ def _output_plan(path: str, probe: dict) -> tuple[str, str, bool]:
     return ".m4a", "audio/mp4", True
 
 
-def prepare_tracks(sources: list[str], workdir: str, bitrate: str, log=print) -> list[AudioTrack]:
+def prepare_tracks(
+    sources: list[str], workdir: str, bitrate: str, log=print, *, audio_format: str = "auto",
+) -> list[AudioTrack]:
     """Copy or transcode every source into an EPUB core media type and measure the result.
 
     MP3, AAC-in-MP4 and Opus-in-Ogg are core media types in EPUB 3, so they are stream-copied.
     Anything else (FLAC, WAV, ALAC, WMA) is transcoded to AAC, because a reading system is not
-    required to play it.
+    required to play it. Explicit MP3 output avoids AAC/Opus decoder limitations in some readers.
     """
+    if audio_format not in {"auto", "mp3"}:
+        raise InputError("audio format must be auto or mp3")
     audio_dir = os.path.join(workdir, "audio")
     os.makedirs(audio_dir, exist_ok=True)
     tracks: list[AudioTrack] = []
@@ -226,13 +234,17 @@ def prepare_tracks(sources: list[str], workdir: str, bitrate: str, log=print) ->
     for index, source in enumerate(sources, start=1):
         probe = ffprobe(source)
         _reject_drm(source, probe)
-        suffix, media_type, transcode = _output_plan(source, probe)
+        suffix, media_type, transcode = _output_plan(source, probe, audio_format)
         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'}")
+        codec_label = "MP3" if suffix == ".mp3" else "AAC"
+        log(f"  {label} -> {'transcoding to ' + codec_label if transcode else 'stream copy'}")
         command = ["ffmpeg", "-nostdin", "-v", "error", "-y", "-i", source,
                    "-map", "0:a:0", "-map_chapters", "0", "-vn"]
-        command += ["-c:a", "aac", "-b:a", bitrate] if transcode else ["-c:a", "copy"]
+        codec = "libmp3lame" if suffix == ".mp3" else "aac"
+        command += ["-c:a", codec, "-b:a", bitrate] if transcode else ["-c:a", "copy"]
         if suffix == ".m4a":
             command += ["-movflags", "+faststart"]
         result = _run([*command, target], f"preparing {source}")
@@ -265,6 +277,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,