트랙 작가 및 기여자 (API)

LabelGrid 공개 API로 트랙을 만들 때는 트랙에 참여한 사람을 두 개의 별도 배열로 설명합니다. 하나는 곡 크레딧(누가 무엇을 했는지)이고, 다른 하나는 퍼블리싱 지분(누가 작품을 소유하며 지분이 몇 퍼센트인지)입니다. 이 가이드에서는 각 배열에 무엇이 필요한지, 그리고 트랙을 만들 때 적용되는 규칙을 설명합니다.

트랙마다 두 개의 배열

각 트랙에는 서로 독립된 두 개의 배열이 들어갑니다.

contributors[]: 곡 크레딧. 트랙에서 누가 무엇을 했는지.
writers[]: 퍼블리싱 지분. 누가 작품을 소유하며 그 지분이 몇 퍼센트인지.

두 배열 모두 writerId(camelCase) 또는 writer_id(snake_case)로 작가 프로필을 참조합니다. 둘 중 하나만 보내세요. 둘 다 보내면 거부됩니다. 해당 ID는 본인이 소유한 작가와 일치해야 합니다.

두 배열은 동일한 작가 레지스트리, 즉 Writers 엔드포인트로 만든 작가들을 가리킵니다. 따라서 기여자와 퍼블리싱 지분의 작가는 같은 작가 레코드를 참조합니다.

`contributors[]`: 생성 시 필수

contributors[]는 생성 시 필수이며 항목이 하나 이상 있어야 합니다. 각 항목은 다음으로 구성됩니다.

writerId / writer_id
roles[]: Contributor Roles 참조 목록에서 선택한 1~3개의 역할
ai_contribution: none, partly, all 중 하나

트랙을 POST할 때 적용되는 규칙은 다음과 같습니다.

세 가지 역할 범주를 모두 포함: 기여자 전체에 걸쳐 Performer, Composition & Lyrics, Production & Engineering 역할이 각각 최소 한 명씩 있어야 합니다.
사람이 최소 한 명: 모든 기여자의 ai_contribution이 all일 수는 없습니다.
contributors 배열 안에 중복된 작가 ID가 없어야 합니다.

`writers[]`: 퍼블리싱 지분 (생성 시에는 선택, 배포하려면 필수)

writers[]는 트랙을 생성할 때는 선택이지만, 릴리스를 배포하려면 필수입니다. 각 트랙에는 Composer 또는 Lyricist 역할과 지분 비율을 가진 작가가 최소 한 명 있어야 하고, 트랙별 지분 합계는 100%여야 하며, 연주곡도 예외가 아닙니다. 즉, 작가 없이도 트랙은 문제없이 저장되지만, 트랙에 작가가 없는 릴리스는 검증을 통과하지 못하고 배포 승인도 받을 수 없습니다.

각 항목은 다음으로 구성됩니다.

writerId / writer_id
roles[]: 역할 하나 이상이며, 허용되는 값은 Composer와 Lyricist뿐입니다
percentage_share: 0에서 100 사이의 숫자

규칙은 다음과 같습니다.

지분 합계는 100%: 모든 작가의 percentage_share 값을 더하면 100이 되어야 합니다.
중복된 작가 ID가 없어야 합니다.
한 작가에게 중복된 역할이 없어야 합니다.

`master_splits[]`: 원반 지분 (저희가 대신 만들어 드립니다)

마스터 지분은 음원 수익을 나누는 기준입니다. writers[]와 마찬가지로 릴리스를 배포하기 전에 반드시 있어야 하지만, writers[]와 달리 직접 보내야 하는 경우는 거의 없습니다. master_splits를 생략하면 LabelGrid가 해당 트랙의 기본 지분을 만들어 줍니다. 레이블의 기본 지분(레이블에서 변경하지 않았다면 50%)을 배정하고, 나머지를 트랙 아티스트들에게 균등하게 나눕니다. 마스터 지분은 LabelGrid 내부의 로열티 정산에만 쓰이며 스토어로 전송되지 않습니다.

카탈로그를 대량으로 가져오는 경우에는 master_splits를 생략하고 기본값을 그대로 쓰세요. 별도의 분배가 필요한 트랙에만 보내면 되고, 레이블의 기본 지분이 원하는 값이 아니라면 가져오기 전에 레이블에서 먼저 변경하세요.

보내는 경우 각 항목은 다음으로 구성됩니다.

entity_type: label 또는 artist
entity_id: 해당 레이블이나 아티스트의 ID
percentage_share: 0에서 100 사이의 숫자

규칙은 다음과 같습니다.

배열을 포함한다면 항목이 최소 하나 있어야 합니다.
지분 합계는 100%여야 합니다.

최소 예시

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

자주 발생하는 오류

단수형 role이 아니라 복수형 roles를 사용하세요.
share가 아니라 percentage_share를 사용하세요.
같은 항목에 writerId와 writer_id를 함께 보내지 마세요.
퍼블리싱 지분 작가의 역할로는 Composer와 Lyricist만 허용됩니다.
트랙에서 writers[]를 빼면 저장은 되지만 나중에 배포가 막힙니다. 각 트랙에는 작가가 최소 한 명 필요하고, 지분 합계는 정확히 100%가 되어야 합니다.
일부만 채운 master_splits 배열을 보내는 경우. 합계가 100%가 아니면 거부됩니다. 필드를 통째로 생략하면 기본 지분을 저희가 만들어 드립니다.

트랙 작가 및 기여자 (API)

트랙마다 두 개의 배열

contributors[]: 생성 시 필수

writers[]: 퍼블리싱 지분 (생성 시에는 선택, 배포하려면 필수)

master_splits[]: 원반 지분 (저희가 대신 만들어 드립니다)

최소 예시

자주 발생하는 오류

관련 문서

`contributors[]`: 생성 시 필수

`writers[]`: 퍼블리싱 지분 (생성 시에는 선택, 배포하려면 필수)

`master_splits[]`: 원반 지분 (저희가 대신 만들어 드립니다)