desphere 0.1.0__tar.gz

desphere-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# Oracle / scratch output (regenerated, not committed)
+*.ref.wav
+/scratch/
+
+# Real corpus test files — license-restricted (TIMIT/Switchboard/etc).
+# Synced via Syncthing for cross-machine local testing; never committed.
+/local-fixtures/
+
+# Black-box oracle BINARIES — used to validate decode output only; we never read
+# their source. License-restricted, synced via Syncthing, not committed. The
+# build SCRIPTS + README ARE committed as clean-room paper-trail evidence
+# (compiling != reading source); see PROVENANCE.md.
+/oracles/sph2pipe
+/oracles/w_decode
+/oracles/shorten
+
+# Local working state — Syncthing-synced, not committed (see CLAUDE.md)
+/memories/
+/plans/
+
+# Editor
+*.swp
+.DS_Store
+
+# Built WASM for the web page (regenerated; deployed by CI)
+/web/pkg/
+
+# Rust build dir (the crate is a workspace member under rust/; cargo builds into
+# the workspace-root target/). Cargo.lock at the root IS committed.
+/target/

desphere-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to desphere (the Python package and the Rust crate) are
+recorded here. Format loosely follows [Keep a Changelog]; versions are shared
+across the Python `desphere`, the Rust crate `desphere`, and the pyo3 module
+`desphere-native`.
+
+## [0.1.0] — 2026-06-28 (first release)
+
+First public release. NIST SPHERE → RIFF/WAV transcoder, clean-room and
+MIT-licensed (see `PROVENANCE.md`).
+
+### Decoding (Python reference + Rust port, byte-for-byte identical)
+- PCM 16/32-bit, byte order `01`/`10`, mono & multi-channel.
+- G.711 μ-law / a-law (ITU-T G.711).
+- Embedded-shorten v2:
+  - 16-bit PCM (DIFF0–3, ZERO, VERBATIM, BLOCKSIZE).
+  - Lossless μ-law (type 8), including the non-linear **BITSHIFT** code-space
+    remap (validated on real CALLHOME audio).
+  - **QLPC** (LPC-predicted) blocks (validated vs the shorten encoder + ffmpeg,
+    orders 1–20, mono & stereo).
+- Fail-loud on everything unvalidated (8/24-bit PCM, QLPC-less unknown codings,
+  corrupt/truncated streams) — never emits a plausible-but-wrong WAV, never
+  panics (safe for WASM).
+
+### Packaging
+- Python package `desphere` with the `sph2wav` CLI (pure Python, zero deps). The
+  whole decode path — the streaming `transcode()`, the one-shot `transcode_bytes()`,
+  and the CLI — transparently uses the optional Rust accelerator when installed
+  (`pip install desphere[fast]` → `desphere-native`) and falls back to pure Python
+  otherwise — same bytes either way. The accelerator delegates the heavy kernels
+  (shorten decode, G.711 expansion); typed error checks stay in Python.
+- Rust crate `desphere` (dependency-free core); Rust clients (e.g. praatfan)
+  import it via a path/git dependency.
+- WASM bindings via `wasm-bindgen` (opt-in `wasm` feature) + a self-contained
+  client-side `sph2wav` web page (`web/`, deployed to GitHub Pages) — converts in
+  the browser, nothing uploaded.
+- Python-native module `desphere-native` via pyo3/maturin (opt-in `python`
+  feature).
+- The CLI and web page pass a stray RIFF/WAV input through unchanged, with a
+  warning (the library API stays strict: SPHERE in, fail loud).
+- Not published to crates.io / npm (consumers depend on the repo directly); PyPI
+  is the target registry.
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/

desphere-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uriel Cohen Priva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

