← All docs

Freesound curate

Download a Freesound sound by ID, trim silence at the boundaries, LUFS-normalise to -20, equal-power-loop, encode WebM + m4a, append attribution. The Freesound API search is a separate step (run the search interactively or via the Notion search MCP tool — there’s no UI page for it yet).

Curate vs generate

From CLAUDE.md:

Curate from Freesound when:

  • The sound is organic / irreplicable with synthesis: animal vocalisations (purrs, bird calls, owl hoots), human sounds (breath, heartbeat that needs to feel human), field recordings (rain-on-this-specific-surface, a particular waterfall, crackling campfire), instruments with complex resonance (singing bowls, gongs, wind chimes, bells).
  • A listener would say “that’s a real X” vs “that’s a synth trying to be X.” If the answer is obviously the latter with DSP, curate.

Generate with DSP when:

  • The sound IS synthetic by nature: binaural beats, isochronic pulses, noise colours, solfeggio tones, synth pads, drones.
license:"Creative Commons 0"
duration:[30.0 TO 600.0]
rating: ≥ 4.5

CC0 first; CC-BY second (but harder to clear if we expand). Look for clean descriptions and recent uploads (less metadata-decay).

Parameters

  • sound_id — numeric Freesound ID from the URL
  • track_id — the catalog id this will install as
  • category — calming | frequencies | neurodivergent | noises | nature
  • offset_sec — trim from start (useful for intro silence)
  • target_sec — truncate to this length (0 = use full source duration)
  • target_lufs (-20) — loudness target

What happens on disk

  1. Downloads the HD preview (128 kbps MP3) via the Freesound API
  2. Decodes to WAV
  3. Trims silence at both boundaries (threshold -45 dB)
  4. LUFS-normalises to target
  5. Equal-power-loop crossfade
  6. Encodes apps/web/public/audio/<category>/<track_id>.{webm,m4a}
  7. Appends entry to content/metadata/attributions.json
  8. Saves source FLAC under tools/curate/sources/<track_id>.flac

After this, you still need to:

  • Add the catalog entry to tools/generate/catalog.py
  • Add the track_id to CURATED_OVERRIDES in the relevant tools/generate/<category>/build.py
  • Regenerate python3 tools/generate/catalog.py etc.

Runtime + cost

~20s per track. Free (Freesound API is free for read).

The API key lives at tools/curate/.freesound-api-key (gitignored).