Skip to main content

Understanding Search

Search is the Cyanite product that finds tracks in your Library by how they sound, not by matching keywords in titles or tags. You can search by a prompt, by one or several of your own tracks, or by a track on Spotify or YouTube, and narrow every search down with a metadata filter.

This page explains the idea behind it, how each search works, how to interpret the results and how metadata filters are applied. For step-by-step instructions, see the Search guide.

Public alpha (subject to change)

Search is a public alpha feature. The behavior described here may change before general availability.


Why search by meaning?​

Keyword search only finds what someone has written down. It depends on every track being tagged consistently, and on the person searching using the same words as the person who tagged the track. Music briefs rarely work that way: they describe a feeling ("hopeful, building, cinematic") or point to an example ("something like this track").

Cyanite's search compares the sound of your tracks with what you're looking for, so it finds suitable tracks even when their metadata doesn't contain the words of the brief.


How it works​

Every track in your Library is analyzed when you upload it. Part of that analysis is an audio embedding: a compact numerical fingerprint of how the track sounds. Tracks that sound alike have embeddings that lie close together.

Every search follows the same steps:

  1. Build a reference. Cyanite turns what you're looking for into an embedding: your text, your reference tracks, or an external track.
  2. Apply your filter. If you send a metadata filter, only the tracks in your Library that match it are considered.
  3. Rank by closeness. Cyanite finds the tracks whose embeddings are closest to the reference and returns them best match first, each with a score.

The search modes only differ in how they build the reference.

Search by Prompt​

Cyanite turns your text into an embedding with a model that places text and audio in the same space, so a description lies close to the tracks that sound like it. That's why a prompt can describe a mood, a scene or a use case ("tense underscore for a car chase") instead of listing genres and instruments.

Prompts in languages other than English are translated to English before the search.

Search by Track and Search by Tracks​

With a single reference track (Search by Track), the reference is that track's audio embedding. With several reference tracks (Search by Tracks), Cyanite blends them into one reference by averaging their embeddings, giving each track the same weight. The results then match the common thread across all references, not any one of them in particular. That's useful for a playlist or a moodboard, but it works best when the references have something in common: blending very different tracks leads to a reference that resembles none of them.

The reference tracks themselves never appear in the results.

Search by External Tracks​

Music briefs often point to a reference instead of describing it: "something like this song from the trailer", or "the vibe of this track, but something we can license". Search by External Tracks takes that reference as it is, a link to a track outside your Library, so you don't have to translate it into words or tags. Currently, Spotify track links and YouTube video links are supported.

Here the reference is a track that isn't in your Library. During the request, Cyanite:

  1. recognizes the track behind the link,
  2. retrieves an embedding of the recording,
  3. searches your Library with that embedding, as described above.

Because the reference is retrieved as part of the request, this search takes longer than a search from your own tracks.

What stays private:

  • The reference track is not added to your Library. It never shows up in your search results or library listings.
  • Results only ever come from your own Library, never from the external platform or other Cyanite customers.

A request can contain one link, and it can't be combined with tracks from your Library. Only individual tracks and videos are supported, not albums, playlists, artists or channels. Some recordings can't be retrieved, for example because they were removed. The request then fails with a 404.


What "similar" means​

Search by Track, Search by Tracks and Search by External Tracks judge similarity from the audio alone. Two tracks are similar when they sound alike: comparable genre and style, mood and energy, instrumentation, rhythm and production. The search doesn't take into account:

  • metadata such as the title, the artist, the label or the release year,
  • popularity or streaming numbers,
  • lyrics or the language of the vocals as text.

So a search by a famous song returns the tracks in your Library that sound like it, not cover versions or tracks by the same artist (unless they also sound alike).


Reading the score​

Each result carries a score between 0 and 1. A higher score means the result is closer to the reference: closer to your text for Search by Prompt, more similar to the reference track(s) for the other searches.

  • Use the score to order and compare results within one search, for example to show only the top matches or to see where the quality drops off.
  • Don't treat it as an absolute threshold across different searches. How high the best scores are depends on the reference and on your catalogue: a catalogue of orchestral music will score lower against a hip-hop reference than a catalogue of hip-hop tracks, even though the best results are still the best your Library has to offer.

Segment scores​

A track can match the reference in one part and not in another: a calm intro followed by an energetic chorus, for example. When you request segment scores, Cyanite compares the reference with each part of every result and returns the time ranges where the track is consistently close to it, best first.

Use them to start a preview at the part of the track that matches the brief, instead of at the beginning.


Results come from your Library only​

  • Search only returns tracks from your own Library, never tracks from other Cyanite customers or from streaming services.
  • Only tracks that have finished analysis can be found. A track you just uploaded appears in search once its analysis is complete.
  • Search returns the top results up to your limit in one response. There's no pagination. Narrow the search with a prompt or a filter instead of paging through a long list.

