From 26cc625de6ad671e0318b7ee434b9a364a7c505c Mon Sep 17 00:00:00 2001
From: claude-bot <claude-bot@tkrmagid.kr>
Date: Mon, 11 May 2026 11:22:49 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EB=A6=AC=EC=86=8C=EC=8A=A4=ED=8C=A9=20?=
 =?UTF-8?q?=EC=84=A4=EC=B9=98=EA=B8=B0=C2=B7=EC=9B=B9=EC=82=AC=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8=20=EC=B6=94=EA=B0=80=EC=82=AC=ED=95=AD=20=EC=A0=95?=
 =?UTF-8?q?=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

add.txt를 md로 옮기면서 비어 있던 칸을 채움:
- 이미지 다운로드 방식 (yt 썸네일 + 일반 URL)
- 리소스팩 패키징 흐름 (painting-variant.md 슬롯 규격에 맞춰 변환)
- 사진목록 UI: 반응형 그리드 카드 + 번호 배지 + 토글 입력
- /op/datapack mcfunction 출력 placeholder

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 docs/add.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 docs/add.md

diff --git a/docs/add.md b/docs/add.md
new file mode 100644
index 0000000..c2df94d
--- /dev/null
+++ b/docs/add.md
@@ -0,0 +1,140 @@
+# 추가사항: 음악퀴즈 리소스팩 간편설치기(exe) & 웹사이트
+
+기본 골격은 현행 음악퀴즈 간편설치기와 동일하므로 그쪽 코드 재활용.
+
+## 작동 방식
+
+`manifest.json` → 음악퀴즈 선택 → `file/list/<음악퀴즈>.json` 에서 음악·사진 목록을 가져온 뒤,
+yt-dlp로 음악 다운로드, 별도 경로로 사진 다운로드 → 리소스팩으로 패키징.
+
+---
+
+## 1. 리소스팩 간편설치기 (exe)
+
+번호가 붙은 단계는 "이전 / 다음"으로 이동 가능하게 한다.
+
+### 1) manifest 선택
+
+- `도메인/manifest.json` 에서 음악퀴즈 선택.
+- `file/list/<음악퀴즈>.json` 에서 다음을 로드:
+  - 음악 목록 (유튜브 영상 주소)
+  - 사진 목록 (유튜브 주소 또는 일반 이미지 주소)
+
+### 2) 리소스팩 설치
+
+- "다음"을 누르면 자동 시작.
+- 설치 로그 표시 (곡 제목이 아니라 `n번 노래 다운로드 중…` 형식).
+- 취소 버튼 / 창 닫기 / 강제 종료 시: 진행 중 다운로드를 안전하게 중단하고 임시 파일을 정리한 뒤 정상 종료.
+
+#### 2-1. yt-dlp 준비
+
+- 설치 경로: `%appdata%/.mc_custom/`
+- 이미 있으면 업데이트 확인 후 사용.
+- 시스템 PATH 에 이미 yt-dlp 가 등록돼 있으면 그것을 사용하고 업데이트 확인.
+
+#### 2-2. 음악 다운로드 (1번부터 순차)
+
+- 임시 경로: `%appdata%/.mc_custom/.temp/`
+- 각 곡을 `ogg` 로 변환 (Minecraft 사운드 호환 포맷).
+- 중단되거나 전부 끝나면 `.temp` 내용 삭제.
+
+#### 2-3. 사진 다운로드 (1번부터 순차) → painting variant 텍스처
+
+이미지는 두 형태로 들어올 수 있다.
+
+- **유튜브 주소**: yt-dlp 가 알려준 영상 ID 로
+  `https://i.ytimg.com/vi/<id>/maxresdefault.jpg` 를 1차 시도, 실패하면 `hqdefault.jpg` 로 폴백.
+- **일반 이미지 주소**: HTTP GET 으로 그대로 다운로드.
+
+다운로드 후 painting variant 슬롯 규격에 맞춰 정규화한다 (자세한 슬롯 구조는
+`docs/painting-variant.md` 참고).
+
+- 데이터팩에 슬롯 `cover_01 … cover_N` 이 미리 등록돼 있음. 각 슬롯의 가로·세로(블록 단위)는 고정.
+- 설치기는 이미지 N장을 받아 슬롯 N개의 PNG 로 변환:
+  - 목표 해상도 = `width * 16 × height * 16` (또는 그 정수배).
+  - 비율이 다르면 letterbox(투명 패딩)로 맞춰 잘림 방지.
+  - 파일명은 `cover_<NN>.png`, 저장 경로는 `resourcepack/assets/musicquiz/textures/painting/`.
+- 패키지 완성된 리소스팩을 `%appdata%/.minecraft/resourcepacks/` 에 zip 으로 배치.
+
+### 3) 설치 완료
+
+- "확인" 누르면 프로그램 종료.
+
+---
+
+## 2. 웹사이트 추가사항
+
+### /op/dashboard 상단
+
+- `[음악목록 수정]` 버튼 → `/op/list`
+- `[데이터팩 수정]` 버튼 → `/op/datapack`
+
+### /op/list
+
+- 상단 왼쪽에 `[돌아가기]` 버튼 → `/op/dashboard`.
+- `manifest.json` 에 등록된 음악퀴즈를 카드 한 줄(가로) 목록으로 표시. 표시 내용은 `/op/dashboard` 와 동일.
+- 카드 클릭 → `/op/list/:음악퀴즈`.
+
+### /op/list/:음악퀴즈
+
+상단에 **음악목록 / 사진목록** 두 탭. 기본 탭은 "음악목록".
+
+#### 음악목록 탭
+
+- 상단 버튼: `[목록 저장]`, `[목록 초기화]` (초기화 시 빈 목록).
+- 그 아래: 플레이리스트 주소 입력칸 + `[플레이리스트 불러오기]`.
+  - 클릭 시 "기존 순서가 전부 사라집니다" 경고 팝업(확인/취소). 확인 시 플레이리스트의 영상들을 아래 목록에 채움.
+- 목록 디자인: 유튜브 플레이리스트 스타일 (좌측 번호 배지 + 썸네일 + 제목·가수·길이).
+  - 항목 드래그로 순서(번호) 변경.
+  - 우클릭 메뉴: 수정, 삭제.
+  - "수정" 선택 시 팝업으로 새 유튜브 주소 입력.
+
+#### 사진목록 탭
+
+- 상단 버튼: `[목록 저장]`, `[목록 초기화]`.
+- 그 아래: 플레이리스트 주소 입력칸 + `[플레이리스트 불러오기]` (확인 팝업 동일).
+  - 불러오기 확정 시 플레이리스트 영상들의 **썸네일만** 추출해 목록에 채움.
+- 목록 디자인: 이미지가 크게 보이도록 **반응형 그리드(카드)** 형식.
+  - 카드 좌상단에 번호 배지, 본문은 정사각형 또는 4:3 썸네일.
+  - 카드 드래그로 위치 변경.
+  - 우클릭 메뉴: 수정, 삭제.
+  - "수정" 팝업 상단에 `[유튜브 주소] / [이미지 주소]` 토글 버튼, 선택한 종류의 입력칸 하나만 표시.
+
+### 저장 포맷: `/file/list/<음악퀴즈>.json`
+
+```json
+{
+  "musicPlaylistUrl": "https://www.youtube.com/playlist?list=...",
+  "imagePlaylistUrl": "https://www.youtube.com/playlist?list=...",
+  "music": [
+    {
+      "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
+      "title": "곡 제목",
+      "artist": "가수",
+      "durationSec": 213
+    }
+  ],
+  "images": [
+    { "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx" },
+    { "url": "https://example.com/cover.png" }
+  ]
+}
+```
+
+### /op/datapack
+
+- 상단 왼쪽에 `[돌아가기]` → `/op/dashboard`.
+- 상단에 `[음악퀴즈 선택]` 버튼. 클릭 시 팝업에 `manifest.json` 의 음악퀴즈를 카드 목록으로 표시, 하나 선택.
+- 선택 후: "총 N개의 음악을 찾았습니다." 텍스트 표시.
+- 아래 `[데이터팩 출력]` 버튼.
+  - 클릭 시 아래 코드 영역에 mcfunction 출력 + 복사 버튼 제공.
+  - **출력 포맷(임시, 실제 포맷은 추후 확정 예정)**:
+
+    ```mcfunction
+    # === musicquiz: <pack name> ===
+    # 총 N곡
+    say [musicquiz] 데이터팩 초기화
+    # 곡별 placeholder. 실제 포맷 확정되면 교체 예정.
+    # 1. <title> - <artist> (<duration>s)
+    # 2. ...
+    ```