# Slap to Talk — design decisions and Phase 0

**Written:** 2026-09-01, against `main` @ `b99f328` (v1.20.1). Design only, no code.

This covers only what you can't get from the repo: external research, the sensor
decision and its reasoning, and the spike that gates everything else. For what Jot
is, the architecture layers, and the ship checklist, read `CLAUDE.md`.

> **Caveat on everything below.** Authored on a Linux box with no Swift toolchain.
> Nothing here has been compiled or run, and line references were accurate at
> `b99f328`. Re-check them.

---

## Status

**Not approved for implementation.** Two owner decisions block it (§6, items 1–2).

**Phase 0 (§4) is the only authorized work.** It's a throwaway standalone CLI that
commits to nothing. Do it, report the data, stop.

---

## 1. What this is

A new *trigger*: double-slap the chassis to start dictation, slap again to stop.
New trigger source against the existing `recorder.toggle()` seam — nothing in the
Recording, Transcription, LLM, or Delivery layers changes.

The gap it fills: every current trigger assumes fingers on home row. The compelling
moments are the ones where your hands aren't.

Origin is an r/SideProject post — "Slap to talk: I've trained my mac to detect
double slap and use it for dictation." That author used the **microphone** plus a
trained classifier. §3 is why we're not doing that.

---

## 2. The finding

Apple Silicon MacBooks (M1–M4) ship a **MEMS accelerometer + gyroscope** driven by
the Sensor Processing Unit, readable over **IOKit HID at up to 800 Hz**. Entirely
undocumented — not in CoreMotion, not in any public framework — but readable.
Reference implementation:

- https://github.com/olvvier/apple-silicon-accelerometer
- https://sesamedisk.com/access-mems-accelerometer-apple-silicon/

Descendant of the Sudden Motion Sensor, which stopped being *exposed* rather than
being removed during the SSD transition.

Two things make it usable here specifically:

1. **Not sandboxed.** `Resources/Jot.entitlements` has
   `com.apple.security.app-sandbox` = `false`; Jot ships Developer ID + notarized
   DMG via Sparkle, not MAS. No sandbox blocking IOKit, no reviewer to reject an
   undocumented interface. Non-starter for a sandboxed app.
2. **IOKit HID is already linked.** `Sources/Permissions/PermissionsService.swift:6`
   imports it for the Input Monitoring capability.

---

## 3. Why accelerometer, not microphone

| | Microphone | Accelerometer |
|---|---|---|
| API status | Public, stable | Undocumented; may break on any macOS release |
| Hardware reach | Every Mac | **MacBooks only** |
| Orange mic indicator | **Permanently lit** | Never |
| Discrimination vs. typing | **Severe problem** | Mild |
| Contends with `AudioCapture` | Yes — AUHAL unit, pinned device | No |
| Breaks if user picks a USB mic | Yes | No |
| Violates the stated non-goal | Directly | Arguably not (§5) |

**The deciding row is typing.** A false trigger isn't cosmetic — the pipeline ends
in synthetic ⌘V at the cursor, so it can inject text into the document someone is
working in. A keystroke *is* a sharp broadband transient, and two keys ~200 ms
apart is ordinary typing cadence. Separating "deliberate slap" from "keystroke" in
audio is the whole difficulty — it's why the Reddit author needed a trained model.

The accelerometer measures the right physical quantity: a palm slap is a large,
low-frequency, whole-chassis impulse; a keypress is small, damped, localized.

**That's a physics argument, not a measurement.** Confirming it is what Phase 0 is
for.

---

## 4. Phase 0 — the spike (current deliverable)

**Pre-check, ten seconds:**

```sh
ioreg -l | grep -i "AppleSPU"
ioreg -r -c IOHIDDevice -l | grep -i -B5 -A5 'accel\|gyro'
```

Nothing enumerates → stop and report; the accelerometer path is dead on this
hardware and the decision reverts to the mic.

**Deliverable:** standalone Swift CLI (~150 lines) that opens the SPU HID device
and dumps timestamped 3-axis readings as CSV. Build it with `swiftc` or a scratch
SPM package — **not** in the Jot Xcode target. Use the §2 reference implementation
for the HID matching dictionary and report parsing; don't reinvent it.

**Three questions:**

1. Does the sensor enumerate on this machine, and does reading it need a TCC grant?
   Note the exact model identifier.
2. Real report rate and payload format — is 800 Hz actually available, what are the
   units, how noisy is the idle baseline?
3. **What do the signals look like?** Labelled traces for: deliberate double slap on
   the chassis · double slap on the desk beside it · ~30 s of normal typing · one
   hard spacebar press · setting a mug down · closing the lid.

**Question 3 decides the feature.** If typing and slapping overlap the way they do
in audio, the DSP-first plan collapses and this becomes an ML project.