Which search to use​

SearchStarting pointUse it when
Search by PromptA text descriptionYou can describe the sound, mood or use case.
Search by TrackOne track from your LibraryYou want more like a track you already have.
Search by TracksUp to 10 tracks from your LibraryYou want the common thread of several examples.
Search by External TracksA link to an external trackThe brief references a track you don't own.

All searches return the same response shape and accept the same metadata filter and segment scores, so you can combine them in one workflow. For example, start from a prompt, then continue with a Search by Track from the best result.


Metadata filters​

A metadata filter restricts a search to the tracks in your Library that match structured criteria, such as a BPM range, a key or a genre. This section explains what a filter can see, how it's evaluated and what to watch out for. For step-by-step examples, see Filter by metadata.

Why combine search with a filter?​

Search ranks tracks by how they sound. Many briefs also have hard requirements that aren't about sound alone: a tempo that fits the edit, a key that fits the rest of the soundtrack, no vocals under a voiceover, or only tracks from a specific catalogue. A filter expresses those requirements exactly, while the search takes care of the rest.

What a filter can see​

When a track's analysis is finished, Cyanite stores a summary of the track next to its audio embedding. A filter can only use what's in that summary:

  • the track-level values of the model outputs, such as BpmV2.tag, KeyV2.tag or MainGenreV2.tags,
  • the custom tags of the Library Track (customTags).

Segment-level data, the scores maps of taxonomy classifiers and generated text aren't part of the summary, so you can't filter on them. For example, you can filter on whether energetic is among a track's dominant MoodSimpleV2.tags, but not on its energetic score. Fields lists every field.

Field names include the model version​

A field is named after the model output it comes from, as <ModelVersion>.<field>. BpmV2.tag is the tag field of the BpmV2 output.

The version is part of the name on purpose. A new version of a model can have a different vocabulary or a different scale, and naming the version makes sure a filter always means exactly one thing. When Cyanite releases a new model version, it comes with new field names, and you move your filters over when you move to the new version.

Fields​

Use the field names exactly as listed: they're case-sensitive. Each model output field is the track-level value of the model output with the same name. The linked vocabularies in the API Reference list every value a field can have.

Model output fields​

FieldTypeValues
AiMusicDetectionV1.isAiMusicbooleantrue, false
AudioFileInfoV1.durationnumberTrack duration in seconds
AugmentedKeywordsV3.tagsstring[]AugmentedKeywordsV3Tags
BpmV2.taginteger60-200
BpmV2.confidences.confidencenumber0.0-1.0
CharacterV2.tagsstring[]CharacterV2Tags
FreeGenreV3.tagsstring[]Free-form genre names, no fixed vocabulary
InstrumentsV2.tagsstring[]InstrumentsV2Tags
KeyV2.tagstringKeyV2Tags
KeyV2.confidences.confidencenumber0.0-1.0
MainGenreV2.tagsstring[]MainGenreV2Tags
MoodAdvancedV2.tagsstring[]MoodAdvancedV2Tags
MoodSimpleV2.tagsstring[]MoodSimpleV2Tags
MovementV2.tagsstring[]MovementV2Tags
MusicForV1.tagsstring[]MusicForV1Tags
MusicalEraV2.tagstringMusicalEraV2Tags
MusicalEraV2.estimatedProductionYearinteger1950-2024
SubgenreV2.tagsstring[]SubgenreV2Tags
TempoV1.tagstringTempoV1Tags
TempoV1.scorenumber0.0-1.0
TimeSignatureV2.tagstringTime signature, for example "4/4"
TimeSignatureV2.confidences.confidencenumber0.0-1.0
ValenceArousalV2.energyLevelstringValenceArousalV2EnergyLevelTags
ValenceArousalV2.energyChangesstringValenceArousalV2EnergyChangesTags
ValenceArousalV2.emotionProfilestringValenceArousalV2EmotionProfileTags
ValenceArousalV2.emotionChangesstringValenceArousalV2EmotionChangesTags
VocalsV2.tagsstring[]VocalsV2Tags
VocalsV2.vocalPresencestringVocalsV2PresenceTags
VocalsV2.predominantVocalGenderstringVocalsV2PredominantVocalGenderTags
VocalStyleV1.tagsstring[]VocalStyleV1Tags
VoiceoverV2.isVoiceoverDominantbooleantrue, false

Segment-level values, scores maps and the modelCertainty and predictionStability confidence values can't be filtered. AutoDescriptionV2, RepresentativeSegmentV2 and SegmentationV1 have no filterable fields.

Library Track fields​

FieldTypeValues
customTagsstring[]The custom tags you set on the Library Track (exact)

How a filter is applied​

