Sound effects

This guide will walk you through the steps to build a sound effect browsing UI, fetch available categories and play/download a sound effect.

Content Access: All partners have access to sound effects, and they are all available to download.

About sound effect metadata: Sound effect responses include basic information (id, title, length, added, images) — there is no BPM, mood, genre or tag data, so client-side filtering of results can only be done using the title or length fields. For complete metadata coverage, see the Metadata guide.

How sound effect titles are structured

Sound effect titles are long — Motors, Combustion, Speed Boat, Highest Speed, Koh Lipe, Thailand rather than something like "Boat Engine" — because they describe the recording instead of naming it. They follow a consistent structure: category, subcategory, then keywords, optionally ending in a variant number. The category and subcategory follow the UCS (Universal Category System) standard.

Footsteps, Human, Wood Floor, Old, Creaky, Stairs, Floorboard 01
└ category┘└ sub ┘└──────────────── keywords ────────────────┘^^
                                                              variant

Display the full title — every part carries information — and group results by category and subcategory to keep them scannable, since the first two segments are predictable enough to use as a heading.

Avoid text-overflow: ellipsis. The segments that tell two effects apart sit at the end, so trimming there leaves rows of near-identical Weather, Thunder, Tropical, Distant Thun…. The last segment alone doesn't work as a label either — values like Close, Fast and Distant repeat throughout the catalog.

A trailing two-digit number identifies the variant, e.g. Booming Thunder 02, Booming Thunder 04.

The prefix is the effect's own category, not necessarily the one you browsed

Parent categories return effects from all their descendants, so a title's first two segments won't always match the category you fetched it from. For example, browsing Chemicals / Acid can return Burn, Short Sizzle, Fizz 12, because that effect's own category is Burn, not Chemicals. Don't parse titles to derive taxonomy — use the category endpoints instead, and treat the title as a display string.

List sound effect collections

Use the sound effect collections endpoint to display curated groups of sound effects in your application.

Collections are managed via the developer portal: an admin imports an Epidemic Sound playlist into a collection, and only Active collections are returned through this endpoint.

Each collection includes id, name, and the first 20 sound effects embedded in the response — regardless of how many the collection actually contains. Use the availableSoundEffects field to know the true total count.

Performance optimization

When building a collection browser, use excludeField=soundEffects to fetch only collection metadata — id, name, and availableSoundEffects — without loading the embedded sound effects. Once a user selects a collection, fetch its full contents using the collection details endpoint, which supports limit and offset for pagination.

List sound effect categories

The sound effects categories endpoint returns category metadata for browsing the sound effects catalog.

Understanding the category hierarchy:

Sound effect categories form a two-level parent-child hierarchy. Fetching a parent category's effects returns everything from its descendants too - category browse filters on the category's taxonomy tag, and those tags are hierarchical. For example Chemicals returns 51 effects, which are exactly the 33 from its Acid child plus the 18 from its Reaction child. So you can offer a parent category as a broad entry point and a child as a narrower one, and both work.

Large parents behave the same way, just paginated: Ambience has 47 children and returns its full combined set page by page.

Category names are not unique - always show the parent

84 of the 788 category names are ambiguous on their own: Air appears twice, Animal three times, Antique five times. A chip labelled "Air" tells the user nothing.

Each category in the list response includes its parent, so render the two together:

{
  "id": "5e899289-eedb-4bc6-93a2-70c3ab601b88",
  "name": "Acid",
  "parent": {
    "id": "7272b788-839e-428f-af1d-808aadc82099",
    "name": "Chemicals"
  }
}

Display this as Chemicals / Acid, not Acid. Categories with no parent are the 81 top-level ones, which is also how you build a two-level menu client-side from the single list call - no per-category requests needed.

children is not included in the list response. If you need a category's children, call the category detail endpoint for that one category.

type=featured returns 12 curated categories and is the practical starting point for a browse UI - but note it mixes levels: Ambience (47 children) and Whoosh (a child of Swooshes) both appear, so render parents there too.

