Ingestion Requirements — Resomix Partner API

Everything you need in place before your catalogue can be ingested, grouped by the stage you are at. Each requirement says whether it is checked automatically — and therefore capable of rejecting a batch — or agreed with your Resomix contact.

If you are looking for the steps rather than the requirements, see Partner Onboarding. This page is the checklist behind those steps.

Validation is strict on purpose. A batch that half-imports is worse than one that is rejected: it leaves your index in a state neither side can describe. Anything that fails a check below stops the whole batch and returns the specific reason, the row number, and the ISRC or filename it applies to.

Stage 1 — Before partnership

Agreed with your Resomix contact. Nothing here is machine-checked.

Requirement	Why it matters
Rights to the recordings	You must own or be licensed to process every recording you deliver. Resomix analyses the audio to build your private index.
Catalogue scope	An approximate track count and expected growth rate. This sizes your index and your quota tier.
A named technical contact	The person who will receive credentials, run the first delivery, and be contacted if a batch fails.
Intended use	Which of the three query modes you plan to use — search, similarity-by-ID, similarity-by-upload — so your key is issued with the right scopes.

Stage 2 — Before your first ingestion

Requirement	Checked
SFTP credentials received and tested. Confirm you can connect and list directories before preparing a real batch.	Manual
Partner API key stored in a secrets manager. Never in source control, never in client-side code.	Manual
Agreement on `test/` vs `live/`. Deliveries land in one of two directories. Use `test/` for your first dry run.	Automatic

Your API key and SFTP credentials are tied to your organisation and grant access to your catalogue. Safeguarding them is your responsibility. If you suspect either has leaked, contact Resomix immediately so it can be rotated.

Stage 3 — Audio file requirements

Every one of these is checked automatically. A single failing file holds the entire batch.

Accepted formats

.wav, .flac, .mp3, .aiff

Anything else is rejected with INVALID_AUDIO_FORMAT. Note that .aif — the three-letter spelling — is not accepted; use .aiff.

The file must actually be audio

The extension is not taken on trust. Every file is probed with ffprobe and must contain a real, decodable audio stream with a duration above zero. A renamed text file, a truncated download, a video container, or a zero-byte placeholder fails with NOT_AUDIO.

Maximum length: 30 minutes

A track longer than 30 minutes is rejected with AUDIO_TOO_LONG. This is a hard limit of the analysis model, not a policy choice — very long files exhaust memory during embedding. DJ sets and continuous mixes need splitting before delivery.

Filenames must match the manifest exactly

The audio_filename column must match the delivered file character for character, including case and extension. A mismatch fails with MISSING_AUDIO_FILE.

The batch and the manifest must agree in both directions

A manifest row with no matching file → MISSING_AUDIO_FILE
A delivered file with no matching manifest row → EXTRA_FILE_NOT_IN_MANIFEST

Neither is treated as harmless. An unlisted file is either something you forgot to describe or something that should not have been sent.

Antivirus

Every file is scanned. An infected file fails the batch with AV_INFECTED, naming the threat.

If you deliver a `.zip`

Archives are accepted, with a strict allowlist applied before anything is extracted:

Rule	Failure code
Flat structure only — no folders, no nested paths	`ZIP_CONTAINS_FOLDER`
Only `.csv` and the four accepted audio formats inside	`DISALLOWED_ZIP_ENTRY`
No symbolic links	`ZIP_SYMLINK`
Uncompressed total under 10 GB, compression ratio under 100:1	`ZIP_BOMB`

Stage 4 — Manifest requirements

One UTF-8 CSV with a header row, one row per track. An empty file fails immediately with EMPTY_CSV; a header row missing any required column fails with MISSING_HEADERS before a single row is read.

Required columns

Every row must carry all four.

Column	Rule	Failure code
`isrc`	Present, and a valid ISRC: 2 alphabetic country characters, 3 alphanumeric registrant characters, then 7 digits (12 total). Case-insensitive.	`MISSING_ISRC` / `INVALID_ISRC_FORMAT`
`title`	Present, non-empty.	`MISSING_TITLE`
`display_artist`	Present, non-empty.	`MISSING_DISPLAY_ARTIST`
`audio_filename`	Present, and matches a delivered file.	`MISSING_AUDIO_FILENAME`

ISRCs must be unique within the batch. A repeat fails with DUPLICATE_ISRC_IN_BATCH. Comparison is case-insensitive, so USRC17607839 and usrc17607839 count as the same ISRC.

Optional columns

Supply them if you have them — but if a value is present it must be valid. A malformed optional field fails the batch just as a missing required one does. An empty cell is skipped entirely.

