specux 0.1.0.dev1__cp313-cp313-win_amd64.whl

specux/__init__.py

@@ -0,0 +1,94 @@
+"""Differentiable audio DSP for Python: fast, fused kernels on GPU and CPU.
+
+Array-agnostic surface: numpy-in/numpy-out, torch-in/torch-out (resident on the
+GPU), cupy-in/cupy-out. The CUDA and Metal backends generate kernel source in
+C++ (src/codegen.h) and compile it at runtime (NVRTC / MSL); the CPU backend
+runs on the AVX2 engine (src/cpu/fft). torch inputs that require grad flow
+through autograd (see interop/torch.py, interop/metal.py).
+
+`import specux` pulls only numpy; torch and the CUDA extension load lazily on
+first use of a torch array or the CUDA backend.
+"""
+from __future__ import annotations
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_0():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'specux.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_0()
+del _delvewheel_patch_1_13_0
+# end delvewheel patch
+
+from typing import TYPE_CHECKING
+
+from .core import config as _config
+from .dsp import filters as _filters
+from .core.version import __version__ as __version__
+
+if TYPE_CHECKING:
+    from .core.plan import STFTPlan
+    from .dsp.transform import CQT, ISTFT, STFT, VQT, Chroma, MelSpectrogram, Transform
+
+__all__ = ["stft", "istft", "melspectrogram", "cqt", "vqt", "chroma",
+           "fft", "ifft", "rfft", "irfft", "fft_plan", "FFTPlan", "mel_filterbank",
+           "hz_to_mel", "mel_to_hz", "mfcc", "lfcc", "fftconvolve",
+           "MFCC", "LFCC", "FFTConvolve",
+           "STFT", "ISTFT", "MelSpectrogram", "CQT", "VQT",
+           "Chroma", "Transform", "FFT", "IFFT", "RFFT", "IRFFT",
+           "stft_plan", "autotune",
+           "STFTPlan", "deterministic", "benchmark", "set_benchmark", "set_num_threads",
+           "get_num_threads", "clear_cache", "set_deterministic"]
+mel_filterbank = _filters.mel_filterbank
+hz_to_mel = _filters.hz_to_mel
+mel_to_hz = _filters.mel_to_hz
+deterministic = _config.deterministic
+benchmark = _config.benchmark
+
+def __getattr__(name):
+    if name == "audio":
+        # audio I/O + signal toolbox subpackage;
+        # resolves once the package is present, AttributeError until then.
+        import importlib
+        try:
+            return importlib.import_module(".audio", __name__)
+        except ModuleNotFoundError:
+            raise AttributeError(
+                "specux.audio is unavailable: this build has no audio I/O "
+                "module (build with FFmpeg dev libraries)") from None
+        except ImportError as e:
+            # the module exists but its extension failed to load (typically
+            # a shared-library resolution problem, e.g. an OpenSSL older
+            # than FFmpeg's already loaded in-process); surface the loader's
+            # message instead of misreporting a missing build
+            raise AttributeError(
+                "specux.audio failed to import: " + str(e)) from e
+    if name in ("stft_plan", "autotune", "STFTPlan"):
+        from .core import plan as _plan
+        return getattr(_plan, name)
+    if name in ("STFT", "ISTFT", "MelSpectrogram", "CQT", "VQT", "Chroma", "Transform",
+                "FFT", "IFFT", "RFFT", "IRFFT"):
+        from .dsp import transform as _transform
+        return getattr(_transform, name)
+    if name in ("mfcc", "lfcc", "fftconvolve"):
+        from .dsp import features as _features
+        return getattr(_features, name)
+    if name in ("MFCC", "LFCC", "FFTConvolve"):
+        from .dsp import transform as _transform
+        return getattr(_transform, name)
+    if name in ("fft", "ifft", "rfft", "irfft", "fft_plan", "FFTPlan"):
+        from .core import fft as _fft
+        return getattr(_fft, name)
+    if name == "set_benchmark":
+        from .core import cache as _cache
+        return _cache.set_benchmark
+    raise AttributeError(f"module 'specux' has no attribute '{name}'")
+
+
+from .core.api import (stft, istft, melspectrogram, cqt, vqt, chroma,  # noqa: E402
+                       clear_cache, set_num_threads, get_num_threads,
+                       set_deterministic,
+                       _check_win_length, _hop)   # noqa: F401  (_plan reaches these via specux)

