Music

This guide covers everything you need to build a music experience: browsing and searching the catalog, streaming and downloading tracks, and accessing timing and waveform data for advanced video sync use cases.

List genres with their tracks

Use the genres endpoint to list the available genres.

We recommend that you specify the "type" featured to only show the genres that are featured by our curation team and order by relevance to make sure that the order is based on the most popular genres.

Parent genres have cover art that you can show in your interface. Filtering by a parent genre (e.g. rock) matches tracks tagged with any of its child genres (indie-rock, alternative-rock, etc.), so the 12 featured genres effectively cover the full catalog.

Cover art is optional for sub-genres

Sub-genres (child genres) may not have cover art — the images field can be empty or absent. This is expected behaviour. Always check for the presence of cover art before rendering it, and provide a fallback (e.g. a placeholder image or text-only display) for sub-genres that have none.

Use the genre details endpoint to show the tracks for a given genre.

List playlists with their tracks

Use the collections endpoint to display playlists curated by our team of in-house experts.

Collections have attributes like title and cover art, and you can choose to return collections with or without tracks.

The response will include a maximum of 20 tracks per collection. If a collection contains more than 20 tracks, use the endpoint '/collections/{collectionId}' to get all tracks.

Dynamic vs. static collections:

• Curated collections are maintained by Epidemic Sound's curation team and may update dynamically — tracks can be added, removed, or reordered at any time. For example, a "Trending on TikTok" collection is refreshed daily. Always fetch collection data from the API rather than caching it locally.
• Imported collections (created by importing a playlist URL from epidemicsound.com) are static snapshots. They do not automatically sync when the source playlist changes on the Epidemic Sound website.

Performance Optimization

For better performance, especially with large collections, use excludeFields=tracks to list only collection metadata. You can then fetch tracks for specific collections separately using the collection details endpoint.

List moods with their tracks

Use the moods endpoint to allow users to browse the music catalog based on moods like happy, epic or relaxing. Moods have cover art that you can show in your interface.

We recommend that you specify the "type" featured to only display moods that are featured on epidemicsound.com.

Use the mood details endpoint to show the tracks for a given mood.

Browse vs. Search

The Epidemic Sound API offers two ways to find tracks — browse and search — and they differ in important ways:

	Browse (/v0/tracks)	Search (/v0/tracks/search)
Purpose	Filter-only discovery	Text-based semantic search
term parameter	Not supported	Required
BPM filtering	bpmMin/bpmMax supported	Not supported
Mood / genre filters	Supported	Supported
Sort options	Relevance, Date, Title, Popularity, BPM, Duration	Same

In short: use search when the user provides a text query, and browse when you want to filter by mood, genre, or BPM without a text query.

Filters use AND logic

When combining multiple filters (mood, genre, BPM), all filters are applied as AND — results must match every specified filter. For example, filtering by mood happy and genre pop returns only tracks that are both happy and pop.

Search for music

Use the search endpoint to search for any given query within our music library (max 500 characters). The search endpoint uses an open language model that allows users to use semantic search terms such as "music for a calm beach scene" or "high energy track for a workout".

The search endpoint indexes track attributes including moods, genres, artist names, song titles, and BPM. You can further refine results by:

• Filtering by specific genres and moods (applied as AND with the search term)
• Sorting results using sort (Relevance, Date, Title, Popularity, BPM, Duration) and order (asc, desc)
• Controlling pagination with offset and limit parameters (default 50, max 60)

Sort and order (ASC/DESC)

The sort parameter chooses what to sort by; the order parameter chooses direction. For most sort types the meaning is intuitive, but for relevance it is easy to get it wrong.

Sort value	Recommended order	Meaning
Relevance	desc	Most relevant first. With order=asc the API returns the least relevant results (a different slice), which is rarely what you want.
Date	desc or asc	desc = newest first; asc = oldest first.
Title	asc or desc	asc = A→Z; desc = Z→A.
Popularity	desc	Most downloaded first. Useful for surfacing trending or popular tracks.
BPM	asc or desc	Sort by tempo. asc = slowest first; desc = fastest first.
Duration	asc or desc	asc = shortest first; desc = longest first.

Search results are paginated. See Pagination for how to page through results.

Browse

Use the browse endpoint to list tracks filtered by mood, genre, and BPM range simultaneously. Unlike the search endpoint, the browse endpoint does not require a term — you can use it purely as a filter. All filters are combined with AND logic, so results must match every specified criterion.

Batch track metadata

Use the track metadata endpoint to fetch metadata for multiple tracks at once by providing a list of track IDs. This is more efficient than making individual requests when you need details for several tracks.

