Compositores e colaboradores de faixas (API)

Quando você cria uma faixa pela API pública do LabelGrid, descreve as pessoas por trás dela com dois arrays separados: um para os créditos da música (quem fez o quê) e outro para os splits de publishing (quem é dono da composição e qual a porcentagem). Este guia explica o que cada array espera e as regras que entram em ação quando você cria uma faixa.

Dois arrays por faixa

Cada faixa carrega dois arrays independentes:

• contributors[]: créditos da música, ou seja, quem fez o quê na faixa.
• writers[]: splits de publishing, ou seja, quem é dono da composição e qual a porcentagem.

Os dois arrays referenciam um perfil de compositor por writerId (camelCase) ou writer_id (snake_case). Envie exatamente um dos dois: enviar os dois é rejeitado. O ID precisa corresponder a um compositor que pertence a você.

Os dois arrays apontam para o mesmo registro de compositores: aqueles que você cria pelo endpoint Writers. Ou seja, um colaborador e um compositor de split de publishing referenciam o mesmo registro de compositor subjacente.

contributors[]: obrigatório na criação

contributors[] é obrigatório na criação, com pelo menos uma entrada. Cada entrada tem:

• writerId / writer_id
• roles[]: de 1 a 3 funções, escolhidas na lista de referência Contributor Roles
• ai_contribution: none, partly ou all

Regras que entram em ação quando você faz POST de uma faixa:

• Cubra as três categorias de função: entre os seus colaboradores, é preciso haver pelo menos uma função de Performer, uma de Composition & Lyrics e uma de Production & Engineering.
• Pelo menos um humano: ai_contribution não pode ser all para todos os colaboradores.
• Sem IDs de compositor duplicados no array de colaboradores.

writers[]: splits de publishing (opcional na criação, obrigatório para distribuir)

writers[] é opcional para criar uma faixa, mas obrigatório para distribuir o lançamento: cada faixa precisa de pelo menos um compositor com função Composer ou Lyricist e um percentual, os splits de cada faixa precisam somar 100% e as faixas instrumentais não são exceção. Ou seja, uma faixa é salva normalmente sem compositores, mas um lançamento cujas faixas não tenham nenhum não passa na validação e não pode ser aprovado para distribuição.

Cada entrada tem:

• writerId / writer_id
• roles[]: pelo menos uma função; os únicos valores permitidos são Composer e Lyricist
• percentage_share: um número de 0 a 100

Regras:

• Os splits devem somar 100%: os valores de percentage_share de todos os compositores precisam totalizar 100.
• Sem IDs de compositor duplicados.
• Sem funções duplicadas para um mesmo compositor.

master_splits[]: splits de master (a gente cria para você)

Os splits de master dividem a receita da gravação. Assim como writers[], eles são obrigatórios antes de um lançamento poder ser distribuído — mas, ao contrário de writers[], você quase nunca precisa enviá-los: se você omitir master_splits, a LabelGrid cria um split padrão para a faixa usando a participação padrão do seu selo (50%, a não ser que você tenha mudado isso no selo) e divide o restante igualmente entre os artistas da faixa. Os splits de master são usados na contabilidade de royalties dentro da LabelGrid e nunca são enviados às lojas.

Se você está importando um catálogo em massa, deixe master_splits de fora e use os valores padrão. Envie o campo só nas faixas que precisam de uma divisão personalizada — e, se a participação padrão do seu selo não for a que você quer, mude isso no selo antes de importar.

Quando você enviar, cada entrada tem:

• entity_type: label ou artist
• entity_id: o ID desse selo ou artista
• percentage_share: um número de 0 a 100

Regras:

• Pelo menos uma entrada se o array estiver presente.
• Os splits precisam somar 100%.

Cuidado

A partir do momento em que você envia master_splits, o split é seu: um array cujos percentuais não somam 100% é recusado, e nenhum split padrão é criado para aquela faixa. Se você não quer uma divisão personalizada, omita o campo por completo em vez de enviar um array incompleto.

Um exemplo 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
    }
  ]
}

Erros comuns

• Use o plural roles, não role.
• Use percentage_share, não share.
• Não envie writerId e writer_id na mesma entrada.
• Para compositores de split de publishing, só Composer e Lyricist são aceitos como funções.
• Deixar writers[] de fora de uma faixa salva normalmente, mas trava a distribuição depois: cada faixa precisa de pelo menos um compositor, e os splits precisam somar exatamente 100%.
• Enviar um array master_splits parcial: se não somar 100%, ele é recusado. Omita o campo por completo e a gente cria o split padrão para você.

Relacionados

• Visão geral da API: endpoints, autenticação e a referência completa (incluindo os dados de referência Contributor Roles)
• Compositores e colaboradores: como funcionam os perfis de compositor no seu catálogo