m4bmaker-filter 1.1.1__py3-none-any.whl

m4bmaker/__init__.py

@@ -0,0 +1,3 @@
+"""m4bmaker — convert a directory of audio files into a single .m4b audiobook."""
+
+__version__ = "1.1.1"

m4bmaker/__main__.py

@@ -0,0 +1,351 @@
+"""m4bmaker — entry point: wire all modules and drive the conversion pipeline."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from argparse import Namespace
+from pathlib import Path
+
+from m4bmaker import __version__
+from m4bmaker.chapters import format_chapter_table
+from m4bmaker.chapters_file import load_chapters_file
+from m4bmaker.cli import parse_args
+from m4bmaker.cover import download_cover, find_cover, is_url
+from m4bmaker.encoder import _render_bar
+from m4bmaker.errors import EncodeCancelled, M4BError
+from m4bmaker.metadata import extract_metadata, prompt_missing
+from m4bmaker.models import BookMetadata, Chapter
+from m4bmaker.pipeline import load_audiobook, run_pipeline
+from m4bmaker.preflight import format_preflight_report, run_preflight
+from m4bmaker.repair import apply_repair, format_repair_report, run_repair
+from m4bmaker.utils import find_ffmpeg, find_ffprobe, log, safe_input
+from m4bmaker.utils import sanitize_filename_component as _safe
+
+
+def _output_path(base_dir: Path, meta: dict[str, str], flat: bool = False) -> Path:
+    """Derive the output .m4b path from metadata.
+
+    Default (organized): ``base_dir/Author/Title/Author - Title.m4b``
+    With *flat*:         ``base_dir/Author - Title.m4b``
+    """
+    title = meta.get("title", "").strip()
+    author = meta.get("author", "").strip()
+
+    if title and author:
+        stem = f"{_safe(author)} - {_safe(title)}"
+        if flat:
+            return base_dir / f"{stem}.m4b"
+        return base_dir / _safe(author) / _safe(title) / f"{stem}.m4b"
+    elif title:
+        stem = _safe(title)
+        if flat:
+            return base_dir / f"{stem}.m4b"
+        return base_dir / stem / f"{stem}.m4b"
+    else:
+        return base_dir / "audiobook.m4b"
+
+
+def _confirm_output(proposed: Path, interactive: bool) -> Path:
+    """Confirm or override the output path interactively."""
+    if not interactive:
+        return proposed
+    value = safe_input(f"Output [{proposed}]: ").strip()
+    if not value:
+        return proposed
+    return Path(value).expanduser().resolve()
+
+
+def _print_chapter_table(chapters: list[Chapter]) -> None:
+    """Print the chapter preview table to stdout (TTY + interactive only)."""
+    print(f"\n  Chapters ({len(chapters)})")
+    print(format_chapter_table(chapters))
+    print()
+
+
+def _edit_chapters_inline(chapters: list[Chapter]) -> list[Chapter]:
+    """Interactively edit chapter titles one by one.
+
+    For each chapter the current title is shown as a prefill; pressing Enter
+    keeps it, typing a new value replaces it.
+    """
+    edited: list[Chapter] = []
+    for ch in chapters:
+        value = safe_input(f"  Chapter {ch.index} [{ch.title}]: ").strip()
+        edited.append(
+            Chapter(
+                index=ch.index,
+                start_time=ch.start_time,
+                title=value if value else ch.title,
+                source_file=ch.source_file,
+            )
+        )
+    return edited
+
+
+def _hints_from_dirname(directory: Path) -> dict[str, str]:
+    """Extract title/author hints from an 'Author - Title' directory name."""
+    name = directory.name
+    if " - " in name:
+        author, _, title = name.partition(" - ")
+        return {"author": author.strip(), "title": title.strip()}
+    return {"title": name.strip()}
+
+
+def _probe_progress(i: int, n: int, name: str) -> None:
+    """Display a progress bar while probing file durations."""
+    if not sys.stdout.isatty():
+        log(f"  [{i}/{n}] {name}")
+        return
+    bar = _render_bar(i / n, width=30)
+    max_name = 35
+    disp = (name[: max_name - 1] + "\u2026") if len(name) > max_name else name
+    sys.stdout.write(f"\r  Probing {bar}  {i}/{n}  {disp:<{max_name}}\033[K")
+    sys.stdout.flush()
+    if i == n:
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
+def _resolve_cover(
+    cover_arg: str | None,
+    directory: Path,
+    tmp_dir: Path,
+    interactive: bool,
+) -> tuple[Path | None, bool]:
+    """Resolve the cover image from CLI argument, directory scan, or user prompt.
+
+    Returns ``(cover, user_specified)`` where *user_specified* is ``True`` when
+    the user explicitly provided a URL or path (via CLI or interactive prompt),
+    indicating that no further confirmation is needed.
+
+    Resolution order:
+    1. *cover_arg* provided — URL: download (retry interactively on failure);
+       local path: passed directly to :func:`find_cover`.
+    2. Auto-detect a single image file in *directory*.
+    3. If *interactive*, prompt the user for a URL or local path.
+    """
+    if cover_arg is not None:
+        if is_url(cover_arg):
+            return _fetch_cover_url(cover_arg, tmp_dir, interactive), True
+        return find_cover(directory, cli_override=Path(cover_arg).expanduser()), True
+
+    cover = find_cover(directory)
+    if cover is not None:
+        return cover, False  # auto-detected — needs confirmation
+
+    if interactive:
+        return _prompt_cover(tmp_dir), True  # user explicitly typed URL/path
+    return None, False
+
+
+def _fetch_cover_url(url: str, tmp_dir: Path, interactive: bool) -> Path | None:
+    """Download a cover image URL.
+
+    On failure, prompt for retry if *interactive*; otherwise raise.
+    """
+    pending: str | None = url
+    while True:
+        if pending is not None:
+            try:
+                return download_cover(pending, tmp_dir)
+            except Exception as exc:
+                log(f"Cover download failed: {exc}")
+        if not interactive:
+            raise M4BError("Error: cover download failed.")
+        source = safe_input(
+            "Enter a different URL or local path (or press Enter to skip): "
+        ).strip()
+        if not source:
+            return None
+        if is_url(source):
+            pending = source
+        else:
+            path = Path(source).expanduser()
+            if path.is_file():
+                return path
+            log(f"File not found: {path} — please try again.")
+            pending = None
+
+
+def _prompt_cover(tmp_dir: Path) -> Path | None:
+    """Interactively prompt for a cover image URL or local path.
+
+    Loops until a valid source is provided or the user presses Enter to skip.
+    """
+    while True:
+        source = safe_input(
+            "Enter URL or local path for cover art (or press Enter to skip): "
+        ).strip()
+        if not source:
+            return None
+        try:
+            if is_url(source):
+                return download_cover(source, tmp_dir)
+            path = Path(source).expanduser()
+            if path.is_file():
+                return path
+            log(f"File not found: {path} — please try again.")
+        except Exception as exc:
+            log(f"Cover error: {exc} — please try again.")
+
+
+def _confirm_cover(
+    cover: Path | None,
+    tmp_dir: Path,
+    interactive: bool,
+) -> Path | None:
+    """Confirm or replace the selected cover image interactively."""
+    if not interactive:
+        return cover
+    while True:
+        display = str(cover) if cover else "none"
+        value = safe_input(f"Cover image [{display}]: ").strip()
+        if not value:
+            return cover  # confirmed as-is
+        if value.lower() in ("none", "skip"):
+            return None
+        try:
+            if is_url(value):
+                return download_cover(value, tmp_dir)
+            path = Path(value).expanduser()
+            if path.is_file():
+                return path
+            log(f"File not found: {path} — please try again.")
+        except Exception as exc:
+            log(f"Cover error: {exc} — please try again.")
+
+
+def _run(args: Namespace) -> None:
+    """Drive the conversion pipeline. Raises M4BError/EncodeCancelled on failure."""
+    directory: Path = args.directory.resolve()
+    interactive = not args.no_prompt
+
+    log(f"m4bmaker {__version__}")
+    log(f"Working directory: {directory}")
+
+    # 1. Detect tool locations (raises M4BError if missing).
+    ffmpeg = find_ffmpeg()
+    ffprobe = find_ffprobe()
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+
+        # 2. Scan the directory first, so a bad path surfaces the scanner's
+        # clean error instead of find_cover's raw FileNotFoundError.
+        log("Scanning audio files…")
+        book = load_audiobook(directory, ffprobe, progress_fn=_probe_progress)
+        log(f"Found {len(book.files)} audio file(s)")
+
+        # 2b. Locate cover image (URL download, auto-detect, or interactive prompt).
+        log("Looking for cover art...")
+        cover, cover_user_specified = _resolve_cover(
+            args.cover, directory, tmp_dir, interactive
+        )
+        if cover:
+            log(f"Cover art: {cover.name}")
+        else:
+            log("No cover art found — skipping")
+
+        # 2c. Confirm or replace cover interactively.
+        if not cover_user_specified:
+            cover = _confirm_cover(cover, tmp_dir, interactive)
+
+        # 3b. Audio preflight analysis.
+        log("Analysing audio formats…")
+        analysis = run_preflight(book.files, ffprobe)
+        print(format_preflight_report(analysis))
+
+        # 3c. Repair damaged / non-standard input files. The result is
+        # passed into run_pipeline below so repair does not run a second
+        # time inside the pipeline.
+        log("Checking for damaged audio files…")
+        repair_result = run_repair(book.files, tmp_dir, ffmpeg, ffprobe)
+        if repair_result.needed_repair:
+            print(format_repair_report(repair_result))
+            book.files = apply_repair(book.files, repair_result)
+
+        # 3d. Override chapters from --chapters-file if supplied.
+        if args.chapters_file:
+            book.chapters = load_chapters_file(args.chapters_file)
+            log(
+                f"Loaded {len(book.chapters)} chapter(s) from {args.chapters_file.name}"
+            )
+        else:
+            log(f"Generated {len(book.chapters)} chapter(s)")
+
+        # Override cover with resolved value (interactive or CLI-supplied).
+        book.cover = cover
+
+        # 4. Complete metadata interactively.
+        log("Reading metadata...")
+        raw_meta = extract_metadata(book.files[0])
+        hints = _hints_from_dirname(directory)
+        filled = prompt_missing(raw_meta, args, hints=hints)
+        book.metadata = BookMetadata(
+            title=filled["title"],
+            author=filled["author"],
+            narrator=filled["narrator"],
+            genre=filled.get("genre", ""),
+        )
+        log(
+            f"Title: {book.metadata.title} | Author: {book.metadata.author} "
+            f"| Narrator: {book.metadata.narrator}"
+            + (f" | Genre: {book.metadata.genre}" if book.metadata.genre else "")
+        )
+
+        # 5. Resolve output path.
+        meta_dict = {
+            "title": book.metadata.title,
+            "author": book.metadata.author,
+        }
+        if args.output:
+            output = args.output.resolve()
+        else:
+            base_dir = args.output_dir.resolve() if args.output_dir else directory
+            output = _output_path(base_dir, meta_dict, flat=args.flat)
+            output = _confirm_output(output, interactive)
+        log(f"Output: {output}")
+
+        # 6. Chapter preview + optional inline editing (interactive only).
+        if interactive and sys.stdout.isatty():
+            _print_chapter_table(book.chapters)
+            answer = safe_input("  Edit chapter titles? [y/N]: ").strip().lower()
+            if answer == "y":
+                book.chapters = _edit_chapters_inline(book.chapters)
+
+        # 7. Encode via shared pipeline.
+        channels = 2 if args.stereo else 1
+        log(
+            f"Encoding audiobook "
+            f"(codec=aac, bitrate={args.bitrate}, "
+            f"channels={'stereo' if channels == 2 else 'mono'})..."
+        )
+        run_pipeline(
+            book=book,
+            output_path=output,
+            bitrate=args.bitrate,
+            stereo=args.stereo,
+            ffmpeg=ffmpeg,
+            ffprobe=ffprobe,
+            repair_result=repair_result,
+        )
+        log(f"Done. Created: {output}")
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        _run(args)
+    except EncodeCancelled:
+        log("Cancelled.")
+        sys.exit(130)
+    except KeyboardInterrupt:
+        log("Cancelled.")
+        sys.exit(130)
+    except M4BError as exc:
+        sys.exit(str(exc))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

m4bmaker/chapters.py

@@ -0,0 +1,210 @@
+"""ffprobe-based duration probing and FFMETADATA chapter file generation."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+from m4bmaker.errors import M4BError
+from m4bmaker.models import BookMetadata, Chapter
+from m4bmaker.utils import subprocess_flags
+
+# Matches leading digits optionally followed by separators (space/dash/dot/underscore).
+# Examples stripped: "01 - ", "1.", "02_", "003 "
+_CHAPTER_TITLE_RE = re.compile(r"^\d+[\s.\-_]*")
+
+
+def _strip_chapter_prefix(stem: str) -> str:
+    """Remove leading numeric prefix and separators from a filename stem."""
+    cleaned = _CHAPTER_TITLE_RE.sub("", stem).strip()
+    return cleaned if cleaned else stem
+
+
+def _probe_file(file: Path, ffprobe: str) -> tuple[float, str | None]:
+    """Run ffprobe on *file* and return (duration_seconds, title_tag_or_None)."""
+    cmd = [
+        ffprobe,
+        "-v",
+        "error",  # "-v quiet" would guarantee an empty stderr on failure
+        "-print_format",
+        "json",
+        "-show_format",
+        str(file),
+    ]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            encoding="utf-8",
+            check=True,
+            timeout=120,
+            **subprocess_flags(),
+        )
+    except subprocess.CalledProcessError as exc:
+        raise M4BError(
+            f"Error: ffprobe failed for '{file}'.\n"
+            f"The file may be corrupt or in an unsupported format.\n"
+            f"ffprobe stderr: {exc.stderr.strip()}"
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise M4BError(f"Error: ffprobe timed out probing '{file}'.") from exc
+    except (FileNotFoundError, OSError) as exc:
+        raise M4BError(f"Error: ffprobe executable not found at '{ffprobe}'.") from exc
+
+    try:
+        data = json.loads(result.stdout)
+        duration = float(data["format"]["duration"])
+    except (KeyError, ValueError, json.JSONDecodeError) as exc:
+        raise M4BError(
+            f"Error: could not parse ffprobe output for '{file}': {exc}"
+        ) from exc
+
+    title = data.get("format", {}).get("tags", {}).get("title") or None
+    return duration, title
+
+
+def get_duration(file: Path, ffprobe: str) -> float:
+    """Return the duration of *file* in seconds using ffprobe JSON output."""
+    return _probe_file(file, ffprobe)[0]
+
+
+def build_chapters(
+    files: list[Path],
+    ffprobe: str,
+    progress_fn: Callable[[int, int, str], None] | None = None,
+) -> list[Chapter]:
+    """Build a Chapter list from *files* using ffprobe for durations.
+
+    Chapters are indexed sequentially starting at 1, with *start_time* in
+    seconds (float).  *source_file* is set to the corresponding input path.
+    """
+    chapters: list[Chapter] = []
+    cursor_s: float = 0.0
+    total = len(files)
+
+    for i, path in enumerate(files, 1):
+        if progress_fn is not None:
+            progress_fn(i, total, path.name)
+        duration_sec, tag_title = _probe_file(path, ffprobe)
+        title = tag_title if tag_title else _strip_chapter_prefix(path.stem)
+        chapters.append(
+            Chapter(
+                index=i,
+                start_time=cursor_s,
+                title=title,
+                source_file=path,
+            )
+        )
+        cursor_s += duration_sec
+
+    return chapters
+
+
+def _format_time(seconds: float) -> str:
+    """Format a duration in seconds as H:MM:SS."""
+    s = int(seconds)
+    h, rem = divmod(s, 3600)
+    m, sec = divmod(rem, 60)
+    return f"{h}:{m:02d}:{sec:02d}"
+
+
+def format_chapter_table(chapters: list[Chapter]) -> str:
+    """Return a Unicode box-drawing table of chapters as a multi-line string."""
+    if not chapters:
+        return "  (no chapters)"
+
+    title_width = min(max(len(c.title) for c in chapters), 40)
+    title_width = max(title_width, 5)  # minimum column width
+
+    num_w = max(len(str(len(chapters))), 1)
+    time_w = 8  # "H:MM:SS" is at most 8 chars (e.g. "9:59:59")
+
+    _h = "\u2500"
+    _cols = [num_w, time_w, title_width]
+
+    def _hline(left: str, join: str, right: str) -> str:
+        return "  " + left + join.join(_h * (w + 2) for w in _cols) + right
+
+    top = _hline("\u250c", "\u252c", "\u2510")
+    sep = _hline("\u251c", "\u253c", "\u2524")
+    bot = _hline("\u2514", "\u2534", "\u2518")
+    hdr = (
+        f"  \u2502 {'#':>{num_w}} \u2502"
+        f" {'Start':<{time_w}} \u2502"
+        f" {'Title':<{title_width}} \u2502"
+    )
+
+    rows = [top, hdr, sep]
+    for ch in chapters:
+        start = _format_time(ch.start_time)
+        title = ch.title
+        if len(title) > title_width:
+            title = title[: title_width - 1] + "\u2026"
+        rows.append(
+            f"  \u2502 {ch.index:>{num_w}} \u2502"
+            f" {start:<{time_w}} \u2502"
+            f" {title:<{title_width}} \u2502"
+        )
+    rows.append(bot)
+    return "\n".join(rows)
+
+
+def _escape_ffmeta(value: str) -> str:
+    """Escape a value for use on the right-hand side of an FFMETADATA1 line.
+
+    Per ffmpeg's ffmetadata spec, the characters ``=``, ``;``, ``#``, ``\\``,
+    and newline are special and must be backslash-escaped. Backslash is
+    escaped first so its escape sequence isn't itself re-escaped.
+    """
+    value = value.replace("\\", "\\\\")
+    value = value.replace("=", "\\=")
+    value = value.replace(";", "\\;")
+    value = value.replace("#", "\\#")
+    value = value.replace("\n", "\\\n")
+    return value
+
+
+def write_ffmetadata(
+    chapters: list[Chapter],
+    meta: BookMetadata,
+    dest: Path,
+    total_duration_s: float,
+) -> None:
+    """Write an FFMETADATA1 file with global tags and chapter markers to *dest*.
+
+    Chapter END timestamps are derived from the next chapter's *start_time*;
+    the final chapter ends at *total_duration_s*. Values are backslash-escaped
+    per the FFMETADATA1 spec (see :func:`_escape_ffmeta`).
+    """
+    lines: list[str] = [";FFMETADATA1\n"]
+
+    # Global metadata tags
+    if meta.title:
+        lines.append(f"title={_escape_ffmeta(meta.title)}\n")
+    if meta.author:
+        lines.append(f"artist={_escape_ffmeta(meta.author)}\n")
+    if meta.narrator:
+        lines.append(f"composer={_escape_ffmeta(meta.narrator)}\n")
+    if meta.genre:
+        lines.append(f"genre={_escape_ffmeta(meta.genre)}\n")
+
+    lines.append("\n")
+
+    for i, chapter in enumerate(chapters):
+        if i + 1 < len(chapters):
+            end_ms = int(chapters[i + 1].start_time * 1000)
+        else:
+            end_ms = int(total_duration_s * 1000)
+        start_ms = int(chapter.start_time * 1000)
+
+        lines.append("[CHAPTER]\n")
+        lines.append("TIMEBASE=1/1000\n")
+        lines.append(f"START={start_ms}\n")
+        lines.append(f"END={end_ms}\n")
+        lines.append(f"title={_escape_ffmeta(chapter.title)}\n")
+        lines.append("\n")
+
+    dest.write_text("".join(lines), encoding="utf-8")

m4bmaker/chapters_file.py

@@ -0,0 +1,129 @@
+"""Parser for external chapter list files (--chapters-file).
+
+File format
+-----------
+Each non-blank, non-comment line must be::
+
+    TIMESTAMP  TITLE
+
+where *TIMESTAMP* is either ``MM:SS`` or ``H:MM:SS`` and *TITLE* is any
+non-empty string.  Lines beginning with ``#`` are treated as comments and
+ignored.
+
+Examples::
+
+    00:00 Opening Engagement
+    10:37 The Surprise
+    1:19:17 Port Mahon
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from m4bmaker.errors import M4BError
+from m4bmaker.models import Chapter
+
+# Matches either  MM:SS  or  H:MM:SS  (H may be more than one digit).
+_TIMESTAMP_RE = re.compile(r"^(\d+:\d{2}(?::\d{2})?)\s+(.+)$")
+
+
+def _parse_timestamp(ts: str) -> float:
+    """Convert a *MM:SS* or *H:MM:SS* string to seconds (float).
+
+    Raises :class:`ValueError` for any string that doesn't match those patterns.
+    """
+    parts = ts.split(":")
+    try:
+        int_parts = [int(p) for p in parts]
+    except ValueError:
+        raise ValueError(f"non-integer in timestamp {ts!r}")
+
+    if len(int_parts) == 2:
+        m, s = int_parts
+        if not (0 <= s < 60):
+            raise ValueError(f"seconds out of range in {ts!r}")
+        return m * 60.0 + s
+    elif len(int_parts) == 3:
+        h, m, s = int_parts
+        if not (0 <= m < 60 and 0 <= s < 60):
+            raise ValueError(f"minutes or seconds out of range in {ts!r}")
+        return h * 3600.0 + m * 60.0 + s
+    raise ValueError(f"unrecognised timestamp format {ts!r}")  # pragma: no cover
+
+
+def load_chapters_file(path: Path) -> list[Chapter]:
+    """Parse *path* and return a :class:`~m4bmaker.models.Chapter` list.
+
+    Raises :class:`~m4bmaker.errors.M4BError` if:
+
+    - the file cannot be read
+    - any non-blank, non-comment line is malformed
+    - the file contains no chapters after filtering
+    - the first chapter does not start at or after 0, or timestamps are not
+      strictly increasing
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise M4BError(f"Error: cannot read chapters file '{path}': {exc}") from exc
+
+    chapters: list[Chapter] = []
+    # Track the source line number for each parsed chapter, for validation
+    # error messages below.
+    linenos: list[int] = []
+    for lineno, raw_line in enumerate(text.splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        m = _TIMESTAMP_RE.match(line)
+        if not m:
+            raise M4BError(
+                f"Error: malformed line {lineno} in '{path.name}':\n"
+                f"  {raw_line!r}\n"
+                f"Expected format: MM:SS TITLE  or  H:MM:SS TITLE"
+            )
+
+        ts_str, title = m.group(1), m.group(2).strip()
+        try:
+            start_time = _parse_timestamp(ts_str)
+        except ValueError as exc:
+            raise M4BError(
+                f"Error: invalid timestamp on line {lineno} of '{path.name}': {exc}"
+            ) from exc
+
+        chapters.append(
+            Chapter(
+                index=len(chapters) + 1,
+                start_time=start_time,
+                title=title,
+                source_file=None,
+            )
+        )
+        linenos.append(lineno)
+
+    if not chapters:
+        raise M4BError(f"Error: no chapters found in '{path.name}'")
+
+    if chapters[0].start_time < 0:
+        raise M4BError(
+            f"Error: line {linenos[0]} of '{path.name}' has a negative start "
+            f"time ({chapters[0].start_time}s) — the first chapter must start "
+            f"at or after 0:00"
+        )
+
+    for i in range(1, len(chapters)):
+        if chapters[i].start_time <= chapters[i - 1].start_time:
+            raise M4BError(
+                f"Error: line {linenos[i]} of '{path.name}' is not after the "
+                f"previous chapter's timestamp — chapter timestamps must be "
+                f"strictly increasing:\n"
+                f"  chapter {chapters[i - 1].index} starts at "
+                f"{chapters[i - 1].start_time}s, "
+                f"chapter {chapters[i].index} starts at "
+                f"{chapters[i].start_time}s"
+            )
+
+    return chapters