desphere 0.1.0__py3-none-any.whl

desphere/__init__.py

@@ -0,0 +1,49 @@
+"""desphere — a clean-room NIST SPHERE -> RIFF/WAV transcoder.
+
+Flatten a "sphere" (NIST SPHERE audio) into a flat WAV. MIT-licensed,
+zero-dependency, built only from public format documentation and black-box
+testing — never from GPL/LGPL source.
+
+Public API::
+
+    from desphere import read_sphere, transcode, sph_to_wav, SphereHeader
+
+    header, data = read_sphere("utt.sph")
+    with open("utt.wav", "wb") as f:
+        transcode(header, data, f)
+"""
+
+from __future__ import annotations
+
+from .errors import (
+    DesphereError,
+    SphereHeaderError,
+    UnsupportedCoding,
+    UnsupportedFormat,
+)
+from .sphere import SphereHeader
+from .transcode import (
+    native_available,
+    read_sphere,
+    sph_to_wav,
+    transcode,
+    transcode_bytes,
+)
+from .wav import write_wav
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "SphereHeader",
+    "read_sphere",
+    "transcode",
+    "transcode_bytes",
+    "sph_to_wav",
+    "native_available",
+    "write_wav",
+    "DesphereError",
+    "SphereHeaderError",
+    "UnsupportedCoding",
+    "UnsupportedFormat",
+]

desphere/cli.py

