Trackschrijvers en bijdragers (API)

Wanneer je via de openbare LabelGrid API een track aanmaakt, beschrijf je de mensen erachter met twee aparte arrays: één voor songcredits (wie wat deed) en één voor publishingsplits (wie de compositie bezit en met welk percentage). Deze handleiding legt uit wat elke array verwacht en welke regels er gelden zodra je een track aanmaakt.

Twee arrays per track

Elke track draagt twee onafhankelijke arrays:

• contributors[]: songcredits, oftewel wie wat deed op de track.
• writers[]: publishingsplits, oftewel wie de compositie bezit en met welk percentage.

Beide arrays verwijzen naar een schrijversprofiel via writerId (camelCase) of writer_id (snake_case). Stuur er precies één van de twee mee; allebei meesturen wordt geweigerd. De ID moet horen bij een schrijver die jij bezit.

Beide arrays wijzen naar hetzelfde schrijversregister: de schrijvers die je aanmaakt via het Writers-endpoint. Een bijdrager en een schrijver met publishingsplit verwijzen dus naar hetzelfde onderliggende schrijversrecord.

contributors[]: verplicht bij aanmaken

contributors[] is verplicht bij het aanmaken, met minstens één item. Elk item bevat:

• writerId / writer_id
• roles[]: 1 tot 3 rollen, gekozen uit de referentielijst met bijdragerrollen
• ai_contribution: none, partly of all

Regels die in werking treden zodra je een track POST’t:

• Dek alle drie de rolcategorieën: over je bijdragers heen moet er minstens één Performer-rol, één Composition & Lyrics-rol en één Production & Engineering-rol zitten.
• Minstens één mens: ai_contribution mag niet voor elke bijdrager all zijn.
• Geen dubbele schrijvers-ID’s in de contributors-array.

writers[]: publishingsplits (optioneel bij aanmaken, verplicht om te distribueren)

writers[] is optioneel om een track aan te maken, maar verplicht om de release te distribueren: elke track heeft minstens één schrijver nodig met de rol Composer of Lyricist en een percentage, de splits per track moeten samen 100% zijn en instrumentals zijn niet uitgezonderd. Een track opslaan zonder schrijvers gaat dus prima, maar een release waarvan de tracks er geen hebben, komt niet door de validatie en kan niet worden goedgekeurd voor distributie.

Elk item bevat:

• writerId / writer_id
• roles[]: minstens één rol; de enige toegestane waarden zijn Composer en Lyricist
• percentage_share: een getal van 0 tot 100

Regels:

• De splits moeten samen 100% zijn: de percentage_share-waarden van alle schrijvers moeten optellen tot 100.
• Geen dubbele schrijvers-ID’s.
• Geen dubbele rollen voor dezelfde schrijver.

master_splits[]: mastersplits (die maken wij voor je aan)

Mastersplits verdelen de opbrengsten van de opname. Net als writers[] zijn ze verplicht voordat een release gedistribueerd kan worden — maar anders dan bij writers[] hoef je ze bijna nooit mee te sturen: laat je master_splits weg, dan maakt LabelGrid een standaardsplit voor de track aan met het standaardaandeel van je label (50%, tenzij je dat op het label hebt aangepast) en verdeelt het restant gelijk over de artiesten van de track. Mastersplits worden gebruikt voor de royaltyboekhouding binnen LabelGrid en gaan nooit naar de winkels.

Importeer je een catalogus in bulk, laat master_splits dan weg en gebruik de standaardwaarden. Stuur het alleen mee voor tracks die een afwijkende verdeling nodig hebben — en als het standaardaandeel van je label niet klopt, pas dat dan op het label aan vóór je importeert.

Stuur je het wel mee, dan bevat elk item:

• entity_type: label of artist
• entity_id: het ID van dat label of die artiest
• percentage_share: een getal van 0 tot 100

Regels:

• Minstens één item als de array aanwezig is.
• De splits moeten samen 100% zijn.

Opgepast

Zodra je master_splits meestuurt, is de split van jou: een array waarvan de aandelen niet samen 100% zijn wordt geweigerd, en er wordt voor die track geen standaardsplit aangemaakt. Wil je geen afwijkende verdeling, laat het veld dan helemaal weg in plaats van een onvolledige array te sturen.

Een minimaal voorbeeld

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

Veelvoorkomende fouten

• Gebruik het meervoud roles, niet role.
• Gebruik percentage_share, niet share.
• Stuur niet zowel writerId als writer_id mee op hetzelfde item.
• Voor schrijvers met een publishingsplit worden alleen Composer en Lyricist als rol geaccepteerd.
• writers[] weglaten bij een track slaat prima op, maar blokkeert de distributie later: elke track heeft minstens één schrijver nodig, en de splits moeten exact optellen tot 100%.
• Een gedeeltelijke master_splits-array meesturen: telt hij niet op tot 100%, dan wordt hij geweigerd. Laat het veld helemaal weg, dan maken wij de standaardsplit voor je aan.

Gerelateerd

• API-overzicht: endpoints, authenticatie en de volledige referentie (inclusief de referentiegegevens voor bijdragerrollen)
• Schrijvers en bijdragers: hoe schrijversprofielen werken in je catalogus