pysacd 0.2.0__py3-none-win_amd64.whl

pysacd/__init__.py

@@ -0,0 +1,19 @@
+"""Pure-Python reader for SACD (Scarletbook) ISO images."""
+
+from .toc import (
+    Area,
+    Disc,
+    Genre,
+    Locale,
+    SACDError,
+    SACDImage,
+    Timecode,
+    Track,
+    read_toc,
+)
+
+__all__ = [
+    "Area", "Disc", "Genre", "Locale", "SACDError", "SACDImage",
+    "Timecode", "Track", "read_toc",
+]
+__version__ = "0.2.0"

pysacd/__main__.py

@@ -0,0 +1,329 @@
+"""pysacd command line: `toc` prints SACD TOCs, `convert` extracts tagged audio."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import getpass
+import json
+import sys
+from pathlib import Path
+
+from . import safetext
+from .toc import Disc, SACDError, read_toc
+
+
+def _to_json(disc: Disc) -> dict:
+    d = dataclasses.asdict(disc)
+    d["manufacturer_info"] = disc.manufacturer_info.rstrip(b"\0").hex()
+    for area, ad in zip(disc.areas, d["areas"]):
+        ad["frame_format_name"] = area.frame_format_name
+        ad["speaker_config"] = area.speaker_config
+        for track, td in zip(area.tracks, ad["tracks"]):
+            td["start_seconds"] = track.start.seconds_float
+            td["duration_seconds"] = track.duration.seconds_float
+    return d
+
+
+def print(*args, **kwargs) -> None:  # TOC text is untrusted: escape control characters
+    import builtins
+    builtins.print(*(safetext.for_terminal(str(a), keep_tab_newline=True) for a in args), **kwargs)
+
+
+def _print(disc: Disc, path: str) -> None:
+    print(f"== {path}")
+    print(f"Disc:      {disc.artist or '?'} - {disc.title or '?'}")
+    for k in ("album_title", "album_artist", "album_publisher", "album_copyright"):
+        if k in disc.text:
+            print(f"  {k:16} {disc.text[k]}")
+    y, m, day = disc.date
+    print(f"  version {disc.version[0]}.{disc.version[1]:02d}  hybrid={disc.hybrid}"
+          f"  set {disc.album_sequence_number}/{disc.album_set_size}"
+          f"  date {y:04d}-{m:02d}-{day:02d}")
+    if disc.disc_catalog_number:
+        print(f"  catalog   {disc.disc_catalog_number}")
+    genres = [str(g) for g in disc.disc_genres if g.genre > 1]
+    if genres:
+        print(f"  genre     {', '.join(genres)}")
+    for area in disc.areas:
+        print(f"Area {area.kind}: {area.speaker_config}, {area.frame_format_name},"
+              f" {len(area.tracks)} tracks, {area.total_playtime}"
+              f" (LSN {area.track_start}-{area.track_end})")
+        for t in area.tracks:
+            who = f" [{t.performer}]" if t.performer else ""
+            print(f"  {t.number:2d}. {t.duration}  {t.title or ''}{who}")
+    for w in disc.warnings + [w for a in disc.areas for w in a.warnings]:
+        print(f"  warning: {w}")
+
+
+def _toc(args) -> int:
+    rc = 0
+    out = []
+    from . import remote
+    for path in args.images:
+        try:
+            addr = remote.parse_address(path)
+            disc = remote.read_remote_toc(*addr)[0] if addr else read_toc(path)
+        except (OSError, SACDError) as e:
+            print(f"{path}: {e}", file=sys.stderr)
+            rc = 1
+            continue
+        if args.json:
+            out.append({"path": path, **_to_json(disc)})
+        else:
+            _print(disc, path)
+    if args.json:
+        json.dump(out if len(out) != 1 else out[0], sys.stdout, ensure_ascii=False, indent=2)
+        print()
+    return rc
+
+
+def _submit_isrcs(args) -> int:
+    from . import isrcsubmit, musicbrainz, remote
+    try:
+        if args.mb_server:
+            musicbrainz.set_server(args.mb_server)
+        addr = remote.parse_address(args.image)
+        disc = remote.read_remote_toc(*addr)[0] if addr else read_toc(args.image)
+    except (OSError, SACDError, musicbrainz.MBError) as e:
+        print(f"{args.image}: {e}", file=sys.stderr)
+        return 1
+    areas = [a for a in (disc.stereo, disc.multichannel) if a is not None
+             and (args.area == "both" or (args.area == "multichannel") == a.is_multichannel)]
+    rc = 0
+    for area in areas:
+        if not any(t.isrc for t in area.tracks):
+            print(f"{area.speaker_config}: the disc has no ISRCs")
+            continue
+        try:
+            match = musicbrainz.find_release(disc, area, args.mb_contact, args.mb_release, text_search=False)
+            if match is None:
+                print(f"{area.speaker_config}: no confident MusicBrainz match (try --mb-release)", file=sys.stderr)
+                rc = 1
+                continue
+            isrcsubmit.offer(match, area, args.mb_contact, dry_run=args.dry_run, yes=args.yes, user=args.mb_user)
+        except musicbrainz.MBError as e:
+            print(f"{area.speaker_config}: {e}", file=sys.stderr)
+            rc = 1
+    return rc
+
+
+def _mb_login(args) -> int:
+    from . import isrcsubmit, musicbrainz
+    try:
+        if args.mb_server:
+            musicbrainz.set_server(args.mb_server)
+        print("Open this URL, allow pysacd to submit ISRCs, then paste the code it shows:\n\n  "
+              + isrcsubmit.authorize_url(args.client_id) + "\n")
+        code = input("code: ")
+        secret = args.client_secret or getpass.getpass("client secret: ")
+        isrcsubmit.finish_login(args.client_id, secret, code, args.mb_contact)
+        print(f"saved the token to {isrcsubmit.TOKEN_FILE} (readable only by you)")
+    except (OSError, musicbrainz.MBError) as e:
+        print(f"mb-login: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+class _Version(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        from . import __version__, _native
+        try:
+            engine = f"{_native.build_info()} ({_native.library_path()})"
+        except (OSError, _native.NativeError) as e:
+            engine = f"not available: {e}"
+        print(f"pysacd {__version__}\nengine: {engine}")
+        parser.exit()
+
+
+def _bool(ap, name, help):
+    ap.add_argument(f"--{name}", dest=name.replace("-", "_"), action=argparse.BooleanOptionalAction,
+                    default=None, help=help)
+
+
+def _convert(args) -> int:
+    from .convert import CONFIG_PATH, Options, convert
+    from .rootcheck import refuse_root
+
+    if refuse_root("pysacd convert", args.allow_root):
+        return 2
+
+    try:
+        opts = Options.from_config(Path(args.config) if args.config else CONFIG_PATH)
+    except (ValueError, OSError) as e:
+        print(f"config: {e}", file=sys.stderr)
+        return 2
+    for k, v in vars(args).items():
+        if v is not None and hasattr(opts, k):
+            setattr(opts, k, v)
+    from . import remote
+
+    rc = 0
+    for iso in args.images:
+        tmp = None
+        try:
+            addr = remote.parse_address(iso)
+            if addr:
+                # Fetch the TOCs and the selected areas from the PS3 into a temporary sparse ISO
+                print(f"{iso}: reading from SACD Ripper server", file=sys.stderr)
+                def wanted(a, which=opts.areas, dry=opts.dry_run):
+                    return not dry and ((a.is_stereo and which in ("stereo", "both")) or
+                                        (a.is_multichannel and which in ("multichannel", "both")))
+                tmp, _ = remote.fetch_temp(
+                    *addr, opts.output_dir or ".", wanted,
+                    progress=remote.RateMeter(lambda m: (sys.stderr.write(m), sys.stderr.flush())))
+            rc |= convert(tmp or iso, opts)
+        except (OSError, SACDError) as e:
+            print(f"{iso}: {e}", file=sys.stderr)
+            rc = 1
+        finally:
+            if tmp:
+                Path(tmp).unlink(missing_ok=True)
+    return rc
+
+
+def _ps3sim(args) -> int:
+    import ipaddress
+
+    from .remote import PS3Simulator
+    try:
+        loopback = ipaddress.ip_address(args.host).is_loopback
+    except ValueError:
+        loopback = args.host == "localhost"
+    if not loopback:
+        print(f"warning: listening on {args.host}: anyone who can reach this port can read {args.image}. "
+              "The protocol has no authentication or encryption; use only on a trusted network.",
+              file=sys.stderr)
+    sim = PS3Simulator(args.image, args.host, args.port, rate=args.rate * 1e6, latency=args.latency / 1000,
+                       drop_after=args.drop_after, fail_lsn=args.fail_lsn, no_disc=args.no_disc,
+                       idle_timeout=args.idle_timeout,
+                       log=lambda m: print(m, file=sys.stderr, flush=True))
+    host, port = sim.address[0], sim.address[1]
+    print(f"serving {args.image} as a SACD Ripper server on {host!s}:{port} (Ctrl-C to stop)", file=sys.stderr)
+    try:
+        sim.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        sim.stop()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:        # run as the command: tracebacks quote exception messages (#47)
+        safetext.install_excepthook()
+    ap = argparse.ArgumentParser(prog="pysacd", description="SACD ISO tools")
+    ap.add_argument("--log-file", help="write a diagnostic log here (default level: debug)")
+    ap.add_argument("--log-level", choices=["debug", "info", "warning", "error"],
+                    help="log detail; without --log-file the log goes to stderr")
+    ap.add_argument("--version", action=_Version, nargs=0, help="show the version and how the engine was built")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    t = sub.add_parser("toc", help="print the TOC of SACD ISO images")
+    t.add_argument("images", nargs="+")
+    t.add_argument("--json", action="store_true", help="emit JSON")
+    t.set_defaults(func=_toc)
+
+    c = sub.add_parser(
+        "convert", help="extract tracks to DSF/FLAC/WAV and tag them",
+        description="Extract an SACD ISO to tagged files. Defaults come from "
+                    "~/.config/pysacd/config.toml (same names as the long options, "
+                    "with underscores); flags override it.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="template fields: albumartist album artist title composer date year originalyear\n"
+               "  label catalognumber barcode tracknumber tracktotal discnumber disctotal\n"
+               "  disc disc_prefix edition layout channels format\n"
+               "  e.g. --dir-template '{albumartist}/{year} - {album} [{edition}]'\n"
+               "       --file-template '{tracknumber:02d} {title}'\n"
+               "  empty [] / () left by blank fields are removed")
+    c.add_argument("images", nargs="+", help="ISO images, or HOST:PORT of a PS3 running SACD Ripper")
+    c.add_argument("--config", help=f"config file (default {Path('~/.config/pysacd/config.toml')})")
+    c.add_argument("-f", "--format", choices=["dsf", "flac", "wav"], help="output format (default dsf)")
+    c.add_argument("-o", "--output-dir", help="root output directory (default .)")
+    c.add_argument("--dir-template", help="album directory template, may contain /")
+    c.add_argument("--file-template", help="track file name template (no extension)")
+    c.add_argument("--stereo-edition", help="{edition} for the stereo area (default 'SACD')")
+    c.add_argument("--multichannel-edition", help="{edition} for the multichannel area (default 'SACD {layout}')")
+    c.add_argument("-a", "--areas", choices=["stereo", "multichannel", "both"], help="areas to extract (default stereo)")
+    c.add_argument("--disc", metavar="N/M",
+                   help="this is disc N of an M-disc set: sets the disc number tags and {disc}/{disc_prefix}, "
+                        "overriding the TOC and MusicBrainz (for sets mastered as 1/1, e.g. Live-Evil)")
+    c.add_argument("-t", "--tracks", type=lambda s: [int(x) for x in s.split(",")], help="only these tracks, e.g. 1,4,5")
+    c.add_argument("-r", "--pcm-rate", type=int, choices=[88200, 176400], help="FLAC/WAV sample rate (default 88200)")
+    c.add_argument("--gain-db", type=float, help="PCM gain in dB (default 0; SACD 0 dB = -6 dBFS)")
+    c.add_argument("--flac-level", type=int, choices=range(9), metavar="0-8", help="FLAC compression (default 5)")
+    c.add_argument("-j", "--jobs", type=int, help="worker threads (default: CPU count)")
+    _bool(c, "musicbrainz", "look up the release on MusicBrainz (default on)")
+    c.add_argument("--mb-release", help="use this MusicBrainz release id")
+    _bool(c, "mb-text-search", "fall back to title/artist search when barcode/catalog fail (default off)")
+    c.add_argument("--mb-contact", help="contact (URL or e-mail) for the MusicBrainz User-Agent")
+    _bool(c, "submit-isrcs", "offer the disc's ISRCs to the matched MusicBrainz release; asks first, needs `pysacd mb-login` (default off)")
+    _bool(c, "cover", "embed front cover from the Cover Art Archive (default on)")
+    c.add_argument("--cover-size", choices=["250", "500", "1200", "full"], help="cover size (default 1200)")
+    c.add_argument("--cover-file", help="save cover as this file in the album dir ('' to skip)")
+    c.add_argument("--id3-version", type=int, choices=[3, 4], help="ID3 version for DSF/WAV (default 3)")
+    _bool(c, "portable-names", "replace characters invalid on Windows/SMB (default off)")
+    _bool(c, "overwrite", "overwrite existing files (default: skip)")
+    c.add_argument("--allow-root", action="store_true",
+                   help="run even as root (not recommended: disc images are untrusted; see docs/security.md)")
+    c.add_argument("-n", "--dry-run", action="store_true", default=None, help="show match and paths only")
+    c.set_defaults(func=_convert)
+
+    i = sub.add_parser(
+        "submit-isrcs", help="add the disc's ISRCs to its MusicBrainz release (asks first)",
+        description="Submit the ISRCs in a disc's TOC to the matching MusicBrainz release. Only a barcode, "
+                    "catalog-number or --mb-release match is used; ISRCs already on another recording are "
+                    "skipped. Sign in once with `pysacd mb-login`, or use --mb-user (HTTP digest).")
+    i.add_argument("image", help="ISO image or PS3 address (host:port)")
+    i.add_argument("--area", choices=["stereo", "multichannel", "both"], default="both")
+    i.add_argument("--mb-release", help="use this MusicBrainz release id")
+    i.add_argument("--mb-contact", help="contact (URL or e-mail) for the MusicBrainz User-Agent")
+    i.add_argument("--mb-server", help="another MusicBrainz server, e.g. https://test.musicbrainz.org")
+    i.add_argument("--mb-user", help="MusicBrainz user name for digest auth (password asked, never stored)")
+    i.add_argument("-n", "--dry-run", action="store_true", help="show what would be submitted")
+    i.add_argument("-y", "--yes", action="store_true", help="submit without asking")
+    i.set_defaults(func=_submit_isrcs)
+
+    g = sub.add_parser(
+        "mb-login", help="sign in to MusicBrainz (OAuth) for ISRC submission",
+        description="Out-of-band OAuth2 sign-in with the submit_isrc scope. Register an application at "
+                    "https://musicbrainz.org/account/applications (type: installed) to get a client id and "
+                    "secret. The token is saved owner-only under ~/.config/pysacd/.")
+    g.add_argument("--client-id", required=True)
+    g.add_argument("--client-secret", help="asked for if not given")
+    g.add_argument("--mb-contact", help="contact (URL or e-mail) for the MusicBrainz User-Agent")
+    g.add_argument("--mb-server", help="another MusicBrainz server, e.g. https://test.musicbrainz.org")
+    g.set_defaults(func=_mb_login)
+
+    s = sub.add_parser(
+        "ps3sim", help="serve an ISO like a PS3 running SACD Ripper (for testing network clients)",
+        description="Serve an already-decrypted SACD ISO over the SACD Ripper network protocol, "
+                    "so `sacd_extract -i HOST:PORT` or pysacd can be tested without a PS3.")
+    s.add_argument("image")
+    s.add_argument("--host", default="127.0.0.1",
+                   help="listen address (default 127.0.0.1; use 0.0.0.0 only on a trusted network)")
+    s.add_argument("--port", type=int, default=2002, help="listen port (default 2002, as on the PS3)")
+    s.add_argument("--rate", type=float, default=0, help="throttle to this many MB/s (0 = unlimited)")
+    s.add_argument("--latency", type=float, default=0, help="delay each request by this many ms")
+    s.add_argument("--drop-after", type=int, default=0, help="close the connection after N reads")
+    s.add_argument("--fail-lsn", type=int, help="make reads covering this LSN fail (result -1)")
+    s.add_argument("--no-disc", action="store_true", help="fail DISC_OPEN, as with an empty drive")
+    s.add_argument("--idle-timeout", type=float, default=60.0,
+                   help="close a connection idle for this many seconds (default 60; 0 = never)")
+    s.set_defaults(func=_ps3sim)
+
+    args = ap.parse_args(argv)
+    from . import log as pslog
+    level, path = args.log_level, args.log_file
+    if level is None and path is None:
+        level, path = pslog.from_env()
+    try:
+        pslog.setup(level, path, ["pysacd", *(sys.argv[1:] if argv is None else argv)])
+    except (OSError, ValueError) as e:
+        print(f"logging: {e}", file=sys.stderr)
+        return 2
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pysacd/_native.py

@@ -0,0 +1,320 @@
+"""ctypes binding for the native engine (_sacdconv.so/.dylib/.dll, built by `make`)."""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import os
+import sys
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .toc import Area, SACDImage, area_frame_capacity
+
+FORMATS = {"dsf": 0, "flac": 1, "wav": 2, "dff": 3, "dff-dst": 4}
+SCAN_SLACK = 128    # sectors read around the needed range (frame context + boundary frames)
+
+
+class _Output(ctypes.Structure):
+    # Must match sc_output_t in csrc/sacdconv.c
+    _fields_ = [
+        ("format", ctypes.c_int),
+        ("path", ctypes.c_char_p),
+        ("tc_start", ctypes.c_uint32),
+        ("tc_end", ctypes.c_uint32),
+        ("head_frame", ctypes.c_int32),
+        ("head_bytes", ctypes.c_uint32),
+        ("tail_bytes", ctypes.c_uint32),
+        ("header", ctypes.c_char_p),
+        ("header_len", ctypes.c_uint32),
+        ("footer", ctypes.c_char_p),
+        ("footer_len", ctypes.c_uint32),
+        ("dst_offsets", ctypes.POINTER(ctypes.c_uint64)),
+        ("dst_lengths", ctypes.POINTER(ctypes.c_uint32)),
+        ("dst_cap", ctypes.c_uint32),
+        ("flac_level", ctypes.c_int),
+        ("flac_padding", ctypes.c_uint32),
+        ("frames_written", ctypes.c_uint32),
+        ("frames_missing", ctypes.c_uint32),
+        ("dst_errors", ctypes.c_uint32),
+        ("dst_count", ctypes.c_uint32),
+        ("samples", ctypes.c_uint64),
+        ("data_bytes", ctypes.c_uint64),
+        ("error", ctypes.c_char * 256),
+    ]
+
+
+# int read_fn(void *ctx, uint32_t lsn, uint32_t count, uint8_t *buf)
+_READ_FN = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_uint32,
+                            ctypes.POINTER(ctypes.c_uint8))
+# void log_fn(void *ctx, int level, const char *msg)
+_LOG_FN = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_int, ctypes.c_char_p)
+
+
+class _Area(ctypes.Structure):
+    # Must match sc_area_t in csrc/sacdconv.c
+    _fields_ = [
+        ("iso_path", ctypes.c_char_p),
+        ("sector_size", ctypes.c_int),
+        ("data_offset", ctypes.c_int),
+        ("scan_lsn_start", ctypes.c_uint32),
+        ("scan_lsn_end", ctypes.c_uint32),
+        ("channels", ctypes.c_int),
+        ("pcm_rate", ctypes.c_int),
+        ("gain_db", ctypes.c_double),
+        ("threads", ctypes.c_int),
+        ("iso_out_path", ctypes.c_char_p),
+        ("iso_sectors", ctypes.c_uint32),
+        ("cancel", ctypes.c_int),
+        ("frames_done", ctypes.c_uint64),
+        ("frames_total", ctypes.c_uint64),
+        ("sectors_done", ctypes.c_uint64),
+        ("sectors_total", ctypes.c_uint64),
+        ("error", ctypes.c_char * 256),
+        ("read_fn", _READ_FN),
+        ("read_ctx", ctypes.c_void_p),
+        ("log_fn", _LOG_FN),
+        ("log_ctx", ctypes.c_void_p),
+        ("log_level", ctypes.c_int),
+    ]
+
+
+class NativeError(RuntimeError):
+    pass
+
+
+log = logging.getLogger("pysacd.engine")
+
+# Reads 2048-byte sectors (lsn, count) -> bytes, e.g. from a disc on a network server
+SectorSource = Callable[[int, int], bytes]
+
+
+_lib = None
+LIBRARY = {"win32": "_sacdconv.dll", "darwin": "_sacdconv.dylib"}.get(sys.platform, "_sacdconv.so")
+
+
+def _load():
+    global _lib
+    if _lib is None:
+        path = Path(__file__).with_name(LIBRARY)
+        if not path.exists():
+            raise NativeError(f"{path} not built; run `make` in the pysacd source tree")
+        lib = ctypes.CDLL(str(path))
+        lib.sacdconv_area_run.argtypes = [ctypes.POINTER(_Area), ctypes.POINTER(_Output), ctypes.c_int]
+        lib.sacdconv_area_run.restype = ctypes.c_int
+        lib.sacdconv_has_flac.restype = ctypes.c_int
+        lib.sacdconv_build_info.restype = ctypes.c_char_p
+        _check_abi(lib, path)
+        _lib = lib
+    return _lib
+
+
+ABI = 1    # SACDCONV_ABI in csrc/sacdconv.c
+
+
+def _layout(struct) -> list[int]:
+    return [ctypes.sizeof(struct)] + [getattr(struct, name).offset for name, _ in struct._fields_]
+
+
+def _check_abi(lib, path) -> None:
+    """Refuse an engine built from different struct definitions than the ctypes mirrors here:
+    a mismatch would make the engine read and write the wrong fields."""
+    try:
+        abi = lib.sacdconv_abi()
+    except AttributeError:
+        abi = 0
+    if abi != ABI:
+        raise NativeError(f"{path} has engine ABI {abi}, this pysacd needs {ABI}; rebuild it (make clean all)")
+    lib.sacdconv_layout.argtypes = [ctypes.c_int, ctypes.POINTER(ctypes.c_uint32), ctypes.c_int]
+    for which, struct in ((0, _Area), (1, _Output)):
+        want = _layout(struct)
+        buf = (ctypes.c_uint32 * 64)()
+        n = lib.sacdconv_layout(which, buf, 64)
+        got = list(buf[:min(n, 64)])
+        if got != want:
+            raise NativeError(f"{path}: {struct.__name__} layout differs from the engine's "
+                              f"(engine {got}, pysacd {want}); rebuild it (make clean all)")
+
+
+def has_flac() -> bool:
+    return bool(_load().sacdconv_has_flac())
+
+
+def library_path() -> str:
+    return str(Path(__file__).with_name(LIBRARY))
+
+
+def build_info() -> str:
+    """Compiler and features the engine was built with, for diagnostic logs."""
+    return _load().sacdconv_build_info().decode()
+
+
+@dataclass
+class OutputSpec:
+    """One file to produce from an area: frames [tc_start, tc_end)."""
+    format: str
+    path: str | os.PathLike
+    tc_start: int
+    tc_end: int
+    head_frame: int = -1          # DSF nopad: carry-in from this frame's tail
+    head_bytes: int = 0
+    tail_bytes: int = 0           # DSF nopad: bytes/channel left for the next file
+    header: bytes = b""           # DSDIFF header
+    footer: bytes = b""           # DSF ID3 tag / DSDIFF trailing chunks
+    flac_level: int = 5
+    flac_padding: int = 0
+    # results
+    frames_written: int = 0
+    frames_missing: int = 0
+    dst_errors: int = 0
+    samples: int = 0
+    data_bytes: int = 0
+    dst_index: list[tuple[int, int]] = field(default_factory=list)   # DSDIFF DST: (offset, length)
+
+
+@dataclass
+class Progress:
+    frames_done: int
+    frames_total: int
+    sectors_done: int
+    sectors_total: int
+
+
+def _scan_range(area: Area, specs: list[OutputSpec]) -> tuple[int, int]:
+    """LSN range covering every frame the outputs need."""
+    tracks = area.tracks
+    lo_tc = min(min(s.tc_start, s.head_frame if s.head_frame >= 0 else s.tc_start) for s in specs)
+    hi_tc = max(s.tc_end for s in specs)
+    lo = area.track_start
+    hi = area.track_end
+    # Track LSNs and timecodes come from the TOC: use them to narrow the scan only when they're
+    # consistent (inside the area's audio and in order, as on every real disc). Otherwise scan
+    # the whole area rather than miss frames or hand the engine a range outside it (#17).
+    lsns = [t.start_lsn for t in tracks]
+    starts = [t.start.total_frames for t in tracks]
+    if not (all(area.track_start <= x <= area.track_end for x in lsns)
+            and lsns == sorted(lsns) and starts == sorted(starts)):
+        log.debug("track LSNs or timecodes inconsistent: scanning the whole area")
+        return area.track_start, area.track_end
+    for i, t in enumerate(tracks):
+        if t.start.total_frames <= lo_tc:
+            lo = t.start_lsn if i else area.track_start
+        nxt = tracks[i + 1] if i + 1 < len(tracks) else None
+        if nxt and nxt.start.total_frames >= hi_tc and hi == area.track_end:
+            hi = nxt.start_lsn
+    return max(area.track_start, lo - SCAN_SLACK), min(area.track_end, hi + SCAN_SLACK)
+
+
+def run_area(image: SACDImage, iso_path: str | os.PathLike, area: Area | None, specs: list[OutputSpec],
+             pcm_rate: int = 88200, gain_db: float = 0.0, threads: int = 0,
+             iso_out: str | os.PathLike | None = None,
+             progress: Callable[[Progress], None] | None = None, interval: float = 0.5,
+             source: SectorSource | None = None) -> None:
+    """Produce all outputs from one area in a single pass. Blocking, multithreaded.
+
+    `progress` is called from this thread every `interval` seconds while the
+    engine runs. Raises NativeError on failure; results are stored on the specs.
+    With `source`, sectors come from that callable instead of the file at
+    iso_path (which is then only a name for messages). Engine diagnostics go to
+    the "pysacd.engine" logger.
+    """
+    lib = _load()
+    outs = (_Output * max(1, len(specs)))()
+    keep = []   # keep ctypes buffers alive
+    for o, s in zip(outs, specs):
+        o.format = FORMATS[s.format]
+        o.path = os.fsencode(s.path)
+        o.tc_start, o.tc_end = s.tc_start, s.tc_end
+        o.head_frame, o.head_bytes, o.tail_bytes = s.head_frame, s.head_bytes, s.tail_bytes
+        o.header, o.header_len = s.header, len(s.header)
+        o.footer, o.footer_len = s.footer, len(s.footer)
+        o.flac_level, o.flac_padding = s.flac_level, s.flac_padding
+        if s.format == "dff-dst":
+            cap = s.tc_end - s.tc_start
+            offs, lens = (ctypes.c_uint64 * cap)(), (ctypes.c_uint32 * cap)()
+            keep += [offs, lens]
+            o.dst_offsets = ctypes.cast(offs, ctypes.POINTER(ctypes.c_uint64))
+            o.dst_lengths = ctypes.cast(lens, ctypes.POINTER(ctypes.c_uint32))
+            o.dst_cap = cap
+
+    a = _Area()
+    a.iso_path = os.fsencode(iso_path)
+    a.sector_size, a.data_offset = image.sector_size, image.data_offset
+    if specs:
+        assert area is not None, "outputs need an area"
+        # Frames the image lacks become silence: never more of it than the area's sectors in this
+        # image could hold, however long the TOC says the tracks are (#17)
+        capacity = area_frame_capacity(area, image.total_sectors)
+        if max(s.tc_end for s in specs) > capacity:
+            raise NativeError(f"the outputs need frames up to {max(s.tc_end for s in specs)}, but the area's "
+                              f"audio in this image (LSN {area.track_start}-{area.track_end}, "
+                              f"{image.total_sectors} sectors) holds at most {capacity}")
+        a.scan_lsn_start, a.scan_lsn_end = _scan_range(area, specs)
+        # The range comes from the TOC, which may be hostile: a sector source must only ever be
+        # asked for sectors that exist (#11). A file needs no check: pread stops at its end.
+        if source is not None and not 0 <= a.scan_lsn_start <= a.scan_lsn_end < image.total_sectors:
+            raise NativeError(f"area LSN {a.scan_lsn_start}-{a.scan_lsn_end} lies outside the image "
+                              f"({image.total_sectors} sectors)")
+        a.channels = area.channel_count
+    else:
+        a.channels = 2
+    a.pcm_rate = pcm_rate
+    a.gain_db = gain_db
+    a.threads = threads
+    if iso_out is not None:
+        a.iso_out_path = os.fsencode(iso_out)
+        a.iso_sectors = image.total_sectors
+
+    # Callbacks run on engine threads; they must never raise into C.
+    def on_log(_ctx, level, msg):
+        log.log(level, msg.decode(errors="replace"))
+
+    def on_read(_ctx, lsn, count, buf):
+        try:
+            data = source(lsn, count)
+            if len(data) != count * 2048:
+                raise OSError(f"short read: {len(data)} of {count * 2048} bytes")
+            ctypes.memmove(buf, data, len(data))
+            return 0
+        except Exception as e:
+            log.exception("sector source failed at LSN %d (+%d)", lsn, count)
+            a.error = str(e).encode(errors="replace")[:255]
+            return -1
+
+    callbacks = [_LOG_FN(on_log)]
+    a.log_fn = callbacks[0]
+    a.log_level = log.getEffectiveLevel()
+    if source is not None:
+        if image.sector_size != 2048:
+            raise NativeError("a sector source must deliver plain 2048-byte sectors")
+        callbacks.append(_READ_FN(on_read))
+        a.read_fn = callbacks[1]
+    for s in specs:
+        log.debug("output %s %s: frames %d-%d%s", s.format, s.path, s.tc_start, s.tc_end,
+                  f", nopad head {s.head_bytes}@{s.head_frame} tail {s.tail_bytes}" if s.head_frame >= 0 or s.tail_bytes
+                  else "")
+
+    result = []
+    t = threading.Thread(target=lambda: result.append(lib.sacdconv_area_run(ctypes.byref(a), outs, len(specs))),
+                         name="engine")
+    t.start()
+    try:
+        while t.is_alive():
+            t.join(interval)
+            if progress:
+                progress(Progress(a.frames_done, a.frames_total, a.sectors_done, a.sectors_total))
+    except BaseException:
+        a.cancel = 1
+        t.join()
+        raise
+
+    for o, s in zip(outs, specs):
+        s.frames_written, s.frames_missing, s.dst_errors = o.frames_written, o.frames_missing, o.dst_errors
+        s.samples, s.data_bytes = o.samples, o.data_bytes
+        if s.format == "dff-dst":
+            n = min(o.dst_count, o.dst_cap)
+            s.dst_index = [(o.dst_offsets[i], o.dst_lengths[i]) for i in range(n)]
+    if result and result[0] != 0:
+        raise NativeError(a.error.decode(errors="replace"))