mea8000-encoder 0.1.0__py3-none-any.whl

mea8000/__init__.py

@@ -0,0 +1,6 @@
+"""MEA8000 speech synthesizer tools."""
+
+from .codec import Frame, Utterance, parse_stream, build_stream
+from .sim import Chip, Model, render
+
+__all__ = ["Frame", "Utterance", "parse_stream", "build_stream", "Chip", "Model", "render"]

mea8000/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m mea8000` is the `mea8000` command."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

mea8000/analysis.py

@@ -0,0 +1,326 @@
+"""Target analysis for the encoder: pitch, voicing, energy and spectral envelope per 8 ms.
+
+Everything works at 8 kHz, the rate of the chip's filter bank: nothing above 4 kHz can be
+represented, so the input is band-limited first.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.signal import resample_poly
+
+RATE = 8000
+HOP = 64                 # 8 ms, the shortest frame of the chip
+ENV_WIN = 256            # 32 ms analysis window for the envelope
+PITCH_WIN = 224          # 28 ms window for the difference function
+MAX_CANDIDATES = 6
+F0_MIN, F0_MAX = 60.0, 510.0
+N_BINS = 129             # envelope grid: 0..4000 Hz in 31.25 Hz steps
+ENV_FREQS = np.linspace(0.0, RATE / 2, N_BINS)
+
+
+@dataclass
+class Analysis:
+    rate: int
+    hop: int
+    f0: np.ndarray          # Hz per frame, nan when unvoiced
+    voiced: np.ndarray      # bool per frame
+    periodicity: np.ndarray  # 1 - min(cmndf), per frame
+    energy_db: np.ndarray   # RMS of the frame, dB re full scale
+    envelope_db: np.ndarray  # (frames, N_BINS) smoothed log magnitude
+    lpc: np.ndarray         # (frames, order + 1) predictor coefficients
+    hnr_db: np.ndarray | None = None  # harmonic-to-noise ratio at the tracked pitch
+
+    @property
+    def n_frames(self) -> int:
+        return len(self.f0)
+
+    def times(self) -> np.ndarray:
+        return np.arange(self.n_frames) * self.hop / self.rate
+
+
+def to_8k(x: np.ndarray, rate: float) -> np.ndarray:
+    """Mono float signal at 8 kHz; `rate` may be fractional (clock compensation)."""
+    x = np.asarray(x, dtype=np.float64)
+    if x.dtype.kind in "iu" or np.abs(x).max() > 1.5:
+        x = x / 32768.0
+    rate = int(round(rate))
+    if rate == RATE:
+        return x
+    from math import gcd
+
+    g = gcd(rate, RATE)
+    return resample_poly(x, RATE // g, rate // g)
+
+
+def n_frames_for(n_samples: int, hop: int = HOP) -> int:
+    return max(1, int(np.ceil(n_samples / hop)))
+
+
+def _frame(x: np.ndarray, start: int, win: int) -> np.ndarray:
+    """Window of `win` samples centred on the frame that starts at `start` (zero padded)."""
+    c = start + HOP // 2
+    a = c - win // 2
+    seg = np.zeros(win)
+    lo, hi = max(a, 0), min(a + win, len(x))
+    if hi > lo:
+        seg[lo - a: hi - a] = x[lo:hi]
+    return seg
+
+
+# ------------------------------------------------------------------ envelope (Burg LPC)
+
+def burg(x: np.ndarray, order: int) -> tuple[np.ndarray, float]:
+    """Burg's method. Returns a[0..order] with a[0] = 1 and the prediction error power."""
+    x = np.asarray(x, dtype=np.float64)
+    n = len(x)
+    a = np.zeros(order + 1)
+    a[0] = 1.0
+    err = float(np.dot(x, x)) / n
+    f = x[1:].copy()   # forward prediction errors
+    b = x[:-1].copy()  # backward prediction errors
+    for m in range(1, order + 1):
+        den = float(np.dot(f, f) + np.dot(b, b))
+        k = -2.0 * float(np.dot(f, b)) / den if den > 0 else 0.0
+        a_prev = a.copy()
+        for i in range(1, m):
+            a[i] = a_prev[i] + k * a_prev[m - i]
+        a[m] = k
+        f, b = f[1:] + k * b[1:], b[:-1] + k * f[:-1]
+        err *= (1.0 - k * k)
+    return a, err
+
+
+def lpc_envelope_db(a: np.ndarray, gain: float, freqs: np.ndarray = ENV_FREQS) -> np.ndarray:
+    w = 2 * np.pi * freqs / RATE
+    k = np.arange(len(a))
+    denom = np.abs(np.exp(-1j * np.outer(w, k)) @ a)
+    return 20 * np.log10(gain / np.maximum(denom, 1e-9) + 1e-12)
+
+
+# ------------------------------------------------------------------ pitch (YIN)
+
+def cmndf(seg: np.ndarray, lag_max: int) -> np.ndarray:
+    """Cumulative mean normalised difference function of YIN for lags 0..lag_max."""
+    n = len(seg) - lag_max
+    x = seg[:n]
+    d = np.empty(lag_max + 1)
+    e0 = float(np.dot(x, x))
+    # d(tau) = sum (x[j] - x[j+tau])^2 over j < n
+    csum = np.concatenate([[0.0], np.cumsum(seg * seg)])
+    for tau in range(lag_max + 1):
+        y = seg[tau: tau + n]
+        d[tau] = e0 + (csum[tau + n] - csum[tau]) - 2.0 * float(np.dot(x, y))
+    out = np.ones(lag_max + 1)
+    run = np.cumsum(d[1:])
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out[1:] = np.where(run > 0, d[1:] * np.arange(1, lag_max + 1) / run, 1.0)
+    return out
+
+
+def _parabolic(y: np.ndarray, i: int) -> float:
+    if i <= 0 or i >= len(y) - 1:
+        return float(i)
+    a, b, c = y[i - 1], y[i], y[i + 1]
+    den = a - 2 * b + c
+    return float(i) if den == 0 else float(i + 0.5 * (a - c) / den)
+
+
+# the subharmonic threshold and penalty live in tuning.current (subharmonic_threshold, _penalty)
+
+
+def _candidates(c: np.ndarray, lag_min: int) -> tuple[np.ndarray, np.ndarray]:
+    """Local minima of the CMNDF (refined lag, cost), best first, at most MAX_CANDIDATES.
+
+    YIN's protection against pitch halving: on a periodic signal the CMNDF is as deep at
+    two periods as at one, so the shortest lag whose dip is under SUBHARMONIC_THRESHOLD
+    is taken as the period and every longer dip pays SUBHARMONIC_PENALTY per octave.
+    Without it the tracker halves the pitch of sung voices and of the chip's own output."""
+    idx = [i for i in range(max(lag_min, 1), len(c) - 1) if c[i] <= c[i - 1] and c[i] < c[i + 1]]
+    if not idx:
+        return np.zeros(0), np.zeros(0)
+    # a dip counts as "good" under the absolute threshold, or within 0.1 of the deepest
+    # one: on a fading note the dip at one period is shallower than 0.15 while the one at
+    # two periods is not, and the pitch would still be halved
+    from . import tuning
+    K = tuning.current
+    cmin = min(c[i] for i in idx)
+    good = [i for i in idx if c[i] < max(K.subharmonic_threshold, min(0.4, cmin + 0.1))]
+    first = min(good) if good else None
+    cost = {i: c[i] + (K.subharmonic_penalty * np.log2(i / first) if first is not None and i > 1.5 * first else 0.0)
+            for i in idx}
+    idx.sort(key=lambda i: cost[i])
+    idx = idx[:MAX_CANDIDATES]
+    return np.array([_parabolic(c, i) for i in idx]), np.array([cost[i] for i in idx])
+
+
+def _viterbi(lags: list[np.ndarray], costs: list[np.ndarray], unvoiced_cost: np.ndarray | float,
+             octave_weight: float, switch_cost: float) -> np.ndarray:
+    """Pick one candidate (or unvoiced, returned as nan) per frame by dynamic programming.
+    `unvoiced_cost` may be one value per frame."""
+    n = len(lags)
+    uc = np.broadcast_to(np.asarray(unvoiced_cost, dtype=np.float64), (n,))
+    best = [None] * n
+    back = [None] * n
+    prev_score = None
+    prev_lags = None
+    for k in range(n):
+        lk = np.append(lags[k], np.nan)                 # last state = unvoiced
+        local = np.append(costs[k], uc[k])
+        if prev_score is None:
+            score = local
+            back[k] = np.full(len(lk), -1)
+        else:
+            m = len(prev_lags)
+            trans = np.full((m, len(lk)), switch_cost)
+            pv = ~np.isnan(prev_lags)
+            cv = ~np.isnan(lk)
+            both = np.outer(pv, cv)
+            ratio = np.abs(np.log2(np.outer(prev_lags, 1.0 / lk)))
+            trans[both] = octave_weight * ratio[both]
+            trans[np.outer(~pv, ~cv)] = 0.0
+            total = prev_score[:, None] + trans
+            back[k] = np.argmin(total, axis=0)
+            score = total[back[k], np.arange(len(lk))] + local
+        best[k] = score
+        prev_score, prev_lags = score, lk
+    path = np.full(n, np.nan)
+    j = int(np.argmin(best[-1]))
+    for k in range(n - 1, -1, -1):
+        path[k] = lags[k][j] if j < len(lags[k]) else np.nan
+        j = int(back[k][j])
+    return path
+
+
+def analyze(x: np.ndarray, rate: int, order: int = 12, unvoiced_cost: float | None = None,
+            switch_cost: float | None = None, min_run: int | None = None, silence_db: float = -60.0,
+            hnr_unvoiced: float | None = None, hnr_voiced: float = float("inf"),
+            loud_range_db: float = 20.0, loud_unvoiced_bonus: float | None = None) -> Analysis:
+    from . import tuning
+    K = tuning.current
+    unvoiced_cost = K.unvoiced_cost if unvoiced_cost is None else unvoiced_cost
+    switch_cost = K.switch_cost if switch_cost is None else switch_cost
+    min_run = K.min_run if min_run is None else min_run
+    hnr_unvoiced = K.hnr_unvoiced if hnr_unvoiced is None else hnr_unvoiced
+    loud_unvoiced_bonus = K.loud_unvoiced_bonus if loud_unvoiced_bonus is None else loud_unvoiced_bonus
+    # hnr_voiced (promotion of unvoiced slots) is disabled by default: on the chip's own
+    # output, noise through narrow resonators shows a median HNR of 13 dB against 17 dB for
+    # voiced slots, so promotion creates far more false voicing than it repairs
+    x8 = to_8k(x, rate)
+    n = n_frames_for(len(x8))
+    lag_min = int(np.floor(RATE / F0_MAX))
+    lag_max = int(np.ceil(RATE / F0_MIN))
+
+    periodicity = np.zeros(n)
+    energy = np.full(n, silence_db)
+    env = np.zeros((n, N_BINS))
+    lpcs = np.zeros((n, order + 1))
+    hann_env = np.hanning(ENV_WIN)
+    cand_lags: list[np.ndarray] = []
+    cand_costs: list[np.ndarray] = []
+
+    for k in range(n):
+        start = k * HOP
+        seg = x8[start: start + HOP]
+        if len(seg):
+            r = float(np.sqrt(np.mean(seg * seg)))
+            energy[k] = 20 * np.log10(r) if r > 0 else silence_db
+
+        # envelope
+        w = _frame(x8, start, ENV_WIN) * hann_env
+        if np.dot(w, w) > 1e-12:
+            a, err = burg(w, order)
+            lpcs[k] = a
+            env[k] = lpc_envelope_db(a, np.sqrt(max(err, 1e-20)))
+        else:
+            env[k] = -120.0
+
+        # pitch candidates
+        p = _frame(x8, start, PITCH_WIN + lag_max)
+        if np.dot(p, p) < 1e-10 or energy[k] <= silence_db + 10:
+            cand_lags.append(np.zeros(0))
+            cand_costs.append(np.zeros(0))
+            continue
+        c = cmndf(p, lag_max)
+        lags, costs = _candidates(c, lag_min)
+        periodicity[k] = 1.0 - float(costs[0]) if len(costs) else 0.0
+        cand_lags.append(lags)
+        cand_costs.append(costs)
+
+    # loud frames are almost always vowels: the unvoiced state costs more near the peak level
+    # (reverberation and background lower the measured periodicity of real recordings)
+    peak = float(np.max(energy))
+    loudness = np.clip((energy - (peak - loud_range_db)) / loud_range_db, 0.0, 1.0)
+    uc = unvoiced_cost + loud_unvoiced_bonus * loudness
+    lag_path = _viterbi(cand_lags, cand_costs, uc, octave_weight=K.octave_weight, switch_cost=switch_cost)
+    f0 = RATE / lag_path
+    voiced = ~np.isnan(f0)
+
+    # harmonic-to-noise ratio at the tracked pitch (or the best candidate) decides the
+    # doubtful slots: periodic energy through narrow resonators is not voicing, and weak
+    # voiced slots at onsets still show harmonics
+    hnr = np.full(n, np.nan)
+    for k in range(n):
+        if energy[k] <= silence_db + 10:
+            continue
+        if voiced[k]:
+            fk = f0[k]
+        elif len(cand_lags[k]):
+            fk = RATE / cand_lags[k][0]
+        else:
+            continue
+        hnr[k] = harmonic_to_noise_db(x8, k * HOP, fk)
+    with np.errstate(invalid="ignore"):
+        voiced = np.where(hnr < hnr_unvoiced, False, voiced)
+        promote = (~voiced) & (hnr > hnr_voiced)
+    for k in np.where(promote)[0]:
+        f0[k] = RATE / cand_lags[k][0]
+    voiced = voiced | promote
+    voiced = _absorb_short_runs(voiced, min_run)
+    # slots voiced by absorption take the pitch of their nearest voiced neighbour
+    idx = np.where(~np.isnan(f0))[0]
+    if len(idx):
+        for k in np.where(voiced & np.isnan(f0))[0]:
+            f0[k] = f0[idx[np.argmin(np.abs(idx - k))]]
+    f0[~voiced] = np.nan
+    return Analysis(RATE, HOP, f0, voiced, periodicity, energy, env, lpcs, hnr)
+
+
+def harmonic_to_noise_db(x8: np.ndarray, start: int, f0_hz: float, fmax: float = 2500.0) -> float:
+    """Mean level difference (dB) between the harmonic peaks of f0 and the valleys between
+    them, over the harmonics below `fmax`, on a window of three periods."""
+    if not np.isfinite(f0_hz) or f0_hz <= 0:
+        return float("nan")
+    win = max(256, int(round(3 * RATE / f0_hz)))
+    win += win % 2
+    seg = _frame(x8, start, win) * np.hanning(win)
+    nfft = 4096
+    spec = 20 * np.log10(np.abs(np.fft.rfft(seg, nfft)) + 1e-9)
+    grid = np.fft.rfftfreq(nfft, 1.0 / RATE)
+    diffs = []
+    k = 1
+    while (k + 0.5) * f0_hz < fmax:
+        fc = k * f0_hz
+        lo, hi = np.searchsorted(grid, fc - 0.25 * f0_hz), np.searchsorted(grid, fc + 0.25 * f0_hz)
+        vlo, vhi = np.searchsorted(grid, fc + 0.3 * f0_hz), np.searchsorted(grid, fc + 0.7 * f0_hz)
+        if hi > lo and vhi > vlo:
+            diffs.append(spec[lo:hi].max() - spec[vlo:vhi].min())
+        k += 1
+    return float(np.mean(diffs)) if diffs else float("nan")
+
+
+def _absorb_short_runs(flags: np.ndarray, min_run: int) -> np.ndarray:
+    """Flip runs shorter than `min_run` that sit between two runs of the other value."""
+    out = flags.copy()
+    n = len(out)
+    k = 0
+    while k < n:
+        j = k
+        while j < n and out[j] == out[k]:
+            j += 1
+        if 0 < k and j < n and j - k < min_run:
+            out[k:j] = not out[k]
+        k = j
+    return out

mea8000/cli.py

@@ -0,0 +1,287 @@
+"""Command line.
+
+    mea8000 encode voice.wav voice.mea                 # profile thomson
+    mea8000 encode voice.wav voice.mea --profile compact
+    mea8000 encode voice.wav voice.mea --profile voice.toml --report
+    mea8000 render voice.mea voice.wav                 # what the chip says
+    mea8000 inspect voice.mea                          # what the file holds
+    mea8000 profiles                                   # the shipped profiles
+    mea8000 profiles thomson > mine.toml               # one of them, to start from
+
+A profile (`--profile`) says how to convert: thomson (default), philips, compact, or a
+TOML file of your own (docs/profile.md). Options override its values. `python -m mea8000`
+is the same command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from . import profile as profiles
+from . import sim
+from .codec import build_stream, describe_stream, detect_layout, parse_stream
+from .filters import convert
+from .wav import AudioError, describe, read_wav, write_wav
+
+MODELS = {"default": sim.DEFAULT, "mame-int": sim.MAME_INT, "mame-float": sim.MAME_FLOAT, "java": sim.LEGACY_JAVA}
+
+
+class Progress:
+    """A percentage on one line of stderr, only when stderr is a terminal."""
+
+    def __init__(self, label: str) -> None:
+        self.label = label
+        self.on = sys.stderr.isatty()
+        self.last = -1
+
+    def __call__(self, fraction: float) -> None:
+        pct = int(100 * min(1.0, max(0.0, fraction)))
+        if self.on and pct != self.last:
+            self.last = pct
+            sys.stderr.write(f"\r{self.label} {pct:3d}%")
+            sys.stderr.flush()
+
+    def done(self) -> None:
+        if self.on and self.last >= 0:
+            sys.stderr.write("\r" + " " * (len(self.label) + 6) + "\r")
+            sys.stderr.flush()
+
+
+def fail(message: str) -> int:
+    print(message, file=sys.stderr)
+    return 2
+
+
+def _profile(args) -> profiles.Profile:
+    prof = profiles.load(args.profile)
+    return prof.with_overrides(format=getattr(args, "format", None), pitch=getattr(args, "pitch", None),
+                               frame_ms=getattr(args, "frame", None), quality=getattr(args, "quality", None),
+                               highpass_hz=getattr(args, "highpass", None), channel=getattr(args, "channel", None),
+                               normalize=getattr(args, "normalize", None), trim=getattr(args, "trim", None))
+
+
+def _load_stream(path: str, fmt: str | None):
+    p = Path(path)
+    if not p.is_file():
+        raise FileNotFoundError(f"{path}: no such file")
+    data = p.read_bytes()
+    layout = fmt or detect_layout(data)
+    try:
+        return parse_stream(data, layout), layout
+    except ValueError as e:
+        raise ValueError(f"{path}: not a {'vocabulary image' if layout == 'vocabulary' else 'speech file'} ({e})") from e
+
+
+def _check_output(output: Path, source: Path, wrong_suffix: str, wrong_what: str) -> str | None:
+    """Why the output cannot be written there, or None: never over the input, never under
+    the other kind's extension, only in a directory that exists."""
+    if output.resolve() == source.resolve():
+        return f"{output}: the output is the input"
+    if output.suffix.lower() == wrong_suffix:
+        return f"{output}: {wrong_what} cannot be written under a {wrong_suffix} name"
+    if not output.parent.is_dir():
+        return f"{output.parent}: no such directory"
+    return None
+
+
+# ----------------------------------------------------------------- commands
+
+def cmd_encode(args) -> int:
+    try:
+        prof = _profile(args)
+    except (FileNotFoundError, ValueError) as e:
+        return fail(str(e))
+    output = Path(args.output)
+    if not output.suffix:
+        output = output.with_name(output.name + prof.extension)
+    name = output.name.lower()
+    if name.endswith(".voc.mea") and prof.format == "speech":
+        return fail(f"{output}: the name says vocabulary image, the format is speech (pass --format vocabulary, or name it .mea)")
+    if name.endswith(".mea") and not name.endswith(".voc.mea") and prof.format == "vocabulary":
+        return fail(f"{output}: the name says speech files, the format is vocabulary (pass --format speech, or name it .voc.mea)")
+    why = _check_output(output, Path(args.source), ".wav", "speech data")
+    if why:
+        return fail(why)
+    try:
+        x, rate = read_wav(args.source)
+        progress = Progress("encoding")
+        prepared, utts, result = convert(prof, x, rate, progress=progress)
+        progress.done()
+    except (AudioError, ValueError) as e:
+        return fail(str(e))
+    print(f"{describe(x, rate, args.source)} -> {prepared.describe()}")
+    data = build_stream(utts, prof.format)
+    output.write_bytes(data)
+    what = "vocabulary image" if prof.format == "vocabulary" else "speech file" + ("s" if len(utts) != 1 else "")
+    frames = sum(len(u.frames) for u in utts)
+    print(f"{output}: {what}, {len(utts)} word group{'s' if len(utts) != 1 else ''}, {frames} frames, {len(data)} bytes "
+          f"(profile {prof.name}, {prof.clock_hz / 1e6:.2f} MHz, pitch {prof.pitch}, frame {prof.frame_ms} ms, {prof.quality})")
+    if args.report:
+        from .report import write_report
+
+        page = output.with_suffix("").with_suffix(".html") if output.name.endswith(".voc.mea") else output.with_suffix(".html")
+        source_wav = page.with_name(page.stem + "-source.wav")
+        chip_wav = page.with_name(page.stem + "-chip.wav")
+        write_report(page, source_wav, chip_wav, Path(args.source).name, prepared, utts, result, prof, len(data))
+        print(f"{page}: report ({source_wav.name}, the recording after the filters, and {chip_wav.name} beside it)")
+    return 0
+
+
+def cmd_render(args) -> int:
+    from .fastsim import HAVE_NUMBA, render_fast
+
+    try:
+        prof = profiles.load(args.profile)
+        utts, layout = _load_stream(args.file, args.format)
+    except (FileNotFoundError, ValueError) as e:
+        return fail(str(e))
+    if args.rate is not None and args.rate < 1:
+        return fail(f"--rate {args.rate}: a rate is a positive number of Hz")
+    why = _check_output(Path(args.output), Path(args.file), ".mea", "a rendering")
+    if why:
+        return fail(why)
+    model = sim.with_model(MODELS[args.model], clock_hz=prof.clock_hz)
+    if args.pitch_scale:
+        model = sim.with_model(model, pitch_scale=args.pitch_scale)
+    if args.truncate_bits:
+        model = sim.with_model(model, truncate_bits=args.truncate_bits)
+    noise = np.fromfile(args.noise_table, dtype="<i4").astype(np.int64) if args.noise_table else None
+    seconds = sum(u.duration_ms() for u in utts) / 1000
+    if args.policy == "java-exact":
+        samples = sim.render_java_like(utts, noise)
+    elif HAVE_NUMBA:
+        if sys.stderr.isatty():
+            sys.stderr.write("rendering ...\r")
+        samples = render_fast(utts, model, args.policy, noise)
+    else:
+        progress = Progress("rendering")
+        samples = sim.render(utts, model, args.policy, noise, progress=progress)
+        progress.done()
+    rate = model.sample_rate
+    if args.rate and args.rate != rate:
+        from math import gcd
+        from scipy.signal import resample_poly
+
+        g = gcd(int(args.rate), rate)
+        samples = np.clip(resample_poly(samples.astype(np.float64), int(args.rate) // g, rate // g), -32767, 32767)
+        rate = int(args.rate)
+    write_wav(args.output, samples, rate)
+    print(f"{args.output}: {len(samples) / rate:.2f} s at {rate} Hz (chip clock {prof.clock_hz / 1e6:.2f} MHz, "
+          f"profile {prof.name}, {layout} of {len(utts)} word group{'s' if len(utts) != 1 else ''})")
+    return 0
+
+
+def cmd_inspect(args) -> int:
+    try:
+        utts, layout = _load_stream(args.file, args.format)
+    except (FileNotFoundError, ValueError) as e:
+        return fail(str(e))
+    what = "vocabulary image" if layout == "vocabulary" else "speech file" + ("s" if len(utts) != 1 else "")
+    print(f"{args.file}: {what}, {len(utts)} word group{'s' if len(utts) != 1 else ''}, "
+          f"{sum(len(u.frames) for u in utts)} frames, {sum(u.duration_ms() for u in utts) / 1000:.2f} s")
+    if not args.summary:
+        print(describe_stream(utts))
+    return 0
+
+
+def cmd_profiles(args) -> int:
+    if args.name:
+        try:
+            print(profiles.path_of(args.name).read_text(), end="")
+        except FileNotFoundError as e:
+            return fail(str(e))
+        return 0
+    for name in profiles.names():
+        p = profiles.load(name)
+        print(f"{name:10s} clock {p.clock_hz / 1e6:.2f} MHz  format {p.format:10s}  pitch {p.pitch:6s}  "
+              f"frame {p.frame_ms:2d} ms  quality {p.quality:8s}  channel {p.channel:5s}  highpass {p.highpass_hz:g} Hz  "
+              f"normalize {'on' if p.normalize else 'off':3s}  trim {'on' if p.trim else 'off'}")
+    return 0
+
+
+# ----------------------------------------------------------------- parser
+
+class Formatter(argparse.RawDescriptionHelpFormatter):
+    pass
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="mea8000", description="A recording in, MEA8000 speech data out.",
+                                 formatter_class=Formatter, epilog=__doc__.split("\n", 2)[2])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("encode", help="encode a recording into MEA8000 speech data",
+                       usage="mea8000 encode SOURCE.wav OUTPUT.mea [--profile NAME|FILE] [options]",
+                       description="Encode a recording (WAV, any rate, any bit depth, mono or stereo).",
+                       formatter_class=Formatter)
+    e.add_argument("source", metavar="SOURCE.wav", help="the recording")
+    e.add_argument("output", metavar="OUTPUT.mea", help="the output (.mea for speech files, .voc.mea for a vocabulary image;"
+                                                        " added when the name has no extension)")
+    e.add_argument("--profile", default="thomson", metavar="NAME|FILE",
+                   help="how to convert: thomson (default), philips, compact, or a TOML file of your own")
+    e.add_argument("--format", choices=profiles.FORMATS,
+                   help="speech: speech files one after the other, one per word group (default); "
+                        "vocabulary: an image with an offset table, each file reachable by its number")
+    e.add_argument("--pitch", choices=profiles.PITCHES,
+                   help="local: a starting pitch per word group, each group its own speech file (default); "
+                        "global: one starting pitch for the whole recording, gliding through the pauses, in a single file")
+    e.add_argument("--frame", type=int, choices=profiles.FRAMES_MS, metavar="{8,16,32,64}",
+                   help="the shortest frame allowed, in ms (default 8, the chip's finest grain; 64 makes "
+                        "every frame 64 ms whatever the quality; only where noise meets voice inside a frame, "
+                        "or at the end of a file, can a frame be shorter)")
+    e.add_argument("--quality", choices=tuple(profiles.QUALITY_PRICE_DB),
+                   help="how much degradation is accepted to lengthen frames beyond --frame: "
+                        "best: none (default); balanced: a little, about 40 %% fewer bytes at --frame; "
+                        "compact: what stays intelligible, about 60 %% fewer bytes at --frame")
+    e.add_argument("--highpass", type=float, metavar="HZ",
+                   help="a high-pass on the recording before analysis (80-150 Hz removes rumble and kick drums)")
+    e.add_argument("--channel", choices=profiles.CHANNELS,
+                   help="which channel of a stereo recording to encode (default left; a mono file has only one)")
+    e.add_argument("--normalize", action=argparse.BooleanOptionalAction, default=None,
+                   help="scale the recording so that its loudest sample reaches full scale (default on; the chip's "
+                        "amplitude codes are absolute, a quiet recording would come out as silence)")
+    e.add_argument("--trim", action=argparse.BooleanOptionalAction, default=None,
+                   help="drop the silence before the first sound and after the last (default on)")
+    e.add_argument("--report", action="store_true",
+                   help="also write, next to the output, the recording after the filters (-source.wav), the chip's "
+                        "rendering (-chip.wav) and an HTML page (.html): spectrograms of both, pitch, voicing and "
+                        "level lanes, the two sounds to play")
+    e.set_defaults(func=cmd_encode)
+
+    r = sub.add_parser("render", help="render speech data to a WAV with the chip simulator",
+                       description="Hear what the chip says: a WAV at the chip's own rate.", formatter_class=Formatter)
+    r.add_argument("file", metavar="INPUT.mea")
+    r.add_argument("output", metavar="OUTPUT.wav")
+    r.add_argument("--profile", default="thomson", metavar="NAME|FILE",
+                   help="the clock of the target machine, taken from the profile: thomson 4 MHz (default), philips 3.84 MHz")
+    r.add_argument("--rate", type=int, metavar="HZ",
+                   help="resample the WAV to this rate (default: the chip's own, 64000 Hz at 3.84 MHz, 66664 Hz at 4 MHz)")
+    r.add_argument("--format", choices=profiles.FORMATS, help="speech or vocabulary; detected from the content when omitted")
+    r.add_argument("--model", choices=list(MODELS), default="default", help=argparse.SUPPRESS)
+    r.add_argument("--policy", choices=["chunk", "philips", "java-exact"], default="chunk", help=argparse.SUPPRESS)
+    r.add_argument("--pitch-scale", type=float, help=argparse.SUPPRESS)
+    r.add_argument("--truncate-bits", type=int, help=argparse.SUPPRESS)
+    r.add_argument("--noise-table", help=argparse.SUPPRESS)
+    r.set_defaults(func=cmd_render)
+
+    i = sub.add_parser("inspect", help="print what a .mea file holds", formatter_class=Formatter)
+    i.add_argument("file", metavar="INPUT.mea")
+    i.add_argument("--format", choices=profiles.FORMATS, help="speech or vocabulary; detected from the content when omitted")
+    i.add_argument("--summary", action="store_true", help="the first line only")
+    i.set_defaults(func=cmd_inspect)
+
+    pr = sub.add_parser("profiles", help="list the shipped profiles, or print one",
+                        description="Without a name, one line per shipped profile; with one, its file, to start yours from.")
+    pr.add_argument("name", nargs="?", metavar="NAME", help="thomson, philips or compact: print that profile's file")
+    pr.set_defaults(func=cmd_profiles)
+
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())