Writing Effective Queries

Supe reads natural language, so the quality of your results tracks closely with the quality of your input. A short word can be a valid starting point, but gives Supe less direction than a descriptive brief. Adding mood, genre, instrumentation, and intent helps focus the recommendations; it does not guarantee a match.

Think of a Supe query the way you would brief a music supervisor: describe the project, the feeling you are going for, and any musical preferences you already have in mind.

What a strong query includes

Supe translates your description into catalog filters, and uses creative context to guide recommendations. Include the details that matter to your project; adding every possible constraint can leave too few matches:

Use case: what the music is for (a travel vlog, a product ad, a meditation app, a sports highlight reel). This guides how Supe interprets everything else.
Mood: calm, uplifting, tense, triumphant, melancholy.
Genre or style: acoustic, cinematic, lo-fi hip hop, synthwave, folk.
Instruments: acoustic guitar, piano, strings, synth, or instruments to avoid such as no drums.
Character or texture: mellow, dreamy, building, aggressive, atmospheric.
Vocals: instrumental only, background vocals only, or lead vocals.
Energy and tempo: low energy and slow, or high energy and driving.
Musical key: only if you need a specific key, such as C major.

Weak query versus strong query

Each of these rewrites keeps the original intent but gives Supe far more to match against.

👎
Weak
sad

👍
Strong
Slow, melancholy piano for an emotional documentary moment. Sparse and reflective, instrumental, no drums.

👎
Weak
workout

👍
Strong
High-energy electronic track for a gym montage. Driving beat, punchy synths, fast tempo, no lead vocals.

👎
Weak
wedding

👍
Strong
Warm, romantic acoustic music for a wedding highlight film. Gentle fingerpicked guitar and soft strings, hopeful and heartfelt.

A template you can adapt

When in doubt, start from a full brief and trim what does not apply:

I need [type of music] for [project or scene]. The mood is [mood].
Think [genre or style]. Include [instruments], and [vocals or no vocals].
Keep the energy [low/medium/high] and the tempo [slow/moderate/fast].

Here is that template filled in:

I need music for a coffee brand ad set in a cozy morning cafe. The mood is
warm and inviting. Think bright indie folk. Include acoustic guitar and light
percussion, and no lead vocals. Keep the energy medium and the tempo moderate.

What leads to weak or empty results

These input patterns can make intent harder to interpret or narrow the available matches:

Fragments and partial words. A mid-typed token like aco may be ambiguous. Wait for a complete word or phrase rather than relying on Supe to infer unfinished input. If your interface sends input as the user types, see Integrating Supe Search for how to debounce so only complete queries reach the API.
A single broad word. One word such as music or happy can be interpreted broadly. Add a mood, a genre, or the use case to focus it.
A named artist or commercial track. Supe recommends music from the Soundstripe catalog; a reference to a commercial artist or song does not guarantee that recording is available. Such references may help communicate a style, but describe the mood, instrumentation, or energy you want rather than relying on an exact-name match.
A specific track length. The duration of your scene is not necessarily the duration of the source track. If you need music for a 15- or 30-second edit, describe the scene and musical direction rather than requiring a source recording of exactly that length. Mention track duration when it is a real selection constraint.
Too many requirements at once. Every detail narrows the pool, and stacking many at once (a genre plus several moods plus instruments plus a key) can leave nothing. Lead with the one or two things that matter most, then refine.
Unrelated text. Interface labels, boilerplate, or anything not about the music dilutes the query. Send only the creative brief.

Add context and reference imagery

query is only one of the inputs Supe accepts. You can pair it with scene context or upload reference images and video to ground the result in your actual project. See Create a search for the full request shape and Supe Search for an overview of how text, context, and assets combine.