Preflight QC

Preflight QC는 전문적인 릴리스 품질 관리(QC)를 제공하는 프리미엄 추가 기능이에요. 릴리스를 제출하면 Preflight QC가 메타데이터, 발매일, 오디오, 아트워크, 라이선스 서류까지 처음부터 끝까지 분석해요. 명확하고 실행 가능한 품질 리포트를 받아 보고, 지적된 사항을 원하는 속도로 수정한 뒤, 만족스러울 때 릴리스를 검토로 확정하세요.

레이블과 API 연동 개발자에게 Preflight QC는 하나의 빌딩 블록이에요. 품질 리포트를 프로그램 방식으로 가져와 자체 QA 파이프라인에 연결하고, 내부 승인 프로세스의 관문으로 삼고, 릴리스를 자동으로 검토에 확정할 수 있어요. 품질 기준은 회원님의 팀이 정하고, 분석은 Preflight QC가 맡아요.

깨끗한 상태로 도착한 릴리스는 검토를 빠르게 통과해요. Preflight QC는 제출 전에 그 상태로 만들어 줘요.

Preflight QC란

계정에서 Preflight QC를 켜면, 유통을 위해 제출한 릴리스가 검토 대기열로 곧바로 들어가지 않아요. 대신 릴리스는 검토 전 대기(“회원님의 확인 대기 중”)로 들어가고, 그동안 Preflight QC가 품질 분석을 실행해요. 분석 대상은 메타데이터, 발매일, 오디오, 아트워크, 라이선스 서류예요. 그 결과가 품질 리포트이고, 이를 어떻게 활용할지는 회원님에게 달려 있어요.

• 자체 QA 워크플로(API). 카탈로그를 품질 분석에 통과시키고, 리포트를 프로그램 방식으로 가져와 자체 QA 파이프라인에서 처리하고, 그 결과를 내부 승인 프로세스의 관문으로 삼은 뒤, 자신의 기준을 통과한 릴리스만 검토로 확정하세요. 연동을 위한 API 사용하기를 참고하세요.
• 앱에서의 워크플로. 릴리스 페이지에서 리포트를 읽고, 지적된 사항을 수정한 뒤, 만족스러울 때 확정하세요.

어느 쪽이든 릴리스를 일반 검토 대기열로 옮기는 것은 확정이에요. 회원님이 승인하기 전에는 아무것도 검토에 들어가지 않아요.

Preflight QC는 검토 전에 품질 단계를 추가해요. 검토 이후의 흐름은 바뀌지 않아요. 확정하면 릴리스는 다른 릴리스와 동일한 검증 및 검토 절차를 거쳐요.

Preflight QC 사용 방법

Preflight QC는 저희 팀이 계정별로 활성화하는 프리미엄 추가 기능이에요. 회원님의 계정에서 켜려면 저희 영업 팀에 문의하시고 Preflight QC를 원한다고 알려 주세요.

활성화되면 다음에 릴리스를 유통을 위해 제출할 때 새로운 대기 및 확정 단계가 표시돼요.

Preflight QC 워크플로

Preflight QC를 켠 릴리스가 제출부터 검토까지 거치는 전체 흐름은 다음과 같아요.

1. 릴리스를 유통을 위해 제출하기

평소처럼 릴리스를 만들고 완성한 다음, 유통을 위해 제출하세요. Preflight QC가 켜져 있으면 이 동작은 릴리스를 즉시 검토 대기열에 넣지 않아요. 대신 릴리스는 검토 전 대기로 이동하고 회원님의 확인 대기 중으로 표시돼요.

2. 품질 분석이 실행됨

릴리스가 대기 중인 동안 Preflight QC가 해당 릴리스를 처음부터 끝까지 분석해요. 분석 범위는 다음과 같아요.

