readalign 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,5 +1,22 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readalign
-Version: 1.2.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
@@ -263,6 +263,7 @@ take precedence over this gate when more than one check fails.
 --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
@@ -276,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
@@ -304,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>.
 
@@ -338,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.2.0 → readalign-1.3.0}/README.md

@@ -230,6 +230,7 @@ take precedence over this gate when more than one check fails.
 --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
@@ -243,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
@@ -271,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>.
 
@@ -305,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.2.0 → readalign-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "readalign"
-version = "1.2.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.2.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.2.0"
+__version__ = "1.3.0"

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

@@ -199,10 +199,12 @@ def _chapters_from(probe: dict) -> list[Chapter]:
     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":
@@ -214,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] = []
@@ -228,15 +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}")

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

@@ -21,7 +21,7 @@ from urllib.parse import unquote
 
 from . import __version__
 from .errors import InputError, ReadAlignError
-from .fs import ensure_directory, same_path
+from .fs import ensure_directory, is_within, same_path
 from .members import open_archive
 
 DEFAULT_MODEL = "large-v3-turbo"
@@ -79,6 +79,9 @@ def build_parser() -> argparse.ArgumentParser:
                        help="disable the voice-activity filter")
     build.add_argument("--audio-bitrate", default="96k",
                        help="bitrate used when audio has to be transcoded (default: 96k)")
+    build.add_argument("--audio-format", choices=["auto", "mp3"], default="auto",
+                       help="embedded audio format: auto preserves supported codecs; mp3 avoids "
+                            "AAC/Opus decoder limitations (default: auto)")
     build.add_argument("--verify", nargs="?", const="auto", default=None, metavar="EPUBCHECK",
                        help="validate the result with epubcheck after writing it (needs Java). "
                             "Pass its jar path, or leave the value off to search PATH, "
@@ -162,11 +165,8 @@ def run_build(args) -> int:
         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")
+    if args.sidecars and is_within(report_path, directory):
+        raise InputError("--report must be outside the generated sidecar directory")
 
     verification_tool = None
     if args.verify and not args.dry_run:
@@ -190,16 +190,28 @@ def run_build(args) -> int:
     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}")
+    if args.sidecars:
+        for path in [args.epub, out_path, *sources]:
+            if is_within(path, directory):
+                raise InputError(f"inputs and output EPUB must be outside the generated "
+                                 f"sidecar directory: {path}")
     log(f"preparing {len(sources)} audio file(s)")
     work_dir = args.work_dir or tempfile.mkdtemp(prefix="readalign-")
     temporary = args.work_dir is None
     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)
+            # Reserve all prepared formats before ffmpeg can modify any existing output.
+            scratch_paths = [os.path.join(work_dir, "audio", f"part{index:03d}{suffix}")
+                             for suffix in (".mp3", ".m4a", ".opus")]
+            scratch_paths.append(os.path.join(work_dir, "wav", f"part{index:03d}.wav"))
+            for path in scratch_paths:
+                if any(same_path(path, protected)
+                       for protected in [args.epub, out_path, report_path, *sources]):
+                    raise InputError(f"the work directory would overwrite an input or output: "
+                                     f"{path}")
+        tracks = prepare_tracks(sources, work_dir, args.audio_bitrate, log=log,
+                                audio_format=args.audio_format)
         if args.dry_run:
             return _dry_run_plan(package, tracks, log)
 
