A distributor receives tracks from artists and passes them on to streaming services. Most submissions are what they claim to be. Some are not: a re-upload of a commercial recording under a new artist name, a track that already went out through you under a different title, a mash-up built on someone else’s master. This recipe checks every submission with AudD before delivery and writes a review queue CSV that tells a person which tracks to look at and why.
There are two checks:
- Against the public database. Recognize the submission and compare the matched recording (artist, label, ISRC) to what the uploader claims.
- Against your own catalog. Catch the same recording delivered twice under different titles, artists, or ISRCs, using a custom catalog of the masters you have already delivered.
What a match means, and what it doesn’t. AudD tells you which recording in its database the audio matches, with the metadata that recording was released with. It can’t verify ownership or tell you who holds the rights. The label field is the releasing label in the release metadata, which is not necessarily the rights owner: catalogs get sold, licensed, and moved between distributors. A match against a different artist is a reason for a person to look, not proof of infringement. The review decision is yours. This page is not legal advice.
What a match means, and what it doesn’t. AudD tells you which recording in its database the audio matches, with the metadata that recording was released with. It can’t verify ownership or tell you who holds the rights. The label field is the releasing label in the release metadata, which is not necessarily the rights owner: catalogs get sold, licensed, and moved between distributors. A match against a different artist is a reason for a person to look, not proof of infringement. The review decision is yours. This page is not legal advice.
What you’ll build
A Python script that takes a batch of submissions and produces review_queue.csv, one row per submission per matched recording, with an action column:
no_match does not mean “cleared”. AudD matches recordings, so it does not detect covers, re-recordings, interpolations, or AI-generated imitations of an artist’s voice, and it can only match what is in its database of about 160 million commercially released songs.
Prerequisites
- An API token. Get your own token at dashboard.audd.io. ISRC, UPC, and score in results require a Startup plan or higher. Without ISRCs the own_release check falls back to artist and title, which is much weaker.
- Python 3.10+ with the SDK: pip install audd
- ffmpeg and ffprobe on your PATH, to cut excerpts and read durations.
- Your own delivery records: for each account, the ISRCs you have delivered and the artist names you have verified for it. The script reads them from whatever store you already have.
- For the catalog check (Part 2): custom catalog access. It isn’t enabled by default; email [email protected] to request it.
Standard excerpt or enterprise scan
You can check a submission two ways, and the choice is a cost and coverage trade-off.
Standard endpoint on a mid-track excerpt. The standard endpoint (https://api.audd.io/) analyzes the first 12 seconds of what you send and returns one best match. Many tracks open with silence, a count-in, or an ambient intro, so cut a 12-second excerpt from the middle of the track and send that. One request per track.
Enterprise endpoint over the whole track. The enterprise endpoint (https://enterprise.audd.io/) splits the file into 12-second chunks and returns every match with its position. It catches a sample at 2:40 that the excerpt would miss, and it tells you how much of the track matched. It is billed one request per 12 seconds of audio processed.
For a 3:30 track (210 seconds, 18 chunks):
A common setup is to run the excerpt check on every submission and the full enterprise scan on a subset: new accounts, accounts with earlier flags, genres where sampling is common, or anything the excerpt check flagged.
Part 1: Check submissions against the public database
Step 1: Describe a submission and your records
Load AccountHistory per account from your own database. The ISRCs are the ones you delivered for that account; the artist names are the ones you have verified the account is allowed to deliver as.
Step 2: Cut an excerpt and recognize it
recognize returns None when nothing matched. That is a normal outcome, not an error. To try the same check by hand, the CLI sends a clip from any point in a file: audd recognize track.wav --at 1:20.
Step 3: Classify a match against the claim
same_artist is deliberately loose ("Artist feat. Guest" contains "Artist"), because the result only routes a track to a person. Two different artists can share a name, so an artist-name match is never enough to clear a track on its own; that is why only an ISRC from your own delivery records produces own_release.
Step 4: Full enterprise scan, with partial matches
For tracks that get the full scan, group the matches by recording and work out how much of the track each recording covers.
start_seconds and end_seconds are positions in the submitted file, in seconds. The SDK requests accurate offsets by default and computes them from the chunk position plus the offset inside the 12-second chunk, so you don’t do that math yourself (see Enterprise response and match fields if you call the HTTP API directly).
The limit is set to the number of chunks in the track, with a ceiling. A submission that turns out to be a two-hour DJ mix uploaded as a “single” stops at 60 chunks instead of metering the whole file.
A file that matches several recordings, or one recording over a small part of its length, lands in partial. Sampling, a DJ edit, a remix built on a released stem, and a track that quotes a famous intro all look like this. Some are cleared, some are not; AudD can’t tell which.
The public database only knows what has been released. A track you delivered last week may not be in it yet, and the public database won’t tell you that two of your own deliveries are the same audio. For that, fingerprint the masters you deliver into a custom catalog: your account’s private fingerprint database. Once a master is in it, ordinary recognition calls can return that master’s audio_id.
Step 5: Add masters to the catalog, without retrying
Use your internal master ID (an integer) as the audio_id, and keep the metadata on your side. A custom match returns the audio_id; its artist and title may be null.
Uploads are metered, and a retried upload that had in fact succeeded the first time leaves you paying twice. The SDK does not retry custom_catalog.add; don’t wrap it in your own retry loop. Record the state before and after each upload, and send anything left in an unknown state to a person.
By uploading audio to the catalog you confirm you have the rights to do so; the terms are on the upload endpoint page. The CLI equivalent for a one-off is audd catalog add master.wav --id 81234.
Step 6: Check before you add
To find duplicates, recognize each new submission before its master goes into the catalog. If it matches a master that is already there, you have the same recording twice. Doing it in this order also works for a backfill: walk your existing masters oldest first, check each one, then add it.
A standard call returns one best match, which can come from your catalog (audio_id set) or from the public database. A master you delivered months ago is likely in the public database too, so check both: the audio_id against your catalog, and the ISRC against your delivery records.
A blank claimed_isrc against a master that already has one shows up as a conflict on purpose: it means someone is about to assign a second ISRC to a recording that already has one.
Step 7: Write the review queue
Run both checks per submission and write one CSV row per finding, with enough evidence that the reviewer doesn’t have to re-run anything.
catalog_check already made the excerpt call, so on the standard path you can reuse its result instead of recognizing twice; it is kept separate here for readability. Write the rows with csv.DictWriter(f, fieldnames=FIELDS, restval="").
A finished queue looks like this:
Reviewing the queue
The reviewer’s job is to decide what the evidence means. Some patterns that come up:
- different_artist with a major-label label. Ask the uploader for the licence or the contract that covers it. A remix contest or a licensed sample is legitimate; an unexplained full re-upload usually isn’t.
- same_artist_no_history. Common when an artist moves their catalog from another distributor; the ISRCs normally travel with the recordings. Confirm the account really belongs to that artist before you deliver.
- partial. Listen to the first_seen_s–last_seen_s range in the submission next to the matched recording’s song_link.
- metadata_conflict. Decide which metadata is right, and whether the submission is a new release of an existing recording or a mistake.
Keep the CSV rows and the reviewer’s decision together. If a decision is challenged later, you have what was matched, when, and why it was held.
Handling errors
- AudDAuthenticationError: bad token. Stop the batch.
- AudDQuotaError, AudDSubscriptionError: out of requests, or a feature (enterprise, ISRC) not available on the plan. Stop and fix the account; retrying won’t help.
- AudDCustomCatalogAccessError: catalog access isn’t enabled yet. Email [email protected].
- AudDInvalidAudioError: the submission isn’t decodable audio. Return it to the uploader.
- AudDConnectionError on a recognition call: safe to retry with backoff. On a catalog upload: don’t retry; the registry marks it needs_check.
Cancelling a recognition request mid-flight might still consume requests.
Going further
- Store every result keyed by submission ID and file hash, so a re-submitted identical file doesn’t get re-scanned.
- Re-check no_match submissions after delivery if you want to catch material that reached the public database later.
- Score a match before routing it: see Interpreting the recognition score.
- AudD for music distributors
- Detect samples and reuse of your own tracks
- Public database vs your custom catalog
- Controlling enterprise endpoint cost
- Enterprise response and match fields
- Python SDK docs