• 메타데이터: 제목, 아티스트, 크레딧, 그 밖의 릴리스 및 트랙 세부 정보
• 발매일: 발매일 설정과 릴리스 버전
• 오디오: 업로드한 오디오 파일
• 아트워크: 커버 이미지
• 라이선스: 커버, 샘플 또는 유사한 것에 증빙 서류가 필요한 경우

분석은 보통 업로드와 트랜스코딩이 완료된 후 몇 분 이내에 끝나요. 아직 실행 중인 동안 품질 리포트는 검사가 진행 중임을 표시하며 아직 문제를 나열하지 않아요.

3. 품질 리포트 읽기

분석이 끝나면 릴리스의 품질 리포트를 열어 주의가 필요한 사항이 있는지 확인하세요. 두 곳에서 읽을 수 있어요.

• 퍼블릭 API를 통해(자체 QA 파이프라인용). 아래의 API 사용하기를 참고하세요.
• 앱 내 릴리스 페이지.

리포트는 각 문제를 명확한 제목과 무엇을 수정해야 하는지 설명하는 메시지와 함께 나열해요. 각 필드를 읽는 방법은 품질 리포트 이해하기를 참고하세요.

4. 지적된 사항 수정하기

리포트의 문제를 하나씩 처리하세요.

• 메타데이터 문제: 릴리스나 트랙의 세부 정보를 편집하세요.
• 오디오 또는 아트워크 문제: 해당 파일을 교체하세요.
• 피드백을 요청하는 문제: 문제의 메모 스레드에 답글을 달거나, 요청된 서류(예: 커버나 샘플의 라이선스)를 업로드하세요.

릴리스가 대기 중인 동안 편집하면 분석의 관련 부분이 다시 실행되고, 리포트가 새로운 결과로 갱신돼요. 이 과정은 필요한 만큼 반복할 수 있어요.

5. 릴리스 확정하기

리포트가 깨끗해지면, 또는 필요한 사항을 모두 처리했으면 릴리스를 확정하세요. 앱에서는 릴리스의 확정 버튼이고, 연동에서는 확정 엔드포인트예요.

확정하면 릴리스가 대기에서 빠져나와 일반 검토 대기열로 이동해요. 확정하려면 분석이 완료되어 있어야 해요. 마지막 실행 이후 릴리스를 편집했다면, 확정하기 전에 갱신된 리포트를 기다리세요.

6. 일반 검토

확정 후 릴리스는 다른 릴리스와 똑같이 검토돼요. 검토 중에 어떤 일이 일어나는지, 소요 시간, 가능한 결과는 검증 및 검토를 참고하세요.

품질 리포트 이해하기

품질 리포트는 두 부분으로 이루어져 있어요. 문제 목록과, 분석 실행에 대한 작은 리포트 세부 정보 블록이에요.

문제

리포트의 각 문제는 살펴봐야 할 사항을 하나씩 설명해요. 회원님이 다루게 될 필드는 다음과 같아요.

필드	무엇을 알려주는지
제목	문제에 대한 짧고 알기 쉬운 이름.
메시지	문제가 무엇이며 어떻게 대처해야 하는지.
심각도	문제의 중요도로, 우선순위를 정하는 데 도움이 돼요.
차단(Blocking)	확정하기 전에 문제를 해결해야 하는지 여부(아래 참고).
피드백 필요	문제에 회원님의 서면 답변이나 업로드한 서류가 필요한지 여부.
맞춤 설명	제공되는 경우, 회원님의 릴리스에 고유한 추가 세부 정보.
영향받는 트랙	문제가 적용되는 트랙. 릴리스 수준의 문제는 특정 트랙을 나열하지 않아요.

차단 대 정보 제공

• 차단 문제는 릴리스를 검토로 확정하기 전에 해결해야 해요. 설명대로 수정하고 분석이 다시 실행되도록 하면 리포트에서 사라져요.
• 정보 제공 문제는 살펴볼 만한 점을 알리기 위한 것이지만, 확정을 막지는 않아요. 검토한 뒤 준비되면 확정하세요.