desphere-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: desphere
+Version: 0.1.0
+Summary: Clean-room NIST SPHERE (and Shorten) to RIFF/WAV transcoder
+Project-URL: Homepage, https://github.com/ucpresearch/desphere
+Author: Uriel Cohen Priva
+License: MIT License
+        
+        Copyright (c) 2026 Uriel Cohen Priva
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: audio,nist,riff,shorten,sph2pipe,sphere,transcode,wav
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: desphere-native; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# desphere
+
+**Flatten a sphere.** `desphere` is a clean-room, MIT-licensed, zero-dependency
+transcoder from **NIST SPHERE** audio (the `.sph` format used by TIMIT, WSJ,
+Switchboard, and friends) to plain **RIFF/WAV**. The CLI is `sph2wav`.
+
+> **No tooling, no upload:** there's a browser page that converts a `.sph` to
+> `.wav` entirely client-side (WASM) — see [`web/`](web/index.html). Prefer
+> `sph2pipe`/`ffmpeg`/`sox` if you have them; the page is for when you don't.
+
+```bash
+pip install desphere            # pure Python, zero deps, works anywhere
+pip install "desphere[fast]"    # + optional Rust accelerator (big shorten files)
+
+sph2wav utterance.sph             # -> utterance.wav
+sph2wav utterance.sph out.wav
+sph2wav --info utterance.sph      # inspect the SPHERE header
+sph2wav utterance.sph -           # WAV to stdout
+```
+
+```python
+from desphere import read_sphere, transcode, transcode_bytes
+
+# Streaming API (the reference):
+header, data = read_sphere("utterance.sph")
+with open("utterance.wav", "wb") as f:
+    transcode(header, data, f)
+
+# One-shot bytes API:
+wav_bytes = transcode_bytes(open("utterance.sph", "rb").read())
+```
+
+**Both APIs transparently use the Rust accelerator when installed** (and fall
+back to pure Python) — same bytes out either way. With `desphere[fast]`, the
+heavy kernels (shorten decode, G.711 expansion) run in Rust; pure-Python PCM is
+already C-speed. The CLI passes a stray `.wav` through unchanged (with a warning),
+so pointing it at an already-decoded file is harmless.
+
+## Why
+
+`libsndfile`/`soundfile` cannot read SPHERE (especially shorten-compressed
+SPHERE), and the tools that can — `sph2pipe`, the original `shorten`, FFmpeg's
+decoder — are GPL/LGPL or otherwise awkwardly licensed. `desphere` is a
+permissively licensed, dependency-free reimplementation.
+
+## Clean-room policy
+
+`desphere` is implemented **only** from:
+
+- The **public NIST SPHERE** format description (ASCII header, typed object fields).
+- **ITU-T G.711** for μ-law / a-law.
+- Tony Robinson (1994), *SHORTEN: Simple lossless and near-lossless waveform
+  compression* (CUED/F-INFENG/TR.156) for the shorten algorithm.
+- **Black-box testing**: running `sox` / `ffmpeg` / `sph2pipe` as binaries and
+  comparing only their **output** — never reading their source.
+
+Copyright protects source code, not file formats or algorithms (the
+idea/expression dichotomy), so consulting *prose/tabular* descriptions of a
+format — even third-party ones — is fine. The one rule we never break: **we do
+not read GPL/LGPL source code, and we do not use writeups that embed verbatim
+GPL source.** Authoritative non-source references (the TR, ITU specs, NIST docs)
+are the primary sources; prose writeups are at most a cross-check.
+
+## Supported matrix
+
+The design principle is **support the obvious lossless path first, and fail
+loudly on anything not yet validated** — never emit a plausible-but-wrong WAV.
+
+| Coding | Status |
+|--------|--------|
+| `pcm`, 16-bit, `01`/`10` byte order | ✅ supported |
+| `pcm`, 32-bit, `01`/`10` byte order | ✅ supported |
+| `pcm`, multi-channel (interleaved)  | ✅ supported (validate against an oracle for exotic files) |
+| `pcm`, 8-bit / 24-bit               | ⛔ rejected (`UnsupportedFormat`) — sign/packing not yet validated |
+| `ulaw` / `alaw` (G.711, 8-bit)      | ✅ supported (Phase B) — verified byte-exact vs ffmpeg on all 256 codes |
+| `pcm,embedded-shorten-v2.00` (16-bit) | ✅ supported (Phase C) — byte-exact vs ffmpeg, mono & stereo |
+| `ulaw,embedded-shorten` (shorten type 8), incl. bitshift | ✅ supported (Phase C) — byte-exact vs sph2pipe (real CALLHOME) |
+| shorten QLPC (LPC) blocks           | ✅ supported (Phase C) — byte-exact vs shorten encoder + ffmpeg (orders 1–20) |
+
+Adding a coding means registering a decoder in `desphere/codecs.py`; until then
+the gate raises a precise error.
+
+## Test fixtures (the "zoo")
+
+We don't depend on real corpus files to test: `tools/make_fixtures.py`
+*generates* a zoo of SPHERE variants — every byte order, bit depth, and channel
+count — and commits them under `tests/fixtures/` with a manifest recording the
+exact expected output. Harder codings (μ-law/a-law, eventually shorten) are
+produced best-effort by driving `sox`/`ffmpeg`/`shorten` as black-box binaries.
+
+```bash
+python tools/make_fixtures.py     # regenerate fixtures + manifest
+pytest                            # validate everything
+```
+
+## Rust, WASM, and consumers
+
+The Python in `src/desphere` is the reference **spec**; [`rust/`](rust/) is a
+Rust port that reproduces it **bit-for-bit** (same fixtures), for speed and for
+the web. It builds three ways from one crate:
+
+- a **Rust library** — a Rust client (praatfan is a likely consumer) imports it
+  via a path/git dependency;
+- **WASM** (`wasm-pack build rust --target web --features wasm`) — a WASM web app
+  and the `web/` page consume it; nothing is sent to a server;
+- a **Python extension** `desphere-native` (pyo3/maturin) — the optional
+  `desphere[fast]` accelerator above.
+
+Because the consumers live in the same `ucpresearch` org, they depend on desphere
+directly (path/git); publishing to **crates.io / npm is not required** (and is
+skipped). **PyPI** is the one registry we target (the pure-Python `desphere`,
+plus the optional `desphere-native` wheels).
+
+## Development
+
+The virtualenv lives **outside** the (Syncthing-synced) repo and is symlinked in:
+
+```bash
+uv venv ~/local/scr/venvs/desphere
+ln -s ~/local/scr/venvs/desphere .venv
+uv pip install -e ".[dev]"
+pytest
+
+# Rust port:
+cd rust && cargo test            # byte-exact vs the same fixtures
+```
+
+## Roadmap
+
+- **Phase A** (done): SPHERE header + 16/32-bit PCM, lossless.
+- **Phase B** (done): μ-law / a-law decode (ITU-T G.711).
+- **Phase C** (done): embedded-shorten of 16-bit PCM, lossless μ-law (type 8,
+  including the non-linear BITSHIFT remap), and QLPC (LPC) blocks — validated
+  byte-for-byte vs ffmpeg / sph2pipe / the `shorten` encoder on real and
+  synthetic streams, mono and stereo. Remaining (low priority): 8/24-bit linear
+  PCM. See `docs/STATUS.md` and `docs/SHORTEN.md`.
+- **Eventually → Rust** (for a Rust client / WASM, and for speed), mirroring
+  `praatfan-core-clean`'s Python-first-then-Rust path. The Python implementation
+  stays as the readable reference. Porting guidance: `docs/RUST_PORT.md`.

