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
Что это такое?Spank — шуточная консольная утилита, которая с помощью акселерометра MacBook на Apple Silicon определяет шлепки по ноутбуку и проигрывает смешные звуковые реакции: звуки боли, нарастающие стоны в режиме Sexy, звуки смерти из Halo или ваши собственные MP3-файлы.
Это фоновый демон или то, что я запускаю вручную?Это один бинарный файл Go, который вы запускаете из терминала с sudo. При желании его можно установить как службу launchd, чтобы он стартовал автоматически при загрузке системы.
Как установить и запустить?Скачайте бинарный файл из последнего релиза на GitHub или соберите его из исходников командой `go install`, затем скопируйте полученный файл в нужный путь в системе. Запустите его с sudo (например, `sudo spank`).
Что нужно для запуска?Нужны macOS на Apple Silicon, доступ sudo для разрешений на акселерометр IOKit HID и Go 1.26+, но только если вы собираете из исходников.
Работает ли это на любом Mac?Нет. Работает только на чипах M2 и новее или на конкретной модификации M1 Pro. Другие чипы M1 и A-серии не поддерживаются, а для прямого доступа к акселерометру через IOKit нужен sudo.
Работает ли это и на Mac с Intel?Нет, это только для Mac на Apple Silicon (чипы серии M), а не для Mac с Intel.
Какие режимы поддерживает spank?Режим боли (по умолчанию, проигрывает случайные звуки протеста), режим Sexy (нарастает через 60 уровней в зависимости от частоты шлепков за 5 минут), режим Halo (проигрывает звуковые эффекты смерти из Halo) и пользовательский режим (проигрывает ваши MP3-файлы из папки).
Как spank отличает шлепок от обычной вибрации?Он читает сырые данные акселерометра через IOKit HID и применяет алгоритмы обнаружения вибраций (STA/LTA, CUSUM, эксцесс (kurtosis), peak/MAD), чтобы выявить заметные удары. Чувствительность настраивается через --min-amplitude.
Можно ли настроить чувствительность и скорость реакции?Да. Флаг --fast включает более частый опрос, более короткую паузу и повышенную чувствительность, а --min-amplitude и --cooldown позволяют тонко настроить пороги обнаружения и задержку между звуками.
Может ли звук реагировать на силу моего удара?Да. Необязательный флаг --volume-scaling делает слабые касания тихими, а сильные шлепки проигрывает на полной громкости. Флаг --speed меняет скорость воспроизведения и высоту тона.
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