**Report back:** the traces, peak deviation magnitude and rise time per gesture
class, model identifier + macOS version + whether any TCC prompt appeared, and your
honest read on whether a threshold state machine can hit zero false positives over
a workday of typing.

**Do not proceed to Phase 1 on your own initiative.**

---

## 5. Blocking: the intent conflict

`docs/design-requirements.md:126` lists "Voice-activity-detection / continuous
listening modes" under Out of Scope, prefaced "should not be reintroduced without a
new intent brief."

The mic path violates it head-on. The accelerometer path arguably doesn't — no
audio is captured — but it still adds a persistent always-on ambient input
modality, which is what the constraint guards. Either way it needs a dated
amendment before implementation. Proposed:

> **Ambient triggers may use non-audio sensors.** Slap-to-talk reads the chassis
> accelerometer. The microphone stays closed until a dictation starts; the "no
> continuous listening" non-goal is specifically about audio and is unchanged.
> *(Decision: 2026-09-01 — a non-audio trigger carries none of the privacy cost the
> original non-goal was written to prevent.)*

**Owner's call. Don't make it.**

---

## 6. Open questions — owner decisions

1. **The §5 amendment** — approve, in which form? **Blocking.**
2. **Is MacBook-only acceptable?** No accelerometer on mini/Studio/iMac. If many
   users are on desktops the calculus shifts back to the mic. **Blocking.**
3. **Toggle or start-only?** Symmetric is memorable, but the stopping slap is the
   highest-risk retrigger. Proposed: toggle, with a refractory period.
4. **Sequencing vs. `features.shortcuts-pane-redesign`** — that item makes *trigger
   type* first-class, and a slap is naturally one. Land it first, or accept rework.
   Don't do them concurrently.
5. **Does this ship at all if the spike says ML is required?** Decide *before* the
   spike so the result doesn't get rationalized.

---

## 7. Design sketch (Phase 1+, for context only)

### Detection — DSP first, not ML

ML is a large fixed cost (training data, a bundled CoreML asset, a retraining
story). Let Phase 0 data decide. Starting parameters, all guesses to be tuned
against real traces:

1. **Baseline:** single-pole IIR estimate of gravity, ~1 s time constant. Work on
   deviation magnitude, so orientation and slow motion are free.
2. **Impulse:** deviation crosses threshold with rise time < ~10 ms, fast decay.
   Rise time is what separates a strike from a shove or a lid close.
3. **Double gate:** two impulses 80–350 ms apart, **no third** within ~250 ms after.
   Lower bound rejects ringing from one strike; the no-third rule kills typing
   drum-rolls.
4. **Refractory:** ~1 s after any trigger. Stops the stopping-slap from restarting.
5. **Adaptive noise floor:** raise threshold in high-motion environments. A fixed
   threshold is unusable off a desk.

**Gating:** suspend when display asleep / locked, lid closed, a dictation or
Rewrite or Transform is in flight, or the feature is off.

### The rule that makes it shippable

`Sources/Overlay/PillViewModel.swift:35-42` — `PillState.savedToRecents(preview:)`
already ships (v1.14): recording stopped without pasting, clickable, opens Recents.

> **A slap-triggered recording that transcribes to empty or near-silent must never
> paste.** It resolves to `savedToRecents`.

Drops the worst-case false positive from "garbage in your document" to "a pill
blinked." **Phase 1, not polish.**

### Files

`TapDetector` must be pure Foundation over a stream of readings — no IOKit, no
clocks, no actors — so Phase 0 traces become golden fixtures.
`SPUAccelerometerSource` is the only platform-coupled file, behind a protocol seam.
`Sources/` is a synchronized folder group, so no `project.pbxproj` edits.

Sensor enumeration failure → disable the feature and post a one-time notice. Never
crash, never spin retrying. Build that in from the start.

### UX

Off by default, behind `ExperimentalBadge`. Settings → Shortcuts. One user-facing
parameter: sensitivity (Light / Medium / Firm). Section **hidden**, not disabled, on
non-MacBook hardware.

Calibration view is non-negotiable — threshold depends on the desk, the feet, and
how hard they hit. Live meter, "slap twice now", ~5 samples → proposed threshold,
and **a false-positive counter running while the user types for 15 seconds**. That
last one is the check that matters and the one nobody would think to run.

No Setup Wizard step.

---

## 8. Phasing

| Phase | Gate |
|---|---|
| **0. Spike** ← you are here | Do the signals separate? |
| **1. Core** — detector + source + `recorder.toggle()`, no UI, DEBUG-only, §7 safety rule | Fires when slapped, silent for a workday of typing? |
| **2. UX** — settings, sensitivity, calibration, Help | Owner review |
| **3. Polish** — adaptive floor, power gating, sensor-absent handling | Ship experimental, off by default |

Phase 1 is the real go/no-go. **Zero false positives over a workday of typing** is
the bar; anything less isn't shippable given the paste path.
