msadpcm 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
msadpcm/__init__.py ADDED
@@ -0,0 +1,33 @@
1
+ """msadpcm - Microsoft ADPCM encoder/decoder in pure Python + NumPy."""
2
+ from .codec import (
3
+ ADAPTATION_TABLE,
4
+ QUALITY_LEVELS,
5
+ STANDARD_COEFFS,
6
+ block_align_for,
7
+ decode,
8
+ default_block_align,
9
+ encode,
10
+ samples_per_block,
11
+ snr_db,
12
+ )
13
+ from .wav import WavInfo, format_chunk, read_adpcm_raw, read_wav, wav_info, write_wav
14
+
15
+ __version__ = "0.1.1"
16
+
17
+ __all__ = [
18
+ "ADAPTATION_TABLE",
19
+ "QUALITY_LEVELS",
20
+ "STANDARD_COEFFS",
21
+ "WavInfo",
22
+ "block_align_for",
23
+ "decode",
24
+ "default_block_align",
25
+ "encode",
26
+ "format_chunk",
27
+ "read_adpcm_raw",
28
+ "read_wav",
29
+ "samples_per_block",
30
+ "snr_db",
31
+ "wav_info",
32
+ "write_wav",
33
+ ]
msadpcm/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
msadpcm/cli.py ADDED
@@ -0,0 +1,220 @@
1
+ """Command line interface and the file-conversion helper shared with the GUI demo."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import sys
6
+ import time
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+ from typing import Callable, List, Optional, Sequence
10
+
11
+ from . import codec, wav
12
+
13
+ __all__ = ["ConversionResult", "convert_file", "main"]
14
+
15
+
16
+ @dataclass
17
+ class ConversionResult:
18
+ """What :func:`convert_file` did."""
19
+
20
+ src: Path
21
+ dst: Path
22
+ mode: str # "encode" or "decode"
23
+ frames: int
24
+ sample_rate: int
25
+ channels: int
26
+ src_bytes: int
27
+ dst_bytes: int
28
+ seconds: float
29
+ block_align: Optional[int] = None
30
+ samples_per_block: Optional[int] = None
31
+ snr_db: Optional[float] = None # encode only: ADPCM output vs. the input
32
+
33
+ @property
34
+ def ratio(self) -> float:
35
+ return self.src_bytes / self.dst_bytes if self.dst_bytes else float("inf")
36
+
37
+
38
+ def convert_file(
39
+ src,
40
+ dst=None,
41
+ *,
42
+ mode: str = "encode",
43
+ block_align: Optional[int] = None,
44
+ samples_per_block: Optional[int] = None,
45
+ quality: str = "normal",
46
+ verify: bool = True,
47
+ progress: Optional[Callable[[int, int], None]] = None,
48
+ ) -> ConversionResult:
49
+ """Convert one WAV file.
50
+
51
+ ``mode="encode"`` writes MS ADPCM, ``mode="decode"`` writes 16-bit PCM.
52
+ With ``verify`` the encoded file is decoded again to report the SNR.
53
+ """
54
+ if mode not in ("encode", "decode"):
55
+ raise ValueError("mode must be 'encode' or 'decode'")
56
+ src = Path(src)
57
+ if dst is None:
58
+ dst = src.with_name(src.stem + (".adpcm.wav" if mode == "encode" else ".pcm.wav"))
59
+ dst = Path(dst)
60
+
61
+ t0 = time.perf_counter()
62
+ pcm, rate = wav.read_wav(src)
63
+ frames, ch = pcm.shape
64
+
65
+ if mode == "decode":
66
+ written = wav.write_wav(dst, pcm, rate, adpcm=False)
67
+ return ConversionResult(src, dst, mode, frames, rate, ch, src.stat().st_size,
68
+ written, time.perf_counter() - t0)
69
+
70
+ if block_align is None and samples_per_block is None:
71
+ block_align = codec.default_block_align(rate, ch)
72
+ ba, spb = codec._resolve_geometry(ch, block_align, samples_per_block)
73
+ written = wav.write_wav(dst, pcm, rate, block_align=ba, quality=quality, progress=progress)
74
+ snr = None
75
+ if verify:
76
+ decoded, _ = wav.read_wav(dst)
77
+ snr = codec.snr_db(pcm, decoded)
78
+ return ConversionResult(src, dst, mode, frames, rate, ch, src.stat().st_size, written,
79
+ time.perf_counter() - t0, ba, spb, snr)
80
+
81
+
82
+ class _ProgressLine:
83
+ """Single updating status line on stderr (``name: encoding 45%``).
84
+
85
+ Shown only on an interactive terminal, so redirected output and logs stay
86
+ clean. Call the instance as the ``progress`` callback; call :meth:`clear`
87
+ before printing anything else.
88
+ """
89
+
90
+ def __init__(self, label: str, stream=None) -> None:
91
+ self.label = label
92
+ self.stream = sys.stderr if stream is None else stream
93
+ self.enabled = bool(getattr(self.stream, "isatty", lambda: False)())
94
+ self._shown = 0
95
+ self._last = -1
96
+ self._t0 = time.perf_counter()
97
+
98
+ def __call__(self, done: int, total: int) -> None:
99
+ if not self.enabled or total <= 0:
100
+ return
101
+ percent = 100 * done // total
102
+ if percent == self._last:
103
+ return
104
+ self._last = percent
105
+ elapsed = time.perf_counter() - self._t0
106
+ text = "%s: encoding %d%%" % (self.label, percent)
107
+ if 0 < done < total and elapsed >= 2.0:
108
+ text += " (%ds left)" % round(elapsed * (total - done) / done)
109
+ self._write(text)
110
+
111
+ def _write(self, text: str) -> None:
112
+ pad = " " * max(0, self._shown - len(text))
113
+ self.stream.write("\r" + text + pad)
114
+ self.stream.flush()
115
+ self._shown = len(text)
116
+
117
+ def clear(self) -> None:
118
+ if self.enabled and self._shown:
119
+ self.stream.write("\r" + " " * self._shown + "\r")
120
+ self.stream.flush()
121
+ self._shown = 0
122
+
123
+
124
+ def _describe(r: ConversionResult) -> str:
125
+ text = "%s -> %s %.1fs audio, %s, %.2fs" % (
126
+ r.src.name, r.dst.name, r.frames / r.sample_rate,
127
+ "stereo" if r.channels == 2 else "mono", r.seconds)
128
+ text += " [%d -> %d bytes, x%.2f]" % (r.src_bytes, r.dst_bytes, r.ratio)
129
+ if r.mode == "encode":
130
+ text += " block %d bytes (%d samples)" % (r.block_align, r.samples_per_block)
131
+ if r.snr_db is not None:
132
+ text += " SNR %.2f dB" % r.snr_db
133
+ return text
134
+
135
+
136
+ def _targets(inputs: Sequence[str], out: Optional[str], outdir: Optional[str], mode: str):
137
+ if out and len(inputs) != 1:
138
+ raise SystemExit("-o/--output works with exactly one input file; use -d/--outdir")
139
+ suffix = ".adpcm.wav" if mode == "encode" else ".pcm.wav"
140
+ for item in inputs:
141
+ src = Path(item)
142
+ if out:
143
+ dst = Path(out)
144
+ elif outdir:
145
+ dst = Path(outdir) / (src.stem + suffix)
146
+ else:
147
+ dst = src.with_name(src.stem + suffix)
148
+ yield src, dst
149
+
150
+
151
+ def _build_parser() -> argparse.ArgumentParser:
152
+ p = argparse.ArgumentParser(
153
+ prog="msadpcm", description="Microsoft ADPCM WAV encoder/decoder.")
154
+ sub = p.add_subparsers(dest="cmd", required=True)
155
+
156
+ enc = sub.add_parser("encode", help="PCM WAV -> MS ADPCM WAV")
157
+ enc.add_argument("inputs", nargs="+")
158
+ g = enc.add_mutually_exclusive_group()
159
+ g.add_argument("--block-align", type=int, help="bytes per block (default: like Windows ACM)")
160
+ g.add_argument("--samples-per-block", type=int, help="sample frames per block, e.g. 128")
161
+ enc.add_argument("--quality", choices=list(codec.QUALITY_LEVELS), default="normal")
162
+ enc.add_argument("-o", "--output")
163
+ enc.add_argument("-d", "--outdir")
164
+ enc.add_argument("--no-verify", action="store_true", help="skip the SNR check")
165
+
166
+ dec = sub.add_parser("decode", help="MS ADPCM WAV -> 16-bit PCM WAV")
167
+ dec.add_argument("inputs", nargs="+")
168
+ dec.add_argument("-o", "--output")
169
+ dec.add_argument("-d", "--outdir")
170
+
171
+ info = sub.add_parser("info", help="show WAV header information")
172
+ info.add_argument("inputs", nargs="+")
173
+ return p
174
+
175
+
176
+ def main(argv: Optional[List[str]] = None) -> int:
177
+ args = _build_parser().parse_args(argv)
178
+
179
+ if args.cmd == "info":
180
+ for item in args.inputs:
181
+ i = wav.wav_info(item)
182
+ kind = {1: "PCM", 2: "MS ADPCM", 3: "float", 0xFFFE: "extensible"}.get(
183
+ i.format_tag, "0x%04X" % i.format_tag)
184
+ line = "%s: %s, %d ch, %d Hz, %d-bit" % (
185
+ item, kind, i.channels, i.sample_rate, i.bits_per_sample)
186
+ if i.is_adpcm:
187
+ line += ", block %d bytes (%d samples)" % (
188
+ i.block_align, codec.samples_per_block(i.block_align, i.channels))
189
+ if i.n_frames is not None:
190
+ line += ", %d frames (%.2fs)" % (i.n_frames, i.duration)
191
+ print(line)
192
+ return 0
193
+
194
+ failures = 0
195
+ for src, dst in _targets(args.inputs, args.output, args.outdir, args.cmd):
196
+ try:
197
+ if args.outdir:
198
+ Path(args.outdir).mkdir(parents=True, exist_ok=True)
199
+ kwargs = {}
200
+ line = None
201
+ if args.cmd == "encode":
202
+ line = _ProgressLine(src.name)
203
+ kwargs = dict(block_align=args.block_align,
204
+ samples_per_block=args.samples_per_block,
205
+ quality=args.quality, verify=not args.no_verify,
206
+ progress=line)
207
+ try:
208
+ result = convert_file(src, dst, mode=args.cmd, **kwargs)
209
+ finally:
210
+ if line is not None:
211
+ line.clear()
212
+ print(_describe(result))
213
+ except Exception as exc: # report and continue with the next file
214
+ failures += 1
215
+ print("%s: error: %s" % (src, exc), file=sys.stderr)
216
+ return 1 if failures else 0
217
+
218
+
219
+ if __name__ == "__main__":
220
+ sys.exit(main())
msadpcm/codec.py ADDED
@@ -0,0 +1,620 @@
1
+ """Microsoft ADPCM (WAVE_FORMAT_ADPCM, tag 0x0002) encoder and decoder.
2
+
3
+ Pure Python + NumPy. All blocks (and, for the encoder, all candidate
4
+ parameter sets) are processed in parallel with vectorised arithmetic, so no
5
+ multiprocessing is needed.
6
+
7
+ Block layout (see the format description in the README):
8
+
9
+ mono : predictor(1) delta(2) sample1(2) sample2(2) | nibbles (high first)
10
+ stereo : predL(1) predR(1) deltaL(2) deltaR(2) s1L(2) s1R(2) s2L(2) s2R(2)
11
+ | bytes with left nibble in the high half, right nibble in the low half
12
+
13
+ The decoder follows the reference behaviour (the same as FFmpeg's
14
+ ``adpcm_ms``): the prediction is ``(s1*c1 + s2*c2) / 256`` with *truncation
15
+ towards zero*, the delta update is ``(table[nibble] * delta) >> 8`` with a
16
+ lower bound of 16. The encoder simulates exactly this decoder, so what it
17
+ measures is what a decoder will output, bit for bit.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ from typing import Callable, Optional, Sequence, Tuple, Union
22
+
23
+ import numpy as np
24
+
25
+ __all__ = [
26
+ "STANDARD_COEFFS",
27
+ "ADAPTATION_TABLE",
28
+ "QUALITY_LEVELS",
29
+ "samples_per_block",
30
+ "block_align_for",
31
+ "default_block_align",
32
+ "encode",
33
+ "decode",
34
+ "snr_db",
35
+ ]
36
+
37
+ #: The seven built-in predictor coefficient pairs (coeff1, coeff2).
38
+ STANDARD_COEFFS: Tuple[Tuple[int, int], ...] = (
39
+ (256, 0), (512, -256), (0, 0), (192, 64),
40
+ (240, 0), (460, -208), (392, -232),
41
+ )
42
+
43
+ #: Delta adaptation multipliers (x/256), indexed by the *unsigned* nibble.
44
+ ADAPTATION_TABLE: Tuple[int, ...] = (
45
+ 230, 230, 230, 230, 307, 409, 512, 614,
46
+ 768, 614, 512, 409, 307, 230, 230, 230,
47
+ )
48
+
49
+ MIN_DELTA = 16
50
+ #: The header stores the initial delta as a signed 16-bit value.
51
+ MAX_HEADER_DELTA = 32767
52
+ #: Same overflow guard as FFmpeg: INT_MAX / 768.
53
+ _DELTA_CEIL = 2147483647 // 768
54
+
55
+ _ADAPT = np.asarray(ADAPTATION_TABLE, dtype=np.int32)
56
+
57
+ ProgressFn = Callable[[int, int], None]
58
+ Coeffs = Sequence[Tuple[int, int]]
59
+
60
+
61
+ # --------------------------------------------------------------------------
62
+ # Block geometry
63
+ # --------------------------------------------------------------------------
64
+ def _check_channels(channels: int) -> None:
65
+ if channels not in (1, 2):
66
+ raise ValueError("MS ADPCM supports only 1 or 2 channels, got %r" % (channels,))
67
+
68
+
69
+ def _header_size(channels: int) -> int:
70
+ return 7 * channels
71
+
72
+
73
+ def samples_per_block(block_align: int, channels: int) -> int:
74
+ """Number of sample frames stored in one block of ``block_align`` bytes."""
75
+ _check_channels(channels)
76
+ hdr = _header_size(channels)
77
+ if not hdr < block_align <= 0xFFFF:
78
+ raise ValueError(
79
+ "block_align must be in (%d, 65535] for %d channel(s), got %r"
80
+ % (hdr, channels, block_align)
81
+ )
82
+ return (block_align - hdr) * 2 // channels + 2
83
+
84
+
85
+ def block_align_for(spb: int, channels: int) -> int:
86
+ """Inverse of :func:`samples_per_block`: bytes per block for ``spb`` frames.
87
+
88
+ Mono blocks need an even number of samples per block.
89
+ """
90
+ _check_channels(channels)
91
+ if spb < 4:
92
+ raise ValueError("samples per block must be >= 4")
93
+ if channels == 1:
94
+ if spb % 2:
95
+ raise ValueError("mono blocks need an even number of samples per block")
96
+ ba = (spb - 2) // 2 + 7
97
+ else:
98
+ ba = spb - 2 + 14
99
+ if ba > 0xFFFF:
100
+ raise ValueError("block would exceed 65535 bytes")
101
+ return ba
102
+
103
+
104
+ def default_block_align(sample_rate: int, channels: int) -> int:
105
+ """The block size Windows' ACM codec picks: 256 bytes per channel per 11 kHz."""
106
+ _check_channels(channels)
107
+ return 256 * channels * max(1, int(sample_rate) // 11025)
108
+
109
+
110
+ def _resolve_geometry(
111
+ channels: int, block_align: Optional[int], spb: Optional[int]
112
+ ) -> Tuple[int, int]:
113
+ if block_align is not None and spb is not None:
114
+ raise ValueError("pass either block_align or samples_per_block, not both")
115
+ if spb is not None:
116
+ block_align = block_align_for(spb, channels)
117
+ elif block_align is None:
118
+ block_align = 256 * channels
119
+ return int(block_align), samples_per_block(int(block_align), channels)
120
+
121
+
122
+ def _coeff_arrays(coeffs: Optional[Coeffs]) -> Tuple[np.ndarray, np.ndarray]:
123
+ table = STANDARD_COEFFS if coeffs is None else tuple(coeffs)
124
+ if not 1 <= len(table) <= 256:
125
+ raise ValueError("need between 1 and 256 coefficient pairs")
126
+ arr = np.asarray(table, dtype=np.int64)
127
+ if arr.ndim != 2 or arr.shape[1] != 2:
128
+ raise ValueError("coeffs must be a sequence of (coeff1, coeff2) pairs")
129
+ if np.abs(arr).max() > 32767:
130
+ raise ValueError("coefficients must fit in 16 bits")
131
+ return arr[:, 0].astype(np.int32), arr[:, 1].astype(np.int32)
132
+
133
+
134
+ # --------------------------------------------------------------------------
135
+ # Input normalisation
136
+ # --------------------------------------------------------------------------
137
+ def _as_frames(pcm, channels: Optional[int]) -> np.ndarray:
138
+ """Return int16 array of shape (frames, channels)."""
139
+ if isinstance(pcm, (bytes, bytearray, memoryview)):
140
+ arr = np.frombuffer(pcm, dtype="<i2")
141
+ else:
142
+ arr = np.asarray(pcm)
143
+ if not isinstance(pcm, np.ndarray) and arr.dtype.kind == "i":
144
+ # A plain Python list of ints: the dtype numpy picked is incidental,
145
+ # so accept it when every value fits into int16. (A real int32/int64
146
+ # *array* stays rejected: its scale, e.g. 24-bit audio, is ambiguous.)
147
+ if arr.size and (arr.min() < -32768 or arr.max() > 32767):
148
+ raise ValueError("integer samples must fit into int16")
149
+ arr = arr.astype(np.int16)
150
+
151
+ if arr.dtype.kind == "f":
152
+ arr = np.clip(np.rint(arr.astype(np.float64) * 32768.0), -32768, 32767)
153
+ elif arr.dtype.kind in "iu" and arr.dtype != np.int16:
154
+ if arr.dtype.itemsize != 2 or arr.dtype.kind != "i":
155
+ raise TypeError(
156
+ "integer input must be int16 (got %s); convert it first or pass "
157
+ "floats in [-1, 1]" % arr.dtype
158
+ )
159
+ elif arr.dtype.kind not in "iuf":
160
+ raise TypeError("unsupported dtype %s" % arr.dtype)
161
+ arr = arr.astype(np.int16, copy=False)
162
+
163
+ if arr.ndim == 1:
164
+ ch = 1 if channels is None else int(channels)
165
+ _check_channels(ch)
166
+ if arr.size % ch:
167
+ raise ValueError("%d samples do not divide into %d channels" % (arr.size, ch))
168
+ arr = arr.reshape(-1, ch)
169
+ elif arr.ndim == 2:
170
+ if channels is not None and arr.shape[1] != channels:
171
+ raise ValueError("array has %d channels, channels=%r" % (arr.shape[1], channels))
172
+ _check_channels(arr.shape[1])
173
+ else:
174
+ raise ValueError("expected a 1-D or 2-D array")
175
+ return arr
176
+
177
+
178
+ # --------------------------------------------------------------------------
179
+ # Quality presets
180
+ # --------------------------------------------------------------------------
181
+ #: ``n_pred`` - how many predictors are tried per block. Ranking them by
182
+ #: open-loop error is unreliable (tonal material loses up to
183
+ #: 5 dB), so every preset tries all of them.
184
+ #: ``mults`` - initial deltas tried, as multiples of the per-block estimate
185
+ #: ``refine`` - second pass: fine search around the winning delta
186
+ def _grid(*parts) -> Tuple[float, ...]:
187
+ return tuple(sorted({round(float(v), 4) for p in parts for v in p}))
188
+
189
+
190
+ # Every preset's coarse search covers all candidates of the previous preset.
191
+ # The refinement pass is centred on each preset's own winner, so the final
192
+ # SNR is almost always, but not strictly always, ordered fast <= normal <= high.
193
+ _FAST = (0.3, 0.7, 1.4)
194
+ _NORMAL = _grid(_FAST, (0.2, 0.4, 1.0, 1.6))
195
+ _HIGH = _grid(_NORMAL, (0.15, 0.25, 0.35, 0.5, 2.0, 3.0))
196
+ _MAX = _grid(_HIGH, np.geomspace(0.05, 6.0, 28))
197
+
198
+ QUALITY_LEVELS = {
199
+ "fast": dict(n_pred=7, mults=_FAST, refine=False),
200
+ "normal": dict(n_pred=7, mults=_NORMAL, refine=True),
201
+ "high": dict(n_pred=7, mults=_HIGH, refine=True),
202
+ "max": dict(n_pred=7, mults=_MAX, refine=True),
203
+ }
204
+
205
+ _REFINE_MULTS = (0.8, 0.9, 1.1, 1.25)
206
+ #: Rough number of candidate lanes processed per vectorised chunk. Larger chunks
207
+ #: amortise the per-chunk Python overhead; timings between 1 << 14 and 1 << 17 differ
208
+ #: by less than run-to-run noise on the machines tested, so this is the value the
209
+ #: 0.1.0 release was measured with. Progress reporting does not depend on it.
210
+ _LANES_PER_CHUNK = 1 << 17
211
+ #: Upper bound for ``rows * samples_per_block`` per chunk; keeps memory flat
212
+ #: (roughly 120 MB) however large the blocks are.
213
+ _ELEMS_PER_CHUNK = 1 << 22
214
+
215
+
216
+ # --------------------------------------------------------------------------
217
+ # Encoder
218
+ # --------------------------------------------------------------------------
219
+ def _trunc_div256(t: np.ndarray) -> np.ndarray:
220
+ """int32 ``t / 256`` truncating toward zero (C semantics)."""
221
+ return (t + ((t >> 31) & 255)) >> 8
222
+
223
+
224
+ def _simulate(
225
+ x: np.ndarray,
226
+ cand_pred: np.ndarray,
227
+ cand_delta: np.ndarray,
228
+ c1_tab: np.ndarray,
229
+ c2_tab: np.ndarray,
230
+ want_nibs: bool = False,
231
+ tick: Optional[Callable[[float], None]] = None,
232
+ ) -> Tuple[np.ndarray, Optional[np.ndarray]]:
233
+ """Encode every row of ``x`` with every candidate.
234
+
235
+ x : (r, N) int32 samples
236
+ cand_pred : (r, M) predictor index per candidate
237
+ cand_delta : (r, M) initial delta per candidate
238
+ want_nibs : also return the nibbles; only worth it for a few candidates,
239
+ the buffer is (N-2) * r * M bytes
240
+ tick : optional ``callback(fraction_done)`` called every 32 samples
241
+ returns : err (r, M) float64 squared error, nibbles (N-2, r*M) uint8 or None
242
+ """
243
+ r, n = x.shape
244
+ m = cand_pred.shape[1]
245
+ lanes = r * m
246
+ row = np.repeat(np.arange(r), m)
247
+ xt = np.ascontiguousarray(x.T) # (N, r)
248
+
249
+ flat_pred = cand_pred.reshape(-1)
250
+ c1 = c1_tab[flat_pred]
251
+ c2 = c2_tab[flat_pred]
252
+ s1 = xt[1][row].astype(np.int32)
253
+ s2 = xt[0][row].astype(np.int32)
254
+ delta = cand_delta.reshape(-1).astype(np.int32)
255
+ err = np.zeros(lanes, dtype=np.float64)
256
+ over = np.zeros(lanes, dtype=bool)
257
+ nibs = np.empty((n - 2, lanes), dtype=np.uint8) if want_nibs else None
258
+
259
+ for i in range(2, n):
260
+ if tick is not None and not (i & 31):
261
+ tick((i - 2) / (n - 2))
262
+ pred = _trunc_div256(s1 * c1 + s2 * c2)
263
+ target = xt[i][row]
264
+ q = np.rint((target - pred) / delta)
265
+ np.clip(q, -8, 7, out=q)
266
+ q = q.astype(np.int32)
267
+ recon = pred + q * delta
268
+ np.clip(recon, -32768, 32767, out=recon)
269
+ e = (target - recon).astype(np.float64)
270
+ err += e * e
271
+ u = q & 15
272
+ if want_nibs:
273
+ nibs[i - 2] = u
274
+ s2 = s1
275
+ s1 = recon
276
+ delta = (_ADAPT[u] * delta) >> 8
277
+ np.maximum(delta, MIN_DELTA, out=delta)
278
+ np.minimum(delta, _DELTA_CEIL, out=delta)
279
+ over |= delta > MAX_HEADER_DELTA
280
+
281
+ # Decoders that keep the delta in 16 bits would diverge once it exceeds
282
+ # 32767; steer away from such candidates whenever an alternative exists.
283
+ err += over * 1e18
284
+ return err.reshape(r, m), nibs
285
+
286
+
287
+ def _search_rows(
288
+ x: np.ndarray,
289
+ c1_tab: np.ndarray,
290
+ c2_tab: np.ndarray,
291
+ n_pred: int,
292
+ mults: Sequence[float],
293
+ refine: bool,
294
+ tick: Optional[Callable[[float], None]] = None,
295
+ ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
296
+ """Find predictor, initial delta and nibbles for each row of ``x``.
297
+
298
+ ``tick(fraction)`` reports progress over the three simulation passes,
299
+ weighted by how many candidate lanes each one processes.
300
+ """
301
+ r, n = x.shape
302
+ n_coef = len(c1_tab)
303
+ n_pred = min(n_pred, n_coef)
304
+
305
+ # Open-loop residuals of every predictor (uses the true signal as history).
306
+ h1 = x[:, 1:-1]
307
+ h2 = x[:, :-2]
308
+ tgt = x[:, 2:]
309
+ res = np.empty((n_coef, r, n - 2), dtype=np.int32)
310
+ for p in range(n_coef):
311
+ res[p] = tgt - _trunc_div256(h1 * c1_tab[p] + h2 * c2_tab[p])
312
+ score = np.empty((n_coef, r), dtype=np.float64)
313
+ for p in range(n_coef): # one predictor at a time: no (P, r, n) float64 temporary
314
+ rp = res[p].astype(np.float64)
315
+ score[p] = np.einsum("ij,ij->i", rp, rp)
316
+ order = np.argsort(score, axis=0)[:n_pred] # (n_pred, r) best first
317
+ sel = order.T # (r, n_pred)
318
+
319
+ # Initial-delta estimate: scale of the first few residuals of that predictor.
320
+ head = min(16, n - 2)
321
+ rows_idx = np.arange(r)[:, None]
322
+ head_res = np.abs(res[:, :, :head]).astype(np.float64).mean(axis=2) # (P, r)
323
+ est = head_res.T[rows_idx, sel] # (r, n_pred)
324
+ est = np.maximum(est, MIN_DELTA)
325
+
326
+ mult = np.asarray(mults, dtype=np.float64)
327
+ cand_delta = np.rint(est[:, :, None] * mult[None, None, :])
328
+ cand_delta = np.clip(cand_delta, MIN_DELTA, MAX_HEADER_DELTA).astype(np.int32)
329
+ cand_pred = np.broadcast_to(sel[:, :, None], cand_delta.shape)
330
+ cand_delta = cand_delta.reshape(r, -1)
331
+ cand_pred = np.ascontiguousarray(cand_pred.reshape(r, -1))
332
+
333
+ w_main, w_ref = cand_pred.shape[1], (len(_REFINE_MULTS) if refine else 0)
334
+ w_all = float(w_main + w_ref + 1)
335
+
336
+ def stage(lo_w: float, hi_w: float):
337
+ if tick is None:
338
+ return None
339
+ return lambda f: tick((lo_w + f * (hi_w - lo_w)) / w_all)
340
+
341
+ err, _ = _simulate(x, cand_pred, cand_delta, c1_tab, c2_tab, tick=stage(0, w_main))
342
+ ar = np.arange(r)
343
+ best = err.argmin(axis=1)
344
+ best_pred = cand_pred[ar, best]
345
+ best_delta = cand_delta[ar, best]
346
+ best_err = err[ar, best]
347
+
348
+ if refine:
349
+ rm = np.asarray(_REFINE_MULTS, dtype=np.float64)
350
+ rdelta = np.rint(best_delta[:, None] * rm[None, :])
351
+ rdelta = np.clip(rdelta, MIN_DELTA, MAX_HEADER_DELTA).astype(np.int32)
352
+ rpred = np.broadcast_to(best_pred[:, None], rdelta.shape).copy()
353
+ err2, _ = _simulate(x, rpred, rdelta, c1_tab, c2_tab, tick=stage(w_main, w_main + w_ref))
354
+ b2 = err2.argmin(axis=1)
355
+ e2 = err2[ar, b2]
356
+ better = e2 < best_err
357
+ best_delta = np.where(better, rdelta[ar, b2], best_delta)
358
+ best_err = np.where(better, e2, best_err)
359
+
360
+ # Only the winners need their nibbles: one extra pass over r lanes.
361
+ final_err, best_nibs = _simulate(
362
+ x, best_pred[:, None], best_delta[:, None].astype(np.int32), c1_tab, c2_tab,
363
+ want_nibs=True, tick=stage(w_main + w_ref, w_all))
364
+ best_err = final_err[:, 0]
365
+ best_nibs = best_nibs.T # (r, N-2)
366
+
367
+ return (
368
+ best_pred.astype(np.uint8),
369
+ best_delta.astype(np.int32),
370
+ np.ascontiguousarray(best_nibs, dtype=np.uint8),
371
+ best_err,
372
+ )
373
+
374
+
375
+ def _encode_rows(
376
+ rows: np.ndarray,
377
+ coeffs: Optional[Coeffs],
378
+ quality: str,
379
+ progress: Optional[ProgressFn],
380
+ ):
381
+ """Encode (R, N) int16 rows. Returns preds, deltas, nibbles, errors."""
382
+ if quality not in QUALITY_LEVELS:
383
+ raise ValueError("quality must be one of %s" % ", ".join(QUALITY_LEVELS))
384
+ cfg = QUALITY_LEVELS[quality]
385
+ c1_tab, c2_tab = _coeff_arrays(coeffs)
386
+ total, n = rows.shape
387
+ x = rows.astype(np.int32)
388
+
389
+ per_row = max(1, min(cfg["n_pred"], len(c1_tab)) * len(cfg["mults"]))
390
+ step = max(1, min(_LANES_PER_CHUNK // per_row, _ELEMS_PER_CHUNK // n))
391
+
392
+ preds = np.empty(total, dtype=np.uint8)
393
+ deltas = np.empty(total, dtype=np.int32)
394
+ nibs = np.empty((total, n - 2), dtype=np.uint8)
395
+ errs = np.empty(total, dtype=np.float64)
396
+ last = -1
397
+
398
+ def report(done: int) -> None:
399
+ nonlocal last
400
+ if progress and done > last:
401
+ last = done
402
+ progress(done, total)
403
+
404
+ report(0)
405
+ for lo in range(0, total, step):
406
+ hi = min(total, lo + step)
407
+ tick = (lambda f, lo=lo, hi=hi: report(lo + int(f * (hi - lo)))) if progress else None
408
+ p, d, nb, e = _search_rows(
409
+ x[lo:hi], c1_tab, c2_tab, cfg["n_pred"], cfg["mults"], cfg["refine"], tick
410
+ )
411
+ preds[lo:hi], deltas[lo:hi], nibs[lo:hi], errs[lo:hi] = p, d, nb, e
412
+ report(hi)
413
+ return preds, deltas, nibs, errs
414
+
415
+
416
+ def _le16(v: np.ndarray) -> np.ndarray:
417
+ """(B,) int -> (B, 2) little-endian bytes (two's complement)."""
418
+ v = np.asarray(v, dtype=np.int64) & 0xFFFF
419
+ return np.stack([v & 0xFF, v >> 8], axis=1).astype(np.uint8)
420
+
421
+
422
+ def _pack_blocks(
423
+ x: np.ndarray,
424
+ preds: np.ndarray,
425
+ deltas: np.ndarray,
426
+ nibs: np.ndarray,
427
+ channels: int,
428
+ block_align: int,
429
+ ) -> bytes:
430
+ """Assemble final blocks. ``x`` is (C*B, N); rows are channel-major."""
431
+ total, n = x.shape
432
+ b = total // channels
433
+ out = np.empty((b, block_align), dtype=np.uint8)
434
+ if channels == 1:
435
+ out[:, 0] = preds
436
+ out[:, 1:3] = _le16(deltas)
437
+ out[:, 3:5] = _le16(x[:, 1])
438
+ out[:, 5:7] = _le16(x[:, 0])
439
+ out[:, 7:] = (nibs[:, 0::2] << 4) | nibs[:, 1::2]
440
+ else:
441
+ pl, pr = preds[:b], preds[b:]
442
+ out[:, 0], out[:, 1] = pl, pr
443
+ out[:, 2:4], out[:, 4:6] = _le16(deltas[:b]), _le16(deltas[b:])
444
+ out[:, 6:8], out[:, 8:10] = _le16(x[:b, 1]), _le16(x[b:, 1])
445
+ out[:, 10:12], out[:, 12:14] = _le16(x[:b, 0]), _le16(x[b:, 0])
446
+ out[:, 14:] = (nibs[:b] << 4) | nibs[b:]
447
+ return out.tobytes()
448
+
449
+
450
+ def encode(
451
+ pcm,
452
+ *,
453
+ channels: Optional[int] = None,
454
+ block_align: Optional[int] = None,
455
+ samples_per_block: Optional[int] = None, # noqa: F811 - public keyword name
456
+ quality: str = "normal",
457
+ coeffs: Optional[Coeffs] = None,
458
+ progress: Optional[ProgressFn] = None,
459
+ ) -> bytes:
460
+ """Encode PCM to raw MS ADPCM blocks.
461
+
462
+ Parameters
463
+ ----------
464
+ pcm
465
+ ``int16`` array shaped ``(frames,)``, ``(frames, 1)`` or ``(frames, 2)``;
466
+ floating-point arrays in [-1, 1]; or ``bytes`` of interleaved
467
+ little-endian int16 (then give ``channels``).
468
+ channels
469
+ Only needed for 1-D interleaved stereo or raw bytes.
470
+ block_align, samples_per_block
471
+ Size of one block in bytes, or, alternatively, in sample frames.
472
+ Defaults to ``256 * channels`` bytes.
473
+ quality
474
+ ``"fast"``, ``"normal"`` (default), ``"high"`` or ``"max"``; slower presets
475
+ try more candidates and gain a fraction of a dB (see :data:`QUALITY_LEVELS`).
476
+ coeffs
477
+ Custom predictor table; default is the seven standard pairs.
478
+ progress
479
+ Optional ``callback(done, total)`` called while encoding.
480
+
481
+ Returns
482
+ -------
483
+ bytes
484
+ Concatenated blocks. The last block is padded by repeating the final
485
+ sample; store the true frame count (e.g. in a WAV ``fact`` chunk) and
486
+ pass it to :func:`decode` as ``n_samples`` to drop the padding.
487
+ """
488
+ frames = _as_frames(pcm, channels)
489
+ n_frames, ch = frames.shape
490
+ block_align, n = _resolve_geometry(ch, block_align, samples_per_block)
491
+ if n_frames == 0:
492
+ return b""
493
+
494
+ pad = (-n_frames) % n
495
+ if pad:
496
+ frames = np.concatenate([frames, np.repeat(frames[-1:], pad, axis=0)], axis=0)
497
+ blocks = frames.shape[0] // n
498
+ # (B, N, C) -> channel-major rows (C*B, N)
499
+ rows = frames.reshape(blocks, n, ch).transpose(2, 0, 1).reshape(ch * blocks, n)
500
+ rows = np.ascontiguousarray(rows)
501
+
502
+ preds, deltas, nibs, _ = _encode_rows(rows, coeffs, quality, progress)
503
+ return _pack_blocks(rows.astype(np.int32), preds, deltas, nibs, ch, block_align)
504
+
505
+
506
+ # --------------------------------------------------------------------------
507
+ # Decoder
508
+ # --------------------------------------------------------------------------
509
+ def _s16(blocks: np.ndarray, off: int) -> np.ndarray:
510
+ v = blocks[:, off].astype(np.int32) | (blocks[:, off + 1].astype(np.int32) << 8)
511
+ return (v ^ 0x8000) - 0x8000
512
+
513
+
514
+ def _decode_full_blocks(
515
+ blocks: np.ndarray,
516
+ channels: int,
517
+ c1_tab: np.ndarray,
518
+ c2_tab: np.ndarray,
519
+ ) -> np.ndarray:
520
+ """Decode (B, block_align) uint8 -> (B, N, C) int16."""
521
+ b, ba = blocks.shape
522
+ n = (ba - 7 * channels) * 2 // channels + 2
523
+ if channels == 1:
524
+ pred_idx = blocks[:, 0].astype(np.int64)[None]
525
+ delta = _s16(blocks, 1)[None]
526
+ s1 = _s16(blocks, 3)[None]
527
+ s2 = _s16(blocks, 5)[None]
528
+ data = blocks[:, 7:]
529
+ nib = np.empty((b, n - 2), dtype=np.uint8)
530
+ nib[:, 0::2] = data >> 4
531
+ nib[:, 1::2] = data & 15
532
+ nib = nib[None] # (1, B, N-2)
533
+ else:
534
+ pred_idx = np.stack([blocks[:, 0], blocks[:, 1]]).astype(np.int64)
535
+ delta = np.stack([_s16(blocks, 2), _s16(blocks, 4)])
536
+ s1 = np.stack([_s16(blocks, 6), _s16(blocks, 8)])
537
+ s2 = np.stack([_s16(blocks, 10), _s16(blocks, 12)])
538
+ data = blocks[:, 14:]
539
+ nib = np.stack([data >> 4, data & 15]) # (2, B, N-2)
540
+
541
+ if pred_idx.max(initial=0) >= len(c1_tab):
542
+ raise ValueError("invalid block predictor index %d" % int(pred_idx.max()))
543
+ c1 = c1_tab[pred_idx]
544
+ c2 = c2_tab[pred_idx]
545
+
546
+ out = np.empty((channels, b, n), dtype=np.int32)
547
+ out[:, :, 0] = s2
548
+ out[:, :, 1] = s1
549
+ for i in range(2, n):
550
+ u = nib[:, :, i - 2].astype(np.int32)
551
+ pred = _trunc_div256(s1 * c1 + s2 * c2)
552
+ pred = pred + ((u ^ 8) - 8) * delta
553
+ np.clip(pred, -32768, 32767, out=pred)
554
+ out[:, :, i] = pred
555
+ s2 = s1
556
+ s1 = pred
557
+ delta = (_ADAPT[u] * delta) >> 8
558
+ np.maximum(delta, MIN_DELTA, out=delta)
559
+ np.minimum(delta, _DELTA_CEIL, out=delta)
560
+ return out.transpose(1, 2, 0).astype(np.int16) # (B, N, C)
561
+
562
+
563
+ def decode(
564
+ data,
565
+ *,
566
+ channels: int,
567
+ block_align: int,
568
+ n_samples: Optional[int] = None,
569
+ coeffs: Optional[Coeffs] = None,
570
+ ) -> np.ndarray:
571
+ """Decode raw MS ADPCM blocks to an ``int16`` array of shape ``(frames, channels)``.
572
+
573
+ A trailing partial block (data length not a multiple of ``block_align``)
574
+ is decoded as far as it goes. ``n_samples`` (e.g. from a ``fact`` chunk)
575
+ truncates the result to the real length.
576
+ """
577
+ _check_channels(channels)
578
+ n = samples_per_block(block_align, channels)
579
+ raw = np.frombuffer(bytes(data) if not isinstance(data, (bytes, bytearray)) else data,
580
+ dtype=np.uint8)
581
+ c1_tab, c2_tab = _coeff_arrays(coeffs)
582
+
583
+ full = raw.size // block_align
584
+ tail = raw.size - full * block_align
585
+ pieces = []
586
+ if full:
587
+ pieces.append(
588
+ _decode_full_blocks(raw[: full * block_align].reshape(full, block_align),
589
+ channels, c1_tab, c2_tab).reshape(-1, channels)
590
+ )
591
+ hdr = _header_size(channels)
592
+ if tail > hdr:
593
+ padded = np.zeros((1, block_align), dtype=np.uint8)
594
+ padded[0, :tail] = raw[full * block_align:]
595
+ frames = _decode_full_blocks(padded, channels, c1_tab, c2_tab).reshape(-1, channels)
596
+ valid = 2 + (tail - hdr) * 2 // channels
597
+ pieces.append(frames[:valid])
598
+ out = np.concatenate(pieces, axis=0) if pieces else np.zeros((0, channels), np.int16)
599
+ if n_samples is not None:
600
+ out = out[: max(0, int(n_samples))]
601
+ assert n >= 2
602
+ return out
603
+
604
+
605
+ # --------------------------------------------------------------------------
606
+ # Utility
607
+ # --------------------------------------------------------------------------
608
+ def snr_db(reference, test) -> float:
609
+ """Signal-to-noise ratio in dB between two int16 arrays (inf if identical)."""
610
+ a = np.asarray(reference, dtype=np.float64)
611
+ b = np.asarray(test, dtype=np.float64)
612
+ k = min(len(a), len(b))
613
+ a, b = a[:k], b[:k]
614
+ noise = float(np.sum((a - b) ** 2))
615
+ sig = float(np.sum(a ** 2))
616
+ if noise == 0.0:
617
+ return float("inf")
618
+ if sig == 0.0:
619
+ return float("-inf")
620
+ return 10.0 * np.log10(sig / noise)
msadpcm/wav.py ADDED
@@ -0,0 +1,256 @@
1
+ """Minimal RIFF/WAVE reading and writing for PCM and MS ADPCM files.
2
+
3
+ The standard library's :mod:`wave` cannot open ADPCM files, so this module
4
+ parses the chunks itself. It understands:
5
+
6
+ * ``WAVE_FORMAT_PCM`` (8/16/24/32-bit integer), ``WAVE_FORMAT_IEEE_FLOAT``
7
+ and ``WAVE_FORMAT_EXTENSIBLE`` wrappers of those, returned as int16;
8
+ * ``WAVE_FORMAT_ADPCM`` (MS ADPCM), decoded with :func:`msadpcm.decode`,
9
+ including a custom coefficient table stored in the ``fmt `` chunk.
10
+ """
11
+ from __future__ import annotations
12
+
13
+ import struct
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+ from typing import Callable, List, Optional, Tuple, Union
17
+
18
+ import numpy as np
19
+
20
+ from . import codec
21
+
22
+ __all__ = ["WavInfo", "format_chunk", "read_wav", "read_adpcm_raw", "write_wav", "wav_info"]
23
+
24
+ WAVE_FORMAT_PCM = 0x0001
25
+ WAVE_FORMAT_ADPCM = 0x0002
26
+ WAVE_FORMAT_IEEE_FLOAT = 0x0003
27
+ WAVE_FORMAT_EXTENSIBLE = 0xFFFE
28
+
29
+ PathLike = Union[str, Path]
30
+
31
+
32
+ @dataclass
33
+ class WavInfo:
34
+ """Header information of a WAV file."""
35
+
36
+ format_tag: int
37
+ channels: int
38
+ sample_rate: int
39
+ block_align: int
40
+ bits_per_sample: int
41
+ n_frames: Optional[int]
42
+ coeffs: Optional[Tuple[Tuple[int, int], ...]] = None
43
+
44
+ @property
45
+ def is_adpcm(self) -> bool:
46
+ return self.format_tag == WAVE_FORMAT_ADPCM
47
+
48
+ @property
49
+ def duration(self) -> Optional[float]:
50
+ return None if self.n_frames is None else self.n_frames / self.sample_rate
51
+
52
+
53
+ # --------------------------------------------------------------------------
54
+ # fmt chunk
55
+ # --------------------------------------------------------------------------
56
+ def format_chunk(
57
+ sample_rate: int,
58
+ channels: int,
59
+ block_align: int,
60
+ coeffs: Optional[codec.Coeffs] = None,
61
+ ) -> bytes:
62
+ """Body of the ``fmt `` chunk (WAVEFORMATEX + ADPCM extra data), 50 bytes
63
+ for the standard seven coefficient pairs."""
64
+ spb = codec.samples_per_block(block_align, channels)
65
+ table = codec.STANDARD_COEFFS if coeffs is None else tuple(coeffs)
66
+ extra = struct.pack("<HH", spb, len(table))
67
+ for c1, c2 in table:
68
+ extra += struct.pack("<hh", c1, c2)
69
+ avg_bytes = (sample_rate * block_align) // spb
70
+ return struct.pack(
71
+ "<HHIIHHH", WAVE_FORMAT_ADPCM, channels, sample_rate, avg_bytes,
72
+ block_align, 4, len(extra),
73
+ ) + extra
74
+
75
+
76
+ def _parse_fmt(body: bytes) -> WavInfo:
77
+ if len(body) < 16:
78
+ raise ValueError("fmt chunk too short")
79
+ tag, ch, rate, _avg, align, bits = struct.unpack_from("<HHIIHH", body, 0)
80
+ coeffs = None
81
+ if tag == WAVE_FORMAT_EXTENSIBLE and len(body) >= 26:
82
+ # sub-format GUID starts with the real format tag
83
+ tag = struct.unpack_from("<H", body, 24)[0]
84
+ if tag == WAVE_FORMAT_ADPCM and len(body) >= 22:
85
+ _spb, ncoef = struct.unpack_from("<HH", body, 18)
86
+ if 0 < ncoef <= 256 and len(body) >= 22 + 4 * ncoef:
87
+ vals = struct.unpack_from("<%dh" % (2 * ncoef), body, 22)
88
+ coeffs = tuple((vals[2 * i], vals[2 * i + 1]) for i in range(ncoef))
89
+ return WavInfo(tag, ch, rate, align, bits, None, coeffs)
90
+
91
+
92
+ # --------------------------------------------------------------------------
93
+ # chunk walking
94
+ # --------------------------------------------------------------------------
95
+ def _read_chunks(raw: bytes) -> List[Tuple[bytes, int, int]]:
96
+ """Return ``(id, body_offset, body_size)`` for every top-level chunk."""
97
+ if len(raw) < 12 or raw[:4] not in (b"RIFF", b"RIFX") or raw[8:12] != b"WAVE":
98
+ raise ValueError("not a RIFF/WAVE file")
99
+ chunks = []
100
+ pos = 12
101
+ while pos + 8 <= len(raw):
102
+ cid, size = struct.unpack_from("<4sI", raw, pos)
103
+ body = pos + 8
104
+ if cid == b"data" and body + size > len(raw):
105
+ size = len(raw) - body # streamed / truncated file
106
+ size = min(size, len(raw) - body)
107
+ chunks.append((cid, body, size))
108
+ pos = body + size + (size & 1)
109
+ return chunks
110
+
111
+
112
+ def _parse(raw: bytes):
113
+ info = None
114
+ fact = None
115
+ data_span = None
116
+ for cid, off, size in _read_chunks(raw):
117
+ if cid == b"fmt " and info is None:
118
+ info = _parse_fmt(raw[off:off + size])
119
+ elif cid == b"fact" and size >= 4:
120
+ fact = struct.unpack_from("<I", raw, off)[0]
121
+ elif cid == b"data" and data_span is None:
122
+ data_span = (off, size)
123
+ if info is None:
124
+ raise ValueError("missing fmt chunk")
125
+ if data_span is None:
126
+ raise ValueError("missing data chunk")
127
+ if info.is_adpcm:
128
+ info.n_frames = fact
129
+ return info, data_span
130
+
131
+
132
+ def wav_info(path: PathLike) -> WavInfo:
133
+ """Read header information (and frame count) without decoding."""
134
+ raw = Path(path).read_bytes()
135
+ info, (_, size) = _parse(raw)
136
+ if info.n_frames is None:
137
+ if info.is_adpcm:
138
+ ba = info.block_align
139
+ full, tail = divmod(size, ba)
140
+ n = full * codec.samples_per_block(ba, info.channels)
141
+ hdr = 7 * info.channels
142
+ if tail > hdr:
143
+ n += 2 + (tail - hdr) * 2 // info.channels
144
+ info.n_frames = n
145
+ elif info.block_align:
146
+ info.n_frames = size // info.block_align
147
+ return info
148
+
149
+
150
+ # --------------------------------------------------------------------------
151
+ # reading
152
+ # --------------------------------------------------------------------------
153
+ def _pcm_to_int16(buf: bytes, tag: int, bits: int, channels: int) -> np.ndarray:
154
+ if tag == WAVE_FORMAT_IEEE_FLOAT:
155
+ if bits not in (32, 64):
156
+ raise ValueError("unsupported float width %d" % bits)
157
+ a = np.frombuffer(buf[: len(buf) // (bits // 8) * (bits // 8)],
158
+ dtype="<f%d" % (bits // 8))
159
+ a = np.clip(np.rint(a.astype(np.float64) * 32768.0), -32768, 32767).astype(np.int16)
160
+ elif tag == WAVE_FORMAT_PCM:
161
+ if bits == 16:
162
+ a = np.frombuffer(buf[: len(buf) // 2 * 2], dtype="<i2").astype(np.int16)
163
+ elif bits == 8:
164
+ a = ((np.frombuffer(buf, dtype=np.uint8).astype(np.int16) - 128) << 8).astype(np.int16)
165
+ elif bits == 24:
166
+ m = len(buf) // 3 * 3
167
+ b = np.frombuffer(buf[:m], dtype=np.uint8).reshape(-1, 3)
168
+ a = (b[:, 1].astype(np.int16) | (b[:, 2].astype(np.int16) << 8)).astype(np.int16)
169
+ elif bits == 32:
170
+ a = (np.frombuffer(buf[: len(buf) // 4 * 4], dtype="<i4") >> 16).astype(np.int16)
171
+ else:
172
+ raise ValueError("unsupported PCM width %d" % bits)
173
+ else:
174
+ raise ValueError("unsupported WAV format tag 0x%04X" % tag)
175
+ usable = a.size // channels * channels
176
+ return a[:usable].reshape(-1, channels)
177
+
178
+
179
+ def read_wav(path: PathLike) -> Tuple[np.ndarray, int]:
180
+ """Read a PCM or MS ADPCM WAV file.
181
+
182
+ Returns ``(samples, sample_rate)`` with ``samples`` an int16 array of shape
183
+ ``(frames, channels)``.
184
+ """
185
+ raw = Path(path).read_bytes()
186
+ info, (off, size) = _parse(raw)
187
+ body = raw[off:off + size]
188
+ if info.is_adpcm:
189
+ pcm = codec.decode(
190
+ body, channels=info.channels, block_align=info.block_align,
191
+ n_samples=info.n_frames, coeffs=info.coeffs,
192
+ )
193
+ else:
194
+ pcm = _pcm_to_int16(body, info.format_tag, info.bits_per_sample, info.channels)
195
+ return pcm, info.sample_rate
196
+
197
+
198
+ def read_adpcm_raw(path: PathLike) -> Tuple[bytes, WavInfo]:
199
+ """Return the undecoded ADPCM block data and header of an ADPCM WAV file."""
200
+ raw = Path(path).read_bytes()
201
+ info, (off, size) = _parse(raw)
202
+ if not info.is_adpcm:
203
+ raise ValueError("not an MS ADPCM file")
204
+ return raw[off:off + size], info
205
+
206
+
207
+ # --------------------------------------------------------------------------
208
+ # writing
209
+ # --------------------------------------------------------------------------
210
+ def write_wav(
211
+ path: PathLike,
212
+ pcm,
213
+ sample_rate: int,
214
+ *,
215
+ adpcm: bool = True,
216
+ channels: Optional[int] = None,
217
+ block_align: Optional[int] = None,
218
+ samples_per_block: Optional[int] = None,
219
+ quality: str = "normal",
220
+ coeffs: Optional[codec.Coeffs] = None,
221
+ progress: Optional[Callable[[int, int], None]] = None,
222
+ ) -> int:
223
+ """Write ``pcm`` to ``path`` as MS ADPCM (or plain 16-bit PCM if ``adpcm=False``).
224
+
225
+ Returns the number of bytes written. When no block size is given it uses
226
+ :func:`msadpcm.default_block_align` for ``sample_rate``.
227
+ """
228
+ frames = codec._as_frames(pcm, channels)
229
+ n_frames, ch = frames.shape
230
+
231
+ if not adpcm:
232
+ data = frames.astype("<i2").tobytes()
233
+ fmt = struct.pack("<HHIIHH", WAVE_FORMAT_PCM, ch, sample_rate,
234
+ sample_rate * ch * 2, ch * 2, 16)
235
+ chunks = [(b"fmt ", fmt), (b"data", data)]
236
+ else:
237
+ if block_align is None and samples_per_block is None:
238
+ block_align = codec.default_block_align(sample_rate, ch)
239
+ ba, _ = codec._resolve_geometry(ch, block_align, samples_per_block)
240
+ data = codec.encode(
241
+ frames, block_align=ba, quality=quality, coeffs=coeffs, progress=progress,
242
+ )
243
+ chunks = [
244
+ (b"fmt ", format_chunk(sample_rate, ch, ba, coeffs)),
245
+ (b"fact", struct.pack("<I", n_frames)),
246
+ (b"data", data),
247
+ ]
248
+
249
+ out = bytearray(b"RIFF\0\0\0\0WAVE")
250
+ for cid, body in chunks:
251
+ out += struct.pack("<4sI", cid, len(body)) + body
252
+ if len(body) & 1:
253
+ out += b"\0"
254
+ struct.pack_into("<I", out, 4, len(out) - 8)
255
+ Path(path).write_bytes(bytes(out))
256
+ return len(out)
@@ -0,0 +1,166 @@
1
+ Metadata-Version: 2.4
2
+ Name: msadpcm
3
+ Version: 0.1.1
4
+ Summary: Microsoft ADPCM (WAVE_FORMAT_ADPCM) encoder and decoder in pure Python + NumPy
5
+ Author: Y-Dr. Now
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Eyef/msadpcm
8
+ Keywords: adpcm,ms-adpcm,microsoft-adpcm,wav,audio,codec,encoder,decoder
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Multimedia :: Sound/Audio
13
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
14
+ Requires-Python: >=3.9
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: numpy>=1.21
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest; extra == "test"
20
+ Dynamic: license-file
21
+
22
+ # msadpcm
23
+
24
+ Microsoft ADPCM (`WAVE_FORMAT_ADPCM`, tag `0x0002`) **encoder and decoder** in pure
25
+ Python + NumPy. No FFmpeg, no compiled extensions, no multiprocessing.
26
+
27
+ * any block size (`block_align` in bytes, or `samples_per_block`), mono and stereo
28
+ * decoder output is **bit-exact with FFmpeg's `adpcm_ms`** (checked in the test suite, both directions)
29
+ * encoder searches all 7 standard predictors and a grid of initial step sizes for every block, with
30
+ the same arithmetic as the decoder, so the quality it measures is the quality you get
31
+ * reads and writes complete WAV files (`fact` chunk included), or works on raw blocks in memory
32
+ * optional custom coefficient tables
33
+ * command line tool and a small tkinter demo (`examples/gui_demo.py`)
34
+
35
+ ```
36
+ pip install msadpcm # once published; until then: pip install .
37
+ ```
38
+
39
+ ## Quick start
40
+
41
+ ```python
42
+ import numpy as np
43
+ import msadpcm
44
+
45
+ # whole files
46
+ msadpcm.write_wav("out.wav", pcm, 22050) # pcm: int16 (frames,) or (frames, 2)
47
+ pcm, rate = msadpcm.read_wav("out.wav") # ADPCM or PCM in, int16 (frames, channels) out
48
+
49
+ # raw blocks
50
+ blocks = msadpcm.encode(pcm, block_align=512) # quality="normal" by default
51
+ pcm = msadpcm.decode(blocks, channels=1, block_align=512, n_samples=len(pcm))
52
+ ```
53
+
54
+ Inputs may be `int16` arrays, floats in [-1, 1], plain lists of ints, or little-endian `bytes`
55
+ (then pass `channels=`). Wider integer arrays are rejected on purpose: a 24-bit file stored in
56
+ `int32` would be silently clipped otherwise; convert it explicitly.
57
+
58
+ ### Block size
59
+
60
+ ```python
61
+ msadpcm.write_wav("a.wav", pcm, 44100, block_align=2048) # bytes per block
62
+ msadpcm.write_wav("b.wav", pcm, 22050, samples_per_block=128) # 70-byte mono / 140-byte stereo blocks
63
+ msadpcm.samples_per_block(512, 2) # -> 500
64
+ msadpcm.block_align_for(128, 1) # -> 70
65
+ ```
66
+
67
+ Without an explicit size `write_wav` uses what Windows' ACM codec does
68
+ (`256 * channels * max(1, rate // 11025)` bytes). A larger block means a smaller file
69
+ (less header overhead) but slower adaptation after a transient.
70
+
71
+ ### Quality presets
72
+
73
+ `quality="fast" | "normal" (default) | "high" | "max"`: how many candidate step sizes are tried per
74
+ block. All presets try all seven predictors. `normal` is within a few hundredths of a dB of `high` at
75
+ about half the encoding time; use `high` or `max` when you want the last bit of quality and don't mind
76
+ waiting, `fast` for quick previews or batch jobs.
77
+
78
+ ### Command line
79
+
80
+ ```
81
+ python -m msadpcm encode in.wav -o out.wav --samples-per-block 128 --quality normal
82
+ python -m msadpcm decode out.wav -o back.wav
83
+ python -m msadpcm info *.wav
84
+ ```
85
+
86
+ `encode` shows a progress line on a terminal (nothing is printed when the output is redirected) and
87
+ reports the SNR of the result (it decodes the file again) unless `--no-verify` is given.
88
+
89
+ ## Quality and speed
90
+
91
+ SNR in dB (higher is better), 6 s of mono audio at 22.05 kHz, run with
92
+ `python benchmarks/compare_ffmpeg.py` (ffmpeg 6.1). All files were decoded with msadpcm's decoder,
93
+ which is bit-exact with FFmpeg's, so the differences come from the encoders only.
94
+
95
+ | signal | block | ffmpeg `adpcm_ms` | fast | normal | high | max |
96
+ |---|---|---|---|---|---|---|
97
+ | voice-like | 256 | 30.40 | 39.20 | 39.76 | 39.88 | 40.04 |
98
+ | music-like | 256 | 34.54 | 42.14 | 42.53 | 42.59 | 42.76 |
99
+ | white noise | 256 | 14.12 | 16.59 | 16.71 | 16.72 | 16.77 |
100
+ | voice-like | 1024 | 30.87 | 38.60 | 38.84 | 38.86 | 38.97 |
101
+ | music-like | 1024 | 34.54 | 39.19 | 39.32 | 39.38 | 39.46 |
102
+ | white noise | 1024 | 14.13 | 16.52 | 16.56 | 16.57 | 16.59 |
103
+
104
+ Caveats: the signals are synthetic (the test suite needs no audio assets), and harmonic signals
105
+ reward good predictor choice more than typical recordings do, so expect smaller gains on real
106
+ material. Run the script on your own files before relying on these numbers.
107
+
108
+ Speed depends on the CPU (NumPy uses SIMD instructions where available). Measured on a 2012 Core
109
+ i7-3770, 184 s of mono 48 kHz music with 1024-byte blocks: `fast` 7.1 s (26x real time, SNR 34.08 dB),
110
+ `normal` 15.8 s (12x, 34.26 dB), `high` 32.7 s (5.6x, 34.30 dB). Newer processors are several times
111
+ faster. Stereo takes twice as long as mono. Memory use stays bounded regardless of block size.
112
+
113
+ ## Format notes
114
+
115
+ Blocks are `predictor, delta, sample1, sample2` followed by 4-bit codes (high nibble first); stereo
116
+ stores both channels' header fields interleaved by field and both channels' codes in one byte (left in the
117
+ high nibble). The decoder uses `(s1*c1 + s2*c2) / 256` **truncated toward zero** and
118
+ `delta = max(16, (table[nibble] * delta) >> 8)`, exactly like FFmpeg and the Microsoft codec.
119
+
120
+ Details worth knowing:
121
+
122
+ * The first two samples of every block are stored verbatim, so each block starts exact.
123
+ * The last block is padded by repeating the final sample; the real length is written to the `fact`
124
+ chunk and honoured by `read_wav`/`decode(n_samples=...)`.
125
+ * The header stores the initial delta as a signed 16-bit value; the encoder never writes more than 32767
126
+ and avoids candidates whose delta would later exceed 32767, for decoders that keep it in 16 bits.
127
+ * Only 1 or 2 channels exist in this format.
128
+
129
+ ### Game audio with fixed block sizes
130
+
131
+ Some games expect a particular block geometry. `samples_per_block=128` produces the 70/140-byte blocks
132
+ and the 32-byte extra data (`wSamplesPerBlock=128, wNumCoef=7` + the standard coefficients) that Doom 3 BFG
133
+ Edition uses, which is the standard layout, nothing proprietary:
134
+
135
+ ```python
136
+ fmt = msadpcm.format_chunk(22050, 1, msadpcm.block_align_for(128, 1)) # 50 bytes, extra data included
137
+ raw = msadpcm.encode(pcm, samples_per_block=128) # blocks without any container
138
+ ```
139
+
140
+ ## API summary
141
+
142
+ | | |
143
+ |---|---|
144
+ | `encode(pcm, *, channels=None, block_align=None, samples_per_block=None, quality="normal", coeffs=None, progress=None) -> bytes` | raw blocks |
145
+ | `decode(data, *, channels, block_align, n_samples=None, coeffs=None) -> int16[frames, channels]` | raw blocks |
146
+ | `write_wav(path, pcm, rate, *, adpcm=True, block_align=None, samples_per_block=None, quality="normal", coeffs=None, progress=None)` | `adpcm=False` writes 16-bit PCM |
147
+ | `read_wav(path) -> (int16[frames, channels], rate)` | PCM 8/16/24/32, float, extensible, MS ADPCM |
148
+ | `wav_info(path) -> WavInfo`, `read_adpcm_raw(path)` | header / undecoded blocks |
149
+ | `format_chunk(rate, channels, block_align, coeffs=None)` | `fmt ` chunk body |
150
+ | `samples_per_block`, `block_align_for`, `default_block_align`, `snr_db` | helpers |
151
+
152
+ `progress` is `callback(done_blocks, total_blocks)`; encoding is vectorised over all blocks, so the
153
+ callback fires once per processed chunk of blocks (a few hundred blocks), not per block.
154
+
155
+ ## Development
156
+
157
+ ```
158
+ pip install -e .[test]
159
+ pytest
160
+ python benchmarks/compare_ffmpeg.py
161
+ ```
162
+
163
+ The ffmpeg interoperability tests are skipped automatically when `ffmpeg` is not installed. The decoder is
164
+ also tested against an independent scalar re-implementation (`tests/helpers.py`).
165
+
166
+ MIT licensed.
@@ -0,0 +1,11 @@
1
+ msadpcm/__init__.py,sha256=Fzh19QMrZ2fv85rpsTamwIfrQSi4QpQkrV2WxsCzCrA,679
2
+ msadpcm/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
3
+ msadpcm/cli.py,sha256=k-3dv8tiiZD8hjhzSdNsNMwNxoAQJxyASBUssOdoFsE,8034
4
+ msadpcm/codec.py,sha256=eerf3w77ZigEJwcuriICQfVvC9QANXp5NUxajjI6wa0,23528
5
+ msadpcm/wav.py,sha256=ZzZUoEuYWSiCIWkf-ZsHhvx4gBYdZ5hgfhD2xDUNwsk,9469
6
+ msadpcm-0.1.1.dist-info/licenses/LICENSE,sha256=YoZSBHnFh8hrYi-wNbmSbuWlc2C0UsjyYPPMG-qT7k0,1066
7
+ msadpcm-0.1.1.dist-info/METADATA,sha256=cZ32t2E79AwKNpACXhzKn6tpYwFP94GFwQOykT9Kd3I,7971
8
+ msadpcm-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
9
+ msadpcm-0.1.1.dist-info/entry_points.txt,sha256=SmZTYMEA2sXfPIBqsgdQai9TPPSFeS0yC3Dhr6rmZME,45
10
+ msadpcm-0.1.1.dist-info/top_level.txt,sha256=IJUFf7TF4PPRZ6CTTNJqIAzfPKRUjp90kHgh-D4ntjo,8
11
+ msadpcm-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ msadpcm = msadpcm.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Y-Dr. Now
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ msadpcm