@@ -279,6 +291,7 @@ def run_build(args) -> int:
             drift_threshold=args.drift_threshold,
             warnings=warnings,
             extras={"elapsed_seconds": round(time.monotonic() - started, 1),
+                    "audio_format": args.audio_format,
                     "token_match_gate": {
                         "threshold": args.min_token_match,
                         "passed": (result.matched_tokens / result.book_tokens

{readalign-1.2.0 → readalign-1.3.0}/src/readalign/fs.py

@@ -24,6 +24,16 @@ def same_path(first: str, second: str) -> bool:
                 and os.path.samefile(first, second)))
 
 
+def is_within(path: str, directory: str) -> bool:
+    """Include the directory itself and resolve aliases before comparing path components."""
+    path = os.path.normcase(os.path.realpath(path))
+    directory = os.path.normcase(os.path.realpath(directory))
+    try:
+        return os.path.commonpath([path, directory]) == directory
+    except ValueError:  # Windows paths can be on different drives.
+        return False
+
+
 def write_text(path: str, text: str) -> None:
     try:
         with atomic_output(path) as temporary, \

{readalign-1.2.0 → readalign-1.3.0}/src/readalign/members.py

@@ -60,11 +60,20 @@ class MemberReader(AbstractContextManager):
     def open(self, member: SourceFile | ArchiveMember) -> BinaryIO:
         if isinstance(member, SourceFile):
             return open(member.path, "rb")
-        archive = self._archives.get(member.epub_path)
+        return self._archive(member.epub_path).open(member.name)
+
+    def size(self, member: SourceFile | ArchiveMember) -> int:
+        """Read metadata, not content, so large entries can select ZIP64 before streaming."""
+        if isinstance(member, SourceFile):
+            return os.path.getsize(member.path)
+        return self._archive(member.epub_path).getinfo(member.name).file_size
+
+    def _archive(self, path: str) -> zipfile.ZipFile:
+        archive = self._archives.get(path)
         if archive is None:
-            archive = zipfile.ZipFile(member.epub_path)
-            self._archives[member.epub_path] = archive
-        return archive.open(member.name)
+            archive = zipfile.ZipFile(path)
+            self._archives[path] = archive
+        return archive
 
     def __exit__(self, *_) -> None:
         while self._archives:

{readalign-1.2.0 → readalign-1.3.0}/src/readalign/package.py

@@ -2,7 +2,7 @@
 
 The OPF gains the audio and overlay manifest items, the ``media-overlay`` attribute on every
 narrated content document, and the ``media:`` metadata EPUB 3.3 section 9.3.5 requires. The
-archive is written mimetype-first and uncompressed, as OCF demands.
+archive is written mimetype-first, with that entry stored as OCF demands.
 """
 
 from __future__ import annotations
@@ -284,7 +284,7 @@ def build_output(
 
 
 def write_epub(path: str, files: Member, original_order: list[str]) -> None:
-    """Write an OCF archive: mimetype first and stored, everything else deflated."""
+    """Write an OCF archive: mimetype first and stored, audio stored for direct seeking."""
     ordered: list[str] = []
     seen = set()
     for name in ["mimetype", "META-INF/container.xml", *original_order]:
@@ -323,6 +323,8 @@ def _write_archive(path: str, files: Member, ordered: list[str]) -> None:
             if isinstance(data, bytes):
                 archive.writestr(info, data)
             else:
+                # zipfile must reserve a ZIP64 header before streaming a large audiobook.
+                info.file_size = read.size(data)
                 with read.open(data) as source, archive.open(info, "w") as target:
                     shutil.copyfileobj(source, target, 1 << 20)
 

{readalign-1.2.0 → readalign-1.3.0}/src/readalign/sidecar.py

@@ -11,6 +11,7 @@ import contextlib
 import json
 import os
 import posixpath
+import re
 from collections import defaultdict
 
 from .align import AlignmentResult, TimedSentence
@@ -101,6 +102,18 @@ def _clear_previous(directory: str) -> None:
                 os.unlink(os.path.join(directory, name))
 
 
+def _sidecar_stem(href: str) -> str:
+    # EPUB paths are untrusted and can contain OS separators or Windows device names.
+    stem = posixpath.splitext(posixpath.basename(href.replace("\\", "/")))[0]
+    stem = re.sub(r'[<>:"|?*\x00-\x1f]', "_", stem).rstrip(" .") or "chapter"
+    device = stem.split(".", 1)[0].upper()
+    if device in {"CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$"} or re.fullmatch(
+        r"(?:COM|LPT)[1-9¹²³]", device
+    ):
+        stem = "_" + stem
+    return stem
+
+
 def write_sidecars(
     directory: str,
     result: AlignmentResult,
@@ -128,7 +141,7 @@ def write_sidecars(
     names = {}
     for doc_index, track_index in sorted(grouped):
         href = doc_hrefs.get(doc_index, f"doc{doc_index}")
-        stem = posixpath.splitext(posixpath.basename(href))[0]
+        stem = _sidecar_stem(href)
         names[(doc_index, track_index)] = (
             f"{stem}.part{track_index:03d}.vtt" if doc_index in multi_track else f"{stem}.vtt"
         )

readalign-1.3.0/tests/test_audio.py

@@ -0,0 +1,145 @@
+"""Input discovery: patterns, directories, and the ordering between numbered files."""
+
+import shutil
+import subprocess
+
+import pytest
+
+from readalign.audio import (
+    _chapters_from,
+    _duration_of,
+    _output_plan,
+    discover_inputs,
+    ffprobe,
+    natural_key,
+    prepare_tracks,
+)
+from readalign.errors import DRMError, InputError
+
+
+def test_natural_order_puts_part2_before_part10():
+    names = ["part10.mp3", "part2.mp3", "part1.mp3"]
+    assert sorted(names, key=natural_key) == ["part1.mp3", "part2.mp3", "part10.mp3"]
+
+
+def test_a_glob_pattern_is_expanded_in_natural_order(tmp_path):
+    """The shell does not expand patterns for a native command on Windows, so readalign must."""
+    for name in ("part10.mp3", "part2.mp3", "part1.mp3"):
+        (tmp_path / name).write_bytes(b"x")
+    assert discover_inputs(str(tmp_path / "part*.mp3")) == [
+        str(tmp_path / "part1.mp3"),
+        str(tmp_path / "part2.mp3"),
+        str(tmp_path / "part10.mp3"),
+    ]
+
+
+def test_a_glob_that_matches_nothing_is_a_clear_error(tmp_path):
+    with pytest.raises(InputError, match="matched no audio files"):
+        discover_inputs(str(tmp_path / "book-*.mp3"))
+
+
+def test_a_glob_skips_files_that_are_not_audio(tmp_path):
+    (tmp_path / "a.mp3").write_bytes(b"x")
+    (tmp_path / "cover.jpg").write_bytes(b"x")
+    assert discover_inputs(str(tmp_path / "*")) == [str(tmp_path / "a.mp3")]
+
+
+def test_a_drm_file_a_glob_matches_is_refused(tmp_path):
+    (tmp_path / "a.mp3").write_bytes(b"x")
+    (tmp_path / "b.aax").write_bytes(b"x")
+    with pytest.raises(DRMError, match=r"b\.aax"):
+        discover_inputs(str(tmp_path / "*"))
+
+
+@pytest.mark.parametrize("duration", ["inf", "nan", "-1", "N/A", {}])
+def test_invalid_audio_duration_is_rejected(duration):
+    probe = {"format": {"duration": duration}, "streams": [{"codec_type": "audio"}]}
+    with pytest.raises(InputError, match="no readable duration"):
+        _duration_of(probe, "audio.mp3")
+
+
+def test_invalid_chapter_marks_are_ignored():
+    probe = {"chapters": [
+        {"start_time": "nan", "end_time": "inf"},
+        {"start_time": "-1", "end_time": "2"},
+        {"start_time": "0", "end_time": "3"},
+    ]}
+    assert len(_chapters_from(probe)) == 1
+
+
+def test_work_directory_cannot_overwrite_any_source_audio(tmp_path, monkeypatch):
+    from readalign import audio
+
+    directory = tmp_path / "audio"
+    directory.mkdir()
+    source = directory / "part001.mp3"
+    source.write_bytes(b"original")
+    monkeypatch.setattr(audio, "ffprobe", lambda path: {
+        "streams": [{"codec_type": "audio", "codec_name": "mp3"}],
+    })
+    with pytest.raises(InputError, match="overwrite source audio"):
+        prepare_tracks([str(source)], str(tmp_path), "96k", log=lambda *_: None)
+    assert source.read_bytes() == b"original"
+
+
+@pytest.mark.parametrize("codec,container,expected", [
+    ("mp3", "mp3", (".mp3", "audio/mpeg", False)),
+    ("aac", "mov,mp4,m4a,3gp,3g2,mj2", (".m4a", "audio/mp4", False)),
+    ("opus", "ogg", (".opus", "audio/ogg; codecs=opus", False)),
+    ("flac", "flac", (".m4a", "audio/mp4", True)),
+])
+def test_output_format_defaults_preserve_existing_behavior(codec, container, expected):
+    probe = {"streams": [{"codec_type": "audio", "codec_name": codec}],
+             "format": {"format_name": container}}
+    assert _output_plan("source", probe) == expected
+    assert _output_plan("source", probe, "mp3") == (".mp3", "audio/mpeg", codec != "mp3")
+
+
+def test_unknown_audio_format_is_rejected(tmp_path):
+    with pytest.raises(InputError, match="audio format"):
+        prepare_tracks([], str(tmp_path), "96k", audio_format="wav")
+
+
+@pytest.mark.skipif(not (shutil.which("ffmpeg") and shutil.which("ffprobe")),
+                    reason="ffmpeg and ffprobe are needed")
+@pytest.mark.parametrize("source_codec,suffix", [("aac", ".m4a"), ("libmp3lame", ".mp3")])
+def test_mp3_mode_prepares_real_audio_without_changing_source(tmp_path, source_codec, suffix):
+    source = tmp_path / ("narration" + suffix)
+    subprocess.run([
+        "ffmpeg", "-nostdin", "-v", "error", "-y", "-f", "lavfi", "-i",
+        "sine=frequency=440:duration=2", "-c:a", source_codec, str(source),
+    ], check=True)
+    original = source.read_bytes()
+    tracks = prepare_tracks([str(source)], str(tmp_path / "work"), "96k",
+                            log=lambda *_: None, audio_format="mp3")
+    track, = tracks
+    assert track.media_type == "audio/mpeg"
+    assert track.path.endswith(".mp3")
+    assert track.transcoded == (source_codec != "libmp3lame")
+    assert 1.9 < track.duration < 2.2
+    assert ffprobe(track.path)["streams"][0]["codec_name"] == "mp3"
+    assert source.read_bytes() == original
+
+
+@pytest.mark.skipif(not (shutil.which("ffmpeg") and shutil.which("ffprobe")),
+                    reason="ffmpeg and ffprobe are needed")
+def test_mp3_conversion_downmixes_surround_and_retains_chapters(tmp_path):
+    source = tmp_path / "surround.m4a"
+    metadata = tmp_path / "chapters.txt"
+    metadata.write_text(";FFMETADATA1\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=0\nEND=1000\n"
+                        "title=First\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=1000\nEND=2000\n"
+                        "title=Second\n", encoding="utf-8")
+    subprocess.run([
+        "ffmpeg", "-nostdin", "-v", "error", "-y", "-f", "lavfi", "-i",
+        "anullsrc=r=48000:cl=5.1", "-i", str(metadata), "-map_metadata", "1",
+        "-t", "2", "-c:a", "aac", str(source),
+    ], check=True)
+    original = source.read_bytes()
+    track, = prepare_tracks([str(source)], str(tmp_path / "work"), "96k",
+                            log=lambda *_: None, audio_format="mp3")
+    probe = ffprobe(track.path)
+    assert probe["streams"][0]["codec_name"] == "mp3"
+    assert probe["streams"][0]["channels"] == 2
+    assert [chapter.title for chapter in track.chapters] == ["First", "Second"]
+    assert track.chapters[1].start == pytest.approx(1, abs=0.05)
+    assert source.read_bytes() == original

{readalign-1.2.0 → readalign-1.3.0}/tests/test_cli.py

@@ -22,6 +22,7 @@ def test_defaults_match_the_documented_ones():
     assert args.dry_run is False
     assert args.language is None
     assert args.report is None
+    assert args.audio_format == "auto"
 
 
 def test_no_sidecars_flag():
@@ -31,6 +32,110 @@ def test_no_sidecars_flag():
     assert args.sidecars is False
 
 
+def test_unknown_audio_format_is_an_argparse_error():
+    with pytest.raises(SystemExit) as error:
+        build_parser().parse_args(["build", "--audio", "a", "--epub", "b", "--out", "c",
+                                  "--audio-format", "wav"])
+    assert error.value.code == 2
+
+
+@pytest.mark.parametrize("protected", ["ebook", "output", "report"])
+@pytest.mark.parametrize("stage", ["audio", "wav"])
+def test_work_files_cannot_overwrite_protected_paths(tmp_path, monkeypatch, capsys,
+                                                   protected, stage):
+    from readalign import audio
+
+    work = tmp_path / "work"
+    target = work / stage / ("part001.mp3" if stage == "audio" else "part001.wav")
+    target.parent.mkdir(parents=True)
+    epub = build_epub(str(target if protected == "ebook" else tmp_path / "book.epub"))
+    if protected != "ebook":
+        target.write_bytes(b"previous successful output")
+    original = target.read_bytes()
+    narration = tmp_path / "narration.mp3"
+    narration.write_bytes(b"input")
+    monkeypatch.setattr(audio, "require_ffmpeg", lambda: None)
+    monkeypatch.setattr(audio, "ffprobe", lambda *_: pytest.fail("must refuse before preparing"))
+    args = ["build", "--audio", str(narration), "--epub", epub, "--out",
+            str(target if protected == "output" else tmp_path / "out.epub"),
+            "--work-dir", str(work)]
+    if protected == "report":
+        args += ["--report", str(target)]
+    assert main(args) == 1
+    assert "overwrite" in capsys.readouterr().err
+    assert target.read_bytes() == original
+
+
+@pytest.mark.parametrize("protected", ["ebook", "audio"])
+def test_sidecar_directory_cannot_contain_protected_paths(tmp_path, monkeypatch, capsys,
+                                                        protected):
+    from readalign import audio
+
+    directory = tmp_path / "out-sidecars"
+    directory.mkdir()
+    target = directory / ("chapter1.vtt" if protected != "audio" else "narration.mp3")
+    epub = build_epub(str(target if protected == "ebook" else tmp_path / "book.epub"))
+    narration = target if protected == "audio" else tmp_path / "narration.mp3"
+    narration.write_bytes(b"input")
+    original = target.read_bytes()
+    monkeypatch.setattr(audio, "require_ffmpeg", lambda: None)
+    monkeypatch.setattr(audio, "ffprobe", lambda *_: pytest.fail("must refuse before preparing"))
+    assert main(["build", "--audio", str(narration), "--epub", epub, "--out",
+                 str(tmp_path / "out.epub")]) == 1
+    assert "sidecar" in capsys.readouterr().err
+    assert target.read_bytes() == original
+
+
+@pytest.mark.skipif(not has_ffmpeg, reason="ffmpeg is needed")
+def test_no_sidecars_allows_input_in_sidecar_directory(tmp_path):
+    directory = tmp_path / "out-sidecars"
+    directory.mkdir()
+    epub = build_epub(str(directory / "book.epub"))
+    original = (directory / "book.epub").read_bytes()
+    assert main(["build", "--audio", "examples/aesop/aesop-section-37.mp3", "--epub", epub,
+                 "--out", str(tmp_path / "out.epub"), "--no-sidecars", "--dry-run"]) == 0
+    assert (directory / "book.epub").read_bytes() == original
+
+
+@pytest.mark.skipif(not has_ffmpeg, reason="ffmpeg is needed")
+def test_mp3_build_converts_aac_and_records_requested_format(tmp_path, monkeypatch):
+    import subprocess
+
+    from conftest import speak
+    from readalign.audio import ffprobe
+    from readalign.cli import check_epub
+    from readalign.epub import load_epub
+
+    epub = build_epub(str(tmp_path / "book.epub"))
+    package = load_epub(epub)
+    words = speak([sentence for doc in package.docs for sentence in doc.sentences])
+    audio = tmp_path / "narration.m4a"
+    subprocess.run([
+        "ffmpeg", "-nostdin", "-v", "error", "-y", "-f", "lavfi", "-i",
+        "anullsrc=r=22050:cl=mono", "-t", str(words[-1].end + 2), "-c:a", "aac", str(audio),
+    ], check=True)
+    monkeypatch.setattr(
+        "readalign.asr.transcribe_tracks",
+        lambda *a, **k: (words, {"cached_tracks": 0, "seconds": 0, "device": "test"}),
+    )
+    out = tmp_path / "mp3.epub"
+    assert main(["build", "--audio", str(audio), "--epub", epub, "--out", str(out),
+                 "--audio-format", "mp3"]) == 0
+    assert check_epub(str(out))["ok"]
+    report = json.loads((tmp_path / "readalign-report.json").read_text(encoding="utf-8"))
+    assert report["audio_format"] == "mp3"
+    assert report["input"]["transcoded"] == ["narration.m4a"]
+    with zipfile.ZipFile(out) as archive:
+        audio_name, = [name for name in archive.namelist() if name.endswith(".mp3")]
+        assert archive.getinfo(audio_name).compress_type == zipfile.ZIP_STORED
+        prepared = tmp_path / "embedded.mp3"
+        prepared.write_bytes(archive.read(audio_name))
+        assert ffprobe(str(prepared))["streams"][0]["codec_name"] == "mp3"
+    sidecars = json.loads((tmp_path / "mp3-sidecars" / "align.json").read_text(encoding="utf-8"))
+    assert sidecars["audio"][0]["href"] == "audio/part001.mp3"
+    assert all(row["audio"] == "audio/part001.mp3" for row in sidecars["alignment"])
+
+
 def test_missing_subcommand_is_an_argparse_error(capsys):
     with pytest.raises(SystemExit):
         main([])

{readalign-1.2.0 → readalign-1.3.0}/tests/test_fs.py

@@ -3,11 +3,19 @@
 import pytest
 
 from readalign.errors import InputError
-from readalign.fs import unique_filenames, write_text
+from readalign.fs import is_within, unique_filenames, write_text
 from readalign.members import SourceFile
 from readalign.package import write_epub
 
 
+def test_directory_containment_compares_components(tmp_path):
+    root = tmp_path / "sidecars"
+    assert is_within(str(root / "chapter.vtt"), str(root))
+    assert is_within(str(root), str(root))
+    assert not is_within(str(tmp_path / "sidecars-other" / "chapter.vtt"), str(root))
+    assert not is_within(str(root / ".." / "book.epub"), str(root))
+
+
 @pytest.mark.parametrize("exists", [False, True])
 def test_failed_epub_write_leaves_no_partial_output(tmp_path, exists):
     target = tmp_path / "out.epub"

{readalign-1.2.0 → readalign-1.3.0}/tests/test_output.py

@@ -13,7 +13,7 @@ from conftest import CHAPTERS, STRUCTURED, build_epub, make_tracks, speak
 from readalign.align import align
 from readalign.cli import check_epub
 from readalign.epub import OPF_NS, load_epub, local_name
-from readalign.members import SourceFile
+from readalign.members import ArchiveMember, SourceFile
 from readalign.package import ACTIVE_CLASS, build_output, ensure_mimetype, write_epub
 from readalign.smil import EPUB_NS, SMIL_NS
 
@@ -211,6 +211,78 @@ def test_check_accepts_what_build_wrote(aligned, tmp_path):
     assert findings["sentences"] == len(result.timed)
 
 
+@pytest.mark.parametrize("from_archive", [False, True])
+def test_streamed_audio_selects_zip64_before_writing(tmp_path, monkeypatch, from_archive):
+    """Lower the threshold to exercise multi-gigabyte audio without a huge fixture."""
+    payload = b"a" * 4096
+    if from_archive:
+        original = tmp_path / "original.epub"
+        with zipfile.ZipFile(original, "w") as archive:
+            archive.writestr("audio.mp3", payload)
+        member = ArchiveMember(str(original), "audio.mp3")
+    else:
+        original = tmp_path / "audio.mp3"
+        original.write_bytes(payload)
+        member = SourceFile(str(original))
+    monkeypatch.setattr(zipfile, "ZIP64_LIMIT", 1024)
+    out = tmp_path / "large.epub"
+    small = tmp_path / "small.mp3"
+    small.write_bytes(b"small")
+    files = {"audio.mp3": member, "small.mp3": SourceFile(str(small))}
+    ensure_mimetype(files)
+    write_epub(str(out), files, ["small.mp3"])
+    with zipfile.ZipFile(out) as archive:
+        assert archive.read("audio.mp3") == payload
+        assert archive.getinfo("audio.mp3").extract_version == 45
+        assert archive.getinfo("small.mp3").extract_version == 20
+
+
+@pytest.mark.parametrize("shared_track", [True, False])
+def test_long_book_uses_file_local_clocks_and_stored_audio(tmp_path, shared_track):
+    from readalign.align import TimedSentence
+    from readalign.clock import parse_clock
+    from readalign.sidecar import build_vtt
+
+    chapters = [(f"Chapter {index}", "".join(
+        f"<p>Voyage sentence {n} describes the sea.</p>" for n in range(450)
+    )) for index in range(2)]
+    package = load_epub(build_epub(str(tmp_path / "long.epub"), chapters=chapters))
+    tracks = make_tracks([16 * 3600] if shared_track else [8 * 3600, 8 * 3600])
+    # These bytes exercise packaging only, not audio decoding or reader playback.
+    for track in tracks:
+        path = tmp_path / f"track{track.index}.mp3"
+        path.write_bytes(b"synthetic audio")
+        track.path = str(path)
+    by_doc = {}
+    for index, doc in enumerate(package.docs):
+        start = index * 8 * 3600 + 15.125
+        by_doc[doc.manifest_id] = [
+            TimedSentence(sentence, start + n * 2, start + n * 2 + 1.5,
+                          confidence=1.0, track_index=1 if shared_track else index + 1)
+            for n, sentence in enumerate(doc.sentences)
+        ]
+    files, summary = build_output(package, by_doc, tracks)
+    assert summary["audio_files"] == len(tracks)
+    out = str(tmp_path / "out.epub")
+    ensure_mimetype(files)
+    write_epub(out, files, package.order)
+    assert check_epub(out, probe_audio=False)["ok"]
+    with zipfile.ZipFile(out) as archive:
+        for index, doc in enumerate(package.docs):
+            root = etree.fromstring(archive.read(f"EPUB/media-overlays/chapter{index + 1}.smil"))
+            clips = list(root.iter(f"{{{SMIL_NS}}}audio"))
+            expected_start = index * 8 * 3600 + 15.125 if shared_track else 15.125
+            assert parse_clock(clips[0].get("clipBegin")) == expected_start
+            assert len(clips) == len(doc.sentences) == 450
+            track = tracks[0 if shared_track else index]
+            vtt = build_vtt(by_doc[doc.manifest_id], track, track.href)
+            assert ("08:00:15.125" if shared_track and index else "00:00:15.125") in vtt
+        for info in archive.infolist():
+            if info.filename.endswith(".mp3"):
+                assert info.compress_type == zipfile.ZIP_STORED
+                assert archive.read(info) == b"synthetic audio"
+
+
 def _clip_past_the_end(root):
     root.find(f".//{{{SMIL_NS}}}audio").set("clipEnd", "9:59:59.000")
 

{readalign-1.2.0 → readalign-1.3.0}/tests/test_sidecar_report.py

@@ -42,6 +42,31 @@ def test_collision_suffix_does_not_overwrite_an_existing_chapter_name(tmp_path):
     assert all(Path(path).is_file() for path in paths)
 
 
+@pytest.mark.parametrize("href", [
+    r"..\escaped.xhtml", r"C:\escaped.xhtml", "CON.xhtml", "NUL.part.xhtml",
+    "chapter:one.xhtml", "chapter?.xhtml", "...xhtml", "COM1.xhtml", "LPT².xhtml",
+    "CONIN$.xhtml", "control\x01.xhtml",
+])
+def test_sidecar_names_are_safe_local_leaves(tmp_path, href):
+    _, result, tracks = prepared(tmp_path)
+    directory = tmp_path / "sidecars"
+    paths = write_sidecars(str(directory), result, tracks, {0: href, 1: "chapter2.xhtml"}, {})
+    assert all(Path(path).resolve().parent == directory.resolve() for path in paths)
+    assert all(Path(path).is_file() for path in paths)
+    assert not (tmp_path / "escaped.vtt").exists()
+    names = [Path(path).name for path in paths]
+    assert all(not any(c in name for c in '<>:"|?*\\') for name in names)
+    devices = {"CON", "NUL", "COM1", "LPT²", "CONIN$"}
+    assert all(name.split(".", 1)[0].upper() not in devices for name in names)
+
+
+def test_sanitized_chapter_names_remain_unique(tmp_path):
+    _, result, tracks = prepared(tmp_path)
+    paths = write_sidecars(str(tmp_path / "sidecars"), result, tracks,
+                           {0: "chapter?.xhtml", 1: "chapter*.xhtml"}, {})
+    assert len(paths) == len({Path(path).name.casefold() for path in paths}) == 3
+
+
 def prepared(tmp_path):
     package = load_epub(build_epub(str(tmp_path / "in.epub")))
     sentences = [sentence for doc in package.docs for sentence in doc.sentences]

readalign-1.2.0/tests/test_audio.py

@@ -1,77 +0,0 @@
-"""Input discovery: patterns, directories, and the ordering between numbered files."""
-
-import pytest
-
-from readalign.audio import (
-    _chapters_from,
-    _duration_of,
-    discover_inputs,
-    natural_key,
-    prepare_tracks,
-)
-from readalign.errors import DRMError, InputError
-
-
-def test_natural_order_puts_part2_before_part10():
-    names = ["part10.mp3", "part2.mp3", "part1.mp3"]
-    assert sorted(names, key=natural_key) == ["part1.mp3", "part2.mp3", "part10.mp3"]
-
-
-def test_a_glob_pattern_is_expanded_in_natural_order(tmp_path):
-    """The shell does not expand patterns for a native command on Windows, so readalign must."""
-    for name in ("part10.mp3", "part2.mp3", "part1.mp3"):
-        (tmp_path / name).write_bytes(b"x")
-    assert discover_inputs(str(tmp_path / "part*.mp3")) == [
-        str(tmp_path / "part1.mp3"),
-        str(tmp_path / "part2.mp3"),
-        str(tmp_path / "part10.mp3"),
-    ]
-
-
-def test_a_glob_that_matches_nothing_is_a_clear_error(tmp_path):
-    with pytest.raises(InputError, match="matched no audio files"):
-        discover_inputs(str(tmp_path / "book-*.mp3"))
-
-
-def test_a_glob_skips_files_that_are_not_audio(tmp_path):
-    (tmp_path / "a.mp3").write_bytes(b"x")
-    (tmp_path / "cover.jpg").write_bytes(b"x")
-    assert discover_inputs(str(tmp_path / "*")) == [str(tmp_path / "a.mp3")]
-
-
-def test_a_drm_file_a_glob_matches_is_refused(tmp_path):
-    (tmp_path / "a.mp3").write_bytes(b"x")
-    (tmp_path / "b.aax").write_bytes(b"x")
-    with pytest.raises(DRMError, match=r"b\.aax"):
-        discover_inputs(str(tmp_path / "*"))
-
-
-@pytest.mark.parametrize("duration", ["inf", "nan", "-1", "N/A", {}])
-def test_invalid_audio_duration_is_rejected(duration):
-    probe = {"format": {"duration": duration}, "streams": [{"codec_type": "audio"}]}
-    with pytest.raises(InputError, match="no readable duration"):
-        _duration_of(probe, "audio.mp3")
-
-
-def test_invalid_chapter_marks_are_ignored():
-    probe = {"chapters": [
-        {"start_time": "nan", "end_time": "inf"},
-        {"start_time": "-1", "end_time": "2"},
-        {"start_time": "0", "end_time": "3"},
-    ]}
-    assert len(_chapters_from(probe)) == 1
-
-
-def test_work_directory_cannot_overwrite_any_source_audio(tmp_path, monkeypatch):
-    from readalign import audio
-
-    directory = tmp_path / "audio"
-    directory.mkdir()
-    source = directory / "part001.mp3"
-    source.write_bytes(b"original")
-    monkeypatch.setattr(audio, "ffprobe", lambda path: {
-        "streams": [{"codec_type": "audio", "codec_name": "mp3"}],
-    })
-    with pytest.raises(InputError, match="overwrite source audio"):
-        prepare_tracks([str(source)], str(tmp_path), "96k", log=lambda *_: None)
-    assert source.read_bytes() == b"original"