Compositores y colaboradores de pista (API)

Cuando crea una pista mediante la API pública de LabelGrid, describes a las personas que hay detrás con dos arrays separados: uno para los créditos de la canción (quién hizo qué) y otro para las reparticiones de publishing (quién posee la composición y su porcentaje). Esta guía explica qué espera cada array y las reglas que se aplican al crear una pista.

Dos arrays por pista

Cada pista lleva dos arrays independientes:

• contributors[] — créditos de la canción: quién hizo qué en la pista.
• writers[] — reparticiones de publishing: quién posee la composición y su porcentaje.

Ambos arrays hacen referencia a un perfil de compositor mediante writerId (camelCase) o writer_id (snake_case). Envíe exactamente uno de los dos — enviar ambos se rechaza. El ID debe coincidir con un compositor que posea.

Ambos arrays apuntan al mismo registro de compositores — los compositores que crea a través del endpoint Writers. Por tanto, un colaborador y un compositor de repartición de publishing hacen referencia al mismo registro de compositor subyacente.

contributors[] — obligatorio al crear

contributors[] es obligatorio al crear, con al menos una entrada. Cada entrada tiene:

• writerId / writer_id
• roles[] — de 1 a 3 roles, tomados de la lista de referencia de Roles de colaborador
• ai_contribution — none, partly o all

Reglas que se aplican al hacer POST de una pista:

• Cubrir las tres categorías de rol — entre sus colaboradores, debe haber al menos un rol de Intérprete (Performer), uno de Composición y letras (Composition & Lyrics) y uno de Producción e ingeniería (Production & Engineering).
• Al menos una persona — ai_contribution no puede ser all para todos los colaboradores.
• Sin IDs de compositor duplicados en el array de colaboradores.

writers[] — reparticiones de publishing (opcional al crear, obligatorio para distribuir)

writers[] es opcional para crear una pista, pero obligatorio para distribuir el lanzamiento: cada pista necesita al menos un compositor con rol Composer o Lyricist y un porcentaje, las reparticiones de cada pista deben sumar 100% y las pistas instrumentales no están exentas. Es decir, una pista se guarda sin problema sin compositores, pero un lanzamiento cuyas pistas no tengan ninguno no pasará la validación ni podrá aprobarse para su distribución.

Cada entrada tiene:

• writerId / writer_id
• roles[] — al menos un rol; los únicos valores permitidos son Composer y Lyricist
• percentage_share — un número de 0 a 100

Reglas:

• Las reparticiones deben sumar 100% — los valores de percentage_share de todos los compositores deben sumar 100.
• Sin IDs de compositor duplicados.
• Sin roles duplicados para un mismo compositor.

master_splits[] — reparticiones de grabación (las creamos por usted)

Las reparticiones de máster reparten los ingresos de la grabación. Igual que writers[], son obligatorias antes de poder distribuir un lanzamiento, pero, a diferencia de writers[], casi nunca tiene que enviarlas: si omite master_splits, LabelGrid crea una repartición por defecto para la pista con la participación predeterminada de su sello (50% salvo que la haya cambiado en el sello) y reparte el resto a partes iguales entre los artistas de la pista. Las reparticiones de máster se usan para la contabilidad de regalías dentro de LabelGrid y nunca se envían a las tiendas.

Si va a importar un catálogo de forma masiva, omita master_splits y deje que se apliquen los valores por defecto. Envíelo solo para las pistas que necesiten un reparto personalizado y, si la participación predeterminada de su sello no es la que quiere, cámbiela en el sello antes de importar.

Cuando sí lo envíe, cada entrada tiene:

• entity_type — label o artist
• entity_id — el ID de ese sello o artista
• percentage_share — un número de 0 a 100

Reglas:

• Al menos una entrada si el array está presente.
• Las reparticiones deben sumar 100%.

Precaución

En cuanto envía master_splits, el reparto es suyo: un array cuyos porcentajes no sumen 100% se rechaza y no se crea ninguna repartición por defecto para esa pista. Si no quiere un reparto personalizado, omita el campo por completo en lugar de enviar un array incompleto.

Un ejemplo mínimo

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

Errores comunes

• Use el plural roles, no role.
• Use percentage_share, no share.
• No envíe writerId y writer_id en la misma entrada.
• Para los compositores de repartición de publishing, solo se aceptan Composer y Lyricist como roles.
• Dejar writers[] fuera de una pista permite guardarla, pero bloquea la distribución más adelante: cada pista necesita al menos un compositor y las reparticiones deben sumar exactamente 100%.
• Enviar un array master_splits parcial: si no suma 100%, se rechaza. Omita el campo por completo y crearemos la repartición por defecto por usted.

Recursos relacionados

• Visión general de la API — endpoints, autenticación y la referencia completa (incluidos los datos de referencia de Roles de colaborador)
• Compositores y colaboradores — cómo funcionan los perfiles de compositor en su catálogo