Vellum Sounds

You are helping the user customize the sound effects their desktop app plays. Sounds are configured in two places: a data/sounds/ directory of audio files and a data/sounds/config.json that controls what plays, at what volume, and whether it is enabled. The Settings > Sounds tab reads the same files on macOS and Windows, so changes appear there live without a restart.

All commands in this skill use the bash tool. $VELLUM_WORKSPACE_DIR is available in the sandbox environment — do not use host_bash.

What you're configuring

Two stores, both under $VELLUM_WORKSPACE_DIR/data/sounds/:

• Sound files: .aiff, .wav, .mp3, .m4a, or .caf. No other extensions are accepted. The app scans this directory to populate the dropdown for each event. Prefer .wav, .mp3, or .m4a when the same file must play on both macOS and Windows.
• config.json: a single JSON file that stores the global on/off switch, the master volume, and a per-event map of { enabled, sounds }. Each event's sounds is a pool of filenames; the app picks one at random on playback. An empty pool falls back to the platform's default blip.

Sound events

macOS supports all nine events below. Windows supports the eight events other than app_open. Do not configure app_open on Windows because it is not displayed or played there. Other keys are ignored by the app.

Mode 1: Inspect current state

Always check current state before making changes — the user may already have things configured.

ls "$VELLUM_WORKSPACE_DIR/data/sounds/" 2>/dev/null || echo "No sounds directory yet"
cat "$VELLUM_WORKSPACE_DIR/data/sounds/config.json" 2>/dev/null || echo "No config yet"

Report back what's there: whether sounds are globally enabled, current volume, which events have custom sounds assigned.

Mode 2: Add a sound file

The user either sends you an audio file or asks you to fetch/generate one. Copy it into data/sounds/ with a clean filename:

mkdir -p "$VELLUM_WORKSPACE_DIR/data/sounds"
cp "<source-path>" "$VELLUM_WORKSPACE_DIR/data/sounds/<descriptive-name>.<ext>"

Rules:

• Extension must be one of: aiff, wav, mp3, m4a, caf. If the user's file is something else (e.g. .ogg, .flac), tell them — don't try to rename.
• Keep the filename simple (no path separators, no leading dots). Spaces are fine.
• After adding a file, it's available in the dropdown — but nothing plays until you assign it to an event (Mode 3).

Mode 3: Configure via the helper script

Use scripts/update-config.ts to edit config.json. It validates inputs, creates the file with defaults if missing, and writes atomically so a crash can't corrupt it. If the existing file uses the legacy single-sound shape ("sound": "foo.wav"), the script normalizes it to the new pool shape ("sounds": ["foo.wav"]) on the next write.

bun run scripts/update-config.ts --global-enabled true
bun run scripts/update-config.ts --volume 0.5
bun run scripts/update-config.ts --event message_sent --enabled true --sound "gentle-ding.aiff"
bun run scripts/update-config.ts --event random --enabled false
bun run scripts/update-config.ts --event task_complete --sound null   # clear the pool, revert to default blip

Mode 3a: Sound pools

Each event can hold one or more sounds. When the event fires, the app picks one entry at random from the pool. This is how you build variety, such as three different "poke" sounds that rotate when the user clicks the avatar. An empty pool falls back to the platform's default blip.

# Replace the pool with three sounds
bun run scripts/update-config.ts --event character_poke --sounds "poke1.wav,poke2.wav,poke3.wav"

# Append one more sound to the existing pool
bun run scripts/update-config.ts --event character_poke --add-sound "poke4.wav"

# Drop a specific entry
bun run scripts/update-config.ts --event character_poke --remove-sound "poke2.wav"

# Empty the pool (back to the default blip)
bun run scripts/update-config.ts --event character_poke --clear-sounds

--sound is retained as a convenience for the common single-sound case: it replaces the whole pool with one entry (or clears it, when given null). Use --sounds / --add-sound / --remove-sound / --clear-sounds for pool edits.

Only one pool-mutation flag is allowed per invocation — mixing --sound and --add-sound (or any other pair) is rejected with a clear error. The one exception is --add-sound, which may be passed multiple times to append several filenames in a single run.

Flag reference:

The script prints the resulting config slice so you can confirm what changed.