@@ -0,0 +1,155 @@
+"""``sph2wav`` command-line interface.
+
+Usage::
+
+    sph2wav INPUT.sph [OUTPUT.wav]
+    sph2wav --info INPUT.sph
+    sph2wav INPUT.sph -        # write WAV to stdout
+
+Mirrors the name of the tool people migrate away from, so it is easy to find.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+
+from . import __version__
+from .errors import DesphereError
+from .sphere import SphereHeader
+from .transcode import transcode_bytes
+
+
+def _default_output(in_path: str) -> str:
+    root, _ = os.path.splitext(in_path)
+    return root + ".wav"
+
+
+def _print_info(header: SphereHeader, in_path: str, data_len: int) -> None:
+    duration = (
+        header.sample_count / header.sample_rate if header.sample_rate else 0.0
+    )
+    print(f"{in_path}")
+    print(f"  sample_coding      : {header.sample_coding}")
+    print(f"  sample_rate        : {header.sample_rate} Hz")
+    print(f"  channel_count      : {header.channel_count}")
+    print(f"  sample_n_bytes     : {header.sample_n_bytes} ({header.sample_n_bytes * 8}-bit)")
+    print(f"  sample_byte_format : {header.sample_byte_format}")
+    print(f"  sample_sig_bits    : {header.sample_sig_bits}")
+    print(f"  sample_count       : {header.sample_count} ({duration:.3f} s)")
+    print(f"  header_size        : {header.header_size} bytes")
+    tokens = [t.strip().lower() for t in header.sample_coding.split(",")]
+    if len(tokens) > 1 and tokens[1]:
+        # Compressed: the payload is a bitstream, so expected_data_bytes is the
+        # UNCOMPRESSED size, not a target to match.
+        print(
+            f"  payload bytes      : {data_len} "
+            f"(compressed; uncompressed ~{header.expected_data_bytes})"
+        )
+    else:
+        print(f"  payload bytes      : {data_len} (expected {header.expected_data_bytes})")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="sph2wav",
+        description="Transcode a NIST SPHERE file to RIFF/WAV (desphere).",
+    )
+    p.add_argument("input", help="input .sph file")
+    p.add_argument(
+        "output",
+        nargs="?",
+        help="output .wav file (default: input with .wav extension; '-' for stdout)",
+    )
+    p.add_argument("--info", action="store_true", help="print header and exit")
+    p.add_argument(
+        "-f", "--force", action="store_true", help="overwrite output if it exists"
+    )
+    p.add_argument("--version", action="version", version=f"desphere {__version__}")
+    return p
+
+
+def _is_wav(b: bytes) -> bool:
+    return len(b) >= 12 and b[:4] == b"RIFF" and b[8:12] == b"WAVE"
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        with open(args.input, "rb") as f:
+            raw = f.read()
+    except OSError as exc:
+        print(f"sph2wav: cannot read {args.input}: {exc}", file=sys.stderr)
+        return 2
+
+    if args.info:
+        if _is_wav(raw):
+            print(f"{args.input}\n  (already a RIFF/WAV file, not NIST SPHERE)")
+            return 0
+        try:
+            header = SphereHeader.parse(raw)
+        except DesphereError as exc:
+            print(f"sph2wav: {exc}", file=sys.stderr)
+            return 2
+        _print_info(header, args.input, len(raw) - header.header_size)
+        return 0
+
+    out_path = args.output or _default_output(args.input)
+    to_stdout = out_path == "-"
+
+    if not to_stdout:
+        if os.path.abspath(out_path) == os.path.abspath(args.input):
+            print(
+                "sph2wav: refusing to overwrite the input file; "
+                "specify a different output path",
+                file=sys.stderr,
+            )
+            return 2
+        if os.path.exists(out_path) and not args.force:
+            print(
+                f"sph2wav: {out_path} exists (use -f/--force to overwrite)",
+                file=sys.stderr,
+            )
+            return 2
+
+    if _is_wav(raw):
+        # A stray WAV is already what the caller wants — pass it through, warning
+        # so the mistake is visible. (The library stays strict; this is CLI UX.)
+        print(
+            f"sph2wav: {args.input} is already a RIFF/WAV file; "
+            "copying it through unchanged",
+            file=sys.stderr,
+        )
+        wav = raw
+    else:
+        try:
+            wav = transcode_bytes(raw)  # uses the Rust accelerator if installed
+        except DesphereError as exc:
+            print(f"sph2wav: {exc}", file=sys.stderr)
+            return 2
+
+    if to_stdout:
+        sys.stdout.buffer.write(wav)
+    else:
+        # Atomic write: a temp file renamed on success leaves no partial output.
+        out_dir = os.path.dirname(os.path.abspath(out_path)) or "."
+        fd, tmp = tempfile.mkstemp(suffix=".wav.tmp", dir=out_dir)
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(wav)
+            os.replace(tmp, out_path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+        print(f"sph2wav: wrote {out_path}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

desphere/codecs.py

@@ -0,0 +1,217 @@
+"""Sample-coding decoders and the capability gate.
+
+``sample_coding`` in a SPHERE header looks like ``pcm``, ``ulaw``, ``alaw``, or
+a base coding plus a compression token, e.g. ``pcm,embedded-shorten-v2.00``.
+
+:func:`resolve_codec` is the single place that decides whether we can handle a
+file. The design goal (per project intent) is: support the obvious, clearly
+documented, lossless path first, and **fail loudly** on everything else so we
+never emit a plausible-but-wrong WAV. New variants slot in by registering a
+decoder; until then the gate raises a precise error.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Tuple
+
+from . import g711, shorten
+from .errors import (
+    DesphereError,
+    SphereHeaderError,
+    UnsupportedCoding,
+    UnsupportedFormat,
+)
+from .sphere import SphereHeader
+
+# Optional Rust accelerator. Only the heavy numeric kernels (shorten decode and
+# G.711 expansion) are delegated; the typed validation/error checks stay here, so
+# behavior is identical with or without it. PCM byte-reorder stays pure (the
+# strided slice is already C-speed). pip install desphere[fast] to enable.
+try:
+    import desphere_native as _native
+except ImportError:  # pragma: no cover - native is optional
+    _native = None
+
+# Map NIST sample_byte_format -> endianness of the stored samples.
+#   "01" = low byte first  (little-endian)
+#   "10" = high byte first  (big-endian)
+#   "1"  = single byte      (order irrelevant)
+_BYTE_ORDER = {
+    "1": "little",
+    "01": "little",
+    "10": "big",
+}
+
+
+def _to_little_endian(raw: bytes, n_bytes: int, order: str) -> bytes:
+    """Return ``raw`` with each ``n_bytes``-wide sample in little-endian order."""
+    if n_bytes == 1 or order == "little":
+        return raw
+    # Reverse byte order within every n_bytes-sized group using strided slice
+    # assignment (C-speed, no numpy dependency).
+    out = bytearray(len(raw))
+    for i in range(n_bytes):
+        out[i::n_bytes] = raw[n_bytes - 1 - i::n_bytes]
+    return bytes(out)
+
+
+class PcmCodec:
+    """Linear PCM: a lossless byte-order normalization to little-endian WAV.
+
+    Supports 16-bit and 32-bit samples (the overwhelming majority of SPHERE
+    corpora). 8-bit and 24-bit are deliberately rejected for now: their sign
+    and packing conventions have not been validated against an oracle, and a
+    wrong guess would silently corrupt audio.
+    """
+
+    name = "pcm"
+    supported_n_bytes = (2, 4)
+
+    @classmethod
+    def decode(cls, header: SphereHeader, data: bytes) -> Tuple[int, bytes]:
+        n_bytes = header.sample_n_bytes
+        if n_bytes not in cls.supported_n_bytes:
+            raise UnsupportedFormat(
+                f"{n_bytes * 8}-bit PCM not supported yet "
+                f"(supported: {[n * 8 for n in cls.supported_n_bytes]} bit)"
+            )
+
+        order = _BYTE_ORDER.get(header.sample_byte_format)
+        if order is None:
+            raise UnsupportedFormat(
+                f"unrecognized sample_byte_format {header.sample_byte_format!r} "
+                "(supported: '1', '01', '10')"
+            )
+
+        little = _to_little_endian(data, n_bytes, order)
+        return n_bytes * 8, little
+
+
+class _G711Codec:
+    """Base for the two ITU-T G.711 companding laws (8-bit in, 16-bit out)."""
+
+    name = "g711"
+    table: list = []
+
+    @classmethod
+    def decode(cls, header: SphereHeader, data: bytes) -> Tuple[int, bytes]:
+        if header.sample_n_bytes != 1:
+            raise UnsupportedFormat(
+                f"{cls.name} expects 1-byte samples, got "
+                f"sample_n_bytes={header.sample_n_bytes}"
+            )
+        if _native is not None:
+            return 16, bytes(_native.g711_expand(bytes(data), cls.name == "alaw"))
+        return 16, g711.expand(data, cls.table)
+
+
+class UlawCodec(_G711Codec):
+    name = "ulaw"
+    table = g711.ULAW_TABLE
+
+
+class AlawCodec(_G711Codec):
+    name = "alaw"
+    table = g711.ALAW_TABLE
+
+
+class ShortenCodec:
+    """Embedded-shorten (v2) lossless decompression to little-endian PCM.
+
+    Handles 16-bit PCM shorten types, the lossless mu-law mode (type 8, including
+    BITSHIFT, expanded to 16-bit PCM via G.711), and QLPC (LPC-predicted) blocks.
+    Only unsupported shorten sample types raise a precise error.
+    """
+
+    name = "embedded-shorten-v2.00"
+
+    @classmethod
+    def decode(cls, header: SphereHeader, data: bytes) -> Tuple[int, bytes]:
+        if _native is not None:
+            # Native does the heavy decode+expand and returns PCM bytes; we keep
+            # the same typed header cross-checks (on the emitted PCM, 2 B/sample).
+            try:
+                nchan, _is_ulaw, pcm = _native.shorten_to_pcm(bytes(data))
+            except ValueError as exc:
+                raise DesphereError(str(exc)) from exc
+            pcm = bytes(pcm)
+            if nchan != header.channel_count:
+                raise UnsupportedFormat(
+                    f"shorten channel count {nchan} disagrees with SPHERE header "
+                    f"channel_count {header.channel_count}"
+                )
+            expected = header.sample_count * nchan  # in samples
+            got = len(pcm) // 2
+            if got < expected:
+                raise SphereHeaderError(
+                    f"shorten stream decoded {got // nchan} samples/channel, "
+                    f"but the SPHERE header declares {header.sample_count} "
+                    "(stream truncated or QUIT came early)"
+                )
+            return 16, (pcm[: expected * 2] if got > expected else pcm)
+
+        values, kind, nchan = shorten.decode(data)
+        if nchan != header.channel_count:
+            raise UnsupportedFormat(
+                f"shorten channel count {nchan} disagrees with SPHERE header "
+                f"channel_count {header.channel_count}"
+            )
+        # Cross-check the decoded length against the header, mirroring the PCM
+        # path's truncation guard: a stream that QUITs early would otherwise yield
+        # a silently-short WAV. Excess (final-block padding) is trimmed.
+        expected = header.sample_count * nchan
+        if len(values) < expected:
+            raise SphereHeaderError(
+                f"shorten stream decoded {len(values) // nchan} samples/channel, "
+                f"but the SPHERE header declares {header.sample_count} "
+                "(stream truncated or QUIT came early)"
+            )
+        if len(values) > expected:
+            values = values[:expected]
+        if kind == "ulaw":
+            return 16, g711.expand(bytes(values), g711.ULAW_TABLE)
+        # kind == "pcm16": signed 16-bit little-endian
+        lo, hi = -32768, 32767
+        clipped = [lo if v < lo else hi if v > hi else v for v in values]
+        return 16, struct.pack("<%dh" % len(clipped), *clipped)
+
+
+# Registry of base codings we can decode. Compression tokens are gated
+# separately so unsupported compressions fail with a clear message.
+# Aliases cover the spellings different encoders write into the header.
+_BASE_CODECS = {
+    "pcm": PcmCodec,
+    "ulaw": UlawCodec,
+    "mu-law": UlawCodec,
+    "mulaw": UlawCodec,
+    "alaw": AlawCodec,
+    "a-law": AlawCodec,
+}
+_COMPRESSORS = {
+    "embedded-shorten-v2.00": ShortenCodec,
+}
+
+
+def resolve_codec(header: SphereHeader):
+    """Return a codec for ``header`` or raise a precise Unsupported* error."""
+    tokens = [t.strip().lower() for t in header.sample_coding.split(",")]
+    base = tokens[0]
+    compression = tokens[1] if len(tokens) > 1 else None
+
+    if compression:
+        if compression not in _COMPRESSORS:
+            raise UnsupportedCoding(
+                f"compressed coding {header.sample_coding!r} not supported yet "
+                f"(compression: {compression!r})"
+            )
+        # Future: return a decoder that decompresses, then applies the base codec.
+        return _COMPRESSORS[compression]
+
+    codec = _BASE_CODECS.get(base)
+    if codec is None:
+        raise UnsupportedCoding(
+            f"sample_coding {base!r} not supported yet "
+            f"(supported: {sorted(_BASE_CODECS)})"
+        )
+    return codec

