Audio Fingerprinting API

JSON API for Emy

Posted by Sergiu Ciumac on June 05, 2021 · 4 mins read

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.


curl 'https://api.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://api.emysound.com/api/v1.1/query' \
    -H 'Authorization: Basic Admin:' \
    -F 'file=@query.ts' \
    -F 'mediaType=Audio,Video' \
    -F 'minCoverage=0.4'

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://api.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://api.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://api.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.

Contact us for feature requests. We are eager to hear about your use cases!