soundverse Trace
Trace Overview
Trace measures how similar two songs are, and in what way. It compares songs on separate layers (the full mix, the individual instruments, the structure, the melody, the lyrics and the style) and returns a score for each, with the evidence behind it.
- What Trace does
- How it works
- Search shapes
- Layers (depths)
- Search types
- Reading scores
- Endpoints
- Good to know
What Trace does
Audio fingerprinting answers “is this the same recording?”. Trace answers “how similar are these two songs, and on which layer?”. That lets it surface reuse an exact-match fingerprint would miss, such as a lifted melody, a re-recorded vocal or a borrowed drum groove.
- Catalog screening — check a new track against your catalog before release.
- Cover, remix and sample detection — find where a melody, a vocal or an instrument part was reused.
- Catalog matching — compare every song in one catalog with every song in another.
Dedicated routes
Trace has its own endpoints under /trace/v3 on https://apiv2.soundverse.ai. Call them directly rather than through POST /v1/generations. Authentication is the same Bearer API key as the rest of the API — see Authentication.
How it works
Trace works in two stages. Ingestion analyses each song once and stores the result. Search then compares the stored analysis, so you can search as often as you like without reprocessing.
- Upload your audio with
POST /v1/filesand keep eachfile_id. - Create a dataset — a named collection of songs you search against.
- Ingest the songs into the dataset, choosing which layers to prepare.
- Search with a custom search, the comprehensive search or a use case. Each returns a
job_idimmediately. - Poll the job until it completes, then read the scores.
Steps 1–3 are on Datasets & Ingest, step 4 on Search and Use Cases, and step 5 on Results & Billing.
A 1:1 search (one song against one song) works directly on two file IDs and needs no dataset or ingestion. Datasets are only needed for 1:N and M:N searches.
Search shapes
Every search endpoint accepts the same three shapes, set with search_type:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| 1:1 | song vs song | No | — | One song against one song. Requires query_file_id and candidate_file_id. |
| 1:n | song vs dataset | No | — | One song against every song in a dataset. Requires query_file_id and candidate_dataset_name. |
| m:n | dataset vs dataset | No | — | Every song in one dataset against every song in another. Requires query_dataset_name and candidate_dataset_name. |
Layers (depths)
A depth is one layer of comparison. You choose depths in a custom search; the comprehensive search and the use cases choose them for you. A dataset can only be searched at the depths it was ingested with.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| track | full mix | No | — | The whole song. Best for overall sound, production and genre. |
| light_stem | vocals + accompaniment | No | — | The vocals and the accompaniment, compared separately. Best for spotting the same vocal recording reused. |
| stem | 4 instruments | No | — | Vocals, bass, drums and other instruments, compared separately. Best for a lifted bassline, drum loop or vocal. |
| section | structure | No | — | Matching sections (intro, verse, chorus, bridge, outro). Best for structure and harmony, part by part. |
| stem_section | structure per instrument | No | — | Sections within each instrument. Available in search only. |
| motif | melody | No | — | Short melodic phrases. Best for melody reuse; in 1:n and m:n searches it also finds a melody moved to another key. |
| lyrics | text | No | — | The transcribed lyrics. Best for covers and reused lyrics. |
| translation | text | No | — | The lyrics after translating both songs to English. Best for covers in another language. |
| insights | tags | No | — | Genre, instrument and style tags. Best for style proximity. |
A high score on the vocal stem means the same vocal recording was reused. It does not identify the same singer singing something new.
Search types
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Custom | POST /trace/v3/search | No | — | You choose the exact depths and instruments to compare. |
| Comprehensive | POST /trace/v3/comprehensive1 | No | — | A fast all-round check of the full mix, vocals, accompaniment and melody. |
| Use case | POST /trace/v3/{use_case} | No | — | A ready-made search for one question: cover, remix, genre, lyrics, melody, sample, voice timbre, or a deep comprehensive check. |
Reading scores
Scores range from 0 (no similarity) to 1 (identical); percentage is the same value from 0 to 100. Trace cuts each song into 16 windows of 8 seconds, compares every window of one song with every window of the other, and reports three numbers per layer:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| hungarian_mean | number | No | — | The headline score: the best one-to-one pairing of windows, averaged. |
| max_then_mean | number | No | — | Each window's closest match, averaged. Several windows may share a partner. |
| max | number | No | — | The single most similar pair of windows. |
Melody (motif) results report the number of matching phrases rather than a percentage. Scores are similarity measurements, not legal or copyright determinations.
Endpoints
POST/v1/filesupload a song, get its file_id
POST/trace/v3/datasetcreate a dataset
GET/trace/v3/datasetlist your datasets
GET/trace/v3/dataset/{dataset_id}get one dataset
GET/trace/v3/dataset/{dataset_id}/tracksper-song ingestion state
DELETE/trace/v3/dataset/{dataset_id}delete a dataset
POST/trace/v3/ingestingest songs into a dataset
GET/trace/v3/ingest/{job_id}ingestion status
POST/trace/v3/searchcustom search
POST/trace/v3/comprehensive1comprehensive search
POST/trace/v3/{use_case}use-case search (8 routes)
GET/trace/v3/jobs/{job_id}job status and results
GET/trace/v3/comprehensive1/jobs/{job_id}comprehensive search status
GET/trace/v3/jobs/{job_id}/resultsfull results
GET/trace/v3/librarylegacy uploads
POST/trace/v3/uploadlegacy upload
Good to know
- Asynchronous. Every ingest and search returns
201with ajob_idstraight away; the work runs in the background. - Incremental ingestion. Layers a song already has are skipped, so you can add a new depth to a dataset later.
- Billing. Ingestion and searches are billed per job, based on usage, when the job completes. Failed jobs are not charged. Uploads, datasets and status checks are free.
- Mapping results to your files. Results name songs by a Trace audio ID. The dataset’s tracks list pairs each audio ID with the
file_idyou uploaded. - One model. Trace runs a single model, which appears as
type3in dataset responses. The earliertype1andtype2models are retired.