desphere/errors.py

@@ -0,0 +1,34 @@
+"""Exception hierarchy for desphere.
+
+Everything that goes wrong raises a subclass of :class:`DesphereError`, so a
+caller (or the ``sph2wav`` CLI) can catch one type and always get an actionable
+message instead of a stack trace or, worse, a plausible-but-wrong WAV.
+"""
+
+from __future__ import annotations
+
+
+class DesphereError(Exception):
+    """Base class for all desphere errors."""
+
+
+class SphereHeaderError(DesphereError):
+    """The NIST SPHERE header is missing, malformed, or internally inconsistent.
+
+    Also raised when the audio payload is shorter than the header claims.
+    """
+
+
+class UnsupportedCoding(DesphereError):
+    """The ``sample_coding`` is structurally valid but not implemented.
+
+    Examples: a base coding desphere does not recognize, or a compression token
+    other than ``embedded-shorten-v2.00``. We fail loudly rather than guess.
+    """
+
+
+class UnsupportedFormat(DesphereError):
+    """A structurally valid field describes a layout we have not validated.
+
+    Examples: 8-bit or 24-bit PCM, or an unrecognized ``sample_byte_format``.
+    """

desphere/g711.py

@@ -0,0 +1,49 @@
+"""ITU-T G.711 mu-law / a-law expansion to 16-bit linear PCM.
+
+Implemented from the **ITU-T G.711** recommendation (a public telecom standard
+that defines the companding tables); no GPL/LGPL source was consulted. The
+decode is a fixed 256-entry table, so we precompute it once at import.
+
+Both laws expand an 8-bit companded code to a signed 16-bit linear sample.
+"""
+
+from __future__ import annotations
+
+import array
+import sys
+from typing import List
+
+_BIAS = 0x84  # 132; the mu-law magnitude bias
+
+
+def _ulaw_to_linear(u_val: int) -> int:
+    """Expand one mu-law byte to a signed 16-bit sample (ITU-T G.711)."""
+    u_val = ~u_val & 0xFF
+    t = ((u_val & 0x0F) << 3) + _BIAS
+    t <<= (u_val & 0x70) >> 4
+    return (_BIAS - t) if (u_val & 0x80) else (t - _BIAS)
+
+
+def _alaw_to_linear(a_val: int) -> int:
+    """Expand one a-law byte to a signed 16-bit sample (ITU-T G.711)."""
+    a_val ^= 0x55
+    mantissa = a_val & 0x0F
+    segment = (a_val & 0x70) >> 4
+    if segment == 0:
+        t = (mantissa << 4) + 8
+    else:
+        t = ((mantissa << 4) + 0x108) << (segment - 1)
+    return t if (a_val & 0x80) else -t
+
+
+# Precomputed expansion tables: code (0..255) -> signed 16-bit sample.
+ULAW_TABLE: List[int] = [_ulaw_to_linear(i) for i in range(256)]
+ALAW_TABLE: List[int] = [_alaw_to_linear(i) for i in range(256)]
+
+
+def expand(data: bytes, table: List[int]) -> bytes:
+    """Expand companded ``data`` to little-endian 16-bit PCM via ``table``."""
+    samples = array.array("h", [table[b] for b in data])
+    if sys.byteorder == "big":
+        samples.byteswap()  # WAV/RIFF is little-endian
+    return samples.tobytes()