installers: add intro notice (main) and finish notice (rp)

- 메인 설치기: 첫 페이지로 "마인크래프트 런처를 끄고 시작해주세요" 안내(renderIntro)
  추가 후 다음 버튼으로 step1 진입.
- 리소스팩 설치기: 완료(step3) 페이지 문구를 "사용자 동의하에 리소스팩이
  설치되었습니다." + "리소스팩은 직접 적용해주세요." 로 변경.
v0.3.12.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

installer-rp/renderer.js

@@ -534,6 +534,7 @@ function renderStep3() {
   section.innerHTML =
     '<h2>' + escapeHtml(tt('step3.heading')) + '</h2>' +
     '<p class="formMessage">' + escapeHtml(tt('step3.message')) + '</p>' +
+    '<p class="formMessage">' + escapeHtml(tt('step3.applyNotice')) + '</p>' +
     (state.resourcepackPath
       ? '<p class="formMessage"><code>' + escapeHtml(state.resourcepackPath) + '</code></p>'
       : '') +

installer/renderer.js

@@ -96,6 +96,20 @@ function clearPage() {
   pageHost.innerHTML = ''
 }
 
+// 첫 진입 안내 페이지: 마인크래프트 런처를 끄고 시작하도록 안내.
+function renderIntro() {
+  setActiveStep(1)
+  clearPage()
+  var section = document.createElement('section')
+  section.className = 'page'
+  section.innerHTML =
+    '<h2>' + tt('intro.heading') + '</h2>' +
+    '<p class="formMessage">' + tt('intro.message') + '</p>' +
+    '<div class="actionRow"><button class="primaryBtn" id="introNext">' + tt('common.next') + '</button></div>'
+  pageHost.appendChild(section)
+  section.querySelector('#introNext').addEventListener('click', renderStep1)
+}
+
 function renderStep1() {
   setActiveStep(1)
   clearPage()
@@ -972,5 +986,5 @@ function escapeHtml(s) {
     I18N = (await installerApi.loadLocale()) || {}
   } catch (_) { I18N = {} }
   applyStaticI18n()
-  renderStep1()
+  renderIntro()
 })()

installer/styles.css

@@ -181,12 +181,15 @@ main {
   overflow-y: auto;
   font-size: 13px;
   line-height: 1.65;
+  /* 약관 본문은 더 진한 순백으로(제목/굵은글씨/목록). */
+  color: #fff;
 }
 .agreementBody h1, .agreementBody h2, .agreementBody h3 { margin: 12px 0 6px; }
 .agreementBody h1 { font-size: 17px; }
 .agreementBody h2 { font-size: 15px; }
 .agreementBody h3 { font-size: 14px; }
