Tutorial5 min di lettura

Annotazione per la classificazione dei generi musicali

Come creare un task di annotazione musicale in Potato: visualizzazione della forma d'onda, riproduzione di anteprime da 30 secondi, alberi gerarchici di generi e confronti a coppie tra preferenze.

Potato Team8 gennaio 2026

Le etichette di genere sono la benzina dei sistemi di raccomandazione, delle playlist generate in automatico e delle funzioni di scoperta musicale. Questo articolo mostra come costruire in Potato delle interfacce per taggare i generi, con anteprime audio e alberi di generi annidati.

Classificazione di genere di base

yaml

annotation_task_name: "Music Genre Classification"
task_dir: "."
 
data_files:
  - data/tracks.json
 
item_properties:
  id_key: track_id
  text_key: audio_preview
 
instance_display:
  fields:
    - key: artist
      type: text
      label: "Artist"
 
    - key: title
      type: text
      label: "Track"
 
    - key: audio_preview
      type: audio
      label: "Preview"
      display_options:
        controls: true
        show_waveform: true
 
annotation_schemes:
  - annotation_type: radio
    name: primary_genre
    description: "Select the primary genre"
    labels:
      - Rock
      - Pop
      - Hip-Hop
      - Electronic
      - Jazz
      - Classical
      - R&B
      - Country
      - Metal
      - Folk
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

Tassonomia di generi annidata

yaml

annotation_schemes:
  - annotation_type: radio
    name: genre
    description: "Primary genre"
    labels:
      - Rock
      - Electronic
      - Hip-Hop
      - Pop
      - Jazz
      - Classical
 
  - annotation_type: radio
    name: subgenre
    description: "Subgenre within the primary genre"
    labels:
      - Indie Rock
      - Punk
      - Metal
      - House
      - Techno
      - Drum & Bass
      - Boom Bap
      - Trap
      - Synth-pop
      - Bebop
      - Baroque
      - Romantic
      - Other

Tagging di genere multi-etichetta

Parecchi brani stanno in più di un genere, quindi lascia che gli annotatori ne scelgano diversi:

yaml

annotation_schemes:
  - annotation_type: multiselect
    name: genres
    description: "Select every genre that applies, up to three"
    labels:
      - Rock
      - Pop
      - Electronic
      - Hip-Hop
      - R&B
      - Jazz
      - Classical
      - Country
      - Folk
      - Metal
      - Punk
      - Indie
      - World
      - Latin
 
  - annotation_type: radio
    name: primary_genre
    description: "Which of the genres you selected is the primary one?"
    labels:
      - Rock
      - Pop
      - Electronic
      - Hip-Hop
      - R&B
      - Jazz
      - Classical
      - Country
      - Folk
      - Metal
      - Punk
      - Indie
      - World
      - Latin

Configurazione completa per l'annotazione musicale

yaml

annotation_task_name: "Music Tagging and Classification"
task_dir: "."
 
data_files:
  - data/music_library.json
 
item_properties:
  id_key: track_id
  text_key: preview_url
 
instance_display:
  layout:
    direction: vertical
    gap: 12px
 
  fields:
    - key: artist
      type: text
      label: "Artist"
 
    - key: title
      type: text
      label: "Track"
 
    - key: album
      type: text
      label: "Album"
 
    - key: year
      type: text
      label: "Year"
 
    - key: preview_url
      type: audio
      label: "Preview"
      display_options:
        controls: true
        show_waveform: true
 
annotation_schemes:
  - annotation_type: multiselect
    name: genres
    description: "Select all applicable genres"
    labels:
      - Rock
      - Pop
      - Electronic/Dance
      - Hip-Hop/Rap
      - R&B/Soul
      - Jazz
      - Classical
      - Country
      - Folk/Acoustic
      - Metal
      - Punk
      - Indie
      - World/International
      - Latin
      - Blues
      - Reggae
 
  - annotation_type: multiselect
    name: mood
    description: "Select the mood or moods of this track"
    labels:
      - Happy/Uplifting
      - Sad/Melancholic
      - Energetic
      - Calm/Relaxing
      - Aggressive
      - Romantic
      - Dark/Moody
      - Nostalgic
      - Motivational
 
  - annotation_type: likert
    name: energy
    description: "Energy level"
    size: 5
    min_label: "Very low energy"
    max_label: "Very high energy"
 
  - annotation_type: likert
    name: danceability
    description: "How danceable is this track?"
    size: 5
    min_label: "Not danceable"
    max_label: "Very danceable"
 
  - annotation_type: radio
    name: vocals
    description: "Vocal content"
    labels:
      - Instrumental only
      - Mostly instrumental
      - Balanced
      - Mostly vocals
      - Vocals dominant
 
  - annotation_type: radio
    name: era
    description: "Musical era or style"
    labels:
      - Pre-1970s
      - 1970s
      - 1980s
      - 1990s
      - 2000s
      - 2010s
      - 2020s
 
  - annotation_type: multiselect
    name: flags
    description: "Special flags, if any apply"
    labels:
      - Explicit content
      - Live recording
      - Remix or cover
      - Holiday/Seasonal
      - Soundtrack
      - Spoken word sections
    label_requirement:
      required: false
 
  - annotation_type: likert
    name: confidence
    description: "Confidence in your genre classification"
    size: 5
    min_label: "Uncertain"
    max_label: "Very confident"
 
annotation_instructions: |
  ## Music Tagging Guidelines
 
  ### Genre selection
  Choose one to three genres that describe the track. Prefer the most
  specific genre that fits, and fall back to a broader one when unsure.
 
  ### Mood
  Judge the overall emotional tone. A track can carry several moods.
 
  ### Energy and danceability
  Energy is tempo, intensity, and power. Danceability is rhythm, beat
  clarity, and groove. A slow track can be highly danceable.
 
  ### Listening
  Listen to at least 30 seconds, and listen past the intro. Drops and
  transitions are where the genre often becomes clear.
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

Formato di output

json

{
  "id": "track_001",
  "audio_url": "/audio/preview_001.mp3",
  "metadata": {
    "artist": "The Beatles",
    "title": "Here Comes the Sun",
    "album": "Abbey Road",
    "year": 1969
  },
  "annotations": {
    "genres": ["Rock", "Pop"],
    "mood": ["Happy/Uplifting", "Nostalgic"],
    "energy": 3,
    "danceability": 2,
    "vocals": "Balanced",
    "era": "Pre-1970s (Classic)",
    "flags": [],
    "confidence": 5
  }
}

Consigli per l'annotazione musicale

Le cuffie buone contano. Con gli altoparlanti del portatile ti sfuggono gli indizi di genere.
Tieni il volume costante, così non stai lì a regolarlo di continuo e non ti stanchi.
Ascolta abbastanza di ogni anteprima da cogliere i cambi, non solo l'intro.
Ripassati cosa vuol dire davvero ciascun genere prima di cominciare.
Fai delle pause. Con le orecchie stanche si giudica peggio.

Dove andare da qui

Aggiungi il rilevamento di eventi sonori per individuare gli strumenti
Imposta il crowdsourcing per portare sui dati orecchie più varie
Scopri le metriche di accordo per la musica

Per l'insieme completo delle opzioni di annotazione audio (visualizzazione della forma d'onda, controlli di riproduzione, selezione di regioni), vedi la documentazione sorgente.

Documentazione completa sull'audio in Annotazione Audio.