Column	Rule	Failure code
`bpm`	Integer between 30 and 300.	`INVALID_BPM` / `INVALID_BPM_FORMAT`
`duration_ms`	Positive integer, milliseconds.	`INVALID_DURATION` / `INVALID_DURATION_FORMAT`
`parental_warning`	Exactly one of `NoAdviceAvailable`, `NotExplicit`, `Explicit`, `ExplicitContentEdited`.	`INVALID_PARENTAL_WARNING`
`release_date`	`YYYY-MM-DD`.	`INVALID_RELEASE_DATE`
`audio_language`	Two characters — an ISO code, or `xx` when unknown.	`INVALID_LANGUAGE_CODE`
`is_explicit`	`0`, `1`, `true` or `false`.	`INVALID_IS_EXPLICIT`
`is_instrumental`	`0`, `1`, `true` or `false`.	`INVALID_IS_INSTRUMENTAL`
`p_line_year`	Integer between 1900 and 2100.	`INVALID_P_LINE_YEAR` / `INVALID_P_LINE_YEAR_FORMAT`
`upc_ean`	Exactly 12 or 13 digits.	`INVALID_UPC_EAN`
`genre`, `mix_name`, `version_title`	Free text.	—

Leave an optional column out entirely, or leave the cell empty, rather than guessing a value. An empty cell is skipped; a wrong one stops the batch.

Stage 5 — Delivering a batch

Requirement	Detail
Order of delivery	Audio files first, then the manifest, then the `.done` marker last.
`.done` is the trigger	Nothing is read until it arrives. A partial or interrupted transfer is therefore never ingested by mistake — if a delivery goes wrong, re-upload and place a fresh `.done` at the end.
One active batch at a time	A second `.done` while a batch is still processing is rejected. Wait for the current batch to reach a terminal state.
Delivery is atomic	Any failing check holds the whole batch. Nothing is partially indexed.

Validation runs in two passes. Cheap per-row checks (columns, formats, ranges) come first across the whole manifest; only rows that clear those are put through the expensive ffprobe and antivirus pass. This means a manifest with a typo in row 3 is reported without waiting for every file to be probed.

Stage 6 — After ingestion, and ongoing

Requirement	Detail
Wait for confirmation	Your catalogue is not queryable until you receive the confirmation email. Processing time scales with batch size.
Read the rejection report	If a batch fails you receive the specific error codes, the row numbers, and the ISRC or filename each applies to. Fix and re-deliver — there is no partial retry.
Top-ups follow the same rules	Adding tracks later means another batch: audio, manifest, `.done`. Every requirement on this page applies again. New tracks are added on top of the existing catalogue and the private index is rebuilt.
Stay within your quota	Query volume is subject to rate limits and monthly quotas. Ingestion volume is agreed per contract.

Pre-flight checklist

Run through this before sending your first .done:

Validation error reference

Every code that can stop a batch.

Manifest-level

Code	Meaning
`EMPTY_CSV`	The manifest file is empty.
`MISSING_HEADERS`	The header row is missing one or more required columns.

Required fields

Code	Meaning
`MISSING_ISRC`	Required `isrc` is empty.
`INVALID_ISRC_FORMAT`	Not a valid 12-character ISRC.
`DUPLICATE_ISRC_IN_BATCH`	The same ISRC appears more than once in this batch.
`MISSING_TITLE`	Required `title` is empty.
`MISSING_DISPLAY_ARTIST`	Required `display_artist` is empty.
`MISSING_AUDIO_FILENAME`	Required `audio_filename` is empty.

Audio

Code	Meaning
`INVALID_AUDIO_FORMAT`	Extension is not `.wav`, `.flac`, `.mp3` or `.aiff`.
`MISSING_AUDIO_FILE`	A manifest row references a file that was not delivered.
`EXTRA_FILE_NOT_IN_MANIFEST`	A delivered file is not described in the manifest.
`NOT_AUDIO`	The file has no decodable audio stream, or zero duration.
`AUDIO_TOO_LONG`	The track exceeds the 30-minute maximum.
`AV_INFECTED`	Antivirus flagged the file.

Optional fields

Code	Meaning
`INVALID_BPM` / `INVALID_BPM_FORMAT`	`bpm` is outside 30–300, or not an integer.
`INVALID_DURATION` / `INVALID_DURATION_FORMAT`	`duration_ms` is not a positive integer.
`INVALID_PARENTAL_WARNING`	Not one of the four allowed values.
`INVALID_RELEASE_DATE`	Not `YYYY-MM-DD`.
`INVALID_LANGUAGE_CODE`	`audio_language` is not two characters.
`INVALID_IS_EXPLICIT` / `INVALID_IS_INSTRUMENTAL`	Not `0`, `1`, `true` or `false`.
`INVALID_P_LINE_YEAR` / `INVALID_P_LINE_YEAR_FORMAT`	Outside 1900–2100, or not an integer.
`INVALID_UPC_EAN`	Not exactly 12 or 13 digits.