피드백이 필요한 문제

일부 문제는 편집만으로는 해결되지 않아요. 서면 설명이나 증빙 서류(예: 커버나 샘플의 라이선스)처럼 회원님으로부터 무언가가 필요해요. 이런 문제는 피드백 필요로 표시돼요. 해결하려면 확정하기 전에 문제의 메모 스레드에 답글을 달거나 요청된 서류를 업로드하세요.

리포트 세부 정보

문제와 함께, 리포트에는 분석 실행에 대한 몇 가지 세부 정보가 포함돼요.

필드	무엇을 알려주는지
generated_at	현재 리포트가 생성된 시각. 첫 분석이 아직 실행 중인 동안에는 비어 있어요.
checks_in_progress	분석이 아직 실행 중인 동안에는 true. 끝날 때까지 문제 목록은 비어 있어요.
hold	릴리스가 현재 검토 전 대기 상태인지 여부.
review_status	릴리스의 현재 검토 상태.
profile	이 릴리스에 적용된 품질 프로파일.

연동을 위한 API 사용하기

LabelGrid 퍼블릭 API 위에 개발하는 경우, Preflight QC를 자체 파이프라인에 연결할 수 있어요. 각 릴리스를 품질 분석에 통과시키고, 리포트를 자체 QA 워크플로로 가져오고, 내부 승인 프로세스의 관문으로 삼고, 자신의 도구에서 검토로 확정하세요. Preflight QC는 이를 위한 두 개의 엔드포인트를 제공하며, 둘 다 퍼블릭 API의 나머지 부분과 동일한 Bearer 토큰 인증을 사용해요. 완전하고 항상 최신인 요청 및 응답 스키마는 API 레퍼런스를 참고하세요.

품질 리포트 가져오기

GET /v4/public/음원/{id}/quality-report
Authorization: Bearer YOUR_API_TOKEN

릴리스의 현재 품질 리포트를 반환해요. 응답에는 다음이 포함돼요.

• issues[]: 문제당 한 개의 항목이며, 각각 code(안정적인 문자열, 문제 코드 다루기 참고), title, message, severity, is_blocking, requires_feedback, custom_description, affected_tracks를 포함해요.
• report: generated_at, checks_in_progress, hold, review_status, profile.

분석이 아직 실행 중인 동안 리포트는 빈 issues 목록과 함께 checks_in_progress: true를 반환해요. generated_at이 설정될 때까지 엔드포인트를 폴링하세요. 보통 업로드와 트랜스코딩이 끝난 후 몇 분이면 설정돼요. 그런 다음 문제를 읽으세요.

분석이 끝난 후의 응답 예시:

{
  "issues": [
    {
      "code": "example.issue-code",
      "title": "Short issue title",
      "message": "What to fix and how.",
      "severity": "…",
      "is_blocking": true,
      "requires_feedback": false,
      "custom_description": null,
      "affected_tracks": [456]
    }
  ],
  "report": {
    "generated_at": "2026-07-07T12:00:00Z",
    "checks_in_progress": false,
    "hold": true,
    "review_status": "…",
    "profile": "…"
  }
}

릴리스를 검토로 확정하기

POST /v4/public/음원/{id}/confirm-review
Authorization: Bearer YOUR_API_TOKEN

릴리스를 대기에서 빼내 일반 검토 대기열로 옮겨요. 앱의 확정 버튼에 해당하는 API예요.

확정하려면 분석이 완료되어 있어야 해요. 마지막 분석 실행 이후 릴리스가 편집되었다면 리포트가 다시 생성되는 중이고, 엔드포인트는 **충돌(conflict)**을 반환해요. 이 경우 품질 리포트를 다시 가져오고, generated_at이 다시 설정될 때까지 기다린 뒤 확정을 재시도하세요.

문제 코드 다루기