desphere-0.1.0/PROVENANCE.md

@@ -0,0 +1,90 @@
+# PROVENANCE — clean-room record for desphere
+
+This document is the paper trail establishing that **desphere contains no
+GPL/LGPL-derived code** and may be licensed under the MIT License. It applies to
+both the Python reference (`src/desphere/`) and the Rust port (`rust/`).
+
+## Summary
+
+desphere is a NIST SPHERE → RIFF/WAV transcoder (PCM, G.711 μ-law/a-law, and
+embedded-shorten v2 including QLPC and lossless μ-law type-8 with bitshift). It
+was implemented **only** from public specifications and **black-box** testing of
+existing tools. **No GPL/LGPL source code was ever read** at any point.
+
+Copyright protects source code — not file formats, facts, or algorithms (the
+idea/expression dichotomy). Building a decoder from a published format/algorithm
+description, and checking it by comparing the *output* of existing binaries, does
+not create a derivative work of those binaries.
+
+## Permitted sources actually used
+
+- **NIST SPHERE format** — public NIST documentation (the ASCII `NIST_1A` header,
+  typed object fields). Used for `sphere.py` / `rust/src/sphere.rs`.
+- **ITU-T G.711** — the public telecom standard defining the μ-law / a-law
+  companding tables. Used for `g711.py` / `rust/src/g711.rs`.
+- **Tony Robinson (1994), _SHORTEN: Simple lossless and near-lossless waveform
+  compression_, CUED/F-INFENG/TR.156** — the published academic report describing
+  the shorten algorithm (Rice/uvar coding, polynomial vs LPC prediction). A copy
+  was read; it describes the *algorithm*, not anyone's source code. Used for the
+  shorten decoder: `shorten.py` / `rust/src/shorten.rs` (block loop, DIFF/QLPC
+  prediction, type-8 mu-law) and the bit primitives in `rust/src/bitreader.rs`
+  (`uvar`/`ulong`/`var`). The non-obvious details (the `k=energy+1` Rice quirk,
+  the type-8 bitshift remap, QLPC fixed-point) were recovered from oracle OUTPUT,
+  not from any decoder source — see below.
+- **Microsoft/IBM RIFF/WAVE** — the public container spec. Used for `wav.py` /
+  `rust/src/wav.rs`.
+- **Black-box oracle testing** — `ffmpeg`, `sox`, `sph2pipe`, NIST `w_decode`, and
+  the `shorten` encoder were run **as binaries**; only their *output bytes* were
+  compared against desphere's output. Running a binary is not reading its source.
+
+## Never read (hard rule, no exceptions)
+
+- FFmpeg's NIST/shorten decoder (LGPL)
+- the original `shorten` C sources and `sph2pipe` sources
+- any GPL/LGPL codebase, **including the author's own praatfan GPL siblings**
+
+The `shorten` **encoder** (Tony Robinson's `drtonyr/shorten`, a non-FOSS license)
+was *downloaded and compiled* to generate test fixtures and act as a second
+black-box oracle. Its `.c/.h` source was **never opened**; the build needed only
+a modern-stdarg shim written from scratch. The build scripts
+`oracles/build_shorten.sh` and `oracles/build_w_decode.sh` are committed (text,
+ours) as evidence; the binaries they produce are gitignored (license-restricted).
+Compiling ≠ reading source.
+
+## How the hard parts were derived (reverse-engineering, from oracle output only)
+
+The non-obvious shorten details were recovered by comparing reconstructed values
+to oracle output, never by reading a decoder:
+
+- The Rice parameter quirk (`k = energy + 1`), the running-mean offset, and bit
+  order: validated byte-exact against ffmpeg/sph2pipe output.
+- **Type-8 μ-law + BITSHIFT**: derived as a code-space remap by tabulating
+  `sph2pipe -u` (true μ-law bytes) against desphere's reconstructed values; the
+  closed form was confirmed by mu-law segment geometry (a G.711 fact) and
+  validated byte-exact on real CALLHOME audio. See `docs/SHORTEN.md`.
+- **QLPC**: no corpus file uses it, so the `shorten` encoder (compiled, not read)
+  was driven on known synthetic input to produce QLPC streams, and the decode
+  was reverse-engineered by matching desphere's output to the known input and to
+  `ffmpeg`/`shorten -x`. See `docs/SHORTEN.md` → "QLPC blocks".
+
+The git history is itself part of the trail: commits record the oracle
+comparisons, the "never reading decoder source" methodology, and that the encoder
+was "compiled, never reading source."
+
+## The Rust port
+
+`rust/` is a direct translation of desphere's **own MIT Python** (`src/desphere/`,
+which is the spec), guided by `docs/RUST_PORT.md`. It is validated bit-for-bit
+against the same committed fixtures and shown byte-identical to the Python
+`sph2wav`. No GPL/LGPL source — and no third-party Rust decoder — was consulted.
+The `praatfan-core-clean` sibling was used only for high-level project *layout*
+conventions (a `rust/` crate with `examples/`, pyo3, maturin); its source was not
+read.
+
+## Licensing
+
+desphere is MIT-licensed (`LICENSE`). The permitted sources above impose no
+copyleft obligation on an independent implementation: file formats and algorithms
+are not copyrightable, ITU/NIST/RIFF specs are public standards, and black-box
+output comparison is not derivation. The non-FOSS `shorten` encoder is a build/
+test tool only — it is not linked into, vendored by, or read for desphere.

