spank

# spank **English** | [简体中文][readme-zh-link] Slap your MacBook, it yells back. > "this is the most amazing thing i've ever seen" — [@kenwheeler](https://x.com/kenwheeler) > "I just ran sexy mode with my wife sitting next to me...We died laughing" — [@duncanthedev](https://x.com/duncanthedev) > "peak engineering" — [@tylertaewook](https://x.com/tylertaewook) Uses the Apple Silicon accelerometer (Bosch BMI286 IMU via IOKit HID) to detect physical hits on your laptop and plays audio responses. Single binary, no dependencies. ## Requirements - macOS on Apple Silicon (any M-series chip M2 or greater, or the M1 Pro SKU specifically, no other M1/A-series chips!) - `sudo` (for IOKit HID accelerometer access) - Go 1.26+ (if building from source) ## Install Download from the [latest release](https://github.com/taigrr/spank/releases/latest). Or build from source: ```bash go install github.com/taigrr/spank@latest ``` > **Note:** `go install` places the binary in `$GOBIN` (if set) or `$(go env GOPATH)/bin` (which defaults to `~/go/bin`). Copy it to a system path so `sudo spank` works. For example, with the default Go settings: > > ```bash > sudo cp "$(go env GOPATH)/bin/spank" /usr/local/bin/spank > ``` ## Usage ``` … ``` ### Modes **Pain mode** (default): Randomly plays from 10 pain/protest audio clips when a slap is detected. **Sexy mode** (`--sexy`): Tracks slaps within a rolling 5-minute window. The more you slap, the more intense the audio response. 60 levels of escalation. **Halo mode** (`--halo`): Randomly plays from death sound effects from the Halo video game series when a slap is detected. **Custom mode** (`--custom`): Randomly plays MP3 files from a custom directory you specify. ### Detection tuning Use `--fast` for a more responsive profile with faster polling (4ms vs 10ms), shorter cooldown (350ms vs 750ms), higher sensitivity (0.18 vs 0.05 threshold), and larger sample batch (320 vs 200). You can still override individual values with `--min-amplitude` and `--cooldown` when needed. ### Sensitivity Control detection sensitivity with `--min-amplitude` (default: `0.05`): - Lower values (e.g., 0.05-0.10): Very sensitive, detects light taps - Medium values (e.g., 0.15-0.30): Balanced sensitivity - Higher values (e.g., 0.30-0.50): Only strong impacts trigger sounds The value represents the minimum acceleration amplitude (in g-force) required to trigger a sound. ## Running as a Service To have spank start automatically at boot, create a launchd plist. Pick your mode: Pain mode (default) ``` … ``` Sexy mode ``` … ``` Halo mode ``` … ``` > **Note:** Update the path to `spank` if you installed it elsewhere (e.g. `~/go/bin/spank`). Load and start the service: ```bash sudo launchctl load /Library/LaunchDaemons/com.taigrr.spank.plist ``` Since the plist lives in `/Library/LaunchDaemons` and no `UserName` key is set, launchd runs it as root — no `sudo` needed. To stop or unload: ```bash sudo launchctl unload /Library/LaunchDaemons/com.taigrr.spank.plist ``` ## How it works 1. Reads raw accelerometer data directly via IOKit HID (Apple SPU sensor) 2. Runs vibration detection (STA/LTA, CUSUM, kurtosis, peak/MAD) 3. When a significant impact is detected, plays an embedded MP3 response 4. **Optional volume scaling** (`--volume-scaling`) — light taps play quietly, hard slaps play at full volume 5. **Optional speed control** (`--speed`) — adjusts playback speed and pitch (0.5 = half speed, 2.0 = double speed) 6. 750ms cooldown between responses to prevent rapid-fire, adjustable with `--cooldown` ## Star History ## Credits Sensor reading and vibration detection ported from [olvvier/apple-silicon-accelerometer](https://github.com/olvvier/apple-silicon-accelerometer). ## License MIT [readme-zh-link]: ./README-zh.md