Audio Fingerprinting API

Emysound now provides an API that will enable you integrating it with third-party systems. You can access the full API documentation on our portal.

Our API provides a JSON interface for platform agnostic integration. It can be used for a variety of use-cases.

audio fingerprinting API
broadcast content monitoring
content deduplication
repeating content detection
shazam style apps

Insert and query with audio files

Before using the API create an account with Emysound.

How to insert an audio track into Emy? Grab the API credentials from the API Keys section in the dashboard. Below is an example of the cUrl request with Application ID Admin and an empty password. These are also default credentials for the Community Edition.

curl 'https://developers.emysound.com/api/v1.1/tracks' \
    -H 'Authorization: Basic Admin:' \
    -F 'track.id=test-id' \
    -F 'track.title=test-title' \
    -F 'track.artist=test-artist' \
    -F 'track.metaFields[test-meta-key]=test-meta-value' \
    -F 'track.mediaType=Audio,Video' \
    -F 'insertOriginalPoints=true' \
    -F 'file=@ad.mp4'

Once you’ve inserted audio tracks into Emy, you can query the storage to identify which ones are matching.

curl 'https://developers.emysound.com/api/v1.1/query' \
    -H 'Authorization: Basic Admin:' \
    -F 'file=@query.ts' \
    -F 'mediaType=Audio,Video' \
    -F 'minCoverage=0.4'

Another way of issuing requests to Emy storage is registering an online stream that will be continuosly monitored, automatically registering successful matches. To register a stream the following sample request can be used. Notice how we specify savePlaybackTrack to true, meaning we want to store matched audio for later playback.

curl --request POST \
  --url https://developers.emysound.com/api/v1.1/streams \
  --header 'Authorization: Basic Admin:' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/*+json' \
  --data '
{
  "streamId": "CNN",
  "streamUrl": "https://tunein.streamguys1.com/cnn-new",
  "savePlaybackTrack": true
}

The playback file can be retrieved via a request to the media API.

curl --request GET \
     --url 'https://developers.emysound.com/api/v1.1/media/query-match-id?applicationId=your-application-id&jsonApiKey=your-json-api-key' \
     --header 'Accept: application/json'

You can learn more about how to monitor online broadcasts on this page.

Search and filter through the matches

Matches that passed the minConfidence threshold will be registered in Emysound, unless you set registerMatches to false. Registered matches are available for search and retrieval from the matches endpoint.

curl --request GET \
  --url 'https://developers.emysound.com/api/v1.1/matches?limit=50&sinceDays=90' \
  --header 'Authorization: Basic Admin:' \
  --header 'Accept: application/json'

Matches endpoint allows you to retrieve facets and their counts. If you want to count how many times a particular track matched, provide trackId in facets parameter.

curl --request GET \
  --url 'https://developers.emysound.com/api/v1.1/matches?facets=trackId&sinceDays=90' \
  --header 'Authorization: Basic Admin:' \
  --header 'Accept: application/json'

The result will include an array of facets objects which will give trackId counts.

{
    "count": 100,
    "cursor": {
        "next": "637659255259564223"
    },
    "facets": [
        {
            "name": "trackId",
            "values": [
                {
                    "count": 2368,
                    "name": "62c6595a-24cc-4f51-bb35-ee39f85bda5f"
                },
                {
                    "count": 2368,
                    "name": "ef56e578-805a-452b-baa3-7007614e808f"
                },
                {
                    "count": 2367,
                    "name": "44c9e6ac-a107-40e3-abdd-9e8bf6965930"
                },
                {
                    "count": 2356,
                    "name": "042c9562-a964-43d8-bb93-61fa3080bb29"
                },
                {
                    "count": 1620,
                    "name": "851deb45-601c-4e36-9b53-2f56446a8bb2"
                }
        }
    ]
}

As of v1.1, facets parameter supports the following fields: trackId, streamId, mediaType, reviewStatus.

Matches endpoint also allows you to drill-down matches on facet fields. If you want to retrieve matches that happened only on CNN stream, provide filters=streamId:CNN as a parameter to the matches endpoint.

curl --request GET \
  --url 'https://developers.emysound.com/api/v1.1/matches?filters=streamId:CNN&sinceDays=90' \
  --header 'Authorization: Basic Admin:' \
  --header 'Accept: application/json'

Similar to facets parameter, filtering can be done on multiple fields simultaneously.

The full list of API operations can be found on our documentation portal. Below are some quick links to most frequently used features:

Insert tracks into Emy.
Query Emy with provided media file.
Register an HTTP stream to be continuosly monitored by Emy.
Retrieve registered matches.