-.agreementBody p { margin: 6px 0; }
+/* 본문 문단은 기존 회색(--text-muted) 대신 이전 흰색 톤(#e6edf3)으로 올린다. */
+.agreementBody p { margin: 6px 0; color: #e6edf3; }
 .agreementBody ul, .agreementBody ol { margin: 6px 0; padding-left: 22px; }
 .agreementBody li { margin: 2px 0; }
 .agreementBody code { background: rgba(255,255,255,0.08); padding: 1px 4px; border-radius: 3px; font-family: 'Consolas', monospace; }

locales/installer-rp/ko-kr.json

@@ -63,7 +63,8 @@
   },
   "step3": {
     "heading": "완료",
-    "message": "리소스팩 설치를 완료했습니다."
+    "message": "사용자 동의하에 리소스팩이 설치되었습니다.",
+    "applyNotice": "리소스팩은 직접 적용해주세요."
   },
   "install": {
     "errorMessage": "설치 중 오류가 발생했습니다: {{message}}",

locales/installer/ko-kr.json

@@ -1,4 +1,8 @@
 {
+  "intro": {
+    "heading": "시작하기 전에",
+    "message": "마인크래프트 런처를 끄고 시작해주세요."
+  },
   "common": {
     "back": "이전",
     "next": "다음",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-music-quiz-installer",
-  "version": "0.3.6",
+  "version": "0.3.12",
   "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
   "main": "dist/installer/main.js",
   "scripts": {

scripts/build-launcher-icon.cjs

@@ -8,26 +8,45 @@
 // build/ 폴더는 electron-builder 가 exe 아이콘으로만 쓰고 asar 에
 // 포함되지 않아서, 런타임에 그 파일을 읽을 수 없다. 대신 빌드(개발) 시점에
 // 이 스크립트를 돌려 PNG 를 소스 코드에 인라인한다.
+//
+// 마인크래프트 런처의 사용자 지정 설치 아이콘 규격은 "128x128 PNG" 로
+// 고정돼 있다(https://minecraft.wiki/w/Launcher). 이 규격과 다른 크기
+// (예: 원본 256x256)를 주면 런처가 아이콘을 무시하고 기본 아이콘(화로)으로
+// 폴백한다. 그래서 build/icon.png 를 정확히 128x128 로 리사이즈해서 박는다.
+// exe 아이콘(build/icon.ico, build/icon.png)은 256x256 그대로 둔다.
 
 'use strict'
 
 const fs = require('node:fs')
 const path = require('node:path')
+const sharp = require('sharp')
 
 const repoRoot = path.resolve(__dirname, '..')
 const pngPath = path.join(repoRoot, 'build', 'icon.png')
 const tsPath = path.join(repoRoot, 'src', 'installer', 'launcherIcon.ts')
 
-const buf = fs.readFileSync(pngPath)
-const b64 = buf.toString('base64')
+const ICON_SIZE = 128
 
-const ts = `// AUTO-GENERATED by scripts/build-launcher-icon.cjs from build/icon.png.
+async function main() {
+  const buf = await sharp(pngPath)
+    .resize(ICON_SIZE, ICON_SIZE, { fit: 'cover' })
+    .png({ compressionLevel: 9 })
+    .toBuffer()
+  const b64 = buf.toString('base64')
+
+  const ts = `// AUTO-GENERATED by scripts/build-launcher-icon.cjs from build/icon.png.
 // 마인크래프트 런처의 "설치 설정" 화면에서 보이는 프로필 아이콘. exe 와 같은
-// 이미지를 쓰기 위해 빌드 시점에 PNG 를 data URL 로 인라인한다. 변경하려면
-// build/icon.png 교체 후 \`node scripts/build-launcher-icon.cjs\` 재실행.
+// 이미지를 ${ICON_SIZE}x${ICON_SIZE} 로 줄여 빌드 시점에 data URL 로 인라인한다.
+// 변경하려면 build/icon.png 교체 후 \`node scripts/build-launcher-icon.cjs\` 재실행.
 export const LAUNCHER_PROFILE_ICON =
   'data:image/png;base64,${b64}'
 `
 
-fs.writeFileSync(tsPath, ts, 'utf8')
-console.log(`wrote ${tsPath} (${buf.length} bytes PNG → ${b64.length} chars base64)`)
+  fs.writeFileSync(tsPath, ts, 'utf8')
+  console.log(`wrote ${tsPath} (${ICON_SIZE}x${ICON_SIZE}, ${buf.length} bytes PNG → ${b64.length} chars base64)`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

src/installer-rp/ffmpeg.ts

@@ -39,9 +39,15 @@ async function migrateLegacyExe(target: string): Promise<void> {
   }
 }
 
-/** BtbN/FFmpeg-Builds 의 win64-gpl 빌드. zip 내부에 bin/ffmpeg.exe 가 들어 있음. */
+/**
+ * BtbN/FFmpeg-Builds 의 win64-gpl 빌드. zip 내부에 bin/ffmpeg.exe 가 들어 있음.
+ * `releases/download/latest/` 형태(=항상 최신 자산이 붙어 있는 롤링 `latest` 태그)를
+ * 쓴다. `releases/latest/download/`(GitHub 의 "최신 릴리스" 자동 포인터)는 갓
+ * 만들어진 `autobuild-<날짜>` 릴리스로 리다이렉트되는데, 그 릴리스에 자산이 아직
+ * 업로드되지 않았거나 없으면 HTTP 404 가 나서 ffmpeg 설치가 실패한다.
+ */
 const FFMPEG_ZIP_URL =
-  'https://github.com/BtbN/FFmpeg-Builds/releases/latest/download/ffmpeg-master-latest-win64-gpl.zip'
+  'https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip'
 
 let installPromise: Promise<string> | null = null
 

src/installer-rp/images.ts

@@ -29,8 +29,35 @@ export function ytIdFromUrl(url: string): string {
   }
 }
 
-/** 단순 HTTP/HTTPS GET (302 따라감, 4xx/5xx 는 reject). */
-function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
+/**
+ * 일시적(transient) 으로 보고 재시도할 HTTP 상태코드.
+ * 429 = Too Many Requests (i.ytimg.com 썸네일 서버가 연속 요청을 속도제한).
+ * 5xx 게이트웨이 계열도 잠깐 뒤 다시 받으면 성공하는 경우가 많다.
+ */
+const TRANSIENT_CODES = new Set([408, 425, 429, 500, 502, 503, 504])
+const MAX_RETRIES = 5
+/** 백오프 상한(ms). Retry-After 헤더가 비정상적으로 커도 이 이상은 기다리지 않는다. */
+const MAX_BACKOFF_MS = 60000
+
+/** Retry-After 헤더(초 또는 HTTP-date) → 대기 ms. 못 읽으면 null. */
+function parseRetryAfter(h: string | string[] | undefined): number | null {
+  if (!h) return null
+  const v = Array.isArray(h) ? h[0] : h
+  const secs = Number(v)
+  if (Number.isFinite(secs)) return Math.min(MAX_BACKOFF_MS, Math.max(0, secs * 1000))
+  const date = Date.parse(v)
+  if (!Number.isNaN(date)) return Math.min(MAX_BACKOFF_MS, Math.max(0, date - Date.now()))
+  return null
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * 단순 HTTP/HTTPS GET (302 따라감).
+ * 429/5xx 등 일시적 오류는 지수 백오프(+jitter, Retry-After 우선)로 최대
+ * MAX_RETRIES 회 재시도한다. 그 외 4xx 나 재시도 소진 시 reject.
+ */
+function fetchBuffer(url: string, redirects = 0, attempt = 0): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     if (redirects > 8) {
       reject(new Error(t('common.tooManyRedirects')))
@@ -38,6 +65,11 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
     }
     const target = new URL(url)
     const lib = target.protocol === 'https:' ? https : http
+    const retryLater = (headerDelay: number | null): void => {
+      const backoff = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt) + Math.floor(Math.random() * 500)
+      const delay = headerDelay ?? backoff
+      sleep(delay).then(() => fetchBuffer(url, redirects, attempt + 1).then(resolve, reject))
+    }
     const req = lib.get(target, {
       timeout: 30000,
       headers: { 'user-agent': 'mc-music-quiz-rp-installer' }
@@ -45,10 +77,15 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
       const code = res.statusCode || 0
       if (code >= 300 && code < 400 && res.headers.location) {
         res.resume()
-        fetchBuffer(new URL(res.headers.location, target).toString(), redirects + 1)
+        fetchBuffer(new URL(res.headers.location, target).toString(), redirects + 1, attempt)
           .then(resolve, reject)
         return
       }
+      if (TRANSIENT_CODES.has(code) && attempt < MAX_RETRIES) {
+        res.resume()
+        retryLater(parseRetryAfter(res.headers['retry-after']))
+        return
+      }
       if (code !== 200) {
         res.resume()
         reject(new Error(`HTTP ${code}`))
@@ -58,7 +95,14 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
       res.on('data', (c: Buffer) => chunks.push(c))
       res.on('end', () => resolve(Buffer.concat(chunks)))
     })
-    req.on('error', reject)
+    req.on('error', (err) => {
+      // 연결 끊김/리셋 등 네트워크 오류도 몇 번은 재시도.
+      if (attempt < MAX_RETRIES) {
+        retryLater(null)
+        return
+      }
+      reject(err)
+    })
     req.on('timeout', () => req.destroy(new Error(t('common.requestTimeout'))))
   })
 }

src/server/datapack.ts

@@ -21,16 +21,18 @@ function aliasListSnbt(aliases: string[]): string {
   return `[${parts.join(',')}]`
 }
 
-/** 한 곡(MusicListEntry) → `{title:"...", author:"...", alias:[...], description:"...", volume:1.0}` SNBT. */
+/** 한 곡(MusicListEntry) → `{volume:0.5, title:"...", author:"...", alias:[...], description:"...", video:"..."}` SNBT. */
 function entrySnbt(entry: MusicListEntry): string {
   const title = escapeSnbtString(entry.title ?? '')
   // launcher 의 artist → 데이터팩 SNBT 의 author. 빈 값은 빈 문자열로 그대로 둔다.
   const author = escapeSnbtString(entry.artist ?? '')
   const alias = aliasListSnbt(entry.aliases ?? [])
   const description = escapeSnbtString(entry.description ?? '')
-  // launcher 가 생성하는 항목에는 volume 기본값 1.0 을 항상 넣는다.
+  // video = 곡의 유튜브 영상 주소(MusicListEntry.url).
+  const video = escapeSnbtString(entry.url ?? '')
+  // launcher 가 생성하는 항목에는 volume 기본값 0.5 를 항상 넣는다.
   // 운영자는 생성된 mcfunction 에서 곡별로 직접 값을 바꿔 사용한다.
-  return `{title:"${title}", author:"${author}", alias:${alias}, description:"${description}", volume:1.0}`
+  return `{volume:0.5, title:"${title}", author:"${author}", alias:${alias}, description:"${description}", video:"${video}"}`
 }
 
 /**
@@ -41,11 +43,11 @@ function entrySnbt(entry: MusicListEntry): string {
 export function buildSongsMcfunction(list: PackList): string {
   const lines: string[] = []
   lines.push('# 곡 한 개 = 한 줄.')
-  lines.push('#   필수 — title, author, alias, description')
+  lines.push('#   필수 — title, author, alias, description, video')
   lines.push('#   선택 — volume (이 곡만의 /playsound 음량. 미지정시 init/config.mcfunction')
   lines.push('#         의 audio.volume 사용)')
   lines.push('# 곡 순서가 리소스팩의 track_NN / cover_NN 인덱스와 1:1 매칭된다.')
-  lines.push('# 예) {title:"Quiet Song", author:"...", alias:[...], description:"...", volume:1.0}')
+  lines.push('# 예) {volume:0.5, title:"Quiet Song", author:"...", alias:[...], description:"...", video:"..."}')
   lines.push('data modify storage mq:main songs set value []')
   for (const entry of list.music) {
     lines.push(`data modify storage mq:main songs append value ${entrySnbt(entry)}`)