specux/audio/__init__.py

@@ -0,0 +1,73 @@
+"""specux audio: fast audio I/O with frame-accurate offset/duration.
+
+    y, sr = specux.audio.load("clip.flac")                            # full decode, float32
+    y, sr = specux.audio.load("clip.flac", offset=5.0, duration=2.0)  # seek + window (seconds)
+    y, sr = specux.audio.load("clip.flac", sr=16000)                  # resample (vendored soxr)
+    y, sr = specux.audio.load("clip.wav", dtype="int16")              # native int16 fast path
+    y, sr = specux.audio.load("song.m4a", track=1)                    # select an audio track
+    specux.audio.save("out.flac", y, sr)                              # encode (fmt from extension)
+    ys    = specux.audio.load_many(paths, workers=8)                  # parallel load -> [(y,sr),...]
+    specux.audio.save_many([(p, y, sr), ...])                         # parallel save
+    for blk in specux.audio.blocks("4hr.flac", sr*30): ...            # stream-read a huge file
+    with specux.audio.StreamWriter("out.mp3", sr, 2) as w: w.write(blk)  # stream-write
+    y, sr = specux.audio.load(open("clip.mp3","rb").read())           # decode from memory (bytes)
+    data  = specux.audio.save_bytes(y, sr, "mp3")                     # encode to memory
+    y2    = specux.audio.codec_roundtrip(y, sr, "mp3", bitrate=64000) # augmentation (same shape)
+    y     = specux.audio.normalize(y, mode="lufs", target_db=-14, sr=sr)  # loudness-normalize
+    lv    = specux.audio.level(y); lufs = specux.audio.loudness(y, sr)      # peak/RMS + LUFS metering
+    nfo   = specux.audio.info("clip.flac")                            # frames/samplerate/channels/format/tracks
+    specux.audio.write_tags("x.flac", {"title": "Take 3"}); specux.audio.tags("x.flac")
+    specux.audio.write_cover("x.flac", open("art.png", "rb").read())  # album art
+    y, sr = specux.audio.load("damaged.mp3", strict=False)            # best-effort decode
+    # every function above also accepts bytes; no filesystem needed anywhere
+
+Citations use keys from docs/references.bib (specux convention): standards
+(BS.1770 loudness, EBU R128), algorithms (De Man K-weighting) and vendored
+libraries (soxr, dr_libs, minimp3, TagLib) are all resolvable there.
+
+`y` is shape (channels, frames), or (frames,) for mono / single-channel; the same
+layout save() expects. dtype is float32 (default) or int16. Backends are chosen by
+sniffing the header: wav -> dr_wav, mp3 -> dr_mp3, flac/ogg/mp4/aac/other -> libav;
+save uses the vendored dr_wav writer for WAV and libav for compressed formats.
+"""
+
+import os as _os
+
+if _os.name == "nt":
+    # dev machines: point SPECUX_FFMPEG_BIN at the FFmpeg DLL directory, or
+    # let a repo checkout fall back to the scripts/get_ffmpeg.ps1 prefix
+    # (wheels bundle the DLLs next to the extension instead)
+    _ffbin = _os.environ.get("SPECUX_FFMPEG_BIN")
+    if not (_ffbin and _os.path.isdir(_ffbin)):
+        import glob as _glob
+        _repo = _os.path.dirname(_os.path.dirname(_os.path.dirname(
+            _os.path.abspath(__file__))))
+        _hits = sorted(_glob.glob(_os.path.join(
+            _repo, ".ffmpeg", "*", "bin", "avformat-*.dll")), reverse=True)
+        _ffbin = _os.path.dirname(_hits[0]) if _hits else None
+        del _glob, _repo, _hits
+    if _ffbin and _os.path.isdir(_ffbin):
+        _os.add_dll_directory(_ffbin)  # type: ignore[attr-defined]  # Windows-only
+    del _ffbin
+del _os
+
+from .. import _audio as _audio
+from ._io import (codec_roundtrip, load, load_many, save, save_bytes,
+                  save_many)
+from ._meta import (cover, info, tags, write_cover, write_cover_bytes,
+                    write_tags, write_tags_bytes)
+from ._signal import (level, loudness, loudness_range, normalize, resample,
+                      to_mono, to_stereo, true_peak)
+from ._stream import StreamReader, StreamWriter, blocks
+from ._types import QUALITY, Cover, Info, Level, Quality, Subtype
+
+__all__ = [
+    "load", "save", "save_bytes", "codec_roundtrip",
+    "load_many", "save_many",
+    "StreamReader", "StreamWriter", "blocks",
+    "resample", "to_mono", "to_stereo",
+    "level", "loudness", "loudness_range", "true_peak", "normalize",
+    "info", "tags", "write_tags", "write_tags_bytes",
+    "cover", "write_cover", "write_cover_bytes",
+    "Info", "Level", "Cover", "Quality", "Subtype", "QUALITY",
+]

