빠른 시작
앱에서 만든 파일과 이 가이드 링크를 ChatGPT, Claude 같은 외부 AI에 함께 전달합니다.
YouTube는 이 단계에서 변경되지 않습니다.AI 분류는 내부 속성 후보를 저장할 뿐입니다. 실제 재생목록 변경은 규칙 계산, 미리보기, 사용자 승인, 적용 단계를 거칩니다.
요청 JSON
앱의 exporter가 생성하는 형식입니다. 사용자는 이 구조를 직접 편집할 필요가 없습니다.
값을 결정하는 기준instructions.allowedAttributes는 AI가 사용할 수 있는 속성 키를 제한하고, instructions.userClassificationCriteria는 문자열 속성에 어떤 값을 사용할지 정하는 사용자 기준입니다. AI는 두 값을 가장 먼저 확인하고 사용자 기준을 최우선으로 적용해야 합니다.
{
"format": "youtube-music-organizer-classification-request",
"schemaVersion": 1,
"createdAtMillis": 1799708400000,
"instructions": {
"task": "Classify each track only when evidence is sufficient. Use UNKNOWN by omitting uncertain attributes.",
"allowedAttributes": [
"contentType",
"longForm",
"mood",
"scene",
"source",
"style",
"vcScope",
"voice",
"voicebank"
],
"requiredOutputFormat": "youtube-music-organizer-classification-pack",
"requiredSchemaVersion": 1,
"confidenceRange": "0.0..1.0",
"minimumAcceptedConfidence": 0.9,
"doNotInventYoutubeIds": true,
"userClassificationCriteria": "동인 음악은 확인 가능한 서클·앨범·원작 근거가 있을 때만 scene=doujin으로 분류",
"outputExample": {
"format": "youtube-music-organizer-classification-pack",
"schemaVersion": 1,
"packVersion": "user-1",
"classifications": [
{
"youtubeId": "copy from tracks",
"attributes": {
"scene": "doujin",
"source": "touhou"
},
"confidence": 0.95,
"evidence": [
"short evidence"
]
}
]
}
},
"tracks": [
{
"youtubeId": "fake-uni-song",
"title": "Into the UNIverse",
"artistChannel": "Sample Producer",
"durationSeconds": 226,
"currentPlaylists": [
"UNI"
],
"note": "동인음악인지 확인"
}
]
}
요청 최상위 키
| Key | Type | Required | Allowed values | Description | Example |
|---|---|---|---|---|---|
format | string | 필수 | 고정 문자열 | 요청 파일 식별자 | youtube-music-organizer-classification-request |
schemaVersion | integer | 필수 | 1 | 요청 스키마 버전 | 1 |
createdAtMillis | integer | 필수 | Unix epoch milliseconds | 앱이 기록한 요청 생성 시각 | 1799708400000 |
instructions | object | 필수 | 아래 명세의 객체 | AI가 지켜야 할 출력 규칙과 사용자 설정 | {...} |
tracks | object[] | 필수 | 1개 이상 | 분류 요청 곡 목록 | [{...}] |
instructions 하위 키
| Key | Type | Required | Allowed values | Description | Example |
|---|---|---|---|---|---|
task | string | 필수 | exporter가 생성한 문자열 | 근거가 충분한 속성만 분류하라는 기본 지침 | Classify each track... |
allowedAttributes | string[] | 필수 | 현재 9개 속성 키 | 결과 attributes에 쓸 수 있는 키의 전체 목록 | ["scene","style",...] |
requiredOutputFormat | string | 필수 | 고정 문자열 | 결과 파일의 필수 format | youtube-music-organizer-classification-pack |
requiredSchemaVersion | integer | 필수 | 1 | 결과 파일의 필수 스키마 버전 | 1 |
confidenceRange | string | 필수 | 0.0..1.0 | confidence 허용 범위를 전달하는 지침 | 0.0..1.0 |
minimumAcceptedConfidence | number | 필수 | 0.9 | RuleEngine이 자동 사용할 최소 confidence | 0.9 |
doNotInventYoutubeIds | boolean | 필수 | true | 요청에 없는 ID 생성 금지 | true |
userClassificationCriteria | string | 필수 | 빈 문자열 또는 사용자 입력 | 다른 일반 예시보다 우선하는 사용자 분류 기준 | scene=doujin은 근거가 있을 때만... |
outputExample | object | 필수 | schema v1 결과 예시 | 현재 앱이 요구하는 결과 객체 모양 | {"format":..., ...} |
tracks[] 키
| Key | Type | Required | Allowed values | Description | Example |
|---|---|---|---|---|---|
youtubeId | string | 필수 | 앱에서 동기화된 원본 ID | 결과에 변경 없이 복사할 YouTube 식별자 | fake-uni-song |
title | string | 필수 | 원본 메타데이터 | 곡 또는 영상 제목 | Into the UNIverse |
artistChannel | string | 필수 | 원본 메타데이터 | 아티스트 또는 채널 | Sample Producer |
durationSeconds | integer | 필수 | 0 이상의 초 단위 값 | 콘텐츠 길이 | 226 |
currentPlaylists | string[] | 필수 | 0개 이상의 재생목록명 | 현재 포함된 실제 YouTube 재생목록 | ["UNI"] |
note | string | 필수 | 빈 문자열 또는 사용자 메모 | 곡별 사용자 지침 | 동인음악인지 확인 |
결과 JSON
앱의 importer가 읽는 전체 형식입니다. 실제 파일에는 JSON 앞뒤의 설명이나 Markdown 코드 펜스를 넣지 마세요.
{
"format": "youtube-music-organizer-classification-pack",
"schemaVersion": 1,
"packVersion": "docs-example-1",
"classifications": [
{
"youtubeId": "fake-uni-song",
"attributes": {
"voice": "vocal_synth",
"voicebank": "UNI",
"scene": "doujin",
"style": "electronic",
"source": "original",
"mood": "bright",
"contentType": "song",
"vcScope": true,
"longForm": false
},
"confidence": 0.95,
"evidence": [
"사용자 메모와 곡 메타데이터를 함께 확인"
]
}
]
}
결과 최상위 키
| Key | Type | Required | Allowed values | Description | Example |
|---|---|---|---|---|---|
format | string | 필수 | 고정 문자열 | 분류 결과 파일 식별자 | youtube-music-organizer-classification-pack |
schemaVersion | integer | 필수 | 1 | 현재 importer가 지원하는 버전 | 1 |
packVersion | string | 필수 | 공백이 아닌 1~100자 | 외부 AI가 결과 묶음을 구분하기 위해 만드는 식별용 버전. 앱은 값을 기록하지만 자동 생성하지 않음 | personal-2026-09-14-1 |
classifications | object[] | 필수 | 1~20,000개 | 곡별 분류 결과 배열 | [{...}] |
classifications[] 키
| Key | Type | Required | Allowed values | Description | Example |
|---|---|---|---|---|---|
youtubeId | string | 필수 | 요청에 포함되고 앱에 동기화된 1~128자 ID | 원본 요청에서 변경 없이 복사한 식별자. 중복 금지 | fake-uni-song |
attributes | object | 필수 | allowedAttributes의 키만 사용, 비어 있지 않음 | 근거가 있는 다중 속성 | {"scene":"doujin"} |
confidence | number | 필수 | 유한한 0.0~1.0 | schema v1에서 이 곡의 전체 attributes 객체에 적용되는 확신도 | 0.95 |
evidence | string[] | 선택 | 최대 20개, 각 500자 이하 | 생략하면 빈 배열로 저장되는 짧은 근거 | ["사용자 메모와 메타데이터가 일치"] |
packVersion은 결과 작성자가 만듭니다.같은 결과 묶음에는 하나의 안정적인 값을 사용하세요. 날짜와 순번을 조합한 personal-2026-09-14-1 같은 값이 권장됩니다. 현재 schema v1에서는 필수이며 앱이 대신 채우지 않습니다.
속성/허용 값
현재 validator는 아래 9개 키만 허용합니다. 문자열 속성은 고정 enum이 아니며 사용자의 분류 기준을 따르는 200자 이하 값입니다. 근거가 부족하면 UNKNOWN을 쓰지 말고 해당 키를 생략하세요.
| 키 | 타입 | 의미 | 예시 값 |
|---|---|---|---|
voice | string | 보컬 유형 | vocal_synth, human, instrumental |
voicebank | string | 보이스뱅크 또는 음성 캐릭터 | Hatsune Miku, UNI |
scene | string | 제작·유통 장면 | doujin, commercial, indie |
style | string | 음악 스타일 | electronic, rock, denpa |
source | string | 원작·프랜차이즈 또는 출처 | touhou, original |
mood | string | 분위기 | bright, dark |
contentType | string | 콘텐츠 형태 | song, mix, album, ost, clip |
vcScope | boolean | VC 관리 범위 포함 여부 | true |
longForm | boolean | 긴 형식 콘텐츠 여부 | false |
예시 값은 고정 enum이 아닙니다. 문자열 값은 요청 파일의 userClassificationCriteria를 우선해 정하고, 비어 있지 않은 경우에만 저장합니다. 공식 결과 파일에서 vcScope와 longForm은 따옴표 없는 JSON boolean만 사용합니다.
검증 규칙
- 결과 파일은 JSON 객체 하나여야 합니다. 설명문과
```json코드 펜스를 포함하지 않습니다. format,schemaVersion,packVersion,classifications이름을 바꾸거나 삭제하지 않습니다.- 원본
youtubeId를 그대로 사용하고, 요청에 없는 곡을 임의로 추가하지 않습니다. confidence는 문자열이 아니라0.0~1.0숫자로 작성합니다.- 허용되지 않은 속성 키를 만들지 않습니다. 문자열 속성은 200자 이하, boolean 속성은 true/false만 사용합니다.
- 확실하지 않은 속성은 생략합니다. 한 결과의
attributes가 완전히 비어 있으면 그 곡 결과 자체를 제외합니다. - 결과 파일은 10MB 이하, 분류 결과는 최대 20,000곡, 근거는 곡당 최대 20개입니다.
자동 사용 기준: confidence ≥ 0.90. 0.90 미만 결과도 가져오지만 RuleEngine에는 즉시 사용하지 않고 사용자 검토 대상으로 남깁니다. 사용자가 승인하면 신뢰도 1.0으로 저장됩니다.
confidence 모델
현재 schema v1은 곡 단위 confidence 하나를 사용합니다. 이 값은 해당 곡의 attributes 객체 전체에 적용됩니다. voice=0.99, style=0.65처럼 속성별 값을 보내면 v1 importer가 읽을 수 없습니다.
향후 schema v2 후보로 속성별 confidence를 검토합니다. 이번 변경에서는 v1 파일 형식과 importer 호환성을 유지하며 새 필드를 추가하지 않습니다.
AI 분류 지침
- 곡 하나에 여러 속성이 동시에 존재할 수 있습니다. 속성 하나만 고르는 단일 분류 문제가 아닙니다.
- 태그/내부 속성과 실제 YouTube 재생목록은 다른 개념입니다. 분류 결과 JSON에는 재생목록 변경을 넣지 않습니다.
currentPlaylists는 중요한 힌트지만 절대적인 정답은 아닙니다.- 사용자 메모와
userClassificationCriteria, 사용자가 직접 만든 규칙을 자동 추론보다 우선합니다. - 확실하지 않으면 억지로 추측하지 않고 해당 속성을 생략하며 confidence를 과장하지 않습니다.
longForm이나 Minor III 같은 관리 개념을 일반 음악 장르와 혼동하지 않습니다. Minor III는 속성이 아니라 사용자 재생목록 이름일 수 있습니다.- 한 곡은 여러 재생목록에 중복 배치될 수 있습니다.
- AI가 기존 YouTube 재생목록에서 곡을 자동 제거한다고 가정하지 않습니다. 자동 제거는 이 앱의 기본 동작이 아닙니다.
규칙 제작 지침
현재 앱은 규칙 JSON 가져오기를 지원하지 않습니다. AI가 규칙을 제안할 때는 아래 실제 Rule Builder 항목만 사용하고, 사용자가 앱 화면에 입력할 수 있는 형태로 설명해야 합니다.
조건 모델
| 구분 | 실제 지원 값 | 설명 |
|---|---|---|
| 조건 결합 | ALL, ANY | 모든 조건 만족 / 하나라도 만족 |
| field | YOUTUBE_ID, TITLE, ARTIST, CHANNEL, ALBUM, DURATION, CURRENT_PLAYLIST, ATTRIBUTE | 제목, 아티스트/채널, 앨범, 초 단위 길이, 현재 재생목록, 내부 속성 |
| operator | EQUALS, CONTAINS, STARTS_WITH, REGEX, GREATER_OR_EQUAL, LESS_OR_EQUAL, IN_PLAYLIST | 같음, 포함, 시작함, 정규식, 이상, 이하, 재생목록에 있음 |
| 속성 조건 값 | ATTRIBUTE_KEY=value | 예: SCENE=doujin. 키는 위 9개 AttributeKey의 대문자 이름 사용 |
실행 모델
| action | 대상 | 동작 |
|---|---|---|
ADD_PLAYLIST | 실제 재생목록 이름 | 재생목록 추가 추천 |
BLOCK_PLAYLIST | 실제 재생목록 이름 | 해당 재생목록 추가 차단 |
SUGGEST_REMOVE | 실제 재생목록 이름 | 제거를 추천하며 자동 제거하지 않음 |
EXCLUDE | 제외 사유 | Organizer 정리 대상에서 제외 |
LONG_FORM | 없음 | LONG_FORM=true 속성 설정 |
SET_ATTRIBUTE | AttributeKey + 값 | 내부 속성 설정 |
지원되는 규칙 예시
조건 방식: ALL
조건
CURRENT_PLAYLIST / EQUALS / UNI
실행
ADD_PLAYLIST / VC
ADD_PLAYLIST / vocal synth
이유
# UNI 곡을 관련 Playlist에 함께 정리
조건 방식: ANY
조건
DURATION / GREATER_OR_EQUAL / 1800
TITLE / CONTAINS / Mix
실행
LONG_FORM
ADD_PLAYLIST / Minor III
이유
# 긴 Mix 또는 장문 콘텐츠를 관리 Playlist에 정리
사용자 직접 규칙은 자동 분류 추론보다 우선합니다. 같은 우선순위에서는 차단 결과가 추가 결과보다 우선합니다.
AI에게 이 지침을 함께 전달하세요
앱에서 만든 요청 파일을 첨부한 뒤 아래 내용을 함께 보냅니다.
오류 해결
| 문제 | 원인 | 해결법 |
|---|---|---|
| JSON 형식 오류 | 설명문, Markdown 코드 펜스 또는 쉼표 오류가 있음 | {부터 }까지 유효한 JSON 객체 하나만 저장합니다. |
| 필수 키 누락 | format, schemaVersion, packVersion 또는 classifications가 없음 | 결과 전체 예시와 키 이름·대소문자를 동일하게 맞춥니다. |
| 잘못된 schema version | schemaVersion이 숫자 1이 아님 | 현재는 schema v1만 지원하므로 숫자 1을 사용합니다. |
| 잘못된 packVersion | 누락, 빈 문자열 또는 100자 초과 | 날짜와 순번 등을 사용해 비어 있지 않은 100자 이하 문자열을 만듭니다. |
| request에 없는 youtubeId | 요청 ID를 바꿨거나 앱에 동기화되지 않은 ID를 추가함 | 요청의 tracks[].youtubeId를 한 글자도 바꾸지 않고 복사합니다. |
| duplicate youtubeId | 같은 곡 결과가 classifications에 두 번 이상 있음 | 곡마다 결과 객체를 하나만 남깁니다. |
| boolean을 문자열로 반환 | "true" 또는 "false"처럼 따옴표를 사용함 | 공식 결과는 JSON boolean true/false를 사용합니다. importer의 문자열 허용은 이전 파일 호환용입니다. |
| invalid confidence | 문자열, NaN 또는 0.0~1.0 범위 밖 값 | 따옴표 없는 유한한 JSON number를 사용합니다. |
| unknown attribute | allowedAttributes에 없는 키를 생성함 | 현재 요청의 허용 키만 사용하고 불확실한 속성은 생략합니다. |
| 사용할 속성이 없음 | attributes가 비어 있거나 빈 문자열만 포함 | 근거 있는 속성을 하나 이상 넣거나 해당 곡 결과를 배열에서 제거합니다. |
| 파일이 너무 큼 | 결과 JSON이 10MB를 초과함 | 요청과 결과를 여러 파일로 나눕니다. |