MacBellows：把 MacBook 屏幕变成手风琴风箱

一个利用 MacBook 屏幕开合角度传感器制作的 Python 创意乐器。

A playful Python instrument powered by the MacBook lid-angle sensor.

MacBellows reads the laptop's lid-angle sensor, turns lid velocity into air pressure, and uses the Mac keyboard as a one-octave chromatic instrument. No audio samples are bundled: the reed-like sound is synthesized at runtime.

Experimental project: the MacBook lid sensor is accessed through an undocumented HID interface. It may not work on every model or future macOS release.

Demo controls

White keys: A=C  S=D  D=E  F=F  G=G  H=A  J=B  K=high C
Black keys: W=C# E=D# T=F# Y=G# U=A#

Hold one or more note keys and gently move the display. Faster movement makes the sound louder. Release the key to stop the note. Press Esc to quit.

Requirements

• A MacBook with an accessible lid-angle sensor
• macOS
• Python 3.9 or newer

The underlying Python library reports testing on Apple Silicon MacBook Pro and macOS Sonoma/Sequoia. Other modern models may work, but are not guaranteed.

Install

Open Terminal and run:

git clone https://github.com/YOUR_USERNAME/MacBellows.git
cd MacBellows
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 macbellows.py

Replace YOUR_USERNAME after creating your GitHub repository.

Test the sensor

After installing the requirements:

pybooklid-demo

If the displayed angle follows the lid, the sensor is working. Stop the demo with Control-C before starting MacBellows.

Troubleshooting

No window appears

Read the Terminal error. Make sure the virtual environment is active and run:

python3 -m pip install -r requirements.txt

Window appears but there is no sound

• Click the MacBellows window so it receives keyboard input.
• Check that macOS is not muted.
• Hold a note while moving the lid; a stationary lid produces no air.

Sensor not found

• Quit other programs that may be reading the sensor.
• Run pybooklid-demo to isolate the problem.
• Your MacBook model may not expose the required HID sensor.

Safety

Move the display gently and within a comfortable angle. Laptop hinges and display cables are not designed for vigorous, repetitive instrument-style motion. Use this project at your own risk.

How it works

1. pybooklid reads the lid angle.
2. MacBellows estimates angular velocity and smooths it into an expression value.
3. Pygame plays click-free looping tones generated from several harmonics.
4. The main loop smooths volume transitions to avoid zipper/static noise.

Practice music

See songs/SONGS.md for keyboard notation.

Acknowledgements

• PyBookLid
• LidAngleSensor, the reverse-engineering work that inspired the Python sensor library

MacBellows does not copy sensor-access code from those projects; it depends on PyBookLid as a separately installed package. Review all dependency licenses before redistributing packaged binaries.

License

MIT

---

中文说明

MacBellows 把 MacBook 屏幕开合动作变成手风琴的“风箱”。按住键盘音符并轻轻推拉 屏幕：移动越快，声音越响；屏幕静止时没有声音。

安装运行

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 macbellows.py

这个项目使用的是未公开的 MacBook HID 角度传感器接口，并非所有机型都支持。 请温和推拉屏幕，不要把转轴当作真正手风琴风箱高强度使用。