• Some categories have cover art that you can display in your interface
• Use the type parameter with value featured to only show categories curated by our team (default is all)
• The categories endpoint returns only metadata - to get the actual sound effects, use the sound effect details endpoint

Note: Browsing categories and searching are mutually exclusive. When a user enters a search term, disable category browsing, and vice versa.

List the sound effects within a category

Use the sound effect details endpoint to display all sound effects within a specific category.

Parent categories return all sound effects from their descendants, so no special handling is needed - both parent and child categories work for browsing.

Search for sound effects

Use the sound effects search endpoint to let users search the sound effects library.

Search is semantic. Your users do not need to guess catalog keywords - they can describe the sound they are after in plain language, and the search engine matches on meaning rather than on words appearing in the title:

What the user types	What comes back
someone walking slowly on creaky wooden floorboards in an old house	Footsteps, Human, Wood Floor, Old, Creaky, Stairs, Floorboard 01
the sound of a door being kicked open in an action movie	Doors, Wood, 70's, Aggressive, Kick Out 01
a cozy rainy evening outside a cafe window	Rain, General, From 2nd Floor, Window, Evening
whoosh for a fast scene transition in a vlog	Designed, Whoosh, Medium Transition

None of those results contain the words "cozy", "cafe", "action movie" or "vlog" in their titles. This works the same way as music search, so a single natural-language search box can serve both libraries.

Design implication: prefer a free-text field with a descriptive placeholder ("Describe the sound you need...") over a keyword input or a tag picker. Passing the user's own phrasing straight through as term gives better results than reducing it to keywords first. This also makes the endpoint a good fit behind an LLM tool call - hand the model a single query string parameter, exactly as in the Soundtrack with an LLM guide.

term is required and capped at 500 characters

Calling the endpoint without term returns 400 with {"key": "term", "messages": ["Parameter term is required"]}, and a term longer than 500 characters returns a 400. There is no "browse everything" mode on search - use categories or collections for browsing without a query.

Search always returns results

Because matching is semantic rather than exact, search effectively never returns an empty list - a nonsense query still returns its closest interpretation. Do not build a "no results found" state around an empty response, and do not treat a full first page as confirmation that the query was understood. Show enough result context (title, length, preview) that users can judge relevance themselves.

Sorting and pagination:

• Use sort to order results: best-match, newest, popular, length, or title
• Use order to specify direction: asc or desc
• Use includeExplicit (default false) to include explicit sound effects in results — it applies to both search and category browsing
• Pagination: default limit is 50, maximum is 60 per request

For best-match (relevance), always use order=desc - the default order=asc returns the least relevant matches first, which is the opposite of what users expect. For other sorts (newest, popular, length, title), asc/desc behave as usual (e.g. newest + desc = newest first).

Pagination works the same way as music search—the response includes pagination and links objects. Use links.next to fetch the next page, or increment offset by limit in your next request.

Best practices:

• Set includeExplicit=true if your audience and content policy allow explicit sound effects
• Disable category browsing when search is active

Play or download a sound effect

There is no separate preview or streaming endpoint for sound effects — the download endpoint serves both purposes. It returns a signed MP3 URL valid for 24 hours:

{
  "url": "https://pdn.epidemicsound.com/audiofiles/lqmp3/01KK27....mp3?exp=...",
  "expires": "2026-09-03T14:20:33Z"
}

To preview, stream that URL instead of downloading the file first. The CDN serves it as audio/mpeg with Accept-Ranges: bytes and permissive CORS, so an <audio> element can point straight at it and playback begins on the first chunk:

<audio src="{url}" controls preload="none"></audio>

This matters most for ambiences, which run long — a 15-minute recording is around 14 MB, so waiting for a complete download before playback adds seconds of silence. Range requests also mean seeking works immediately, without the whole file being present.

Reuse the URL rather than re-requesting it

The URL remains valid for 24 hours and the CDN sends Cache-Control: max-age=86400, immutable. Request it lazily when a user first plays an effect and keep it for the session — calling the download endpoint on every play burns per-user rate limit for no benefit.

Pass the URL through unmodified. The signature covers the query string, so appending your own parameters — a cache-buster, for instance — returns 401. See audio download URL errors.