Understanding track response fields

Track responses include several important fields you should be aware of:

• isPreviewOnly: When true, the track can only be streamed for preview but not downloaded. This depends on the user's subscription status and your partnership agreement. Known issue: Partners with full catalogue access may see isPreviewOnly: true on tracks discovered outside their collections (e.g. via search, similar tracks, or mood/genre browsing), even though these tracks are actually downloadable. Do not rely on this flag alone to determine download eligibility — attempt the download regardless. See the Fundamentals on content access for details.
• isExplicit: When true, the track contains explicit content. Consider filtering or flagging these tracks in your UI if appropriate for your audience.
• hasVocals: When true, the track contains vocals. Useful for allowing users to filter for instrumental-only tracks.

Audio formats

The API supports low and high quality MP3 files for downloads, and adaptive HLS streaming for real-time playback. See Tracks in the API Reference for full details.

Play a track

For real-time playback while users browse the music library, use the streaming endpoint which returns an HLS (HTTP Live Streaming) manifest URL.

Why HLS for previewing:

• Smaller file transfers: Audio is encoded using the AAC standard, which has a smaller footprint than MP3 for similar quality
• Adaptive quality: The HLS client library automatically switches between two variant quality streams based on network speed
• Seeking support: Users can skip forward/backward during playback

Implementation:

The format consists of audio files split into smaller chunks with manifests (.m3u8 files) that reference these audio files. HLS client libraries handle the complexity automatically:

• iOS/Safari: Native HLS support via AVFoundation (no additional library needed)
• Web browsers: Use hls.js library
• Android: ExoPlayer with HLS support

Here is an example app for iOS that plays HLS streams.

Access to tracks for preview depends on your partnership agreement. See the Fundamentals on content access for details.

Preview vs. Download:

Use HLS streaming for previewing tracks during browsing. When users want to add a track to their project, use the download endpoint below which provides MP3 files.

Download a track

When a user wants to add a track to their project for editing or export, use the download endpoint to get an MP3 file.

Available qualities:

• Normal (128kbps): Sufficient for most use cases
• High (320kbps): For content requiring higher audio quality

The download links expire after 24 hours (normal quality) or 1 hour (high quality). The expiration time is included in the response.

Access to tracks for download depends on your partnership agreement. See the Fundamentals on content access for details.

Report usage of a track

Report usage of a track to the usage endpoint when a user exports their content to social media or downloads the content file to their device.

You can specify which platform (YouTube, Twitch, Instagram, Facebook, TikTok, Twitter or "other") they exported the file to. Use the platform "local" if the user downloads the content to their device.

This data is used for attribution and analytics purposes as well as to improve personalization.

If you prefer to report events in bulk, you can also use the bulk reporting endpoint.

Partner Token Required for Bulk Reporting

The bulk reporting endpoint requires Partner Token authentication. For individual usage reporting in the context of a user, use the /v0/usage endpoint with a User Token.

Get waveform

All tracks in the library come with a waveform. Waveforms can be used for the following use cases:

• From our user research we know that users look at the waveform to understand track capabilities such as build, drop etc.
• Use it for selection of the particular parts of the track
• Use it to find similar repetitions in the entire track
• Loop selected part of the track using the waveform

Waveform URL data

Each track response includes a waveformUrl field containing a link to the track's waveform data in JSON format. You can find this field in the track response.

Each file consists of a single JSON object containing waveform data points and some meta-information used for its generation. Waveform files were generated for the audio files using 8-bit resolution featuring ~1600 minimum and maximum value pairs in the resulting waveform data.

The format follows the BBC audiowaveform JSON data format.

Example waveform object:

{
    "version": 2,
    "channels": 1,
    "sample_rate": 48000,
    "samples_per_pixel": 5539,
    "bits": 8,
    "length": 1601,
    "data": [-46, 52, -44, 44, ...]
}

Segments

Use the highlights endpoint to get the most popular section of a track. Powered by machine learning trained on billions of YouTube streams, this endpoint recommends the best time sections for your use case.

Use cases:

• Start playback from the most engaging part of the track
• Recommend the right section for short-form content (Reels, TikTok, Shorts)

The endpoint accepts up to 5 different durations per request (5-60 seconds each) and returns start/stop timestamps in milliseconds.

Get beat timestamps

Use the beats endpoint to get precise beat timestamps for a track. Unlike BPM which is a single number, beats data captures dynamic tempo changes throughout the track.

Use cases:

• Automatically cut video clips in sync with the beat
• Add snap markers aligned with beat timestamps in your editing UI

The response includes time (timestamp in milliseconds) and value (beat position in a bar, where 1 is the downbeat).