Copyright 2016 Ico Doornekamp
Fork with additional features: custom sound pack support (MechVibes-compatible), press-only mode, OGG segment extraction, and sound pack loading.
This project emulates the sound of my old faithful IBM Model-M space saver bucklespring keyboard while typing on my notebook, mainly for the purpose of annoying the hell out of my coworkers.
Bucklespring runs as a background process and plays back the sound of each key pressed and released on your keyboard, just as if you were using an IBM Model-M. The sound of each key has carefully been sampled, and is played back while simulating the proper distance and direction for a realistic 3D sound palette of pure nostalgic bliss.
To temporarily silence bucklespring, for example to enter secrets, press
ScrollLock twice (but be aware that those ScrollLock events are delivered to
the application); same to unmute. The keycode for muting can be changed with
the -m option. Use keycode 0 to disable the mute function.
Bucklespring is available in the latest Debian and Ubuntu dev-releases, so you can install with
$ sudo apt-get install bucklespring
Bucklespring is available in the VoidLinux repositories, so you can install with
$ sudo xbps-install -S bucklespring
Bucklespring can be installed via package:
$ pkg install bucklespring
or built via port:
$ cd /usr/ports/games/bucklespring
$ make install clean
To compile on debian-based linux distributions, first make sure the require
libraries and header files are installed, then simply run make:
$ sudo apt-get install libopenal-dev libalure-dev libxtst-dev pkg-config
$ sudo pacman -S openal alure libxtst
$ sudo dnf install gcc openal-soft-devel alure-devel libX11-devel libXtst-devel
$ make
$ ./buckle
The default Linux build requires X11 for grabbing events. If you want to use Bucklespring on the linux console or Wayland display server, you can configure buckle to read events from the raw input devices in /dev/input. This will require special permissions for buckle to open the devices, though. Build with
$ make libinput=1
$ sudo snap install bucklespring
$ bucklespring.buckle
The snap includes the OpenAL configuration tweaks mentioned in this README. See http://snapcraft.io/ for more info about Snap packages
I've heard rumours that bucklespring also runs on MacOS. I've been told that the following should do:
$ brew install alure pkg-config
$ git clone https://github.com/zevv/bucklespring.git && cd bucklespring
$ sed -i '' 's/-Wall -Werror/-Wall/' Makefile
$ make
$ ./buckle
Note that you need superuser privileges to create the event tap on Mac OS X. Also give your terminal Accessibility rights: system preferences -> security -> privacy -> accessibility
If you want to use buckle while doing normal work, add an & behind the command.
$ sudo ./buckle &
The program has been compiled, but it has not yet received Microsoft's security certificate. Therefore, it may be detected as a virus by some antivirus software. To view reports from some antivirus programs, you can visit link to reports.
For better performance and to resolve some issues, it is recommended to run the program in Administrator mode.
usage: ./buckle [options]
options:
-d, --device=DEVICE use OpenAL audio device DEVICE
-f, --fallback-sound use a fallback sound for unknown keys
-g, --gain=GAIN set playback gain [0..100]
-m, --mute-keycode=CODE use CODE as mute key (default 0x46 for scroll lock)
-M, --mute start the program muted
-c, --no-click don't play a sound on mouse click
-p, --pack=NAME load sound pack NAME from wav directory
-u, --press-only don't play sound on key release (press-only mode)
-h, --help show help
-l, --list-devices list available OpenAL audio devices
-s, --stereo-width=WIDTH set stereo width [0..100]
-v, --verbose increase verbosity / debugging
-w, --wav-dir=DIR set base wav directory (default ./wav)
This fork extends bucklespring with comprehensive MechVibes-compatible sound pack support. You can now use sound packs designed for MechVibes by placing a config.json file in your audio directory.
- MechVibes config.json support - Load packs with JSON configuration
- Two audio modes - Multi-file (individual WAVs) and Single-file (OGG with segments)
- OGG segment extraction - Extract key sounds from a single OGG file using
[start_ms, duration_ms]timing - Sound pack loading - Use
-p/--packto load packs from subdirectories - Random fallback segments - Undefined keys randomly pick from defined segments
- Fallback WAV support -
fallback.wavfor missing keys with-fflag
In this mode, each key has its own audio file. Use key_define_type: "multi" in config.json:
{
"key_define_type": "multi",
"defines": {
"1": "key-1.wav",
"2": "key-2.wav",
"30": "key-a.wav"
}
}In this mode, all key sounds come from a single OGG file using time segments. Use key_define_type: "single":
{
"key_define_type": "single",
"sound": "keyboard.ogg",
"defines": {
"1": [971, 142],
"2": [1276, 115],
"30": [11171, 109]
}
}The segment format [start_ms, duration_ms] specifies where in the OGG file to extract each key's sound.
Create a config.json file in your audio directory:
{
"id": "sound-pack-123",
"name": "My Sound Pack",
"key_define_type": "single",
"sound": "main.ogg",
"defines": {
"1": [971, 142],
"2": [1276, 115],
"30": [11171, 109],
"31": [11462, 120]
}
}| Field | Required | Description |
|---|---|---|
key_define_type |
Yes | "single" for OGG segments, "multi" for individual files |
sound |
Yes (single mode) | Main audio filename (OGG format) |
defines |
Yes | Keycode mappings to filenames or [start_ms, duration_ms] arrays |
Organize sound packs in subdirectories under your audio directory:
wav/
├── oreo/
│ ├── config.json
│ └── oreo.ogg
├── banana1/
│ ├── config.json
│ ├── banana-l-1.wav
│ └── ...
└── my-pack/
└── ...
Load a pack using the -p option:
# Load "oreo" pack from wav/oreo/
./buckle -p oreo
# Load pack with custom audio directory
./buckle -w /path/to/packs -p my-pack
# Verbose mode to see config loading
./buckle -v -p oreoThis feature is designed to work with MechVibes sound packs. Many community-created packs include a config.json file that can be used directly with this fork.
Example MechVibes pack structure:
my-pack/
├── config.json
├── main.ogg
└── ...audio files
If a key has no defined sound, bucklespring will:
- Single-file mode: Randomly pick a segment from another defined key
- Multi-file mode / with -f flag: Use
fallback.wavif it exists - Otherwise: Play nothing
Use the -f flag to enable fallback.wav for missing keys:
./buckle -fbucklespring/
├── buckle # Compiled binary
├── wav/ # Audio files directory
│ ├── config.json # Root config (optional)
│ ├── fallback.wav # Fallback for missing keys
│ ├── *.wav # Individual key sounds
│ ├── pack1/ # Sound pack 1
│ │ ├── config.json
│ │ └── ...
│ └── pack2/ # Sound pack 2
│ ├── config.json
│ └── ...
└── deps/
├── minivorbis.c # OGG decoder
└── json.h # JSON parser
Keycodes use the Linux input subsystem standard. Common codes:
| Code | Key |
|---|---|
| 1 | ESC |
| 2-13 | F1-F12 |
| 14 | Backspace |
| 15 | Tab |
| 16-28 | Q-P |
| 29-42 | A-L |
| 43-53 | Z-M |
| 57 | Space |
| 58 | Caps Lock |
| 59-68 | F1-F10 (alternate) |
The --press-only (-u) option disables audio playback for key release events, playing sounds only when keys are pressed down:
./buckle --press-onlyBucklespring uses the OpenAL library for mixing samples and providing a realistic 3D audio playback. This section contains some tips and tricks for properly tuning OpenAL for bucklespring.
- The default OpenAL settings can cause a slight delay in playback. Edit or create
the OpenAL configuration file
~/.alsoftrcand add the following options:
period_size = 32
periods = 4
- If you are using headphones, enabling the head-related-transfer functions in OpenAL for a better 3D sound:
hrtf = true
- When starting an OpenAL application, the internal sound card is selected for output, and you might not be able to change the device using pavucontrol. The option to select an alternate device is present, but choosing the device has no effect. To solve this, add the following option to the OpenAL configuration file:
allow-moves = true