품질 리포트 위에 로직을 구축한다면 문제의 code를 기준으로 삼으세요.

• code는 안정적인 문자열이에요. 슬러그 형식(예: audio.trailing-silence)으로, 시스템에서 코드를 매핑하고 그 위에 로직을 구축해도 안전해요.
• 제목과 메시지는 사람이 읽는 문구예요. 시간이 지나면서 다듬어질 수 있으니, 로직을 텍스트에 의존하지 말고 표시 용도로만 사용하세요.
• 새로운 코드가 추가될 수 있어요. Preflight QC의 범위가 확장되면서 새 코드가 등장해요. 인식할 수 없는 코드는 일반적으로 처리하세요. 실패하는 대신 응답의 title과 message를 그대로 표시하면 돼요.
• 중요한 코드는 리포트가 알려줘요. 릴리스를 Preflight QC에 통과시키다 보면, 회원님의 카탈로그와 관련된 코드가 자신의 품질 리포트에 자연스럽게 나타나요.
• 분석이 다루는 범위. 문제는 다음 카테고리로 나뉘어요: 릴리스 및 트랙 메타데이터, 릴리스 날짜와 버전, 오디오 품질, 아트워크, 라이선스 및 서류.

문제 카탈로그

자체 QA 워크플로를 구축할 때 문제를 매핑하려면, 전체 카탈로그를 프로그램 방식으로 가져오세요.

GET /v4/public/issue-definitions
Authorization: Bearer YOUR_API_TOKEN

품질 리포트에 나타날 수 있는 모든 문제를 안정적인 문자열 코드를 키로 반환하며, 각 항목에는 제목, 메시지 템플릿, 심각도, 차단 플래그, requires_feedback가 포함돼요. 이 엔드포인트는 Preflight QC 추가 기능이 있는 계정만 사용할 수 있어요.

자주 묻는 질문

분석이 아직 실행 중이면 어떻게 되나요?

리포트는 아직 문제가 나열되지 않은 채로 checks_in_progress: true를 표시해요. 제출 직후에는 정상이에요. 업로드와 트랜스코딩이 끝난 후 몇 분 기다렸다가 다시 확인하세요. 앱에서는 리포트가 자동으로 갱신되고, API에서는 generated_at이 설정될 때까지 폴링할 수 있어요.

대기 중에 릴리스를 편집할 수 있나요?

네. 검토 전 대기에 있는 릴리스를 편집하면 분석의 관련 부분이 다시 실행되고 리포트가 갱신되므로, 대기에서 나가지 않고도 문제를 수정하고 갱신된 결과를 볼 수 있어요. 다만 편집 후에는 확정할 수 있게 되기 전에 갱신된 리포트를 기다려야 한다는 점만 기억하세요.

확정한 후에는 어떻게 되나요?

릴리스가 대기에서 나와 일반 검토 대기열에 들어가고, 다른 릴리스와 똑같이 검토돼요. 검토가 어떻게 진행되는지, 얼마나 걸리는지, 가능한 결과는 검증 및 검토를 참고하세요.

릴리스를 초안으로 되돌릴 수 있나요?

네. 릴리스가 검토 전 대기에 있고 아직 확정하지 않은 동안에는 검토에 들어간 것이 아니므로, 계속 편집하거나 초안으로 남겨 두었다가 나중에 다시 볼 수 있어요. 릴리스는 회원님이 확정할 때만 검토 대기열에 들어가요.

확정하기 전에 모든 문제를 수정해야 하나요?

확정할 수 있게 되기 전에 차단 문제는 해결해야 해요. 정보 제공 문제는 확정을 막지 않지만 살펴볼 가치가 있어요. 검토 전에 가능한 한 많이 정리해 두는 것이 승인으로 가는 가장 빠른 길이에요.

---

Preflight QC에 대해 궁금한 점이 있으신가요? 저희 팀에 문의하세요. 기꺼이 도와드릴게요.