spank Documentation

Slap your MacBook, it yells back. Uses Apple Silicon accelerometer via IOKit HID.

4,628 stars Go Go 1 file · ~2,832 tokens #accelerometer#apple-silicon#fun#go#iokit#macos
RAW Doc

File: README.md

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

  • 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.

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

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

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

bash
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">

<dict>
    <key>Label</key>
    <string>com.taigrr.spank</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/spank</string>
    </array>
    <key>RunAtLoad</key>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

Sexy mode

bash
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">

<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>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

Halo mode

bash
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">

<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>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

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.

License

MIT

File: README-zh.md

spank

English | 简体中文

拍打你的 MacBook，它会回应你。

"这是我见过的最神奇的东西" — @kenwheeler

"我刚才在妻子旁边运行了性感模式...笑死我们了" — @duncanthedev

"巅峰工程" — @tylertaewook

使用 Apple Silicon 芯片的加速度传感器，检测笔记本电脑的物理撞击并播放音频回应。单个二进制文件，无依赖。

系统要求

  • 基于 Apple Silicon 的 macOS（任何 M2 及以上型号的 M 系列芯片，或特定的 M1 Pro 型号，不包括其他 M1/A 系列芯片！）
  • sudo（用于访问加速度传感器）
  • Go 1.26+（如果从源代码构建）

安装

从最新版本下载。

或者从源代码构建：

bash
go install github.com/taigrr/spank@latest

注意： go install 会将二进制文件放在 $GOBIN（如果已设置）或 $(go env GOPATH)/bin（默认为 ~/go/bin）。将其复制到系统路径以便 sudo spank 能够工作。例如，使用默认的 Go 设置：

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

使用方法

bash
# 普通模式 — 拍打时说"ow!"
sudo spank

# 性感模式 — 根据拍打频率升级回应
sudo spank --sexy

# 光环模式 — 拍打时播放光环死亡音效
sudo spank --halo

# 快速模式 — 更快的轮询和更短的冷却时间
sudo spank --fast
sudo spank --sexy --fast

# 自定义模式 — 从指定目录播放你自己的 MP3 文件
sudo spank --custom /path/to/mp3s

# 使用振幅阈值调整灵敏度（数值越低越敏感）
sudo spank --min-amplitude 0.1   # 更敏感
sudo spank --min-amplitude 0.25  # 不太敏感
sudo spank --sexy --min-amplitude 0.2

# 设置冷却时间（毫秒，默认：750）
sudo spank --cooldown 600

# 设置播放速度倍数（默认：1.0）
sudo spank --speed 0.7   # 更慢更深沉
sudo spank --speed 1.5   # 更快
sudo spank --sexy --speed 0.6

模式

疼痛模式（默认）：检测到拍打时随机播放 10 个疼痛的音频片段之一。

性感模式（--sexy）：监听在 5 分钟滚动窗口内的拍打次数。拍打越多，音频回应越强烈。60 个升级级别。

光环模式（--halo）：检测到拍打时随机播放光环视频游戏系列的死亡音效。

自定义模式（--custom）：从你指定的自定义目录中随机播放 MP3 文件。

检测调优

使用 --fast 获得更响应的配置，具有更快的轮询（4ms vs 10ms）、更短的冷却时间（350ms vs 750ms）、更高的灵敏度（0.18 vs 0.05 阈值）和更大的样本批次（320 vs 200）。

需要时，你仍然可以使用 --min-amplitude 和 --cooldown 覆盖单个值。

灵敏度

使用 --min-amplitude 控制检测灵敏度（默认：0.05）：

  • 较低值（例如 0.05-0.10）：非常敏感，检测轻拍
  • 中等值（例如 0.15-0.30）：平衡的灵敏度
  • 较高值（例如 0.30-0.50）：只有强烈的撞击才会触发声音

该值表示触发声音所需的最小加速度幅度（以 g 为单位）。

作为服务运行

要让 spank 在启动时自动运行，请创建一个系统守护进程配置文件。选择运行模式，如下：

疼痛模式（默认）

bash
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">

<dict>
    <key>Label</key>
    <string>com.taigrr.spank</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/spank</string>
    </array>
    <key>RunAtLoad</key>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

性感模式

bash
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">

<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>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

光环模式

bash
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">

<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>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/tmp/spank.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/spank.err</string>
</dict>

EOF

注意： 如果你将 spank 安装在其他位置（例如 ~/go/bin/spank），请更新 spank 的路径。

加载并启动服务：

bash
sudo launchctl load /Library/LaunchDaemons/com.taigrr.spank.plist

由于 plist 文件位于 /Library/LaunchDaemons 且未设置 UserName ，launchctl 命令会以 root 身份运行它， 所以不需要加 sudo。

要停止或卸载：

bash
sudo launchctl unload /Library/LaunchDaemons/com.taigrr.spank.plist

工作原理

  1. 通过 Apple Silicon 芯片的加速度传感器直接读取原始加速度传感器数据
  2. 运行振动检测（瞬态/长时瞬态、累积偏差、峰度、峰值/平均绝对偏差）
  3. 当检测到显著撞击时，播放嵌入的 MP3 回应
  4. 可选音量缩放（--volume-scaling）— 轻拍时安静播放，重拍时以全音量播放
  5. 可选速度控制（--speed）— 调整播放速度和音调（0.5 = 半速，2.0 = 2倍速）
  6. 有 750ms 响应冷却时间以防止快速连续播放，可通过 --cooldown 调整

Star History

致谢

传感器读取和振动检测来源于 olvvier/apple-silicon-accelerometer。

许可证

MIT

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#accelerometer Browse accelerometer catalog → #apple-silicon Browse apple-silicon catalog → #fun Browse fun catalog → #go Browse go catalog → #iokit Browse iokit catalog → #macos Browse macos catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →