Skip to main content

​
Quickstart

This guide gets you from installation to your first successful slap detection.
1

Run Spank with default settings

Start Spank in pain mode (the default):
sudo spank
You should see:
spank: listening for slaps in pain mode... (ctrl+c to quit)
Spank requires sudo for IOKit HID access to the accelerometer. This is a hardware requirement.
2

Slap your laptop

Gently slap the palm rest or keyboard area of your MacBook. You should hear an audio response (“ow!”) and see console output:
slap #1 [medium amp=0.45231g] -> audio/pain/ow-03.mp3
The output shows:
  • Slap number (sequential counter)
  • Severity classification (light/medium/hard)
  • Amplitude in g-force
  • Audio file played
Start with gentle taps. The default threshold is 0.3g. If nothing happens, try slightly harder slaps or adjust sensitivity (next step).
3

Adjust sensitivity (optional)

If detection is too sensitive or not sensitive enough, use the --min-amplitude flag:
# More sensitive (detects lighter taps)
sudo spank --min-amplitude 0.1

# Less sensitive (requires harder hits)
sudo spank --min-amplitude 0.5
The value represents minimum acceleration amplitude in g-force (0.0-1.0). From main.go:200:
cmd.Flags().Float64Var(&minAmplitude, "min-amplitude", 0.3, 
    "Minimum amplitude threshold (0.0-1.0, lower = more sensitive)")
Recommended ranges:
  • Very sensitive (light taps): 0.05-0.10
  • Balanced: 0.15-0.30 (default: 0.3)
  • Only strong impacts: 0.30-0.50
4

Try different modes

Spank has multiple audio modes. Stop the current session (Ctrl+C) and try:
sudo spank
Pain mode: Randomly plays from 10 pain/protest audio clips.Sexy mode: Tracks slaps within a rolling window. The more you slap, the more intense the audio. Uses exponential decay with a 30-second half-life (main.go:66) to create 60 levels of escalation.Halo mode: Randomly plays death sounds from Halo video games.Custom mode: Randomly plays your own MP3 files from a specified directory.
Modes are mutually exclusive. You can only use one at a time.

​
Understanding the output

When a slap is detected, you’ll see output like: 
slap #3 [hard amp=0.67234g] -> audio/pain/ow-07.mp3
Breakdown:
  • slap #3: Third slap since Spank started (from main.go:343)
  • [hard amp=0.67234g]: Severity and amplitude in g-force
  • audio/pain/ow-07.mp3: Audio file played

​
How detection works

Spank processes accelerometer data continuously:
  1. Sensor polling: Reads accelerometer at 100Hz (every 10ms) from main.go:72: 
    sensorPollInterval = 10 * time.Millisecond
  2. Batch processing: Processes up to 200 samples per tick (main.go:76): 
    maxSampleBatch = 200
  3. Event detection: Uses vibration detection algorithms (STA/LTA, CUSUM, kurtosis, peak/MAD) to identify impacts
  4. Threshold filtering: Only triggers if amplitude >= min-amplitude (main.go:336-338): 
    if ev.Amplitude < minAmplitude {
    continue
}
  5. Cooldown: 750ms minimum between audio playback (main.go:69): 
    slapCooldown = 750 * time.Millisecond

​
Common workflows

​
Run Spank continuously

To keep Spank running in the background: 
# Run in background
sudo spank &

# Or use nohup to persist after terminal closes
nohup sudo spank > /tmp/spank.log 2>&1 &

​
Combine sensitivity with modes

You can adjust sensitivity for any mode: 
# Sexy mode with higher sensitivity
sudo spank --sexy --min-amplitude 0.2

# Halo mode requiring harder impacts
sudo spank --halo --min-amplitude 0.4

​
Stop Spank

Press Ctrl+C in the terminal, or if running in background: 
# Find the process
ps aux | grep spank

# Kill it
sudo kill <PID>

​
Next steps

Run as a service

Set up Spank to start automatically at boot using launchd

Advanced configuration

Explore custom audio directories and fine-tune detection parameters

​
Troubleshooting

  • Verify you’re running with sudo
  • Lower the threshold: sudo spank --min-amplitude 0.1
  • Try slapping harder or on different parts of the laptop
  • Check that your chip is M2+ (M1 not supported)
  • Raise the threshold: sudo spank --min-amplitude 0.4
  • Ensure your laptop is on a stable surface
  • The default cooldown (750ms) prevents most false triggers
  • Check system audio volume
  • Verify audio output device is not muted
  • Test with a different mode (e.g., --halo)
  • Check console for error messages about audio decoding
  • Ensure you have sudo: sudo spank
  • Check that no other process is using the accelerometer
  • Verify macOS version compatibility (requires recent macOS on Apple Silicon)

Build docs developers (and LLMs) love

Get started for freeTalk to us