TaggingV7 Guide
Deprecated TaggingV7 is deprecated. For new integrations, use the Model Outputs approach to retrieve individual model results. This guide is retained for reference by existing integrations.
TaggingV7 is Cyanite's music analysis object that extracts detailed musical characteristics from your track. The following guide explains each field in the tagging response.
New to Cyanite? Start with the Quick Start Guide to upload your first track and retrieve taggings.
Understanding TaggingV7
TaggingV7 provides a wide range of musical classifiers ranging from genre and mood to instruments and BPM. Classifications are provided both as overall track-level data and as time-segmented data. The segmented data give a closer look into your music by showing how characteristics evolve over time.
There are two main types of data returned:
- Tags: Labels describing the track.
- Confidence scores: Values from 0 to 1 indicating how strongly a characteristic is present.
For example, a track might have the following mood data:
{
"mood": {
"happy": 0.85,
"energetic": 0.60,
...
},
"moodTags": ["happy", "energetic"]
}
Here, the mood object provides confidence scores for each mood, while the
moodTags array lists the dominant moods. In the example, the happy mood has a
high confidence of 0.85, indicating it's a strong characteristic of the track
while energetic is also present but to a lesser degree at 0.60.
Confidence scores are given for all taxonomies (except free genres) and can be used to understand the strength of each characteristic in the track while tags only list the dominant characteristics.
Track level versus segment level data
Track level data describe the overall characteristics of the track, while segment level data provide insights into a particular time interval in the track.
For example, a track may be classified as rock genre overall, but the
individual segments may reveal that certain parts of the song are closer to
pop or electronicDance genres. Similarly, a track may have an overall
happy mood, but the segments may show that the beginning is more calm while
the chorus is more energetic.
Additionally, the representativeSegmentIndex field indicates which segment
best represents the overall track characteristics.
The example below demonstrates a song with three segments. The track scores
highest for the ambient genre at the track level, but the segment data show
that the track progresses towards the rock genre in the later segments, with
the third segment being the most representative of the track overall.
{
"tagging": {
"version": "TaggingV7",
"advancedGenre": {
"ambient": 0.4021,
"rock": 0.334,
...
},
"segments": {
"representativeSegmentIndex": 2,
"timestamps": [
15,
30,
45
],
"advancedGenre": {
"ambient": [
0.4525,
0.2907,
0.2814
],
"rock": [
0.2639,
0.4199,
0.4507
],
...
}
}
}
}
The representativeSegmentIndex is indexed from 0. In the example
above, the third segment (index 2) is the most representative of the track
overall.
Genre
The genre classifier consists of genre, advancedGenre, subgenre,
advancedSubgenre with a fixed taxonomy and confidence scores. And a
freeGenreTags field without a fixed taxonomy or a confidence score.
A genre is the overall musical style (genre) of the track such as rock,
pop, or jazz, while subgenre provides a more specific classification
within a genre such as hardRock or synthPop. The freeGenre field may
return both main genres and subgenres or even niche genres not covered by a
fixed taxonomy. Such as post punk revival, jazz fusion, or darkwave. Due
to not having a fixed taxonomy, the freeGenreTags field does not provide
confidence scores.
The advanced genre classifiers have an extended taxonomy compared to the
non-advanced versions.
Genre and Advanced genre
The genre/genreTags and advancedGenre/advancedGenreTags fields detect
whether the track belongs to a particular genre.
The genre and genreTags fields are deprecated. Please use
advancedGenre and advancedGenreTags instead.
Available genres: ambient, blues, classical, electronicDance,
folkCountry, funkSoul, jazz, latin, metal, pop, rapHipHop,
reggae, rnb, rock, singerSongwriter
The advancedGenre and advancedGenreTags fields extend the taxonomy with 8
additional categories.
Available advanced genres: afro, ambient, arab, asian, blues,
childrenJingle, classical, electronicDance, folkCountry, funkSoul,
indian, jazz, latin, metal, pop, rapHipHop, reggae, rnb, rock,
singerSongwriter, sound, soundtrack, spokenWord
Below is an example of the advancedGenre with confidence scores and tags.
{
"advancedGenre": {
"pop": 0.80,
"electronicDance": 0.55,
"afro": 0.30,
...
},
"advancedGenreTags": ["pop", "electronicDance", "afro"]
}
Please note that while the genre will provide confidence scores for
all genres in the taxonomy, the genreTags array will only list the dominant
genres.
Subgenre and Advanced subgenre
The subgenre/subgenreTags and advancedSubgenre/advancedSubgenreTags
fields detect whether the track belongs to a particular subgenre. There may be
cases, where the track does not fit in a particular subgenre and the result will
be null.
The subgenre and subgenreTags fields are deprecated. Please use
advancedSubgenre and advancedSubgenreTags instead.
| Genre | Subgenres |
|---|---|
| Rock | bluesRock, folkRock, hardRock, indieAlternative, psychedelicProgressiveRock, punk, rockAndRoll, popSoftRock |
| Electronic | abstractIDMLeftfield, breakbeatDnB, deepHouse, electro, house, minimal, synthPop, techHouse, techno, trance |
| Hip-hop | contemporaryRnB, gangsta, jazzyHipHop, popRap, trap |
| Metal | blackMetal, deathMetal, doomMetal, heavyMetal, metalcore, nuMetal |
| Funk/Soul | disco, funk, gospel, neoSoul, soul |
| Jazz | bebop, bigBandSwing, contemporaryJazz, easyListening, fusion, latinJazz, smoothJazz |
| Folk/Country | country, folk |
The subgenre list above is comprehensive and the genre column reflects the strict hierarchical relationship between genres and subgenres. Subgenres are only detected within their corresponding parent genre (e.g., bluesrock under rock).
The advancedSubgenre classifier uses the same taxonomy as subgenre.
However, it is applied to the extended taxonomy of advancedGenre.
Moods (mood, moodAdvanced, tags)
The mood, moodTags, moodAdvanced, and moodAdvancedTags fields describe
the emotional character of the track. Similar to genre, there are advanced
classifiers with an extended taxonomy present.
Mood
The mood object scores 13 mood descriptors. The moodTags array lists the
dominant moods.
{
"mood": {
"happy": 0.78,
"energetic": 0.65,
"sad": 0.05,
...
},
"moodTags": ["happy", "energetic"]
}
Available moods: aggressive, calm, chilled, dark, energetic,
epic, ethereal, happy, romantic, sad, scary, sexy, uplifting
Advanced moods
The moodAdvanced and moodAdvancedTags fields provide an extended taxonomy
for a finer mood classification. Examples: adventurous, anthemic,
bittersweet, celebratory, dreamy and more.
Emotional metrics
In addition to moods, TaggingV7 also provides emotional metrics through the
valence, arousal, emotionalProfile, and emotionalDynamics fields.
| Field | Type | Description |
|---|---|---|
valence | 0–1 | Emotional positivity. Higher values indicate happier, more positive emotions. |
arousal | 0–1 | The energetic expressiveness of the emotion in the track. |
emotionalProfile | Tag | Overall character: negative, balanced, positive, or variable |
emotionalDynamics | Tag | How much emotion changes: low, medium, or high |
BPM & rhythm
The BPM and rhythm are described through bpm, timeSignature, and movement
fields. These fields provide insights into the track's speed, meter, and
rhythmic feel.
BPM
The bpmPrediction describes the detected tempo in beats per minute (BPM) along
with a confidence score while the bpmRangeAdjusted field doubles or halves
BPMs outside the range of 60-180.
{
"bpmPrediction": {
"value": 128,
"confidence": 0.95
},
"bpmRangeAdjusted": 128
}
| Field | Description |
|---|---|
bpmPrediction.value | Detected BPM (30–285 range) |
bpmPrediction.confidence | Reliability score (0–1) |
bpmRangeAdjusted | Doubles or halves BPMs outside the range of 60-180 |
Time signature
The timeSignature field indicates the track's meter (e.g., "4/4", "3/4").
{
"timeSignature": "4/4"
}
Movement
The movement object and movementTags array describe rhythmic feel:
| Tag | Description |
|---|---|
bouncy | Light, springy rhythm |
driving | Persistent forward momentum |
flowing | Smooth, continuous motion |
groovy | Strong rhythmic feel |
nonrhythmic | Ambient or free-form |
pulsing | Regular, repetitive beat |
robotic | Mechanical, precise rhythm |
running | Fast, energetic pace |
steady | Consistent, unchanging tempo |
stomping | Heavy, emphatic beats |
Key
The keyPrediction field identifies the musical key of the track along with a
confidence score.
{
"keyPrediction": {
"value": "aMinor",
"confidence": 0.87
}
}
Available keys: All 24 major and minor keys using the format
{note}{Major|Minor}. Examples: cMajor, fsMinor, bbMajor, gsMinor.
The s in the key names stands for sharp e.g., fsMinor is F-sharp
minor (F# minor), while b stands for flat e.g., abMajor is A-flat major (Ab
major).
Instruments
TaggingV7 provides three levels of instrument detection with increasing taxonomy:
- Instrument Presence and Tags - 9 instruments
- Advanced Instrument Presence and Tags - 10 instruments
- Advanced Instrument Presence and Tags Extended - 47 instruments
The instrumentPresence/instrumentTags and
advancedInstrumentPresence/advancedInstrumentTags fields are deprecated.
Please use advancedInstrumentPresenceExtended and
advancedInstrumentTagsExtended instead.
Instrument Presence and Tags
The instrumentTags classifier detects 9 instruments:
Instruments: percussion, synth, piano, acousticGuitar,
electricGuitar, strings, bass, bassGuitar, brassWoodwinds
The instrumentPresence classifier detects their presence throughout the track.
| Value | Meaning |
|---|---|
absent | Instrument is not present in the track |
partially | Instrument is occasionally present |
frequently | Instrument is often present |
throughout | Instrument is present in the whole track |
{
"instrumentPresence": {
"percussion": "throughout",
"synth": "frequently",
"piano": "absent",
"acousticGuitar": "absent",
"electricGuitar": "partially",
"strings": "absent",
"bass": "throughout",
"bassGuitar": "absent",
"brassWoodwinds": "absent"
},
"instrumentTags": ["percussion", "synth", "bass"]
}
Advanced instruments
The advancedInstrumentPresence object and advancedInstrumentTags array
detect 10 instruments, splitting brass and woodwinds:
Instruments: percussion, synth, piano, acousticGuitar,
electricGuitar, strings, bass, bassGuitar, woodwinds, brass
Extended instruments
The advancedInstrumentPresenceExtended and advancedInstrumentTagsExtended
classifier detects 47 instruments:
| Category | Instruments |
|---|---|
| Strings | strings, violin, cello, harp, sitar, mandolin, banjo, ukulele, doubleBass, asianStrings, luteOud, pizzicato |
| Keyboards | piano, electricPiano, harpsichord, churchOrgan, electricOrgan, celeste |
| Guitars | acousticGuitar, electricGuitar, bassGuitar |
| Synths | synth |
| Percussion | percussion, drumKit, electronicDrums, tabla, taiko, steelDrums, africanPercussion, bongoConga, bells, glockenspiel, marimba, vibraphone, xylophone |
| Winds | woodwinds, flute, clarinet, oboe, sax, asianFlute |
| Brass | brass, trumpet, frenchHorn, tuba |
| Other | accordion, bass |
Voice
Voice characteristics
| Field | Values | Description |
|---|---|---|
voicePresenceProfile | none, low, medium, high | How much vocals appear throughout the track |
predominantVoiceGender | female, male, none | Dominant vocal character |
voiceTags | Array | Labels: female, male, or instrumental |
We recommend using predominantVoiceGender.
Voice scores
The voice object provides continuous scores for vocal characteristics:
{
"voice": {
"female": 0.85,
"male": 0.12,
"instrumental": 0.03
}
}
Voiceover detection
| Field | Type | Description |
|---|---|---|
voiceoverExists | Boolean | Whether spoken word (talkover) is present |
voiceoverDegree | 0–1 | Confidence of voiceover detection |
Character
The character object and characterTags array describe the track's sonic
personality:
{
"character": {
"bold": 0.7,
"cool": 0.5,
"epic": 0.6,
...
},
"characterTags": ["bold", "epic", "warm"]
}
Available tags: bold, cool, epic, ethereal, heroic, luxurious,
magical, mysterious, playful, powerful, retro, sophisticated,
sparkling, sparse, unpolished, warm
Energy
| Field | Values | Description |
|---|---|---|
energyLevel | low, medium, high, variable | Overall intensity of the track |
energyDynamics | low, medium, high | How much energy varies throughout |
{
"energyLevel": "high",
"energyDynamics": "medium"
}
Era & epoch
The musical Era and Classical Epoch fields provide which time period the track
stylistically belongs to. The musicalEraTag field is available for all tracks,
while the classicalEpoch and classicalEpochTags fields are specific to
tracks where the genre classifier detected classical genre.
Musical era
The musicalEraTag field indicates when the track sounds like it was produced:
early / mid 1950s, mid / late 1950s, late 1950s / early 1960s,
early / mid 1960s, mid / late 1960s, late 1960s / early 1970s,
early / mid 1970s, mid / late 1970s, late 1970s / early 1980s,
early / mid 1980s, mid / late 1980s, late 1980s / early 1990s,
early / mid 1990s, mid / late 1990s, late 1990s / early 2000s,
early / mid 2000s, mid / late 2000s, late 2000s / early 2010s,
contemporary
Classical epoch
For tracks tagged as classical genre, the classicalEpoch and
classicalEpochTags fields identify the musical period. Returns null for
non-classical tracks.
Available epochs: middleAge, renaissance, baroque, classical,
romantic, contemporary
Auto-description
The transformerCaption field contains a natural language description of the
track:
{
"transformerCaption": "An energetic electronic dance track with driving synths, punchy percussion, and an uplifting vocal melody."
}
Segments
The segments object provides analysis at set time intervals in the track. This
data provides a more granular insights into the track for each TaggingV7 model.
{
"segments": {
"representativeSegmentIndex": 3,
"timestamps": [0, 15, 30, 45, 60],
"mood": {
"happy": [0.3, 0.5, 0.7, 0.8, 0.6],
"sad": [0.6, 0.4, 0.2, 0.1, 0.3]
},
"genre": {
"pop": [0.8, 0.85, 0.9, 0.88, 0.82]
},
"valence": [0.4, 0.5, 0.7, 0.8, 0.6],
"arousal": [0.3, 0.5, 0.8, 0.9, 0.7],
...
}
}
| Field | Description |
|---|---|
timestamps | Array of millisecond positions marking each segment |
representativeSegmentIndex | Index of the segment that best represents the track overall (indexed from 0) |
| All other fields | Arrays of scores aligned with timestamps |
Segment data is available for: mood, moodAdvanced, genre, advancedGenre,
subgenre, advancedSubgenre, instruments, advancedInstruments,
advancedInstrumentsExtended, movement, character, classicalEpoch,
voice, valence, arousal.