The filter is applied before the ranking:

  1. Cyanite restricts the search to the tracks in your Library.
  2. It keeps only the tracks that match your filter.
  3. It ranks the remaining tracks by closeness to your prompt or reference tracks.

A filter doesn't sort or weight results. It decides which tracks take part in the ranking at all, and the results are the closest matches among the tracks that pass the filter. Two consequences:

  • A strict filter can return fewer results than your limit, or none at all, even though your Library has many tracks.
  • A filter never lowers the quality of the ranking. The best remaining match is always first.

Your filter is always combined with the restriction to your own Library, so not even an $or can return tracks from outside it.

Operators​

Which operators you can use depends on the type of the field.

OperatorMeaningNumberStringString[]Boolean
$eqEqual to the value✓✓✓ (contains the value)✓
$neNot equal to the value✓✓✓ (doesn't contain it)✓
$gtGreater than✓
$gteGreater than or equal to✓
$ltLess than✓
$lteLess than or equal to✓
$inEqual to any value in the list✓✓✓ (contains any of them)
$ninEqual to none of the values in the list✓✓✓ (contains none of them)
$existstrue: the track has the field. false: it doesn't have it✓✓✓✓

Logical operators​

OperatorMeaningExample
$andEvery condition in the array must match{ "$and": [{ "BpmV2.tag": { "$gte": 120 } }, { ... }] }
$orAt least one condition in the array must match{ "$or": [{ "TempoV1.tag": { "$eq": "fast" } }, { ... }] }

Several fields in the same object are combined with AND, so { "BpmV2.tag": { "$gte": 120 }, "KeyV2.tag": { "$eq": "aMinor" } } is the same as an $and of both conditions. $and and $or can be nested.

Always write a condition with an explicit operator, for example { "KeyV2.tag": { "$eq": "aMinor" } }.

Not supported​

$not, $all, $elemMatch, $regex, $size and other MongoDB operators that aren't listed above aren't supported, and a request that uses one fails with an error.

How conditions match​

Single values and lists​

Some fields hold a single value, like BpmV2.tag (a number) or KeyV2.tag (a string). Others hold a list, like MainGenreV2.tags or customTags, because a track can have several genres or tags.

On a list field, conditions look at the individual elements:

  • $in and $eq match if at least one element matches. A rock-and-pop track matches { "$in": ["rock", "jazz"] }.
  • $nin and $ne match if no element matches. The same track doesn't match { "$nin": ["pop"] }.

There's no operator that requires a list to contain all of several values. Write one $in condition per value and combine them with $and (see Require several tags).

Types matter​

Numbers are compared as numbers and strings as strings. A number sent as a string, like { "$eq": "120" }, is a different value from 120 and matches no BPM. $gt, $gte, $lt and $lte only compare numbers: a range on a text field, like { "KeyV2.tag": { "$gte": 5 } }, matches no track, and a range with a text operand, like { "$gte": "120" }, fails with an error.

Missing fields​

A track only has a field if the model output was produced for it:

  • the model isn't part of your account's analysis, or
  • the model had no answer for the track, like SubgenreV2 when no subgenre fits well enough.

A condition like $eq, $in or a range never matches a track that doesn't have the field. If you rely on $ne or $nin to exclude something, add { "$exists": true } on the same field when you want to be sure that only tracks with that field are returned.

Filters aren't checked against the field list​

Cyanite doesn't reject a filter because of an unknown field name or tag value. A filter like { "bpm": { "$gte": 120 } } or { "MainGenreV2.tags": { "$in": ["Rock"] } } is accepted, but no track has a bpm field or a Rock genre (the value is rock), so the search returns no results.

So a typo doesn't produce an error. When a filtered search returns nothing, check the field names and values first. Only filters that aren't JSON objects (422), use an unsupported operator or use a text value in a range, such as { "$gte": "120" } (500), fail with an error.

Coming from the Cyanite v1 API​

The v1 advancedSearch filter used the same operators but different, flat field names, like bpmPrediction or genreTags. In the REST API, fields are named after the model output they come from:

v1 fieldREST API field
bpmPredictionBpmV2.tag
keyPredictionKeyV2.tag
genreTagsMainGenreV2.tags
subgenreTagsSubgenreV2.tags
moodTagsMoodSimpleV2.tags
moodAdvancedTagsMoodAdvancedV2.tags
characterTagsCharacterV2.tags
movementTagsMovementV2.tags
instrumentTagsInstrumentsV2.tags
freeGenreTagsFreeGenreV3.tags
musicalEraTagMusicalEraV2.tag
customTagscustomTags

The vocabularies of the new model versions can differ from v1. Check the values in the vocabularies linked under Fields. valence and arousal have no numeric equivalent. Use the categorical ValenceArousalV2 fields such as ValenceArousalV2.energyLevel instead.


Further reading​