Autori e collaboratori di traccia (API)

Quando crei una traccia tramite l’API pubblica di LabelGrid, descrivi le persone che ci sono dietro con due array separati: uno per i crediti del brano (chi ha fatto cosa) e uno per le ripartizioni editoriali (chi possiede la composizione e la sua percentuale). Questa guida spiega cosa si aspetta ciascun array e le regole che si applicano quando crei una traccia.

Due array per traccia

Ogni traccia comprende due array indipendenti:

• contributors[] — crediti del brano: chi ha fatto cosa nella traccia.
• writers[] — ripartizioni editoriali: chi possiede la composizione e la sua percentuale.

Entrambi gli array fanno riferimento a un profilo autore tramite writerId (camelCase) o writer_id (snake_case). Invia esattamente uno dei due — inviarli entrambi viene rifiutato. L’ID deve corrispondere a un autore che possiedi.

Entrambi gli array puntano allo stesso registro di autori — gli autori che crei tramite l’endpoint Writers. Quindi un collaboratore e un autore di ripartizione editoriale fanno riferimento allo stesso record autore sottostante.

contributors[] — obbligatorio alla creazione

contributors[] è obbligatorio alla creazione, con almeno una voce. Ogni voce ha:

• writerId / writer_id
• roles[] — da 1 a 3 ruoli, presi dall’elenco di riferimento dei Ruoli collaboratore
• ai_contribution — none, partly o all

Regole che si applicano quando fai il POST di una traccia:

• Coprire tutte e tre le categorie di ruolo — tra i tuoi collaboratori deve esserci almeno un ruolo di Interprete (Performer), uno di Composizione e testi (Composition & Lyrics) e uno di Produzione e ingegneria (Production & Engineering).
• Almeno una persona — ai_contribution non può essere all per tutti i collaboratori.
• Nessun ID autore duplicato nell’array dei collaboratori.

writers[] — ripartizioni editoriali (facoltativo alla creazione, obbligatorio per distribuire)

writers[] è facoltativo per creare una traccia, ma obbligatorio per distribuire la release: ogni traccia ha bisogno di almeno un autore con ruolo Composer o Lyricist e una percentuale, le ripartizioni di ciascuna traccia devono totalizzare 100% e gli strumentali non fanno eccezione. Una traccia si salva senza problemi anche senza autori, ma una release le cui tracce non ne hanno nessuno non supera la validazione e non può essere approvata per la distribuzione.

Ogni voce ha:

• writerId / writer_id
• roles[] — almeno un ruolo; gli unici valori consentiti sono Composer e Lyricist
• percentage_share — un numero da 0 a 100

Regole:

• Le ripartizioni devono totalizzare 100% — i valori di percentage_share di tutti gli autori devono sommare a 100.
• Nessun ID autore duplicato.
• Nessun ruolo duplicato per uno stesso autore.

master_splits[] — ripartizioni del master (le creiamo noi per te)

Le ripartizioni del master dividono i ricavi della registrazione. Come writers[], sono obbligatorie prima che una release possa essere distribuita, ma, a differenza di writers[], quasi mai devi inviarle: se ometti master_splits, LabelGrid crea una ripartizione predefinita per la traccia usando la quota predefinita della tua etichetta (50% se non l’hai modificata sull’etichetta) e divide il resto in parti uguali tra gli artisti della traccia. Le ripartizioni del master servono alla contabilità delle royalty all’interno di LabelGrid e non vengono mai inviate agli store.

Se stai importando un catalogo in blocco, lascia fuori master_splits e affidati ai valori predefiniti. Invialo solo per le tracce che richiedono una divisione personalizzata e, se la quota predefinita della tua etichetta non è quella che vuoi, modificala sull’etichetta prima di importare.

Quando lo invii, ogni voce ha:

• entity_type — label o artist
• entity_id — l’ID di quell’etichetta o di quell’artista
• percentage_share — un numero da 0 a 100

Regole:

• Almeno una voce se l’array è presente.
• Le ripartizioni devono totalizzare 100%.

Attenzione

Nel momento in cui invii master_splits, la ripartizione è tua: un array le cui quote non totalizzano 100% viene rifiutato e per quella traccia non viene creata nessuna ripartizione predefinita. Se non vuoi una divisione personalizzata, ometti del tutto il campo invece di inviare un array incompleto.

Un esempio minimo

{
  "title": "Track One",
  "contributors": [
    {
      "writerId": "wr_123",
      "roles": ["Vocals", "Composer", "Producer"],
      "ai_contribution": "none"
    }
  ],
  "writers": [
    {
      "writerId": "wr_123",
      "roles": ["Composer", "Lyricist"],
      "percentage_share": 100
    }
  ]
}

Errori comuni

• Usa il plurale roles, non role.
• Usa percentage_share, non share.
• Non inviare writerId e writer_id nella stessa voce.
• Per gli autori di ripartizione editoriale, sono accettati come ruoli solo Composer e Lyricist.
• Lasciare writers[] fuori da una traccia consente di salvarla ma blocca la distribuzione più avanti: ogni traccia ha bisogno di almeno un autore e le ripartizioni devono totalizzare esattamente 100%.
• Inviare un array master_splits parziale: se non totalizza 100%, viene rifiutato. Ometti del tutto il campo e creeremo noi la ripartizione predefinita.

Risorse correlate

• Panoramica dell’API — endpoint, autenticazione e il riferimento completo (compresi i dati di riferimento dei Ruoli collaboratore)
• Autori e collaboratori — come funzionano i profili autore nel tuo catalogo