Skip to main content

Guides

Music browsing

This guide will walk you through the steps to build a music browsing UI, fetch available playlists, moods and genres with their tracks, play a track, download a track and how to report usage of a track.

User flow​

  1. User clicks on the music tab
  2. User browse available playlists & tracks
  3. User browse available genres & tracks
  4. User browse available moods & track
  5. User searches for music
  6. User play a track
  7. User adds a track to the project
  8. User exports video with a track

Workflow steps​

  1. List genres with their tracks
  2. List playlists with their tracks
  3. List moods with their tracks
  4. Search for music
  5. Play a track
  6. Download a track
  7. Report usage of a track

1. List genres with their tracks​

Use the [genres endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-all-genres) 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.

Use the [genre details endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-genre-details) to show the tracks for a given genre.

2. List playlists with their tracks​

Use the [collections endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-collections) 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.

3. List moods with their tracks​

Use the [moods endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-all-moods) 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] (https://developers.epidemicsound.com/docs/Endpoints/get-mood-details) to show the tracks for a given mood.

4. Search for music​

Use the [search endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-tracks-search) to search for any given query within our music library. 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”.

5. Play a track​

We recommend using our [streaming endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-stream) to allow users to play/preview a track. The main benefits of this compared to MP3 are smaller file transfers and alternate qualities, allowing the HLS client library to switch to a lower quality when necessary.

The audio is encoded using the AAC coding standard, which results in a smaller footprint for a similar quality compared to MP3. The primary manifest refers to two variant quality streams. HLS client libraries typically choose the optimal quality automatically, based on download speed.

The format consists of audio files split into smaller chunks and manifests that refer to these audio files. Since the format is made up of multiple files, access to these are controlled using cookies.

Here is an [example app for iOS] (https://github.com/epidemicsound/partner-content-api-demo-ios/) that plays HLS streams.

6. Download a track​

Use the [download endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-download) when a user wants to add a track to their project. We offer MP3 files in two qualities; normal (128kbps) and high (320kbps). The high quality files can be used in content when needed, but note that normal should be sufficient for most use cases. The download links expire after 24 hours (normal quality) or 10 minutes (high quality files). The expiration time is stated in the response.

7. Report usage of a track​

Report usage of a track to the [usage endpoint] (https://developers.epidemicsound.com/docs/Endpoints/post-use) 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.

Sound effects browsing

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

User flow​

  1. User clicks on the sound effect tab
  2. User browse available sound effect categories
  3. User browse the sound effects of a specific category
  4. User searches for a sound effect
  5. User plays a sound effect or downloads a sound effect to their project

Workflow steps​

  1. List sound effect categories
  2. List the sound effects within a category
  3. Search for Sound affects
  4. Play a sound effect

1. List sound effect categories​

The [sound effects categories] (https://developers.epidemicsound.com/docs/Endpoints/get-sound-effect-categories) endpoint allows users to browse the sound effects catalog based on categories like "Applause" or "Crowds".

Some sound effect categories have cover art that you can use in your interface. You can choose to display all categories, or choose type “featured” to only show the categories that are chosen by our curation team.

2. List the sound effects within a category​

Use the [sound effect details endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-sound-effect-category-tracks) to display all sound effects of a given category.

3. Search for Sound affects​

Use the [sound effects search endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-sound-effect-search) to allow users to search within the sound effects library.

4. Play or download a sound effect​

Use the [download sound effect endpoint] (https://developers.epidemicsound.com/docs/Endpoints/get-sound-effect-download) to play or download a specific sound effect. Since most sound effects are short with small file sizes we do not offer a specific endpoint for streaming/previewing sound effects.

Get recommendations based on your video

Spend less time searching and more creating by using the video itself to find relevant music.

The Soundmatch feature analyzes video frames and provides a list of recommended tracks perfectly suited to the video’s visual scenes. This guide will walk you through how to implement Soundmatch in your app, allowing users to delete their content and the partner partner requirements to use this feature.

But let’s first start with an example UI. In the example below, users can click to “Get music recommendations based on the current frame”. When the user clicks the button, you send an image from the user’s video to Epidemic Sound. Based on the content of the frame, we’ll give a list of recommended tracks in return.

Soundmatch: get music recommendations​

Workflow steps​

  1. Upload an image and receive the corresponding imageID
  2. Get recommendations based on imageID

1. Upload image​

The first step is to post an image from the user’s video to the image upload endpoint. That will give you an ImageID in return that you will use in the next step to get the actual track recommendations.

We currently only support jpeg files, and the size limit for the file is 2MB.

2. Get recommendations based on imageID​

Use the ImageID from the previous step to get track recommendations by using the matching image endpoint. This will give you a list of tracks to show to your user.

Soundmatch: Delete frames​

If you wish to implement the Soundmatch feature, we have a strict requirement that you offer the capability for users to delete their uploaded content. We recommend that you place this functionality in the settings of your app.

A. Delete all frames that a user uploaded​

Users who can upload their content to get recommendations should also be able to easily delete all frames that they have previously uploaded.

Use the delete user images endpoint to delete all images for the specified userID.

B. Delete specific frames​

We also offer the functionality to delete a specific image based on the imageID. Use the delete images endpoint using the imageID as a reference.

Soundmatch: Partner requirements​

We’re very excited to partner with you to offer a better soundtracking experience for your users. However, since some of the uploaded images can potentially be considered personal data we want to make sure that we respect the users’ privacy.

If you wish to implement Soundmatch, we have the following requirements towards you as a partner:

  • Update your privacy policy to reflect that you are sharing the user’s personal data with us.
  • Allow users to delete their uploaded content. Please see the guide to Delete all frames that a user uploaded above.

Remix your templates

Breathe fresh life into your templates by letting users replace the default music with a song with their creative flair! No matter if your templates have music from Epidemic Sound or not, our API utilizes EAR (Epidemic Audio Reference) to instantly find music that sounds similar to any part of another track.

In the example UI below, a user has started the editing process with one of your templates. When they click to Swap out the music they get a list of other tracks to try. With just a click of a button, users get access to a new world of content!

The guides below will walk you through the process to send a reference and get back track recommendations.

Templates with Epidemic Sound music​

Each track in the Epidemic Sound library has a trackID. If your template has a default sound from Epidemic Sound, you can use the similar sections endpoint to get recommendations of similar track segments. Specify in the request which track you want recommendations for, and the timestamps of the section that is used in your template.

In return, you will get a list of tracks and timestamps for the sections that sound similar to the default sound.

Templates with music from another music provider​

This guide will walk you through the steps to upload any music file and get music recommendations from Epidemic Sound’s library in return. Please make sure that the agreement with your music provider allows you to use their music as a reference.

Workflow steps:​

  1. Upload an audio file
  2. Get recommendations based on audioId
  3. Check if the file is already uploaded

1. Upload an audio file​

The first step is to post an audio file to the audio upload endpoint. That will give you an AudioID in return that you will use in the next step to get the actual track recommendations.

We currently support the formats: mp3, mpeg, ogg and vorbis. Maximum file size is 3.5MB. You can only upload music with the partner token, since we currently do not allow end users to use this feature.

2. Get recommendations based on audioId​

Use the AudioID from the previous step to get track recommendations by using the matching audio endpoint. This will give you a list of tracks to show to your user.

3. Check if the file is already uploaded​

To avoid duplicate uploads we provide an additional endpoint to get the audioID of an already uploaded asset. Use the checksum endpoint to get the AudioID based on the checksum of the uploaded file.

Waveforms

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​

Track response contains a link to generated waveform data in JSON format. 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.

You can find more information about waveform data format here.

The shape of the waveform object:

{
    "sample_rate":44100,
    "samples_per_pixel":7548,
    "bits":8,
    "length":1601,
    "data":
    [-7, 6],
    "channels":10,
    "example_rate":10,
    "version":1,
}