puntorigen Sound Effects Generator
Generate production-ready sound effects for mobile and web apps using Stable Audio 2.5 on Replicate.
Setup
Install dependencies (one-time):
pip3 install -r ~/.cursor/skills/sound-effects/scripts/requirements.txt
Set your Replicate API token (one-time — skipped if already configured by another skill):
python3 ~/.cursor/skills/sound-effects/scripts/setup_key.py YOUR_REPLICATE_API_TOKEN
Quick Reference
Generate a sound effect
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "button click" \
--category ui --duration 1 --output click.mp3
Generate with enhanced prompt (default)
The script automatically enhances your description into an optimal prompt for the model. Use --raw-prompt to skip enhancement:
# Enhanced (default): "button click" becomes a detailed audio-engineering prompt
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "button click" -c ui -d 1 -o click.mp3
# Raw: use your prompt verbatim
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "soft digital click, clean, minimal, 44.1kHz" \
--raw-prompt -d 1 -o click.mp3
Batch generate multiple effects
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "success chime" \
--category notification --duration 2 --variations 3 --output success.mp3
# Generates: success_1.mp3, success_2.mp3, success_3.mp3
generate_sfx.py Options
| Option | Short | Description |
|---|---|---|
--category CAT |
-c |
Sound category preset (see below) |
--duration SECS |
-d |
Duration in seconds (1-90, default: 3) |
--output PATH |
-o |
Output file path (default: auto-named) |
--variations N |
-n |
Number of variations to generate (1-5) |
--seed INT |
Random seed for reproducible results | |
--steps INT |
Diffusion steps (default: 8, higher = better but slower) | |
--cfg-scale FLOAT |
Guidance scale (default: 3.5, higher = stricter prompt adherence) | |
--raw-prompt |
Use prompt as-is, skip enhancement | |
--trim / --no-trim |
Auto-trim leading/trailing silence (default: on) | |
--trim-threshold DB |
Silence detection threshold in dB (default: -35) | |
--fade-out MS |
Fade-out applied after trim in ms (default: 20) | |
--list-categories |
Show all available categories |
Sound Categories
| Category | Best For | Gen Duration | Prompt Style |
|---|---|---|---|
ui |
Clicks, toggles, swipes, taps | 3s | Clean, digital, minimal |
notification |
Alerts, badges, messages | 3s | Tonal, melodic, clear |
success |
Completions, achievements, confirmations | 3s | Positive, bright, resolved |
error |
Failures, warnings, invalid actions | 3s | Discordant, attention-grabbing |
transition |
Screen changes, modals, reveals | 3s | Swoosh, whoosh, smooth |
ambient |
Background loops, atmosphere | 20s | Textural, environmental |
game |
Power-ups, collectibles, impacts | 3s | Dynamic, punchy, satisfying |
voice |
Vocal textures, vocalizations | 3s | Human vocal elements |
nature |
Rain, wind, birds, water | 15s | Organic, environmental |
mechanical |
Motors, gears, machinery | 3s | Industrial, metallic |
musical |
Jingles, stingers, intros | 5s | Melodic, composed |
foley |
Footsteps, doors, objects | 3s | Realistic, physical |
generic |
General purpose (default) | 3s | Neutral, versatile |
Gen Duration is the minimum passed to the model (-d flag). Actual file duration will be shorter after auto-trim strips silence.
Categories are defined in scripts/categories.json and can be customized or extended.
Common Workflows
Generate a UI sound set for a mobile app
# Button tap (3s gen → auto-trimmed to ~150ms)
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "button tap" \
-c ui -o sounds/tap.mp3
# Toggle switch
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "toggle switch on" \
-c ui -o sounds/toggle_on.mp3
# Back swipe
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "swipe back gesture" \
-c transition -o sounds/swipe_back.mp3
Generate notification sounds
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "new message received" \
-c notification -d 2 -o sounds/message.mp3
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "task completed successfully" \
-c success -d 2 -o sounds/complete.mp3
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "error occurred" \
-c error -d 1 -o sounds/error.mp3
Generate ambient loops
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "calm office background" \
-c ambient -d 30 -o sounds/office_ambient.mp3
Reproducible results with seed
# Same seed = same output
python3 ~/.cursor/skills/sound-effects/scripts/generate_sfx.py "coin collect" \
-c game -d 1 --seed 42 -o coin.mp3
Silence Trimming
The model needs at least 3 seconds of generation time to follow prompts well, but many SFX (clicks, taps, pops) are 60-400ms of actual audio followed by silence. By default, --trim is enabled and automatically:
- Detects where actual audio begins and ends using ffmpeg's
silencedetectfilter - Trims the file to just the active region (with 10ms padding)
- Applies a subtle 20ms fade-out for clean tails
- Overwrites the file in-place
This is especially important for UI micro-interactions where sub-200ms precision matters.
Use --no-trim to disable (useful for ambient loops or music that fills the full duration).
Standalone trimming
The trim tool can also be used independently on any audio file:
# Trim a single file
python3 ~/.cursor/skills/sound-effects/scripts/trim_silence.py input.mp3 --output trimmed.mp3
# Trim in-place
python3 ~/.cursor/skills/sound-effects/scripts/trim_silence.py input.mp3 --in-place
# Tighter threshold for very quiet sounds
python3 ~/.cursor/skills/sound-effects/scripts/trim_silence.py input.mp3 --threshold -40 --in-place
# Add a longer fade-out
python3 ~/.cursor/skills/sound-effects/scripts/trim_silence.py input.mp3 --fade-out 50 -o smooth.mp3
# Batch process a folder
python3 ~/.cursor/skills/sound-effects/scripts/trim_silence.py sounds/*.mp3 --in-place
trim_silence.py Options
| Option | Short | Description |
|---|---|---|
--output PATH |
-o |
Output file or directory |
--threshold DB |
-t |
Silence threshold in dB (default: -35, lower = more aggressive) |
--min-duration SECS |
Min silence segment to detect (default: 0.05) | |
--pad MS |
Padding around active region in ms (default: 10) | |
--fade-out MS |
Fade-out duration in ms (default: 0) | |
--in-place |
Overwrite input files |
Model
This skill uses Stable Audio 2.5 (stability-ai/stable-audio-2.5) on Replicate. Key capabilities:
| Feature | Specification |
|---|---|
| Min Duration | 1 second (3s recommended for quality) |
| Max Duration | 90 seconds |
| Output Format | MP3 |
| Sample Rate | 44.1 kHz |
| Diffusion Steps | Configurable (default 8) |
| CFG Scale | Configurable (default 3.5) |
Prompt Enhancement
By default, the script enhances your natural-language description into an audio-engineering prompt optimized for Stable Audio 2.5. The enhancement:
- Adds technical audio descriptors (clean, high-fidelity, 44.1kHz)
- Injects category-specific style keywords (e.g., "digital, minimal, crisp" for UI sounds)
- Adds appropriate mood and texture descriptors
- Keeps the core intent of your description intact
Use --raw-prompt to bypass this and send your exact text to the model.
Note: Stable Audio 2.5 is a synthesis model — great for clean UI/abstract/designed sounds, but real-world foley and nature ambiences can sound synthetic. For maximum realism, prefer a real-recording source (e.g. the audio-theater skill's ElevenLabs or Freesound backends).
Configuration
Config stored at ~/.cursor/skills/sound-effects/config.json:
{
"replicate_api_token": "YOUR_TOKEN",
"default_category": "generic",
"default_duration": 3,
"default_steps": 8,
"default_cfg_scale": 3.5
}
The skill also checks for an existing Replicate token in ~/.cursor/skills/avatar-video-reel/config.json as a fallback, so you may not need to configure it again if you already use that skill.