samplerdisc 0.5.1__py3-none-any.whl

samplerdisc/__init__.py

@@ -0,0 +1,3 @@
+"""Convert vintage sampler CD-ROM images to uncompressed WAV."""
+
+__version__ = "0.5.0"

samplerdisc/audiocd.py

@@ -0,0 +1,212 @@
+"""Red Book audio CDs.
+
+Not a CD-ROM: no filesystem, no partition, nothing to walk. The sectors *are*
+the audio. A raw 2352-byte CD audio sector is already 16-bit 44.1 kHz stereo
+little-endian PCM, so a track becomes a WAV by putting a header in front of it
+-- the same "copy, never convert" guarantee as the sampler path (ADR-0011).
+
+These discs sit in the same archives as the sampler CD-ROMs and are easy to
+mistake for one, so recognising them is as useful as converting them.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from samplerdisc import cue as cuesheet
+from samplerdisc.wav import write_wav, write_wav_streaming
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from samplerdisc.container.base import SectorImage
+
+#: A raw CD audio sector: 588 stereo frames of 16-bit samples.
+AUDIO_SECTOR_SIZE = 2352
+CDDA_RATE = 44100
+CDDA_CHANNELS = 2
+CDDA_WIDTH = 2
+
+
+@dataclass
+class AudioTrack:
+    number: int
+    title: str
+    path: str
+    frames: int
+
+    @property
+    def seconds(self) -> float:
+        return self.frames / CDDA_RATE
+
+
+def detect(image_path: str | os.PathLike[str]) -> cuesheet.CueSheet | None:
+    """Return the cue sheet if ``image_path`` is an audio CD, else None.
+
+    Requires a cue: without one there is no way to know where tracks begin, and
+    nothing in the bytes distinguishes CD audio from any other PCM.
+    """
+    sheet = cuesheet.load(image_path)
+    if sheet is None or not sheet.all_audio:
+        return None
+    if os.path.getsize(image_path) % AUDIO_SECTOR_SIZE != 0:
+        return None
+    return sheet
+
+
+#: Windows sampled across an image when judging whether it holds CD audio, and
+#: how many bytes each. Spread rather than contiguous: a sample CD is mostly
+#: silence between hits, and one window can easily land in a gap.
+_GATE_WINDOWS = 12
+_GATE_WINDOW_BYTES = 1 << 16
+
+#: A window quieter than this carries no evidence either way.
+_GATE_SILENCE = 8
+
+#: Interleaved stereo makes a lag-1 step a hop between channels and a lag-2
+#: step a move along one channel, so lag-1 differences dominate. Mono data read
+#: as stereo inverts that: lag-1 is a single step in time and lag-2 is two, so
+#: the ratio sits near 0.5. Measured across the reference discs, audio CDs land
+#: at 5.1-14.0 and every sampler disc at or below 1.01 -- including Roland
+#: discs whose payload is smooth enough to fool a plain smoothness test.
+_GATE_STEREO_RATIO = 2.0
+
+#: Each channel must also look like a waveform rather than noise. Audio CDs
+#: measure 0.10-0.25 here; uniform noise sits near 1.33.
+_GATE_SMOOTHNESS = 0.75
+
+#: Read size when streaming a whole disc to one WAV.
+_WHOLE_DISC_CHUNK = 1 << 22
+
+
+def _window_stats(buf: bytes) -> tuple[float, float] | None:
+    """(lag-1 / lag-2, lag-2 / mean) for ``buf`` read as 16-bit LE stereo."""
+    if len(buf) < 4096:
+        return None
+    values = struct.unpack(f"<{len(buf) // 2}h", buf[: len(buf) // 2 * 2])
+    mean = sum(map(abs, values)) / len(values)
+    if mean < _GATE_SILENCE:
+        return None
+    lag1 = sum(abs(values[i] - values[i - 1]) for i in range(1, len(values))) / (len(values) - 1)
+    lag2 = sum(abs(values[i] - values[i - 2]) for i in range(2, len(values))) / (len(values) - 2)
+    if lag2 == 0:
+        return None
+    return lag1 / lag2, lag2 / mean
+
+
+def _median(values: list[float]) -> float:
+    ordered = sorted(values)
+    return ordered[len(ordered) // 2]
+
+
+def looks_like_cd_audio(image: SectorImage) -> bool:
+    """Does this image's stream look like 44.1 kHz 16-bit stereo PCM?
+
+    This answers a narrower question than "is this an audio CD", and it cannot
+    replace a cue sheet: track boundaries are not in the bytes, which is why
+    ``detect`` still requires one. What it is good for is telling a user whose
+    disc yielded no filesystem *why* -- an image of a Red Book disc decodes
+    perfectly and then has nothing to walk, which otherwise looks identical to
+    a container we got wrong.
+
+    Deliberately conservative. It is consulted only when no backend claimed the
+    disc, and it must not fire on a sampler disc whose payload happens to be
+    smooth -- see the constants above for the measured margins.
+    """
+    stats = []
+    for index in range(_GATE_WINDOWS):
+        offset = (image.size // (_GATE_WINDOWS + 1)) * (index + 1)
+        offset -= offset % 4
+        window = _window_stats(image.read(offset, _GATE_WINDOW_BYTES))
+        if window is not None:
+            stats.append(window)
+    if len(stats) < 3:
+        # Too little to judge. Say no rather than guess.
+        return False
+    return (
+        _median([s[0] for s in stats]) > _GATE_STEREO_RATIO
+        and _median([s[1] for s in stats]) < _GATE_SMOOTHNESS
+    )
+
+
+def write_whole_disc(image: SectorImage, out_path: str | os.PathLike[str]) -> int:
+    """Write an image's entire stream as one stereo WAV. Returns frames.
+
+    For a disc with no filesystem whose content is CD audio. The bytes are
+    copied verbatim -- a raw audio sector is already 588 stereo frames of
+    signed 16-bit LE PCM, so this is a header in front of the stream and
+    nothing else (ADR-0011).
+    """
+    frame_bytes = CDDA_CHANNELS * CDDA_WIDTH
+    total = (image.size // frame_bytes) * frame_bytes
+
+    def stream():
+        done = 0
+        while done < total:
+            chunk = image.read(done, min(_WHOLE_DISC_CHUNK, total - done))
+            if not chunk:
+                # Tail damage. The declared length must still be met, so pad
+                # with silence rather than writing a truncated data chunk.
+                yield b"\x00" * (total - done)
+                return
+            done += len(chunk)
+            yield chunk
+
+    write_wav_streaming(
+        out_path,
+        stream(),
+        total_bytes=total,
+        rate=CDDA_RATE,
+        channels=CDDA_CHANNELS,
+        sample_width=CDDA_WIDTH,
+    )
+    return total // frame_bytes
+
+
+def track_name(track: cuesheet.CueTrack) -> str:
+    return track.title or f"Track {track.number:02d}"
+
+
+def extract_tracks(
+    image_path: str | os.PathLike[str],
+    sheet: cuesheet.CueSheet,
+    out_dir: str,
+) -> Iterator[AudioTrack]:
+    """Write each audio track as a stereo WAV."""
+    from samplerdisc.extract import safe_name, unique_path
+
+    size = os.path.getsize(image_path)
+    total_sectors = size // AUDIO_SECTOR_SIZE
+    os.makedirs(out_dir, exist_ok=True)
+
+    starts = [t.start_lba for t in sheet.tracks]
+    with open(image_path, "rb") as source:
+        for index, track in enumerate(sheet.tracks):
+            start = starts[index]
+            end = starts[index + 1] if index + 1 < len(starts) else total_sectors
+            if end <= start or start >= total_sectors:
+                continue
+            end = min(end, total_sectors)
+            source.seek(start * AUDIO_SECTOR_SIZE)
+            pcm = source.read((end - start) * AUDIO_SECTOR_SIZE)
+            if not pcm:
+                continue
+            name = track_name(track)
+            path = unique_path(out_dir, safe_name(name))
+            write_wav(
+                path,
+                pcm,
+                rate=CDDA_RATE,
+                channels=CDDA_CHANNELS,
+                sample_width=CDDA_WIDTH,
+                name=name,
+            )
+            yield AudioTrack(
+                number=track.number,
+                title=name,
+                path=path,
+                frames=len(pcm) // (CDDA_CHANNELS * CDDA_WIDTH),
+            )

samplerdisc/banks.py

@@ -0,0 +1,83 @@
+"""Loose sample banks in an ordinary directory, converted to WAV.
+
+Some E-mu libraries ship not as a disc image but as loose files in the clear:
+an Emulator X / Proteus X bank is a ``.exb`` definition beside a ``SamplePool/``
+of ``.ebl`` sample files. There is no disc, no container and no on-disc
+filesystem to read -- the operating system's own filesystem already presents
+the bytes and the tree -- so this is a *source*, not a container or a
+``Backend`` (ADR-0042). It runs the same verified ``emu_ebl`` decoder the
+on-disc path does, through ``extract.ebl_to_wav``.
+
+The ``.exb`` holds the preset key ranges and zone mappings; like the on-disc
+``.exb`` and the E-IV presets it is left to ConvertWithMoss and is not read
+here (ADR-0011). Only the ``.ebl`` sample files are converted.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from samplerdisc.extract import Extracted, Skipped, ebl_to_wav, safe_name
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+def find_bank_dirs(root: str) -> list[Path]:
+    """Every directory under ``root`` that directly holds ``.ebl`` files.
+
+    Returned in stable sorted order. A render/oracle tree or a stray folder
+    with no ``.ebl`` is not a bank and is passed over: the presence of the
+    sample files is the whole test, so ``.exb``-only or FLAC-only folders never
+    qualify.
+    """
+    found: list[Path] = []
+    for directory, _dirs, files in os.walk(root):
+        if any(name.lower().endswith(".ebl") for name in files):
+            found.append(Path(directory))
+    return sorted(found)
+
+
+def bank_name(bank_dir: Path) -> str:
+    """The library name for a bank directory.
+
+    An E-mu bank keeps its samples in a child ``SamplePool/``, so the name that
+    means something is the parent (``Proteus 1``), not the pool. A directory
+    that holds the ``.ebl`` files directly is named for itself.
+    """
+    if bank_dir.name.lower() == "samplepool":
+        return bank_dir.parent.name
+    return bank_dir.name
+
+
+def extract_bank(bank_dir: Path, out_dir: str, volume: str) -> Iterator[Extracted | Skipped]:
+    """Convert every ``.ebl`` in one bank directory to a WAV in ``out_dir``.
+
+    Files are walked in sorted order for a stable run. Each is decoded by the
+    shared ``ebl_to_wav``, which names the output from the sample's own header
+    and refuses a bad payload with a reason rather than raising -- one damaged
+    ``.ebl`` never ends the bank. Unlike the AKAI path there is no stereo
+    ``-L``/``-R`` pairing and no de-duplication: an ``.ebl`` has no on-disc
+    twin (as on the disc EBL path).
+    """
+    for path in sorted(bank_dir.glob("*.ebl")):
+        try:
+            payload = path.read_bytes()
+        except OSError as exc:  # pragma: no cover - filesystem-level failure
+            yield Skipped(volume, path.name, f"unreadable: {exc}")
+            continue
+        yield ebl_to_wav(payload, path.name, volume, out_dir)
+
+
+def extract_banks(root: str, out_root: str) -> Iterator[Extracted | Skipped]:
+    """Convert every loose bank found under ``root``.
+
+    Each bank's WAVs land under ``out_root/<bank name>/`` so several banks share
+    an output tree without colliding.
+    """
+    for bank_dir in find_bank_dirs(root):
+        name = bank_name(bank_dir)
+        out_dir = os.path.join(out_root, safe_name(name))
+        yield from extract_bank(bank_dir, out_dir, name)

