Track-Autoren & -Mitwirkende (API)

Wenn Sie einen Track über die öffentliche LabelGrid-API erstellen, beschreiben Sie die beteiligten Personen mit zwei separaten Arrays: eines für die Songcredits (wer was gemacht hat) und eines für die Verlagsanteile (wer die Komposition besitzt und mit welchem Prozentsatz). Diese Anleitung erklärt, was jedes Array erwartet, und die Regeln, die beim Erstellen eines Tracks gelten.

Zwei Arrays pro Track

Jeder Track enthält zwei unabhängige Arrays:

• contributors[] — Songcredits: wer was am Track gemacht hat.
• writers[] — Verlagsanteile: wer die Komposition besitzt und mit welchem Prozentsatz.

Beide Arrays verweisen über writerId (camelCase) oder writer_id (snake_case) auf ein Autorenprofil. Senden Sie genau eines von beiden — beide zu senden wird abgelehnt. Die ID muss zu einem Autor passen, den Sie besitzen.

Beide Arrays verweisen auf dasselbe Autorenregister — die Autoren, die Sie über den Writers-Endpunkt anlegen. Ein Mitwirkender und ein Verlagsanteil-Autor verweisen also auf denselben zugrunde liegenden Autorendatensatz.

contributors[] — beim Erstellen erforderlich

contributors[] ist beim Erstellen erforderlich, mit mindestens einem Eintrag. Jeder Eintrag hat:

• writerId / writer_id
• roles[] — 1 bis 3 Rollen aus der Referenzliste der Mitwirkenden-Rollen
• ai_contribution — none, partly oder all

Regeln, die bei einem Track-POST gelten:

• Alle drei Rollenkategorien abdecken — unter Ihren Mitwirkenden muss es mindestens eine Rolle als Interpret (Performer), eine für Komposition & Text (Composition & Lyrics) und eine für Produktion & Engineering (Production & Engineering) geben.
• Mindestens eine Person — ai_contribution darf nicht für jeden Mitwirkenden all sein.
• Keine doppelten Autoren-IDs im Mitwirkenden-Array.

writers[] — Verlagsanteile (beim Erstellen optional, für die Distribution erforderlich)

writers[] ist beim Erstellen eines Tracks optional, für die Distribution des Releases aber erforderlich — jeder Track braucht mindestens einen Autor mit der Rolle Composer oder Lyricist und einem Prozentanteil, die Anteile je Track müssen zusammen 100 % ergeben, und Instrumentals sind davon nicht ausgenommen. Ein Track lässt sich also ohne Autoren speichern, ein Release, dessen Tracks keine haben, besteht die Validierung jedoch nicht und kann nicht zur Distribution freigegeben werden.

Jeder Eintrag hat:

• writerId / writer_id
• roles[] — mindestens eine Rolle; die einzigen zulässigen Werte sind Composer und Lyricist
• percentage_share — eine Zahl von 0 bis 100

Regeln:

• Die Anteile müssen zusammen 100 % ergeben — die percentage_share-Werte aller Autoren müssen in Summe 100 ergeben.
• Keine doppelten Autoren-IDs.
• Keine doppelten Rollen für einen einzelnen Autor.

master_splits[] — Aufnahmeanteile (die legen wir für Sie an)

Master-Anteile teilen die Einnahmen aus der Aufnahme auf. Wie writers[] sind sie erforderlich, bevor ein Release distribuiert werden kann — anders als writers[] müssen Sie sie aber so gut wie nie senden: Wenn Sie master_splits weglassen, legt LabelGrid für den Track eine Standardaufteilung an, mit dem Standardanteil Ihres Labels (50 %, sofern Sie ihn am Label nicht geändert haben) und dem Rest zu gleichen Teilen auf die Künstler des Tracks verteilt. Master-Anteile dienen der Lizenzabrechnung innerhalb von LabelGrid und werden nie an Stores übermittelt.

Wenn Sie einen Katalog in großem Umfang importieren, lassen Sie master_splits weg und nutzen Sie die Standardwerte. Senden Sie das Feld nur für Tracks, die eine abweichende Aufteilung brauchen — und wenn der Standardanteil Ihres Labels nicht der gewünschte ist, ändern Sie ihn vor dem Import am Label.

Wenn Sie es doch senden, hat jeder Eintrag:

• entity_type — label oder artist
• entity_id — die ID dieses Labels oder Künstlers
• percentage_share — eine Zahl von 0 bis 100

Regeln:

• Mindestens ein Eintrag, wenn das Array vorhanden ist.
• Die Anteile müssen zusammen 100 % ergeben.

Achtung

Sobald Sie master_splits senden, gehört die Aufteilung Ihnen: Ein Array, dessen Anteile nicht 100 % ergeben, wird abgelehnt, und für diesen Track wird keine Standardaufteilung angelegt. Wenn Sie keine abweichende Aufteilung möchten, lassen Sie das Feld ganz weg, statt ein unvollständiges Array zu senden.

Ein minimales Beispiel

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

Häufige Fehler

• Verwenden Sie den Plural roles, nicht role.
• Verwenden Sie percentage_share, nicht share.
• Senden Sie nicht writerId und writer_id im selben Eintrag.
• Für Verlagsanteil-Autoren werden als Rollen nur Composer und Lyricist akzeptiert.
• writers[] bei einem Track wegzulassen, lässt sich zwar speichern, blockiert aber später die Distribution: Jeder Track braucht mindestens einen Autor, und die Anteile müssen genau 100 % ergeben.
• Ein unvollständiges master_splits-Array zu senden: Ergibt es nicht 100 %, wird es abgelehnt. Lassen Sie das Feld ganz weg, dann legen wir die Standardaufteilung für Sie an.

Verwandte Ressourcen

• API-Überblick — Endpunkte, Authentifizierung und die vollständige Referenz (einschließlich der Referenzdaten zu den Mitwirkenden-Rollen)
• Autoren & Mitwirkende — wie Autorenprofile in Ihrem Katalog funktionieren