specux/audio/_io.py

@@ -0,0 +1,400 @@
+"""specux audio I/O: decode, encode, and batch load / save variants."""
+from __future__ import annotations
+
+import os
+import struct
+from concurrent.futures import ThreadPoolExecutor
+from typing import Literal
+
+import numpy as np
+
+from .. import _audio
+from ._types import Quality, Subtype, _recipe
+
+_WAV_DTYPES = {(1, 8): np.uint8, (1, 16): np.int16, (1, 32): np.int32,
+               (3, 32): np.float32, (3, 64): np.float64}
+
+
+_SAVE_EXT = {
+    "wav": "wav", "wave": "wav",
+    "flac": "flac", "mp3": "mp3", "ogg": "ogg", "oga": "ogg",
+    "m4a": "mp4", "mp4": "mp4", "aac": "aac", "opus": "opus",
+}
+
+
+def _cpu_count() -> int:
+    return os.cpu_count() or 1
+
+
+def _container_for(name, *, is_path: bool) -> str:
+    """Container key for an output path's extension (or a bare format name)."""
+    name = str(name)
+    key = (name.rsplit(".", 1)[-1].lower() if "." in name else
+           ("" if is_path else name.lower()))
+    container = _SAVE_EXT.get(key)
+    if container is None:
+        what = (f"extension '.{key}'" if is_path and key
+                else f"path {name!r} (no extension)" if is_path
+                else f"format {name!r}")
+        raise ValueError(f"unsupported output {what} "
+                         f"(one of: {', '.join(sorted(set(_SAVE_EXT)))})")
+    return container
+
+
+def _as_float32(y):
+    """Input audio (any float/int dtype) -> float32 scaled to [-1, 1)."""
+    y = np.asarray(y)
+    if np.issubdtype(y.dtype, np.unsignedinteger):
+        # offset-binary: the zero point sits at half range (128 for uint8)
+        half = float(np.iinfo(y.dtype).max + 1) / 2.0
+        return (y.astype(np.float32) - half) / half
+    if np.issubdtype(y.dtype, np.integer):
+        return y.astype(np.float32) / float(np.iinfo(y.dtype).max + 1)
+    return np.asarray(y, dtype=np.float32)
+
+
+def _wav_map_raw(path):
+    """Parse an uncompressed WAV header and memory-map its PCM as an interleaved
+    (frames, channels) view. Returns (mm, sr, ch, npdt) or None if not a plain
+    PCM/float WAV we can map."""
+    with open(path, "rb") as f:
+        head = f.read(12)
+        if len(head) < 12 or head[:4] != b"RIFF" or head[8:12] != b"WAVE":
+            return None
+        fmt = None
+        data_off = data_len = None
+        while True:
+            hdr = f.read(8)
+            if len(hdr) < 8:
+                break
+            cid, size = hdr[:4], struct.unpack("<I", hdr[4:])[0]
+            if cid == b"fmt ":
+                b = f.read(size)
+                afmt, ch, sr, _, _, bits = struct.unpack("<HHIIHH", b[:16])
+                fmt = (afmt, ch, sr, bits)
+            elif cid == b"data":
+                data_off, data_len = f.tell(), size
+                break
+            else:
+                f.seek(size + (size & 1), 1)
+        if fmt is None or data_off is None:
+            return None
+    afmt, ch, sr, bits = fmt
+    npdt = _WAV_DTYPES.get((afmt, bits))
+    if npdt is None or ch <= 0:
+        return None
+    # Clamp to the real file size: truncated downloads and streaming writers
+    # (data size left as 0xFFFFFFFF) overstate the chunk; trust the bytes on
+    # disk, not the header, so np.memmap can't raise "length greater than file".
+    data_len = min(data_len, os.path.getsize(path) - data_off)
+    total = data_len // (ch * np.dtype(npdt).itemsize)
+    if total <= 0:
+        return None
+    mm = np.memmap(path, dtype=npdt, mode="r", offset=data_off, shape=(total, ch))
+    return mm, sr, ch, npdt
+
+
+def _wav_memmap(path, offset, duration, mono):
+    """Zero-copy WAV read: a (channels, frames) view over the file's PCM (read
+    deferred until touched), or None. Ideal for large files sliced downstream."""
+    got = _wav_map_raw(path)
+    if got is None:
+        return None
+    mm, sr, ch, _ = got
+    # A stereo->mono downmix must read every sample; numpy's strided mean over a
+    # transposed memmap is far slower than the NEON downmix in _audio.load, so
+    # bail and let the caller take that path. Mono files (ch==1) stay zero-copy.
+    if mono and ch > 1:
+        return None
+    start = int(offset * sr) if offset > 0 else 0
+    stop = mm.shape[0] if duration is None else min(mm.shape[0], start + int(duration * sr))
+    view = mm[start:stop]                         # zero-copy slice
+    view = view.T if ch > 1 else view[:, 0]       # channels-first view
+    return view, sr
+
+
+def _wav_downmix(path, offset, duration):
+    """Stereo/multichannel WAV -> mono float32 without a full-stereo decode: mmap
+    the PCM and fuse the downmix (NEON, parallel) in a single pass over the mapped
+    int16/float samples. Returns (mono, sr) or None if not a mappable PCM WAV."""
+    got = _wav_map_raw(path)
+    if got is None:
+        return None
+    mm, sr, ch, npdt = got
+    if ch == 1:
+        return None                               # already mono; mmap view is better
+    if npdt not in (np.int16, np.float32):
+        return None                               # _audio.downmix dtypes only; fall back
+    start = int(offset * sr) if offset > 0 else 0
+    stop = mm.shape[0] if duration is None else min(mm.shape[0], start + int(duration * sr))
+    y = _audio.downmix(np.ascontiguousarray(mm[start:stop]))
+    return y, sr
+
+
+def _wav_resample(path, out_sr, res_type, mono):
+    """WAV resample without the decode threadpool: mmap the PCM, convert to
+    float32, and resample with the native soxr. Returns (samples, out_sr) or
+    None. Skipping the threadpool keeps it immune to a perturbed thread
+    environment."""
+    got = _wav_map_raw(path)
+    if got is None:
+        return None
+    mm, sr, ch, npdt = got
+    y = np.asarray(mm, dtype=np.float32)          # (frames, ch), materialises
+    if npdt == np.uint8:
+        y = (y - 128.0) / 128.0                   # offset-binary: zero point is 128
+    elif np.issubdtype(npdt, np.integer):
+        y = y / float(np.iinfo(npdt).max + 1)
+    if mono and ch > 1:
+        y = y.mean(axis=1, keepdims=True)
+    out, _ = _audio.resample(np.ascontiguousarray(y), sr, out_sr, res_type)
+    out = out[:, 0] if (out.ndim == 2 and out.shape[1] == 1) else out
+    return (out.T if out.ndim == 2 else out), out_sr
+
+
+def load(path, *, sr: int | None = None, offset: float = 0.0,
+         duration: float | None = None, mono: bool = False,
+         dtype: Literal["float32", "int16"] = "float32",
+         quality: Quality = "high",
+         backend: Literal["auto", "dr", "libav"] = "auto", threads: int = 0,
+         mmap: bool = False, track: int = 0, strict: bool = True,
+         _serial: bool = False):
+    """Decode `path` to a numpy array; returns (samples, samplerate).
+
+    sr:        target sample rate (None = native).
+    offset:    start position in seconds (frame-accurate).
+    duration:  seconds to read (None = to end).
+    mono:      downmix to a single channel.
+    dtype:     "float32" (default) or "int16".
+    quality:   resample quality when `sr` is set; one of QUALITY
+               ("quick".."very_high", default "high").
+    backend:   "auto" (sniff+route), "dr" (force dr_wav/dr_mp3), or "libav".
+    threads:   libav decode threads (0 = auto); ignored by the dr backends.
+    mmap:      for uncompressed WAV, return a zero-copy memory-mapped VIEW in the
+               file's native dtype (read deferred until touched). Ignores sr /
+               dtype conversion; falls back to a normal decode if unsupported.
+    track:     audio-track index to decode (0 = first). Multi-track containers
+               like Native-Instruments .stem.m4a expose several; see info().tracks.
+    strict:    True (default) surfaces decode errors. strict=False is
+               best-effort for messy datasets: mid-file corruption already
+               yields the decodable prefix, and on a hard open failure the
+               other backend is tried before raising; an exception then means
+               nothing was recoverable. Pairs with load_many(on_error="skip").
+
+    `path` may also be a bytes-like object (bytes / bytearray / memoryview) -
+    audio already in memory (archive members, network payloads) decodes through
+    the same engines with no filesystem involved; `mmap` is meaningless there.
+    """
+    recipe = _recipe(quality)
+    if isinstance(path, (bytes, bytearray, memoryview)):
+        return _audio.load_bytes(
+            path, sr=0 if sr is None else int(sr), offset=float(offset),
+            duration=-1.0 if duration is None else float(duration),
+            mono=bool(mono), dtype=dtype, res_type=recipe,
+            threads=int(threads), stream=int(track), strict=bool(strict))
+    spath = str(path)
+    # The three fast paths below are WAV-only (they map raw PCM). Gate them on the
+    # extension so a compressed file (mp3/flac/ogg) doesn't pay an open+header-read
+    # just to be rejected; that wasted probe is ~as costly as a short mp3 decode.
+    # A mis-named WAV simply misses the zero-copy path; _audio.load still sniffs by
+    # content and decodes it correctly. (A non-zero track is libav-only, so the
+    # single-stream WAV fast paths never apply.)
+    maybe_wav = (track == 0 and
+                 (spath.rsplit(".", 1)[-1].lower() in ("wav", "wave")
+                  if "." in spath else True))
+    if maybe_wav:
+        if mmap and sr is None:
+            got = _wav_memmap(spath, float(offset), duration, bool(mono))
+            if got is not None:
+                return got
+        # WAV mono fast path: mmap the PCM and fuse the downmix (NEON); one pass
+        # over the mapped samples, no full-stereo decode.
+        if mono and sr is None and dtype == "float32" and backend == "auto":
+            got = _wav_downmix(spath, float(offset), duration)
+            if got is not None:
+                return got
+        # WAV resample fast path: mmap + native soxr, off the decode threadpool.
+        if (sr is not None and dtype == "float32" and offset == 0.0
+                and duration is None and backend == "auto"):
+            got = _wav_resample(spath, int(sr), recipe, bool(mono))
+            if got is not None:
+                return got
+    try:
+        return _audio.load(
+            spath, sr=0 if sr is None else int(sr), offset=float(offset),
+            duration=-1.0 if duration is None else float(duration),
+            mono=bool(mono), dtype=dtype, res_type=recipe, backend=backend,
+            threads=int(threads), stream=int(track), serial=bool(_serial))
+    except Exception as first:
+        # Best-effort salvage: a damaged header can fail the dr tier while
+        # libav's deeper probing still recovers the audio. Only on hard
+        # failures; short/corrupt-mid-file reads never raise in the first
+        # place; and only when the libav tier wasn't already the one that
+        # failed. A missing file is not salvageable, so that error stands.
+        if strict or backend == "libav" or not os.path.exists(spath):
+            raise
+        try:
+            return _audio.load(
+                spath, sr=0 if sr is None else int(sr), offset=float(offset),
+                duration=-1.0 if duration is None else float(duration),
+                mono=bool(mono), dtype=dtype, res_type=recipe, backend="libav",
+                threads=int(threads), stream=int(track), serial=bool(_serial))
+        except Exception:
+            raise first from None
+
+
+def save(path, y, sr: int, *, subtype: Subtype | None = None,
+         bitrate: int | None = None, compression_level: int | None = None):
+    """Write audio `y` (sample rate `sr`) to `path`; the format is chosen from the
+    extension. Mirrors `load`'s layout: a 2-D array is (channels, frames), a 1-D
+    array is mono. Any float or int dtype is accepted (scaled to float32).
+
+    path:     output file; extension selects the codec/container
+              (.wav .flac .mp3 .ogg .m4a/.aac .opus).
+    subtype:  WAV sample format; "PCM_16" (default), "PCM_24", "PCM_32",
+              "FLOAT". Ignored by compressed formats.
+    bitrate:  target bits/s for the lossy codecs (mp3/aac/ogg/opus); None =
+              codec default. Ignored by WAV and FLAC (lossless).
+    """
+    y = _as_float32(y)
+    if y.ndim not in (1, 2):
+        raise ValueError(f"save expects a 1-D or 2-D array, got {y.ndim}-D")
+    # Pass the (channels, frames) planar array straight through; _audio.save
+    # interleaves it in C++ (NEON), so no strided transpose happens here.
+    arr = np.ascontiguousarray(y, dtype=np.float32)
+
+    ext = str(path).rsplit(".", 1)[-1].lower() if "." in str(path) else ""
+    container = _SAVE_EXT.get(ext)
+    if container is None:
+        raise ValueError(f"unsupported output extension '.{ext}' "
+                         f"(one of: {', '.join(sorted(set(_SAVE_EXT)))})")
+    _audio.save(str(path), arr, int(sr), container,
+               subtype or "", int(bitrate or 0),
+               -1 if compression_level is None else int(compression_level))
+
+
+def _run_batch(work, n, workers, on_error):
+    """Run `work(i)` for i in range(n) across a thread pool (each task releases
+    the GIL in C++). Returns a list of results; on_error='skip' puts the caught
+    Exception in that slot (so you get both *which* failed and *why*), 'raise'
+    re-raises the first failure. Order is preserved."""
+    if on_error not in ("raise", "skip"):
+        raise ValueError(f"on_error must be 'raise' or 'skip'; got '{on_error}'")
+    out: list = [None] * n
+    with ThreadPoolExecutor(max(1, workers)) as ex:
+        futs = {ex.submit(work, i): i for i in range(n)}
+        for fut in futs:
+            i = futs[fut]
+            try:
+                out[i] = fut.result()
+            except Exception as e:  # noqa: BLE001
+                if on_error == "raise":
+                    raise
+                out[i] = e
+    return out
+
+
+def save_bytes(y, sr: int, format: str, *,
+               subtype: Subtype | None = None, bitrate: int | None = None,
+               compression_level: int | None = None) -> bytes:
+    """Encode `y` to an in-memory container and return the bytes; the mirror
+    of ``load(bytes)``; nothing touches the filesystem.
+
+    format: "wav", "flac", "mp3", "ogg", or "m4a"/"mp4"/"aac"; other kwargs as
+    in save(). `load(save_bytes(y, sr, fmt))` round-trips.
+    """
+    y = _as_float32(y)
+    if y.ndim not in (1, 2):
+        raise ValueError(f"save_bytes expects a 1-D or 2-D array, got {y.ndim}-D")
+    return _audio.save_bytes(
+        np.ascontiguousarray(y), int(sr), _container_for(format, is_path=False),
+        subtype or "", int(bitrate or 0),
+        -1 if compression_level is None else int(compression_level))
+
+
+def codec_roundtrip(y, sr: int, format: str = "mp3", *,
+                    bitrate: int | None = None,
+                    compression_level: int | None = None):
+    """Encode+decode `y` through a lossy codec entirely in memory and return an
+    array with the SAME shape; codec-artifact augmentation for training
+    (simulate MP3/OGG compression). Length differences from encoder
+    delay/padding are trimmed / zero-padded back to the input length.
+    """
+    y = np.asarray(y, dtype=np.float32)
+    out, _ = load(save_bytes(y, sr, format, bitrate=bitrate,
+                             compression_level=compression_level))
+    out = np.asarray(out, dtype=np.float32)
+    if y.ndim == 2 and out.ndim == 1:
+        out = out[None, :]
+    elif y.ndim == 1 and out.ndim == 2:
+        out = out.mean(axis=0)
+    n, m = y.shape[-1], out.shape[-1]
+    if m > n:
+        out = out[..., :n]
+    elif m < n:
+        pad = [(0, 0)] * (out.ndim - 1) + [(0, n - m)]
+        out = np.pad(out, pad)
+    return out
+
+
+def load_many(paths, *, workers: int = 0,
+              on_error: Literal["raise", "skip"] = "raise", **kwargs):
+    """Load several files in parallel; returns a list of ``(samples, samplerate)``
+    in the same order as `paths`. `kwargs` are passed to `load` (sr, offset,
+    duration, mono, dtype, …) and apply to every file.
+
+    workers:  thread count (0 = auto: all cores). Decode releases the GIL, so
+              this scales across files.
+    on_error: 'raise' (default) aborts on the first failure; 'skip' completes the
+              batch and returns the Exception object in that file's slot instead
+              of a result; so a failed file is both detectable (`isinstance(r,
+              Exception)`) and inspectable (the error itself).
+
+    Files are decoded serially-per-file and parallelised across files (the right
+    model for many files); for fewer files than cores, each file keeps its own
+    internal parallelism.
+    """
+    paths = list(paths)
+    n = len(paths)
+    if n == 0:
+        return []
+    ncpu = _cpu_count()
+    if n < ncpu and workers == 0:      # few files: per-file parallelism, in order
+        out: list = []
+        for p in paths:
+            try:
+                out.append(load(p, **kwargs))
+            except Exception as e:     # noqa: BLE001
+                if on_error == "raise":
+                    raise
+                out.append(e)
+        return out
+    nworkers = workers or min(n, ncpu)
+    return _run_batch(lambda i: load(paths[i], _serial=True, **kwargs),
+                      n, nworkers, on_error)
+
+
+def save_many(items, *, workers: int = 0,
+              on_error: Literal["raise", "skip"] = "raise", **kwargs):
+    """Save several ``(path, y, sr)`` items in parallel. `kwargs` are passed to
+    `save` (subtype, bitrate, …) and apply to every item.
+
+    Returns None on full success. With on_error='skip' the batch always completes
+    and a list is returned whose entries are None (ok) or the Exception for a
+    failed item. Encoding releases the GIL, so this scales across files.
+    """
+    items = list(items)
+    n = len(items)
+    if n == 0:
+        return None
+    nworkers = workers or min(n, _cpu_count())
+
+    def one(i):
+        path, y, sr = items[i]
+        save(path, y, sr, **kwargs)
+
+    res = _run_batch(one, n, nworkers, on_error)
+    if on_error == "skip":
+        return [r if isinstance(r, Exception) else None for r in res]
+    return None
+