spank README

The project's README from github.com/taigrr/spank. As one markdown file: README.md.

spank logo

spank

English | 简体中文

Slap your MacBook, it yells back.

"this is the most amazing thing i've ever seen" — @kenwheeler

"I just ran sexy mode with my wife sitting next to me...We died laughing" — @duncanthedev

"peak engineering" — @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

Install

Download from the latest release.

Or build from source:

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:

sudo cp "$(go env GOPATH)/bin/spank" /usr/local/bin/spank

Usage

# Normal mode — says "ow!" when slapped
sudo spank

# Sexy mode — escalating responses based on slap frequency
sudo spank --sexy

# Halo mode — plays Halo death sounds when slapped
sudo spank --halo

# Fast mode — faster polling and shorter cooldown
sudo spank --fast
sudo spank --sexy --fast

# Custom mode — plays your own MP3 files from a directory
sudo spank --custom /path/to/mp3s

# Adjust sensitivity with amplitude threshold (lower = more sensitive)
sudo spank --min-amplitude 0.1   # more sensitive
sudo spank --min-amplitude 0.25  # less sensitive
sudo spank --sexy --min-amplitude 0.2

# Set cooldown period in millisecond (default: 750)
sudo spank --cooldown 600

# Set playback speed multiplier (default: 1.0)
sudo spank --speed 0.7   # slower and deeper
sudo spank --speed 1.5   # faster
sudo spank --sexy --speed 0.6

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):

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) 
sudo tee /Library/LaunchDaemons/com.taigrr.spank.plist > /dev/null << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.taigrr.spank</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/spank</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>
</plist>
EOF
Sexy mode 
sudo tee /Library/LaunchDaemons/com.taigrr.spank.plist > /dev/null << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.taigrr.spank</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/spank</string>
        <string>--sexy</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>
</plist>
EOF
Halo mode 
sudo tee /Library/LaunchDaemons/com.taigrr.spank.plist > /dev/null << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.taigrr.spank</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/spank</string>
        <string>--halo</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>
</plist>
EOF

Note: Update the path to spank if you installed it elsewhere (e.g. ~/go/bin/spank).

Load and start the service:

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:

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

Star History Chart

Credits

Sensor reading and vibration detection ported from olvvier/apple-silicon-accelerometer.

License

MIT

spank (taigrr/spank)

Searching Database…

5K ·GitHub
Spank
What is this?Spank is a joke CLI tool that uses your MacBook's Apple Silicon accelerometer to detect physical slaps on the laptop and plays funny audio responses (pain sounds, escalating 'sexy mode' moans, Halo death sounds, or your own MP3s).
Is this a background daemon or something I run manually?It is a single Go binary you run from the terminal with sudo, and it can optionally be installed as a launchd service to start automatically at boot.
How do I install and run it?Download the binary from the latest GitHub release, or build from source with `go install` and copy the resulting binary to a path on your system; then run it with sudo (e.g. `sudo spank`).
What do I need to run this?You need macOS running on Apple Silicon, sudo access for IOKit HID accelerometer permissions, and Go 1.26+ only if you're building from source.
Does it work on any Mac?No — it only works on M2-or-later chips or the specific M1 Pro SKU; other M1/A-series chips are not supported, and it needs sudo for raw accelerometer access via IOKit.
Does it run on Intel Macs too?No, it's exclusively for Apple Silicon Macs (M-series chips), not Intel Macs.
What modes does spank support?Pain mode (default, plays random protest sounds), Sexy mode (escalates through 60 levels based on slap frequency over 5 minutes), Halo mode (plays Halo death sound effects), and Custom mode (plays your own MP3s from a directory).
How does it detect a slap versus normal vibration?It reads raw accelerometer data via IOKit HID and runs vibration detection algorithms (STA/LTA, CUSUM, kurtosis, peak/MAD) to identify significant impacts, with tunable sensitivity via --min-amplitude.
Can I tune how sensitive or responsive it is?Yes — --fast switches to faster polling, shorter cooldown, and higher sensitivity, while --min-amplitude and --cooldown let you fine-tune detection thresholds and the delay between triggered sounds.
Can audio react to how hard I hit it?Yes — the optional --volume-scaling flag makes light taps play quietly and hard slaps play at full volume, and --speed adjusts playback speed and pitch.
What are similar projects?greenbubbles, TurboBench, hub, fx, spotify-tui, whatcable, git-blame-someone-else, fzf
Which topics is it in?fun, hardware, apple-silicon, cli-tool, audio, command-line, go, command-line-tool, terminal, cli, developer-tools, mit
Creator
taigrr
Size
1.3 MB
Stars
5K
Updated
CommitAug 23Releasev1.3.0Jul 03
Age
7mo
Commits · 90 Days