Enterprise response and match fields

We have a separate endpoint that handles large files: the enterprise endpoint (POST https://enterprise.audd.io/). You can send hours-long or even days-long audio to this endpoint: full-length songs, short-form videos, podcasts, broadcasts, DJ sets. When you upload a file, our servers split it into 12-second chunks, and the response contains all the tracks recognized in them. So the response is different from the standard endpoint’s response: result is an array of chunks. Each chunk has its offset in the file and the songs recognized in it. This page describes the response, the fields of each song, and the request parameters that control the chunking. The standard endpoint returns a single result object; for it, see the recognition result fields reference.

Response shape

result is an array. Each element in the array is a chunk with the following members:

Field	Type	Description
`offset`	string	The position, in the file you submitted, of the start of the 12-second fragment this chunk covers, `MM:SS` or `HH:MM:SS`
`songs`	array	The songs recognized in this chunk. Usually there’s one song; there can be more when two tracks overlap (e.g., a DJ transition)

The response also has execution_time (a string like "159.226763ms") at the top level, and status is "success" as usual. A chunked response looks like this:

{
  "status": "success",
  "result": [
    {
      "songs": [
        {
          "score": 81,
          "artist": "Tears For Fears",
          "title": "Everybody Wants To Rule The World",
          "album": "Songs From The Big Chair",
          "release_date": "2014-11-10",
          "label": "UMC (Universal Music Catalogue)",
          "timecode": "00:57",
          "isrc": "GBUM71403885",
          "upc": "00602547037169",
          "song_link": "https://lis.tn/NbkVb"
        }
      ],
      "offset": "00:00"
    }
  ],
  "execution_time": "159.226763ms"
}

Song fields

Each entry in the songs array of a chunk has the following fields:

Field	Type	Description
`score`	integer	The confidence of the match, 0–100; the higher, the stronger. Requires the Startup plan or higher
`artist`	string	The artist of the track
`title`	string	The title of the track
`album`	string \| null	The album the recording appears on
`release_date`	string \| null	The release date, `YYYY-MM-DD`
`label`	string \| null	The record label
`timecode`	string	The position, in the original song, where the matched fragment is playing, `MM:SS`. It’s a position in the song, not in your file
`isrc`	string \| null	The International Standard Recording Code of the recording. Requires the Startup plan or higher
`upc`	string \| null	The Universal Product Code of the release. Requires the Startup plan or higher
`song_link`	string	The universal link to the song’s page on `lis.tn`
`start_offset`	integer	Only with `accurate_offsets=true`. The start of the matched fragment, in milliseconds, in the 12-second chunk (from 0 to about 12000). See below
`end_offset`	integer	Only with `accurate_offsets=true`. The end of the matched fragment, in milliseconds, in the 12-second chunk

offset vs. start_offset / end_offset

Note that start_offset is not the same as offset: offset places the chunk in the file, and start_offset places the match in the chunk, in milliseconds. If you confuse them, you will get timestamps that are off by minutes.

offset (in the chunk) is the position, in the audio file you submitted, of the start of the 12-second fragment that contains the match, in MM:SS or HH:MM:SS. It tells you where the chunk is in the file.
start_offset and end_offset (in the song, only with accurate_offsets=true) are the positions of the start and the end of the match, in milliseconds, in that 12-second fragment. They aren’t seconds in the file: their values are from 0 to about 12000.

To get the position of a match in the whole file, parse the chunk’s offset into seconds and add the song’s start_offset. Since start_offset is in milliseconds, convert it to seconds by dividing by 1000:

file_seconds = parse_mmss(chunk.offset) + song.start_offset / 1000

So if the chunk’s offset is "04:48" and the song’s start_offset is 3520, the match starts at 288 + 3.52 = 291.52 seconds into the file.

Request parameters

Send the parameters as multipart/form-data. There are two ways of sending the audio: provide a URL of the file (or of a web page that contains it) in the url parameter, or post the file in the file parameter. api_token is required for all your requests.

Parameter	Type	Description
`return`	string	By default, the enterprise endpoint doesn’t return the provider blocks (Apple Music, Deezer, MusicBrainz). If you need them, send an email to [email protected]. Each song has `song_link` and, on the Startup plan or higher, `isrc` and `upc`
`limit`	integer	How many chunks at most the server recognizes. Always set it in development; see the note below
`every`	integer	How many chunks should be recognized in a row
`skip`	integer	How many 12-second chunks are skipped after each recognized run. Together with `every`, it lets you sample the file instead of recognizing all of it
`skip_first_seconds`	integer	How many seconds of the file the server should skip at the beginning before starting the recognition (the start time of the first chunk). Do not use it together with `use_timecode`
`use_timecode`	string	Set it to `"true"` to use the time from the `t`, `time_continue`, or `start` parameter of the URL (if there is one) as `skip_first_seconds`. Do not use it together with `skip_first_seconds`
`accurate_offsets`	string	Set it to `"true"` to get `start_offset` and `end_offset` for each recognized song

Always set limit during development. The requests to the enterprise endpoint are counted as 1 request per 12 seconds of audio, and without a limit, the server can process hours of audio before it returns. So set limit to a small number while you’re testing.

Notes

result is an array, not an object. Go through the chunks, and then through the songs of each chunk.
A chunk can have more than one song. In this case, the songs with a lower score are usually from the audio that overlaps or blends with the main song, not separate placements.
The typed SDKs flatten the chunks into one list of matches, and each match has its position in your file in seconds, in start_seconds and end_seconds. The SDKs request accurate_offsets=true by default, so the seconds are precise. They calculate start_seconds and end_seconds from offset and start_offset for you, so you don’t need the chunk’s offset or the raw response to place a match. The raw start_offset and end_offset are also there, as the milliseconds in the fragment. Use the formula directly only when you call the HTTP API yourself.
You need the Startup plan or higher to get score, isrc, and upc with the results. On the lower plans, the response doesn’t have these fields.
start_offset and end_offset are only in the response if the request has accurate_offsets=true.

Related