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
• producer_alias (facoltativo) — una stringa di massimo 255 caratteri, oppure null. Accredita l’autore con questo nome su questa traccia al posto del nome legale, come l’opzione Use Writer Alias nell’editor della traccia. Un valore non null richiede Producer tra i roles di quella voce. Ometti il campo per mantenere l’alias già salvato per quell’autore sulla traccia (compreso quello impostato nell’editor web); invia null per cancellarlo. use_producer_alias viene impostato dall’API a partire da questo campo, e qualsiasi valore inviato per quel campo viene ignorato. I collaboratori predefiniti degli artisti non memorizzano un alias, quindi lì producer_alias viene ignorato.

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.
• Un producer_alias non null su un collaboratore i cui roles non includano Producer restituisce 422, con l’errore su contributors.N.producer_alias.
• 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