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 +33 -0
- msadpcm/__main__.py +5 -0
- msadpcm/cli.py +220 -0
- msadpcm/codec.py +620 -0
- msadpcm/wav.py +256 -0
- msadpcm-0.1.1.dist-info/METADATA +166 -0
- msadpcm-0.1.1.dist-info/RECORD +11 -0
- msadpcm-0.1.1.dist-info/WHEEL +5 -0
- msadpcm-0.1.1.dist-info/entry_points.txt +2 -0
- msadpcm-0.1.1.dist-info/licenses/LICENSE +21 -0
- msadpcm-0.1.1.dist-info/top_level.txt +1 -0
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
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,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
|