samplerdisc/batch.py

@@ -0,0 +1,260 @@
+"""Convert a directory of disc images in one pass, and record what happened.
+
+A collection is the real use case: dozens of images from different sites in
+different containers, some of which will not open. One bad disc must not stop
+the run, and the manifest is how a user finds the ones that need attention.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from samplerdisc import banks
+from samplerdisc.audiocd import detect as detect_audio_cd
+from samplerdisc.audiocd import extract_tracks
+from samplerdisc.container.detect import open_image, sniff
+from samplerdisc.extract import Credited, Extracted, Joined, Kept, Skipped, extract_disc, safe_name
+from samplerdisc.fs.probe import find_origin
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+#: Extensions worth opening. Detection is by signature (ADR-0004), but walking
+#: a directory needs some filter or every README becomes a candidate disc.
+IMAGE_SUFFIXES = {
+    ".mdx", ".nrg", ".iso", ".img", ".bin", ".mds", ".cdr", ".tao", ".ccd",
+}  # fmt: skip
+
+
+@dataclass
+class DiscReport:
+    source: str
+    container: str | None = None
+    filesystem: str | None = None
+    origin: int | None = None
+    #: The backend's one line on how the disc is divided, verbatim -- the same
+    #: line ``list`` prints, or None where the filesystem has no structure
+    #: above the volume. It is here because it is the only place a run over a
+    #: collection records that an image is **short of the disc it was made
+    #: from**: its samples extract and verify, and the disc has more on it than
+    #: the file does (ADR-0028).
+    layout: str | None = None
+    volumes: list[dict[str, Any]] = field(default_factory=list)
+    samples: int = 0
+    #: Samples that were stereo on the disc, of ``samples``. Counted apart
+    #: from ``stereo_pairs`` because they are different news: one is a channel
+    #: count the record declared, the other a pairing this tool guessed from
+    #: two filenames (ADR-0007, ADR-0026).
+    stereo_samples: int = 0
+    stereo_pairs: int = 0
+    originals: int = 0
+    #: Disc provenance lines written to a ``Credits.txt`` sidecar, from the
+    #: E-IV ``Credits``/``E-mu Systems 96`` text banks. 0 unless ``--metadata``
+    #: is set or the disc has no such bank (ADR-0043).
+    credit_lines: int = 0
+    #: Entries read, understood, and deliberately not written because their
+    #: audio was already written from another file on the same disc. Counted
+    #: apart from ``skipped`` so a clean disc does not read as a damaged one.
+    duplicates: int = 0
+    #: Entries whose payload is not the file the directory placed there.
+    #: Counted apart from ``skipped`` because it is a different fault: the
+    #: filesystem and the data have come apart, which on these discs means the
+    #: image is short of the disc it was made from (ADR-0027).
+    mismatches: int = 0
+    #: Samples written whose bytes were displaced inside a partition by blocks
+    #: the rip lost and recovered a whole number of container blocks earlier,
+    #: each confirmed by its own header (issue #35, ADR-0045). A subset of
+    #: ``samples``: says how many of them the image would have had wrong, or
+    #: refused, before recovery.
+    recovered: int = 0
+    audio_tracks: int = 0
+    skipped: list[dict[str, object]] = field(default_factory=list)
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and (self.samples > 0 or self.audio_tracks > 0)
+
+
+def find_images(root: str) -> list[str]:
+    """Every plausible disc image under ``root``, in stable order.
+
+    Companion files are excluded by simply not listing their suffixes: a
+    ``.cue`` describes its ``.bin`` and a ``.mdf`` holds data for its ``.mds``,
+    so each pair is reached once, through the member that is actually opened.
+    """
+    found: list[str] = []
+    for directory, _dirs, files in os.walk(root):
+        for name in sorted(files):
+            if os.path.splitext(name)[1].lower() in IMAGE_SUFFIXES:
+                found.append(os.path.join(directory, name))
+    return sorted(found)
+
+
+def convert_disc(
+    path: str,
+    out_root: str,
+    join_stereo: bool = True,
+    keep_originals: bool = False,
+    metadata: bool = False,
+) -> DiscReport:
+    """Convert one image. Never raises: a failure becomes a report."""
+    report = DiscReport(source=path)
+    try:
+        # An audio CD has no filesystem to find -- the sectors are the audio.
+        sheet = detect_audio_cd(path)
+        if sheet is not None:
+            report.container = "audio-cd"
+            report.filesystem = "none (Red Book audio)"
+            out_dir = os.path.join(out_root, safe_name(os.path.splitext(os.path.basename(path))[0]))
+            for _track in extract_tracks(path, sheet, out_dir):
+                report.audio_tracks += 1
+            return report
+
+        report.container = sniff(path)
+        with open_image(path) as image:
+            origin = find_origin(image)
+            if origin is None:
+                report.error = "no recognised filesystem"
+                return report
+            report.filesystem = origin.backend.name
+            report.origin = origin.offset
+            describe = getattr(origin.backend, "layout", None)
+            report.layout = describe(image, origin.offset) if describe is not None else None
+
+            out_dir = os.path.join(out_root, safe_name(os.path.splitext(os.path.basename(path))[0]))
+            # Keyed by partition *and* name: nearly every partition of an AKAI
+            # disc has a "VOLUME 001", and keying by name alone reported nine
+            # volumes' samples as one entry (ADR-0023).
+            volumes: dict[tuple[int, str], dict[str, Any]] = {}
+            results = extract_disc(
+                image,
+                origin.backend,
+                origin.offset,
+                out_dir,
+                join_stereo,
+                keep_originals,
+                metadata,
+            )
+            for result in results:
+                if isinstance(result, Credited):
+                    report.credit_lines += result.lines
+                elif isinstance(result, Extracted):
+                    report.samples += 1
+                    if result.channels > 1:
+                        report.stereo_samples += 1
+                    if result.displaced:
+                        report.recovered += 1
+                    entry = volumes.setdefault(
+                        (result.partition, result.volume),
+                        {"name": result.volume, "partition": result.partition, "samples": 0},
+                    )
+                    entry["samples"] += 1
+                elif isinstance(result, Joined):
+                    report.stereo_pairs += 1
+                elif isinstance(result, Kept):
+                    report.originals += 1
+                elif isinstance(result, Skipped):
+                    if result.duplicate:
+                        report.duplicates += 1
+                    if result.mismatch:
+                        report.mismatches += 1
+                    report.skipped.append(
+                        {
+                            "volume": result.volume,
+                            "partition": result.partition,
+                            "name": result.name,
+                            "reason": result.reason,
+                            "duplicate": result.duplicate,
+                            "mismatch": result.mismatch,
+                        }
+                    )
+            report.volumes = list(volumes.values())
+    except (OSError, ValueError) as exc:
+        # One unreadable disc must not end the run.
+        report.error = str(exc)
+    return report
+
+
+def convert_bank(bank_dir: str, out_root: str) -> DiscReport:
+    """Convert one loose ``.ebl`` bank directory. Never raises.
+
+    A loose bank has no container and no on-disc filesystem -- the OS presents
+    the files directly (ADR-0042) -- so the report names those layers ``none``
+    and records the bank as a single volume. Reported alongside disc images so a
+    mixed tree runs in one pass and lands in one manifest.
+    """
+    name = banks.bank_name(Path(bank_dir))
+    report = DiscReport(source=bank_dir, container="loose-ebl", filesystem="none")
+    out_dir = os.path.join(out_root, safe_name(name))
+    samples = 0
+    try:
+        for result in banks.extract_bank(Path(bank_dir), out_dir, name):
+            if isinstance(result, Extracted):
+                report.samples += 1
+                samples += 1
+                if result.channels > 1:
+                    report.stereo_samples += 1
+            elif isinstance(result, Skipped):
+                report.skipped.append(
+                    {
+                        "volume": result.volume,
+                        "partition": result.partition,
+                        "name": result.name,
+                        "reason": result.reason,
+                        "duplicate": result.duplicate,
+                        "mismatch": result.mismatch,
+                    }
+                )
+    except OSError as exc:  # pragma: no cover - filesystem-level failure
+        report.error = str(exc)
+        return report
+    report.volumes = [{"name": name, "partition": 0, "samples": samples}]
+    return report
+
+
+def convert_tree(
+    root: str,
+    out_root: str,
+    join_stereo: bool = True,
+    keep_originals: bool = False,
+    metadata: bool = False,
+) -> Iterator[DiscReport]:
+    for path in find_images(root):
+        yield convert_disc(path, out_root, join_stereo, keep_originals, metadata)
+    # Loose banks are files in the clear, not disc images, so find_images passes
+    # them over (.ebl is not an image suffix); they are discovered separately and
+    # converted through their own source. A render/oracle tree carries no .ebl
+    # and is skipped by construction.
+    for bank_dir in banks.find_bank_dirs(root):
+        yield convert_bank(str(bank_dir), out_root)
+
+
+def write_manifest(path: str, reports: list[DiscReport]) -> None:
+    payload = {
+        "discs": [asdict(report) for report in reports],
+        "totals": {
+            "discs": len(reports),
+            "converted": sum(1 for r in reports if r.ok),
+            "failed": sum(1 for r in reports if not r.ok),
+            "samples": sum(r.samples for r in reports),
+            "stereo_samples": sum(r.stereo_samples for r in reports),
+            "stereo_pairs": sum(r.stereo_pairs for r in reports),
+            "audio_tracks": sum(r.audio_tracks for r in reports),
+            "originals": sum(r.originals for r in reports),
+            "credit_lines": sum(r.credit_lines for r in reports),
+            "skipped": sum(len(r.skipped) for r in reports),
+            "duplicates": sum(r.duplicates for r in reports),
+            "mismatches": sum(r.mismatches for r in reports),
+            "recovered": sum(r.recovered for r in reports),
+        },
+    }
+    directory = os.path.dirname(os.path.abspath(path))
+    os.makedirs(directory, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as out:
+        json.dump(payload, out, indent=2)
+        out.write("\n")