desphere-0.1.0/README.md

@@ -0,0 +1,139 @@
+# desphere
+
+**Flatten a sphere.** `desphere` is a clean-room, MIT-licensed, zero-dependency
+transcoder from **NIST SPHERE** audio (the `.sph` format used by TIMIT, WSJ,
+Switchboard, and friends) to plain **RIFF/WAV**. The CLI is `sph2wav`.
+
+> **No tooling, no upload:** there's a browser page that converts a `.sph` to
+> `.wav` entirely client-side (WASM) — see [`web/`](web/index.html). Prefer
+> `sph2pipe`/`ffmpeg`/`sox` if you have them; the page is for when you don't.
+
+```bash
+pip install desphere            # pure Python, zero deps, works anywhere
+pip install "desphere[fast]"    # + optional Rust accelerator (big shorten files)
+
+sph2wav utterance.sph             # -> utterance.wav
+sph2wav utterance.sph out.wav
+sph2wav --info utterance.sph      # inspect the SPHERE header
+sph2wav utterance.sph -           # WAV to stdout
+```
+
+```python
+from desphere import read_sphere, transcode, transcode_bytes
+
+# Streaming API (the reference):
+header, data = read_sphere("utterance.sph")
+with open("utterance.wav", "wb") as f:
+    transcode(header, data, f)
+
+# One-shot bytes API:
+wav_bytes = transcode_bytes(open("utterance.sph", "rb").read())
+```
+
+**Both APIs transparently use the Rust accelerator when installed** (and fall
+back to pure Python) — same bytes out either way. With `desphere[fast]`, the
+heavy kernels (shorten decode, G.711 expansion) run in Rust; pure-Python PCM is
+already C-speed. The CLI passes a stray `.wav` through unchanged (with a warning),
+so pointing it at an already-decoded file is harmless.
+
+## Why
+
+`libsndfile`/`soundfile` cannot read SPHERE (especially shorten-compressed
+SPHERE), and the tools that can — `sph2pipe`, the original `shorten`, FFmpeg's
+decoder — are GPL/LGPL or otherwise awkwardly licensed. `desphere` is a
+permissively licensed, dependency-free reimplementation.
+
+## Clean-room policy
+
+`desphere` is implemented **only** from:
+
+- The **public NIST SPHERE** format description (ASCII header, typed object fields).
+- **ITU-T G.711** for μ-law / a-law.
+- Tony Robinson (1994), *SHORTEN: Simple lossless and near-lossless waveform
+  compression* (CUED/F-INFENG/TR.156) for the shorten algorithm.
+- **Black-box testing**: running `sox` / `ffmpeg` / `sph2pipe` as binaries and
+  comparing only their **output** — never reading their source.
+
+Copyright protects source code, not file formats or algorithms (the
+idea/expression dichotomy), so consulting *prose/tabular* descriptions of a
+format — even third-party ones — is fine. The one rule we never break: **we do
+not read GPL/LGPL source code, and we do not use writeups that embed verbatim
+GPL source.** Authoritative non-source references (the TR, ITU specs, NIST docs)
+are the primary sources; prose writeups are at most a cross-check.
+
+## Supported matrix
+
+The design principle is **support the obvious lossless path first, and fail
+loudly on anything not yet validated** — never emit a plausible-but-wrong WAV.
+
+| Coding | Status |
+|--------|--------|
+| `pcm`, 16-bit, `01`/`10` byte order | ✅ supported |
+| `pcm`, 32-bit, `01`/`10` byte order | ✅ supported |
+| `pcm`, multi-channel (interleaved)  | ✅ supported (validate against an oracle for exotic files) |
+| `pcm`, 8-bit / 24-bit               | ⛔ rejected (`UnsupportedFormat`) — sign/packing not yet validated |
+| `ulaw` / `alaw` (G.711, 8-bit)      | ✅ supported (Phase B) — verified byte-exact vs ffmpeg on all 256 codes |
+| `pcm,embedded-shorten-v2.00` (16-bit) | ✅ supported (Phase C) — byte-exact vs ffmpeg, mono & stereo |
+| `ulaw,embedded-shorten` (shorten type 8), incl. bitshift | ✅ supported (Phase C) — byte-exact vs sph2pipe (real CALLHOME) |
+| shorten QLPC (LPC) blocks           | ✅ supported (Phase C) — byte-exact vs shorten encoder + ffmpeg (orders 1–20) |
+
+Adding a coding means registering a decoder in `desphere/codecs.py`; until then
+the gate raises a precise error.
+
+## Test fixtures (the "zoo")
+
+We don't depend on real corpus files to test: `tools/make_fixtures.py`
+*generates* a zoo of SPHERE variants — every byte order, bit depth, and channel
+count — and commits them under `tests/fixtures/` with a manifest recording the
+exact expected output. Harder codings (μ-law/a-law, eventually shorten) are
+produced best-effort by driving `sox`/`ffmpeg`/`shorten` as black-box binaries.
+
+```bash
+python tools/make_fixtures.py     # regenerate fixtures + manifest
+pytest                            # validate everything
+```
+
+## Rust, WASM, and consumers
+
+The Python in `src/desphere` is the reference **spec**; [`rust/`](rust/) is a
+Rust port that reproduces it **bit-for-bit** (same fixtures), for speed and for
+the web. It builds three ways from one crate:
+
+- a **Rust library** — a Rust client (praatfan is a likely consumer) imports it
+  via a path/git dependency;
+- **WASM** (`wasm-pack build rust --target web --features wasm`) — a WASM web app
+  and the `web/` page consume it; nothing is sent to a server;
+- a **Python extension** `desphere-native` (pyo3/maturin) — the optional
+  `desphere[fast]` accelerator above.
+
+Because the consumers live in the same `ucpresearch` org, they depend on desphere
+directly (path/git); publishing to **crates.io / npm is not required** (and is
+skipped). **PyPI** is the one registry we target (the pure-Python `desphere`,
+plus the optional `desphere-native` wheels).
+
+## Development
+
+The virtualenv lives **outside** the (Syncthing-synced) repo and is symlinked in:
+
+```bash
+uv venv ~/local/scr/venvs/desphere
+ln -s ~/local/scr/venvs/desphere .venv
+uv pip install -e ".[dev]"
+pytest
+
+# Rust port:
+cd rust && cargo test            # byte-exact vs the same fixtures
+```
+
+## Roadmap
+
+- **Phase A** (done): SPHERE header + 16/32-bit PCM, lossless.
+- **Phase B** (done): μ-law / a-law decode (ITU-T G.711).
+- **Phase C** (done): embedded-shorten of 16-bit PCM, lossless μ-law (type 8,
+  including the non-linear BITSHIFT remap), and QLPC (LPC) blocks — validated
+  byte-for-byte vs ffmpeg / sph2pipe / the `shorten` encoder on real and
+  synthetic streams, mono and stereo. Remaining (low priority): 8/24-bit linear
+  PCM. See `docs/STATUS.md` and `docs/SHORTEN.md`.
+- **Eventually → Rust** (for a Rust client / WASM, and for speed), mirroring
+  `praatfan-core-clean`'s Python-first-then-Rust path. The Python implementation
+  stays as the readable reference. Porting guidance: `docs/RUST_PORT.md`.

desphere-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "desphere"
+version = "0.1.0"
+description = "Clean-room NIST SPHERE (and Shorten) to RIFF/WAV transcoder"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Uriel Cohen Priva" }]
+keywords = ["sphere", "nist", "shorten", "wav", "riff", "audio", "transcode", "sph2pipe"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Conversion",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+# Optional Rust accelerator: `pip install desphere[fast]`. desphere transparently
+# uses it for the slow path (shorten on large files) and falls back otherwise.
+fast = ["desphere-native"]
+
+[project.scripts]
+sph2wav = "desphere.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ucpresearch/desphere"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/desphere"]
+
+# The pure-Python distribution is just the package + tests + docs. A strict
+# allowlist so the sdist never sweeps in rust/, rust/target/, oracles/, web/, etc.
+# (the isolated build doesn't see .gitignore).
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/desphere",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "PROVENANCE.md",
+    "CHANGELOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

desphere-0.1.0/src/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",
+]