mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/snapshots.py

@@ -0,0 +1,306 @@
+"""Screenshot baselines (docs/testing.mdx, "Screenshots that must not change"): a perceptual pixel diff, no model.
+
+A check's ``snapshot:`` compares the screen it ends on to a PNG under ``.mobster/snapshots/``. Both images are blurred
+by 2 px and a pixel counts as changed only when a colour channel moves by more than TOLERANCE, so antialiasing and
+sub-pixel text never fail a check. Masked regions count in neither the changed pixels nor the total."""
+
+import math
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .assertions import CheckError, parse_selector, reject_unknown_keys
+
+BLUR_PX = 2
+TOLERANCE = 24            # of 255, per colour channel, after the blur
+DEFAULT_THRESHOLD = 0.1   # percent of the unmasked pixels that may differ
+MASK_FILL = (128, 128, 128)
+CELL_PX = 16              # regions are found on a grid this coarse
+REGION_PAD_PX = 4
+MAX_REGIONS = 20
+STATUS_BAR_POINTS = 59    # the top of a Dynamic Island iPhone's screen, when the tree names no status bar
+NAME = re.compile(r"[a-z0-9][a-z0-9_-]{0,59}")
+MASK_KEYS = ("id", "label", "rect")
+MASK_LIMIT = 20
+SNAPSHOT_STATUS_BAR = {"time": "9:41", "data_network": "wifi", "wifi_mode": "active", "wifi_bars": 3,
+                       "cellular_mode": "active", "cellular_bars": 4, "battery_state": "charged",
+                       "battery_level": 100}
+TEXT_ENTRY = frozenset({"TextField", "SecureTextField", "SearchField", "TextView"})
+FOLDER = "snapshots"
+
+MATCHED, CHANGED, SIZE_CHANGED, RECORDED, UPDATED = "matched", "changed", "size_changed", "recorded", "updated"
+
+
+@dataclass(frozen=True)
+class Mask:
+    """A region the diff ignores: the elements a selector matches, or a rectangle in points (x, y, width, height)."""
+    selector: Optional[object] = None
+    rect: Optional[tuple] = None
+
+    def to_dict(self):
+        return {"rect": list(self.rect)} if self.rect is not None else self.selector.to_dict()
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """The ``snapshot:`` entry of a check's ``expect``."""
+    name: str
+    masks: tuple = ()
+    threshold: float = DEFAULT_THRESHOLD   # percent
+
+    def to_dict(self):
+        out = {"snapshot": self.name}
+        if self.masks:
+            out["mask"] = [mask.to_dict() for mask in self.masks]
+        if self.threshold != DEFAULT_THRESHOLD:
+            out["threshold"] = self.threshold
+        return out
+
+
+def parse_mask(obj, where):
+    if not isinstance(obj, dict):
+        raise CheckError(f"{where} must be an object such as {{id: clock}}, {{label: Last sync}} or "
+                         "{rect: [0, 100, 390, 40]}")
+    reject_unknown_keys(obj, MASK_KEYS, where)
+    if "rect" in obj:
+        if len(obj) != 1:
+            raise CheckError(f"{where}: rect goes alone, in points as [x, y, width, height]")
+        rect = obj["rect"]
+        if (not isinstance(rect, list) or len(rect) != 4 or any(
+                isinstance(item, bool) or not isinstance(item, (int, float)) or not math.isfinite(item)
+                for item in rect) or rect[2] <= 0 or rect[3] <= 0):
+            raise CheckError(f"{where}.rect must be four numbers in points: x, y, width and height (the last two "
+                             "above 0)")
+        return Mask(rect=tuple(float(item) for item in rect))
+    if not obj:
+        raise CheckError(f"{where} needs id, label or rect")
+    return Mask(selector=parse_selector(obj, where))
+
+
+def parse_snapshot(obj, where="snapshot"):
+    """The ``snapshot`` entry of ``expect``. Raises CheckError."""
+    reject_unknown_keys(obj, ("snapshot", "mask", "threshold"), where)
+    name = obj.get("snapshot")
+    if not isinstance(name, str) or not NAME.fullmatch(name):
+        raise CheckError(f"{where}.snapshot is the screen's name, 1 to 60 of a-z, 0-9, - and _, such as home; it "
+                         "names the baseline file")
+    masks = obj.get("mask", [])
+    if not isinstance(masks, list):
+        raise CheckError(f"{where}.mask must be a list, such as [{{id: clock}}]")
+    if len(masks) > MASK_LIMIT:
+        raise CheckError(f"{where}.mask has more than {MASK_LIMIT} entries")
+    threshold = obj.get("threshold", DEFAULT_THRESHOLD)
+    if isinstance(threshold, bool) or not isinstance(threshold, (int, float)) or not 0 <= threshold <= 100 \
+            or not math.isfinite(threshold):
+        raise CheckError(f"{where}.threshold is the percent of the screen that may change, from 0 to 100 "
+                         f"(default {DEFAULT_THRESHOLD:g})")
+    return Snapshot(name, tuple(parse_mask(item, f"{where}.mask[{index}]") for index, item in enumerate(masks)),
+                    float(threshold))
+
+
+# -- where baselines live ---------------------------------------------------------------------------------------
+
+def slug(text):
+    return re.sub(r"[^a-z0-9]+", "-", str(text).lower()).strip("-") or "default"
+
+
+def check_key(source, root, name=""):
+    """The folder a check's baselines live in: its file's path under .mobster/checks (or the project), without the
+    suffix; the check's name for a check with no file."""
+    if source and root:
+        path = Path(source)
+        for base in (Path(root) / ".mobster" / "checks", Path(root)):
+            try:
+                return path.resolve().relative_to(base.resolve()).with_suffix("").as_posix()
+            except ValueError:
+                continue
+    return Path(source).stem if source else slug(name)
+
+
+def variant(device, conditions):
+    """``iphone-17-pro-dark-accessibility-large-de_DE``: the device and the three conditions a baseline is for."""
+    conditions = conditions or {}
+    parts = [slug(device)] + [str(conditions.get(key) or "default") for key in ("appearance", "content_size", "locale")]
+    return "-".join(part.replace("/", "_") for part in parts)
+
+
+def baseline_file(root, key, name, device, conditions):
+    return Path(root) / ".mobster" / FOLDER / key / f"{name}@{variant(device, conditions)}.png"
+
+
+# -- the diff ---------------------------------------------------------------------------------------------------
+
+@dataclass
+class Comparison:
+    status: str
+    changed_pixels: int = 0
+    compared_pixels: int = 0
+    regions: list = field(default_factory=list)   # [x, y, w, h] in pixels
+    diff: object = None                           # a PIL image, only for a change
+    seconds: float = 0.0
+
+    @property
+    def changed_percent(self):
+        return 100.0 * self.changed_pixels / self.compared_pixels if self.compared_pixels else 0.0
+
+
+def compare(baseline, current, masks=(), threshold=DEFAULT_THRESHOLD):
+    """Compare two PIL images. ``masks`` are [x, y, w, h] pixel rectangles. Status: matched, changed or size_changed."""
+    from PIL import Image, ImageChops, ImageDraw, ImageFilter
+    started = time.perf_counter()
+    if baseline.size != current.size:
+        return Comparison(SIZE_CHANGED, seconds=time.perf_counter() - started)
+    first, second = baseline.convert("RGB"), current.convert("RGB")
+    counted = Image.new("L", current.size, 255)
+    for x, y, w, h in masks:
+        box = [round(x), round(y), round(x + w) - 1, round(y + h) - 1]
+        for image in (first, second):
+            ImageDraw.Draw(image).rectangle(box, fill=MASK_FILL)   # the same in both, so the blur leaves no halo
+        ImageDraw.Draw(counted).rectangle(box, fill=0)
+    red, green, blue = ImageChops.difference(first.filter(ImageFilter.GaussianBlur(BLUR_PX)),
+                                             second.filter(ImageFilter.GaussianBlur(BLUR_PX))).split()
+    moved = ImageChops.lighter(ImageChops.lighter(red, green), blue).point([255 if v > TOLERANCE else 0
+                                                                           for v in range(256)])
+    changed = moved.histogram()[255]
+    compared = counted.histogram()[255]
+    percent = 100.0 * changed / compared if compared else 0.0
+    if percent <= threshold:
+        return Comparison(MATCHED, changed, compared, seconds=time.perf_counter() - started)
+    regions = _regions(moved)
+    return Comparison(CHANGED, changed, compared, regions, _diff_image(current, moved, regions),
+                      time.perf_counter() - started)
+
+
+def _regions(moved):
+    """Boxes around the changed pixels: neighbouring cells of a CELL_PX grid join, each box padded a little."""
+    from PIL import Image
+    width, height = moved.size
+    columns, rows = -(-width // CELL_PX), -(-height // CELL_PX)
+    grid = moved.resize((columns, rows), Image.BOX).point([255 if v else 0 for v in range(256)])
+    data = grid.load()
+    cells = {(x, y) for y in range(rows) for x in range(columns) if data[x, y]}
+    boxes = []
+    while cells:
+        start = cells.pop()
+        stack, low, high = [start], list(start), list(start)
+        while stack:
+            cx, cy = stack.pop()
+            for nx in (cx - 1, cx, cx + 1):
+                for ny in (cy - 1, cy, cy + 1):
+                    if (nx, ny) in cells:
+                        cells.discard((nx, ny))
+                        stack.append((nx, ny))
+            low[0], low[1] = min(low[0], cx), min(low[1], cy)
+            high[0], high[1] = max(high[0], cx), max(high[1], cy)
+        left, top = max(0, low[0] * CELL_PX - REGION_PAD_PX), max(0, low[1] * CELL_PX - REGION_PAD_PX)
+        right = min(width, (high[0] + 1) * CELL_PX + REGION_PAD_PX)
+        bottom = min(height, (high[1] + 1) * CELL_PX + REGION_PAD_PX)
+        boxes.append([left, top, right - left, bottom - top])
+    boxes.sort(key=lambda box: (box[1], box[0]))
+    if len(boxes) > MAX_REGIONS:
+        left, top = min(b[0] for b in boxes), min(b[1] for b in boxes)
+        boxes = [[left, top, max(b[0] + b[2] for b in boxes) - left, max(b[1] + b[3] for b in boxes) - top]]
+    return boxes
+
+
+def _diff_image(current, moved, regions):
+    """The current screen faded, the changed pixels red, a box around each region."""
+    from PIL import Image, ImageDraw
+    faded = Image.blend(current.convert("RGB"), Image.new("RGB", current.size, "white"), .6)
+    faded.paste(Image.new("RGB", current.size, (230, 30, 30)), mask=moved)
+    draw = ImageDraw.Draw(faded)
+    line = max(2, current.width // 300)
+    for x, y, w, h in regions:
+        draw.rectangle([x, y, x + w - 1, y + h - 1], outline=(230, 30, 30), width=line)
+    return faded
+
+
+# -- masks from the tree ----------------------------------------------------------------------------------------
+
+def mask_rects(snapshot, tree, pixel_width, *, status_bar_set):
+    """Every masked region as [x, y, w, h] pixels: the check's masks, the keyboard (and the fields, whose caret blinks,
+    while it shows) and, when the status bar isn't set, the status bar."""
+    scale = pixel_width / tree.size[0] if tree.size and tree.size[0] else 1.0
+    shown = tree.shown()
+    rects = []
+
+    def add(rect):
+        x, y, w, h = rect
+        rects.append([x * scale, y * scale, w * scale, h * scale])
+    for mask in snapshot.masks:
+        if mask.rect is not None:
+            add(mask.rect)
+        else:
+            for node in shown:
+                if mask.selector.matches(node):
+                    add(node.rect)
+    if any(node.role == "Keyboard" for node in shown):
+        for node in shown:
+            if node.role == "Keyboard" or node.role in TEXT_ENTRY:
+                add(node.rect)
+    if not status_bar_set:
+        bars = [node for node in shown if node.role == "StatusBar"]
+        for node in bars:
+            add(node.rect)
+        if not bars:
+            add((0, 0, tree.size[0], STATUS_BAR_POINTS))
+    return rects
+
+
+def save_png(image, path):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    image.save(temporary, format="PNG")
+    os.replace(temporary, path)
+
+
+# -- listing baselines ------------------------------------------------------------------------------------------
+
+BASELINE_NAME = re.compile(r"(?P<name>[a-z0-9][a-z0-9_-]*)@(?P<variant>.+)\.png")
+
+
+def baselines(root):
+    """Every baseline under .mobster/snapshots: [{file, check, name, variant}], sorted."""
+    base = Path(root) / ".mobster" / FOLDER
+    out = []
+    if not base.is_dir():
+        return out
+    for path in sorted(base.rglob("*.png")):
+        found = BASELINE_NAME.fullmatch(path.name)
+        if found is None:
+            continue
+        out.append({"file": path.relative_to(root).as_posix(),
+                    "check": path.parent.relative_to(base).as_posix(), "name": found["name"],
+                    "variant": found["variant"]})
+    return out
+
+
+def audit(root, checks):
+    """Mark each baseline in a project. ``checks``: [(check key, Check)] of the project's checks.
+    orphaned: no check has that key or snapshot name. stale: the check has the snapshot, but not for this appearance,
+    text size or locale (a check without conditions lists "default" in each)."""
+    from . import conditions as conditions_module
+    wanted = {}
+    for key, check in checks:
+        spec = getattr(check, "snapshot", None)
+        if spec is None:
+            continue
+        combos = conditions_module.combinations(check.conditions)
+        wanted.setdefault((key, spec.name), set()).update(
+            "-".join(str(combo.get(k) or "default") for k in ("appearance", "content_size", "locale"))
+            for combo in combos)
+    out = []
+    for item in baselines(root):
+        sets = wanted.get((item["check"], item["name"]))
+        if sets is None:
+            state = "orphaned"
+        elif not any(item["variant"].endswith("-" + tail) for tail in sets):
+            state = "stale"
+        else:
+            state = "current"
+        out.append({**item, "state": state})
+    return out

mobile_agent/verify/sound.py

@@ -0,0 +1,335 @@
+"""Sound as a verification signal (`expect: [{sound: sent}]`, experimental): matched in code, with no model.
+
+A fingerprint is a short recording of one sound (a sent chime, an error tock) reduced to the shape of its spectrum over
+time: 16 frequency bands per 64 ms frame, as shares of the frame's energy, plus each frame's loudness against the
+loudest. It is recorded once per app under ``.mobster/sounds/<bundle>/<name>.json`` and matched against what the iPhone
+played during a run. A match is a pass (the sound did happen) and the screen read follows as usual; a sound that isn't
+heard fails the assertion and says how close the best window came. Hearing needs a real iPhone (listen.py): a
+simulator's sound doesn't leave the Mac, so a sound assertion on a simulator is not met.
+"""
+
+import cmath
+import json
+import math
+import operator
+import os
+import re
+import threading
+import wave
+from array import array
+from pathlib import Path
+
+from .assertions import AssertionResult
+
+__all__ = ["SETTING", "NAME", "enabled", "fingerprint_wav", "match_wav", "save", "load", "names", "Watch"]
+
+SETTING = "MOBSTER_EXPERIMENTAL_SOUND"
+NAME = re.compile(r"[a-z0-9][a-z0-9_-]{0,39}")
+FRAME = 1024
+HOP = 512
+BANDS = 16
+LOW_HZ, HIGH_HZ = 250.0, 7000.0
+TARGET_RATE = 16000
+ACTIVE_DB = -35.0  # a reference keeps the frames within this many dB of its loudest
+SILENT_DBFS = -55.0  # a window whose loudest frame is quieter than this heard nothing
+MATCH_SCORE = 0.92
+MAX_REFERENCE_SECONDS = 5
+MAX_RECORDING_SECONDS = 120
+WINDOW_SECONDS = 20
+VERSION = 1
+
+
+class SoundError(ValueError):
+    """What is wrong with a sound file or fingerprint, and what to do."""
+
+
+def enabled():
+    return os.environ.get(SETTING, "").strip().lower() in ("1", "on", "true", "yes")
+
+
+def _samples(path):
+    """(mono float samples in -1..1 decimated to about 16 kHz, the rate after decimation) from a 16-bit PCM wav."""
+    try:
+        with wave.open(str(path), "rb") as handle:
+            channels, width, rate, count = (
+                handle.getnchannels(),
+                handle.getsampwidth(),
+                handle.getframerate(),
+                handle.getnframes(),
+            )
+            if width != 2:
+                raise SoundError(f"{Path(path).name} is not 16-bit PCM. Record it as 16-bit WAV.")
+            if count > rate * MAX_RECORDING_SECONDS:
+                raise SoundError(f"{Path(path).name} is longer than {MAX_RECORDING_SECONDS} s. Use a shorter one.")
+            raw = array("h")
+            raw.frombytes(handle.readframes(count))
+    except (wave.Error, EOFError, OSError) as error:
+        raise SoundError(f"{Path(path).name} can't be read as a WAV ({error}). Record it again.") from None
+    if raw.itemsize != 2:
+        raise SoundError("this platform's 16-bit array is not 2 bytes")
+    if channels > 1:
+        raw = array("h", (sum(raw[i : i + channels]) // channels for i in range(0, len(raw) - channels + 1, channels)))
+    step = max(1, rate // TARGET_RATE)
+    mono = [sum(raw[i : i + step]) / (step * 32768.0) for i in range(0, len(raw) - step + 1, step)]
+    return mono, rate / step
+
+
+def _fft(values):
+    """The discrete Fourier transform of ``values`` (a power-of-two length), by the iterative radix-2 method."""
+    n = len(values)
+    out = [values[int(format(i, f"0{n.bit_length() - 1}b")[::-1], 2)] for i in range(n)]
+    size = 2
+    while size <= n:
+        half = size // 2
+        step = [cmath.exp(-2j * math.pi * k / size) for k in range(half)]
+        for start in range(0, n, size):
+            for k in range(half):
+                odd = out[start + k + half] * step[k]
+                out[start + k + half] = out[start + k] - odd
+                out[start + k] = out[start + k] + odd
+        size *= 2
+    return out
+
+
+def _band_of_bins(rate):
+    """For each bin up to Nyquist, the band it belongs to (None outside LOW_HZ..HIGH_HZ); bands are log-spaced."""
+    edges = [LOW_HZ * (HIGH_HZ / LOW_HZ) ** (b / BANDS) for b in range(BANDS + 1)]
+    out = []
+    for k in range(FRAME // 2):
+        hz = k * rate / FRAME
+        out.append(next((b for b in range(BANDS) if edges[b] <= hz < edges[b + 1]), None))
+    return out
+
+
+def _frames(samples, rate):
+    """[(band shares, dBFS of the frame)] for every frame of ``samples``."""
+    hann = [0.5 - 0.5 * math.cos(2 * math.pi * n / (FRAME - 1)) for n in range(FRAME)]
+    bins = _band_of_bins(rate)
+    out = []
+    for start in range(0, len(samples) - FRAME + 1, HOP):
+        spectrum = _fft([x * w for x, w in zip(samples[start : start + FRAME], hann)])
+        power = [0.0] * BANDS
+        for k, band in enumerate(bins):
+            if band is not None:
+                power[band] += abs(spectrum[k]) ** 2
+        total = sum(power)
+        db = 10 * math.log10(total * 2 / sum(hann) ** 2 + 1e-12)
+        out.append(([p / total for p in power] if total > 1e-12 else [0.0] * BANDS, db))
+    return out
+
+
+def fingerprint_wav(path):
+    """The fingerprint (a JSON-able dict) of the sound in the WAV at ``path``, trimmed to its audible part."""
+    samples, rate = _samples(path)
+    if len(samples) > rate * MAX_REFERENCE_SECONDS:
+        raise SoundError(
+            f"{Path(path).name} is longer than {MAX_REFERENCE_SECONDS} s. A fingerprint is one short "
+            "sound: cut it to the chime."
+        )
+    frames = _frames(samples, rate)
+    if not frames:
+        raise SoundError(f"{Path(path).name} is too short to fingerprint. Record at least a tenth of a second.")
+    peak = max(db for _, db in frames)
+    if peak < SILENT_DBFS:
+        raise SoundError(f"{Path(path).name} is silent. Record the sound with the iPhone's volume up.")
+    active = [i for i, (_, db) in enumerate(frames) if db >= peak + ACTIVE_DB]
+    kept = frames[active[0] : active[-1] + 1]
+    return {
+        "version": VERSION,
+        "frame": FRAME,
+        "hop": HOP,
+        "bands": BANDS,
+        "seconds": round(len(kept) * HOP / rate, 2),
+        "frames": [{"shares": [round(s, 4) for s in shares], "db": round(db - peak, 1)} for shares, db in kept],
+    }
+
+
+def _cosine(a, b):
+    dot = sum(map(operator.mul, a, b))
+    na, nb = math.sqrt(sum(x * x for x in a)), math.sqrt(sum(x * x for x in b))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+def best_score(fingerprint, recording_frames):
+    """(best weighted similarity 0..1, the frame it starts at) of the fingerprint over the recording's frames; the
+    window's loudest frame must clear SILENT_DBFS, so silence can't match."""
+    ref = fingerprint["frames"]
+    if fingerprint.get("version") != VERSION or not ref or not recording_frames:
+        raise SoundError("this fingerprint is not one this version of Mobster reads. Record the sound again.")
+    weights = [10 ** (frame["db"] / 20) for frame in ref]
+    best, at = 0.0, 0
+    for start in range(0, len(recording_frames) - len(ref) + 1):
+        window = recording_frames[start : start + len(ref)]
+        if max(db for _, db in window) < SILENT_DBFS:
+            continue
+        score = sum(w * _cosine(frame["shares"], shares) for w, frame, (shares, _) in zip(weights, ref, window)) / sum(
+            weights
+        )
+        if score > best:
+            best, at = score, start
+    return best, at
+
+
+def match_wav(fingerprint, path):
+    """(heard, score, seconds into the recording) for ``fingerprint`` against the WAV at ``path``."""
+    samples, rate = _samples(path)
+    score, start = best_score(fingerprint, _frames(samples, rate))
+    return score >= MATCH_SCORE, round(score, 2), round(start * HOP / rate, 1)
+
+
+def folder(root, bundle):
+    return Path(root) / ".mobster" / "sounds" / re.sub(r"[^A-Za-z0-9._-]", "_", bundle)
+
+
+def save(root, bundle, name, wav):
+    """Record the sound in ``wav`` as ``name`` for the app ``bundle`` under ``root``/.mobster/sounds; the path."""
+    if not NAME.fullmatch(name):
+        raise SoundError("a sound's name is lowercase letters, digits, - and _ (up to 40), such as sent")
+    target = folder(root, bundle) / f"{name}.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(fingerprint_wav(wav), separators=(",", ":")) + "\n")
+    return target
+
+
+def load(root, bundle, name):
+    path = folder(root, bundle) / f"{name}.json"
+    try:
+        return json.loads(path.read_text())
+    except FileNotFoundError:
+        have = ", ".join(names(root, bundle)) or "none"
+        raise SoundError(
+            f"no sound {name!r} is recorded for {bundle} (recorded: {have}). Record it with "
+            "`python -m mobile_agent.verify.sound record`."
+        ) from None
+    except (OSError, ValueError):
+        raise SoundError(f"{path} isn't a fingerprint. Record the sound again.") from None
+
+
+def names(root, bundle):
+    return sorted(p.stem for p in folder(root, bundle).glob("*.json"))
+
+
+def evaluate(root, bundle, wanted, wav, *, why=None):
+    """One AssertionResult per sound name in ``wanted`` against the recording ``wav`` (None when nothing was heard).
+    Fails closed: a sound with no recording to check, or no fingerprint, is not met."""
+    out = []
+    for name in wanted:
+        text = f"sound {name}"
+        if wav is None:
+            out.append(AssertionResult(False, text, "not checked: " + (why or "the iPhone's sound wasn't recorded")))
+            continue
+        try:
+            heard, score, at = match_wav(load(root, bundle, name), wav)
+        except SoundError as error:
+            out.append(AssertionResult(False, text, str(error)))
+            continue
+        out.append(
+            AssertionResult(
+                heard,
+                text,
+                f"heard at {at} s (match {score})" if heard else f"not heard (best match {score}, needs {MATCH_SCORE})",
+            )
+        )
+    return out
+
+
+class Watch:
+    """Records the iPhone's sound in a thread while a run's steps go; ``stop`` waits and gives the WAV, or None."""
+
+    def __init__(self, capture, wav, seconds=WINDOW_SECONDS):
+        self._capture, self.wav, self._seconds = capture, Path(wav), seconds
+        self.error = None
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def _run(self):
+        try:
+            self._capture(self._seconds, keep=str(self.wav))
+        except Exception as error:  # the run goes on; the assertions say the sound wasn't recorded
+            self.error = error
+
+    def start(self):
+        self._thread.start()
+        return self
+
+    def stop(self):
+        self._thread.join(self._seconds + 180)
+        return self.wav if self.wav.is_file() and self.error is None and not self._thread.is_alive() else None
+
+
+class Signal:
+    """A run's sound assertions: ``start`` after the app is up, ``results`` once the steps are done."""
+
+    def __init__(self, wanted, run, *, capture=None):
+        self.wanted, self._run, self._capture, self._watch, self._dir = wanted, run, capture, None, None
+        self._why = None
+
+    def start(self):
+        from .smart import is_real_device
+
+        if not enabled():
+            self._why = f"sound checks are experimental. Set {SETTING}=1 to run them"
+        elif not is_real_device(self._run._manager()):
+            self._why = "a simulator's sound doesn't leave the Mac, so only a real iPhone can be heard"
+        else:
+            import tempfile
+
+            capture = self._capture
+            if capture is None:
+                from ..listen import listen
+
+                capture = lambda seconds, keep: listen(seconds, udid=self._run.target.udid, keep=keep)  # noqa: E731
+            self._dir = tempfile.mkdtemp(prefix="mobster-sound-")
+            os.chmod(self._dir, 0o700)
+            self._watch = Watch(capture, Path(self._dir) / "heard.wav").start()
+
+    def results(self):
+        wav = self._watch.stop() if self._watch is not None else None
+        if self._watch is not None and wav is None:
+            self._why = "the iPhone's sound wasn't recorded" + (
+                f" ({type(self._watch.error).__name__})" if self._watch.error else ""
+            )
+        run = self._run
+        parent = run.runs_dir.parent
+        root = (
+            parent.parent
+            if parent.name == ".mobster"
+            else (Path(run.check.source).parent if run.check.source else Path.cwd())
+        )
+        try:
+            return evaluate(root, run.app.bundle_id, self.wanted, wav, why=self._why)
+        finally:
+            if self._dir:
+                import shutil
+
+                shutil.rmtree(self._dir, ignore_errors=True)
+
+
+def main(argv=None):
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="python -m mobile_agent.verify.sound", description="record and list sound fingerprints"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    record = sub.add_parser("record", help="fingerprint a short WAV of one sound")
+    record.add_argument("--bundle", required=True)
+    record.add_argument("--name", required=True)
+    record.add_argument("--wav", required=True)
+    record.add_argument("--root", default=".")
+    ls = sub.add_parser("list", help="list the recorded sounds of an app")
+    ls.add_argument("--bundle", required=True)
+    ls.add_argument("--root", default=".")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "record":
+            print(f"wrote {save(args.root, args.bundle, args.name, args.wav)}")
+        else:
+            print("\n".join(names(args.root, args.bundle)))
+    except SoundError as error:
+        print(error)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())