pretendrop

A Pretentious Backdrop for videos, based on Butterchurn.

Pretendrop is a silent, fullscreen music-reactive visual system for a second display, a projector, or the wall behind a set. It decodes a random track from your own library to drive the visuals, then routes the audio through a gain of zero. The screen gets the motion; the room stays quiet.

It ships with the Butterchurn preset collection, fast preset transitions, favorites, and three deliberately different shuffle engines.

Start it

Pretendrop requires Node.js 22.12 or newer.

cd ~/src/pretendrop
npm ci
npm run electron:binary
npm run build
npm run start

Dependencies are pinned to exact versions and .npmrc disables install scripts, so npm ci does not download Electron by itself. npm run electron:binary runs Electron's own installer on purpose: it fetches the pinned release and checks it against the checksums shipped in the package.

For live UI development, run these in separate terminals:

npm run dev
npm run dev:desktop

The regular app opens fullscreen in kiosk mode. Move the pointer to reveal its controls. Press F to leave or return to kiosk mode, and Ctrl+Q to quit.

Everyday controls

Key	Action
Space	Pause or resume the reactive track
N	Pick another random track
← / →	Change preset
H	Love or unlove the current preset
Z	Undo the favorite you just removed
B	Blackout the screen
O	Open the curation panel
F	Toggle fullscreen kiosk mode
Ctrl+Q	Quit

Space, the arrows and Enter belong to whatever control has keyboard focus, so tabbing through the transport and pressing space activates the button you are on rather than pausing playback.

The heart updates immediately and the status line confirms that it was saved. Favorite names wrap to as many lines as they need; they are never abbreviated.

Audio sources and privacy

The audio source control supports local library tracks and microphones on Linux and macOS. Microphone audio goes directly to Butterchurn through Web Audio: it is not recorded, written to disk, sent over the network, or connected to the speakers. The selected source and microphone are saved with the other preferences. When a live source is selected, the settings panel shows the raw RMS level received by Electron in dB plus a peak marker, so silence and routing problems are visible before the signal reaches the visual intensity control.

On Linux, Pretendrop can also react to the system output. This installation is tuned for PulseAudio on PipeWire: it finds the monitor belonging to the current default sink and uses pactl to move only Pretendrop's recording stream to that monitor. It does not change the global default input or reroute another app. The system-audio option is disabled with a diagnostic message when pactl, the default sink, or its monitor is unavailable.

On macOS, the packaged app declares why it needs microphone access. The system permission prompt appears the first time a microphone is selected. System-audio capture is intentionally not offered on macOS.

On Linux, the first scan starts at ~/Music. Choose any library from the console whenever you want. Pretendrop reads embedded title, artist, and album tags only for the selected track; it does not send library data anywhere.

No personal media path is embedded in the source or build. The music index is held in memory for the running session and audio output remains muted.

Favorites and settings

On Linux, preferences are written in the standard XDG location:

$XDG_CONFIG_HOME/pretendrop/preferences.json
# or ~/.config/pretendrop/preferences.json when XDG_CONFIG_HOME is unset

The file is plain JSON and is created automatically on first run. Existing Butter preferences are migrated once if they are found, without deleting the old file. Set PRETENDROP_PREFERENCES_FILE to use an explicit JSON path.

When ~/dot exists, npm run install:linux keeps the plain JSON in your private dotfiles source and exposes it at the standard XDG path:

~/.config/pretendrop/preferences.json
  -> ~/dot/stow/common/.config/pretendrop/preferences.json

Pretendrop resolves that link before its atomic save, so it never replaces the link itself. This keeps personal preference data in the private dotfiles repo, not in the Pretendrop source repository. The macOS build uses the platform app-data directory instead of an XDG path.

Shuffle

Choose all presets or favorites, then choose an engine:

• Entropy uses cryptographic randomness and avoids recent repeats.
• Deck deals a complete random permutation before repeating a preset.
• Explorer favors presets seen least during the current session.

The seconds field controls automatic preset changes. Set it to 0 for manual changes only.

Scene controls

The control panel also gives the visual system a small, practical set of live parameters:

• Intensity changes the audio level fed to Butterchurn without changing the muted speaker output.
• Transition sets the preset crossfade duration.
• Vignette sets the edge darkness from 0 to 100 percent.

Those three are sliders and apply while you drag, so you set them by watching the screen rather than by typing a number and tabbing away.

• Quality selects eco, normal, or full renderer budgets.
• Lock preset stops automatic preset changes while tracks keep rotating.
• Track interval selects a silent random track every N minutes; 0 keeps the natural end-of-track behavior.
• Interface can auto-hide, stay visible, or remain hidden.
• New chaos resets session shuffle history; blackout hides the canvas and the interface without closing Pretendrop, and stops rendering while it is on. Press B for blackout from the keyboard.
• Restore defaults puts every scene parameter back where it started.

Interface text is drawn with its own dark halo, so it stays readable over a bright preset even with the vignette at 0.

Install and build

Linux and Rofi

npm run install:linux
rofi -show drun

The installer builds the UI, writes an XDG desktop entry named Pretendrop, and replaces the previous Butter launcher if it exists. It does not require a system-wide install.

To make distributable Linux artifacts:

npm run dist:linux

This creates an AppImage and a tarball in release/.

macOS

Run this on a Mac:

npm run install:mac

It generates a DMG and ZIP in release/. Mount the DMG and drag Pretendrop.app to Applications. The GitHub Actions workflow builds Linux x64, macOS x64, and macOS arm64 artifacts; public distribution still needs your own Apple signing and notarization credentials.

License

Pretendrop is released under the MIT License. Butterchurn and its preset collection are also MIT-licensed; direct runtime dependency notices are kept in THIRD_PARTY_NOTICES.md and copied into packaged apps.