gahusb/web-page-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 배치 음악 생성 + 자동 영상 파이프라인 spec + plan

Browse Source
This commit is contained in:
gahusb
2026-05-10 18:49:16 +09:00
parent 84548a326e
commit f074cbec2d
2 changed files with 1320 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

815
docs/superpowers/plans/2026-05-10-batch-music-generation.md Normal file
View File

@@ -0,0 +1,815 @@
# Batch Music Generation — Implementation Plan
> **For agentic workers:** Use `superpowers:subagent-driven-development`. Steps use `- [ ]` checkboxes.
**Goal:** 장르 1개로 N(1-10) 트랙 Suno 자동 순차 생성 + 자동 컴파일 + 영상 파이프라인 자동 시작.
**Architecture:** music-lab 신규 `batch_generator` 모듈이 BackgroundTask로 N회 Suno 호출 → compile_job 자동 생성 → orchestrator.run_step("cover") 자동 호출.
**Spec:** `docs/superpowers/specs/2026-05-10-batch-music-generation-design.md`
---
## File Structure
| 경로 | 책임 |
|------|------|
| `music-lab/app/db.py` (modify) | `music_batch_jobs` 테이블 + 5 헬퍼 |
| `music-lab/app/random_pools.py` (new) | 장르별 mood/instr/BPM/key/scale 랜덤 풀 + `randomize()` |
| `music-lab/app/batch_generator.py` (new) | `run_batch(batch_id)` 순차 오케스트레이션 |
| `music-lab/app/main.py` (modify) | 3개 endpoint (POST /generate-batch, GET /:id, GET 목록) |
| `web-ui/src/api.js` (modify) | 3개 헬퍼 |
| `web-ui/src/pages/music/components/BatchProgress.jsx` (new) | 진행 표시 컴포넌트 |
| `web-ui/src/pages/music/MusicStudio.jsx` (modify) | Create 탭에 배치 섹션 + 폴링 |
| `web-ui/src/pages/music/MusicStudio.css` (modify) | 배치 섹션 스타일 |
---
## Task 1: DB 테이블 + 헬퍼 + random_pools
**Files:**
- Modify: `music-lab/app/db.py`
- Create: `music-lab/app/random_pools.py`
- Test: `music-lab/tests/test_batch_db.py`
- [ ] **Step 1: random_pools.py 작성**
```python
"""장르별 음악 파라미터 랜덤 풀."""
import random
POOLS = {
"lo-fi": {
"moods": ["chill", "relaxing", "dreamy", "melancholic", "mellow", "nostalgic", "peaceful"],
"instruments_pool": ["piano", "synth", "drums", "vinyl", "rhodes", "soft bass", "ambient pads"],
"instruments_count": (3, 4),
"bpm": (70, 90),
"keys": ["C", "D", "F", "G", "A"],
"scales": ["minor", "major"],
"prompt_modifiers": ["cozy bedroom vibes", "rainy night", "late night study", "cafe ambience"],
},
"phonk": {
"moods": ["dark", "aggressive", "moody", "intense", "hypnotic"],
"instruments_pool": ["808 bass", "hi-hat", "synth lead", "vocal chops", "bass drops", "trap drums"],
"instruments_count": (3, 4),
"bpm": (130, 160),
"keys": ["C", "D", "F", "G"],
"scales": ["minor"],
"prompt_modifiers": ["drift atmosphere", "dark neon", "midnight drive"],
},
"ambient": {
"moods": ["peaceful", "meditative", "ethereal", "spacious", "dreamy"],
"instruments_pool": ["pad synths", "atmospheric guitar", "soft strings", "field recordings", "drone bass"],
"instruments_count": (2, 3),
"bpm": (50, 75),
"keys": ["C", "D", "E", "G", "A"],
"scales": ["major", "minor"],
"prompt_modifiers": ["misty mountain morning", "deep space", "still water", "forest dawn"],
},
"pop": {
"moods": ["uplifting", "happy", "energetic", "romantic", "catchy"],
"instruments_pool": ["acoustic guitar", "piano", "drums", "bass", "synth", "vocals harmonies"],
"instruments_count": (3, 5),
"bpm": (95, 130),
"keys": ["C", "D", "E", "F", "G", "A"],
"scales": ["major"],
"prompt_modifiers": ["radio-ready", "summer vibe", "feel-good"],
},
"default": {
"moods": ["chill", "relaxing", "uplifting", "mellow"],
"instruments_pool": ["piano", "synth", "drums", "guitar", "bass", "strings"],
"instruments_count": (3, 4),
"bpm": (80, 110),
"keys": ["C", "D", "F", "G", "A"],
"scales": ["minor", "major"],
"prompt_modifiers": [""],
},
}
def randomize(genre: str, rng=None) -> dict:
rng = rng or random.Random()
pool = POOLS.get(genre.lower(), POOLS["default"])
n_instr = rng.randint(*pool["instruments_count"])
instruments = rng.sample(pool["instruments_pool"], min(n_instr, len(pool["instruments_pool"])))
return {
"moods": [rng.choice(pool["moods"])],
"instruments": instruments,
"bpm": rng.randint(*pool["bpm"]),
"key": rng.choice(pool["keys"]),
"scale": rng.choice(pool["scales"]),
"prompt_modifier": rng.choice(pool["prompt_modifiers"]),
}
```
- [ ] **Step 2: DB 테이블 + 헬퍼 추가** (db.py)
`init_db()`에 추가:
```python
cursor.execute("""
CREATE TABLE IF NOT EXISTS music_batch_jobs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
genre TEXT NOT NULL,
count INTEGER NOT NULL,
target_duration_sec INTEGER NOT NULL DEFAULT 180,
auto_pipeline INTEGER NOT NULL DEFAULT 1,
completed INTEGER NOT NULL DEFAULT 0,
track_ids_json TEXT NOT NULL DEFAULT '[]',
current_track_index INTEGER NOT NULL DEFAULT 0,
current_track_status TEXT,
status TEXT NOT NULL DEFAULT 'queued',
error TEXT,
compile_job_id INTEGER,
pipeline_id INTEGER,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
)
""")
```
`db.py` 끝에 헬퍼:
```python
_BATCH_ALLOWED_COLS = frozenset([
"completed", "track_ids_json", "current_track_index",
"current_track_status", "status", "error",
"compile_job_id", "pipeline_id",
])
def create_batch_job(genre: str, count: int, target_duration_sec: int = 180,
auto_pipeline: bool = True) -> int:
with _conn() as conn:
now = _now()
cur = conn.cursor()
cur.execute("""
INSERT INTO music_batch_jobs
(genre, count, target_duration_sec, auto_pipeline,
status, created_at, updated_at)
VALUES (?, ?, ?, ?, 'queued', ?, ?)
""", (genre, count, target_duration_sec, 1 if auto_pipeline else 0, now, now))
return cur.lastrowid
def get_batch_job(batch_id: int) -> dict | None:
with _conn() as conn:
row = conn.execute(
"SELECT * FROM music_batch_jobs WHERE id = ?", (batch_id,)
).fetchone()
if not row:
return None
d = dict(row)
d["track_ids"] = json.loads(d.get("track_ids_json") or "[]")
return d
def update_batch_job(batch_id: int, **fields) -> None:
unknown = set(fields) - _BATCH_ALLOWED_COLS
if unknown:
raise ValueError(f"unknown batch job columns: {unknown}")
cols = ", ".join(f"{k} = ?" for k in fields)
vals = list(fields.values()) + [_now(), batch_id]
with _conn() as conn:
conn.execute(
f"UPDATE music_batch_jobs SET {cols}, updated_at = ? WHERE id = ?",
vals,
)
def append_batch_track(batch_id: int, track_id: int) -> None:
"""track_ids_json에 새 track_id 추가 + completed += 1 (atomic)."""
with _conn() as conn:
row = conn.execute(
"SELECT track_ids_json, completed FROM music_batch_jobs WHERE id = ?",
(batch_id,),
).fetchone()
if not row:
return
ids = json.loads(row["track_ids_json"] or "[]")
ids.append(track_id)
conn.execute(
"UPDATE music_batch_jobs SET track_ids_json = ?, completed = ?, updated_at = ? WHERE id = ?",
(json.dumps(ids), row["completed"] + 1, _now(), batch_id),
)
def list_batch_jobs(active_only: bool = False) -> list[dict]:
sql = "SELECT * FROM music_batch_jobs"
if active_only:
sql += " WHERE status NOT IN ('failed','cancelled','piped')"
sql += " ORDER BY created_at DESC"
with _conn() as conn:
rows = conn.execute(sql).fetchall()
out = []
for r in rows:
d = dict(r)
d["track_ids"] = json.loads(d.get("track_ids_json") or "[]")
out.append(d)
return out
```
- [ ] **Step 3: Test 작성**
```python
# tests/test_batch_db.py
import pytest
from app import db
@pytest.fixture
def fresh_db(monkeypatch, tmp_path):
monkeypatch.setattr(db, "DB_PATH", str(tmp_path / "music.db"))
db.init_db()
return db
def test_create_batch_job(fresh_db):
bid = db.create_batch_job(genre="lo-fi", count=10)
j = db.get_batch_job(bid)
assert j["genre"] == "lo-fi"
assert j["count"] == 10
assert j["status"] == "queued"
assert j["track_ids"] == []
assert j["auto_pipeline"] == 1
def test_update_batch_job(fresh_db):
bid = db.create_batch_job(genre="phonk", count=5)
db.update_batch_job(bid, status="generating", current_track_index=2)
j = db.get_batch_job(bid)
assert j["status"] == "generating"
assert j["current_track_index"] == 2
def test_update_batch_rejects_unknown_col(fresh_db):
bid = db.create_batch_job(genre="lo-fi", count=1)
with pytest.raises(ValueError):
db.update_batch_job(bid, evil_col="x")
def test_append_batch_track(fresh_db):
bid = db.create_batch_job(genre="lo-fi", count=3)
db.append_batch_track(bid, 101)
db.append_batch_track(bid, 102)
j = db.get_batch_job(bid)
assert j["track_ids"] == [101, 102]
assert j["completed"] == 2
def test_list_batch_jobs_active_filter(fresh_db):
b1 = db.create_batch_job(genre="lo-fi", count=1)
b2 = db.create_batch_job(genre="phonk", count=1)
db.update_batch_job(b1, status="failed")
actives = db.list_batch_jobs(active_only=True)
assert all(j["status"] not in ("failed",) for j in actives)
assert any(j["id"] == b2 for j in actives)
assert not any(j["id"] == b1 for j in actives)
def test_random_pools_randomize():
from app.random_pools import randomize, POOLS
import random
rng = random.Random(42)
result = randomize("lo-fi", rng)
assert result["bpm"] in range(70, 91)
assert result["key"] in POOLS["lo-fi"]["keys"]
assert result["scale"] in POOLS["lo-fi"]["scales"]
assert len(result["moods"]) == 1
assert result["moods"][0] in POOLS["lo-fi"]["moods"]
assert 3 <= len(result["instruments"]) <= 4
def test_random_pools_unknown_genre_uses_default():
from app.random_pools import randomize, POOLS
import random
result = randomize("nonexistent", random.Random(0))
assert result["bpm"] in range(80, 111) # default range
```
- [ ] **Step 4: Run + commit**
```bash
cd music-lab && python -m pytest tests/test_batch_db.py -v
```
Expected: 7 PASS.
```bash
git add music-lab/app/db.py music-lab/app/random_pools.py music-lab/tests/test_batch_db.py
git commit -m "feat(music-lab): music_batch_jobs 테이블 + 장르별 랜덤 풀"
```
---
## Task 2: batch_generator + 3 엔드포인트
**Files:**
- Create: `music-lab/app/batch_generator.py`
- Modify: `music-lab/app/main.py`
- Test: `music-lab/tests/test_batch_endpoints.py`
- [ ] **Step 1: batch_generator.py 작성**
```python
"""배치 음악 생성 + 자동 컴파일·영상 파이프라인."""
import asyncio
import logging
from . import db
from .random_pools import randomize
logger = logging.getLogger("music-lab.batch")
POLL_INTERVAL_S = 5
TRACK_GEN_TIMEOUT_S = 240
async def run_batch(batch_id: int) -> None:
job = db.get_batch_job(batch_id)
if not job:
return
genre = job["genre"]
count = job["count"]
duration = job["target_duration_sec"]
auto_pipe = bool(job["auto_pipeline"])
db.update_batch_job(batch_id, status="generating")
track_ids: list[int] = []
for i in range(1, count + 1):
title = f"{genre.title()} Mix Track {i}"
params = randomize(genre)
db.update_batch_job(batch_id,
current_track_index=i,
current_track_status="generating")
track_id = await _generate_one_track(title=title, genre=genre,
duration_sec=duration,
params=params)
if track_id:
track_ids.append(track_id)
db.append_batch_track(batch_id, track_id)
db.update_batch_job(batch_id, current_track_status="succeeded")
else:
db.update_batch_job(batch_id, current_track_status="failed")
logger.warning("배치 %d 트랙 %d 실패 — 계속 진행", batch_id, i)
if not track_ids:
db.update_batch_job(batch_id, status="failed",
error="모든 트랙 생성 실패")
return
db.update_batch_job(batch_id, status="generated")
if not auto_pipe:
return
# 자동 컴파일
db.update_batch_job(batch_id, status="compiling")
try:
compile_id = db.create_compile_job(
title=f"{genre.title()} Mix",
track_ids=track_ids,
crossfade_sec=3,
)
db.update_batch_job(batch_id, compile_job_id=compile_id)
except Exception as e:
db.update_batch_job(batch_id, status="failed", error=f"compile create: {e}")
return
from . import compiler
try:
await asyncio.to_thread(compiler.run, compile_id)
except Exception as e:
db.update_batch_job(batch_id, status="failed", error=f"compile run: {e}")
return
job_after = db.get_compile_job(compile_id)
if not job_after or job_after.get("status") not in ("done", "succeeded"):
db.update_batch_job(
batch_id, status="failed",
error=f"compile not done (status={job_after.get('status') if job_after else 'unknown'})"
)
return
# 자동 영상 파이프라인
pipeline_id = db.create_pipeline(compile_job_id=compile_id)
db.update_batch_job(batch_id, pipeline_id=pipeline_id, status="piped")
from .pipeline import orchestrator
await orchestrator.run_step(pipeline_id, "cover")
async def _generate_one_track(*, title: str, genre: str, duration_sec: int,
params: dict) -> int | None:
"""기존 Suno generate 호출 + 완료까지 polling. 성공 시 새 track id 반환."""
from .suno_provider import run_suno_generation
from .db import create_task, get_task
import uuid
task_id = str(uuid.uuid4())
suno_params = {
"title": title,
"genre": genre,
"moods": params["moods"],
"instruments": params["instruments"],
"duration_sec": duration_sec,
"bpm": params["bpm"],
"key": params["key"],
"scale": params["scale"],
"prompt": params.get("prompt_modifier", ""),
}
create_task(task_id, suno_params, provider="suno")
# Suno background task 직접 호출 (BackgroundTasks 미사용 — 우리가 await)
asyncio.create_task(asyncio.to_thread(run_suno_generation, task_id, suno_params))
# Polling
waited = 0
while waited < TRACK_GEN_TIMEOUT_S:
await asyncio.sleep(POLL_INTERVAL_S)
waited += POLL_INTERVAL_S
task = get_task(task_id)
if not task:
continue
if task.get("status") == "succeeded":
tr = task.get("track")
return tr.get("id") if tr else None
if task.get("status") == "failed":
return None
return None # timeout
```
NOTE: This assumes existing `db.create_task`, `db.get_task`, `suno_provider.run_suno_generation` are reusable. Read existing code to confirm function signatures, adjust if needed (especially `task["track"]["id"]` vs other format).
- [ ] **Step 2: main.py에 3 endpoint 추가**
```python
from app.batch_generator import run_batch as _run_batch
class BatchGenerateRequest(BaseModel):
genre: str
count: int = 10
target_duration_sec: int = 180
auto_pipeline: bool = True
@app.post("/api/music/generate-batch", status_code=201)
async def generate_batch(req: BatchGenerateRequest, bg: BackgroundTasks):
if not (1 <= req.count <= 10):
raise HTTPException(400, "count는 1-10 사이")
if not (60 <= req.target_duration_sec <= 300):
raise HTTPException(400, "target_duration_sec는 60-300 사이")
if not req.genre:
raise HTTPException(400, "genre 필수")
if not SUNO_API_KEY:
raise HTTPException(400, "SUNO_API_KEY 미설정")
batch_id = _db_module.create_batch_job(
genre=req.genre, count=req.count,
target_duration_sec=req.target_duration_sec,
auto_pipeline=req.auto_pipeline,
)
bg.add_task(_run_batch, batch_id)
return _db_module.get_batch_job(batch_id)
@app.get("/api/music/generate-batch/{batch_id}")
def get_batch(batch_id: int):
j = _db_module.get_batch_job(batch_id)
if not j:
raise HTTPException(404)
# tracks 메타 LEFT JOIN (id, title, audio_url)
if j["track_ids"]:
ids_csv = ",".join(str(i) for i in j["track_ids"])
# 간단한 in-Python 매핑 (sqlite IN (...))
import sqlite3
conn = sqlite3.connect(_db_module.DB_PATH)
conn.row_factory = sqlite3.Row
rows = conn.execute(
f"SELECT id, title, audio_url, duration_sec FROM music_library WHERE id IN ({ids_csv})"
).fetchall()
conn.close()
j["tracks"] = [dict(r) for r in rows]
else:
j["tracks"] = []
return j
@app.get("/api/music/generate-batch")
def list_batches(status: str = "all"):
return {"batches": _db_module.list_batch_jobs(active_only=(status == "active"))}
```
(SUNO_API_KEY는 main.py에 이미 import돼있다고 가정. 없으면 `_db_module` 패턴처럼 처리.)
- [ ] **Step 3: 테스트 작성**
```python
# tests/test_batch_endpoints.py
import pytest
from unittest.mock import AsyncMock, patch, MagicMock
from fastapi.testclient import TestClient
from app.main import app
from app import db
@pytest.fixture
def client(monkeypatch, tmp_path):
monkeypatch.setattr(db, "DB_PATH", str(tmp_path / "music.db"))
db.init_db()
monkeypatch.setenv("SUNO_API_KEY", "test")
return TestClient(app)
def test_create_batch_201(client):
with patch("app.main._run_batch", new=AsyncMock()):
r = client.post("/api/music/generate-batch",
json={"genre": "lo-fi", "count": 3})
assert r.status_code == 201
body = r.json()
assert body["genre"] == "lo-fi"
assert body["count"] == 3
assert body["status"] == "queued"
def test_create_batch_rejects_count_too_high(client):
r = client.post("/api/music/generate-batch",
json={"genre": "lo-fi", "count": 11})
assert r.status_code == 400
def test_create_batch_rejects_count_zero(client):
r = client.post("/api/music/generate-batch",
json={"genre": "lo-fi", "count": 0})
assert r.status_code == 400
def test_create_batch_rejects_no_genre(client):
r = client.post("/api/music/generate-batch", json={"count": 3})
# Pydantic missing 필드 → 422 (FastAPI default validation)
assert r.status_code in (400, 422)
def test_get_batch_returns_tracks(client):
bid = db.create_batch_job(genre="lo-fi", count=2)
db.append_batch_track(bid, 999) # phantom track id (not in library)
r = client.get(f"/api/music/generate-batch/{bid}")
assert r.status_code == 200
body = r.json()
assert body["track_ids"] == [999]
# tracks 배열은 비어있음 (해당 track 미존재)
assert body["tracks"] == []
def test_list_batches(client):
db.create_batch_job(genre="lo-fi", count=1)
db.create_batch_job(genre="phonk", count=2)
r = client.get("/api/music/generate-batch")
assert len(r.json()["batches"]) == 2
```
- [ ] **Step 4: Run + commit + push**
```bash
cd music-lab && python -m pytest tests/ -v
```
Expected: 모두 PASS.
```bash
git -C C:/Users/jaeoh/Desktop/workspace/web-backend add music-lab/app/batch_generator.py \
music-lab/app/main.py \
music-lab/tests/test_batch_endpoints.py
git -C C:/Users/jaeoh/Desktop/workspace/web-backend commit -m "feat(music-lab): 배치 음악 생성 endpoint + orchestrator"
git -C C:/Users/jaeoh/Desktop/workspace/web-backend push origin main
```
---
## Task 3: Frontend Create 탭 배치 섹션
**Files:**
- Modify: `web-ui/src/api.js`
- Create: `web-ui/src/pages/music/components/BatchProgress.jsx`
- Modify: `web-ui/src/pages/music/MusicStudio.jsx`
- Modify: `web-ui/src/pages/music/MusicStudio.css`
- [ ] **Step 1: api.js 헬퍼**
```javascript
// === Batch generation ===
export const startBatchGen = (payload) => apiPost('/api/music/generate-batch', payload);
export const getBatchJob = (id) => apiGet(`/api/music/generate-batch/${id}`);
export const listBatchJobs = (status='all') => apiGet(`/api/music/generate-batch?status=${status}`);
```
- [ ] **Step 2: BatchProgress.jsx 신규**
```jsx
const STATUS_LABELS = {
queued: '대기 중', generating: '음악 생성 중', generated: '음악 완료, 컴파일 대기',
compiling: '컴파일 중', piped: '영상 파이프라인 시작됨',
failed: '실패', cancelled: '취소',
};
export default function BatchProgress({ batch }) {
if (!batch) return null;
const trackList = Array.from({ length: batch.count }, (_, i) => i + 1);
return (
<div className="ms-batch-progress">
<div className="ms-batch-header">
배치 #{batch.id} — {batch.genre} ·{' '}
{batch.completed}/{batch.count} 완료 ·{' '}
<strong>{STATUS_LABELS[batch.status] || batch.status}</strong>
</div>
{batch.error && <div className="ms-error">에러: {batch.error}</div>}
<ol className="ms-batch-tracks">
{trackList.map(n => {
const completed = n <= batch.completed;
const current = n === batch.current_track_index && batch.status === 'generating';
const tr = (batch.tracks || [])[n - 1];
return (
<li key={n} className={completed ? 'done' : current ? 'current' : 'pending'}>
{completed ? '✓' : current ? '⏳' : '○'}
{' '}Track {n}: {tr?.title || (current ? '생성 중...' : '대기')}
</li>
);
})}
</ol>
{batch.compile_job_id && (
<div className="ms-batch-link">📀 컴파일 #{batch.compile_job_id}</div>
)}
{batch.pipeline_id && (
<div className="ms-batch-link">
🎬 영상 파이프라인 #{batch.pipeline_id} —
{' '}<em>YouTube 탭 → 진행 탭에서 확인</em>
</div>
)}
</div>
);
}
```
- [ ] **Step 3: MusicStudio.jsx Create 탭에 배치 섹션 추가**
Create 탭 jsx 영역 (handleGenerate 근처) 위 또는 옆에:
```jsx
import BatchProgress from './components/BatchProgress';
import { startBatchGen, getBatchJob } from '../../api';
// 컴포넌트 내부 state:
const [batchOpen, setBatchOpen] = useState(false);
const [batchGenre, setBatchGenre] = useState('lo-fi');
const [batchCount, setBatchCount] = useState(10);
const [batchDuration, setBatchDuration] = useState(180);
const [batchAutoPipe, setBatchAutoPipe] = useState(true);
const [currentBatch, setCurrentBatch] = useState(null);
const [batchPolling, setBatchPolling] = useState(false);
const batchPollRef = useRef(null);
const startBatch = async () => {
try {
const res = await startBatchGen({
genre: batchGenre,
count: batchCount,
target_duration_sec: batchDuration,
auto_pipeline: batchAutoPipe,
});
setCurrentBatch(res);
setBatchPolling(true);
} catch (e) {
alert(`배치 시작 실패: ${e.message || e}`);
}
};
useEffect(() => {
if (!batchPolling || !currentBatch?.id) return;
const tick = async () => {
const j = await getBatchJob(currentBatch.id).catch(() => null);
if (j) {
setCurrentBatch(j);
if (['piped', 'failed', 'cancelled'].includes(j.status)) {
setBatchPolling(false);
if (j.pipeline_id) loadLibrary?.(); // refresh library to show new tracks
}
}
};
batchPollRef.current = setInterval(tick, 5000);
return () => clearInterval(batchPollRef.current);
}, [batchPolling, currentBatch?.id]);
// ... Create 탭 jsx 안:
<details className="ms-batch-section" open={batchOpen} onToggle={(e) => setBatchOpen(e.target.open)}>
<summary>🎲 배치 생성 (장르 → 1-10트랙 + 자동 영상)</summary>
<div className="ms-batch-form">
<label>장르
<select value={batchGenre} onChange={e => setBatchGenre(e.target.value)}>
<option value="lo-fi">Lo-Fi</option>
<option value="phonk">Phonk</option>
<option value="ambient">Ambient</option>
<option value="pop">Pop</option>
</select>
</label>
<label>트랙 수: {batchCount}
<input type="range" min={1} max={10} value={batchCount}
onChange={e => setBatchCount(parseInt(e.target.value))} />
</label>
<label>트랙당 길이: {batchDuration}초
<input type="range" min={60} max={300} step={10} value={batchDuration}
onChange={e => setBatchDuration(parseInt(e.target.value))} />
</label>
<label className="ms-batch-checkbox">
<input type="checkbox" checked={batchAutoPipe}
onChange={e => setBatchAutoPipe(e.target.checked)} />
모든 트랙 생성 후 자동 영상 파이프라인 시작
</label>
<p className="ms-batch-estimate">
예상: 약 {Math.ceil(batchCount * 1.5)}-{batchCount * 2}분 ·
비용 ~${(batchCount * 0.005 + (batchAutoPipe ? 0.05 : 0)).toFixed(2)}
</p>
<button className="button primary" onClick={startBatch}
disabled={batchPolling}>
🎵 배치 생성 시작
</button>
</div>
{currentBatch && <BatchProgress batch={currentBatch} />}
</details>
```
- [ ] **Step 4: CSS 추가**
```css
/* === Batch generation section === */
.ms-batch-section { margin: 16px 0; padding: 12px; background: rgba(0,0,0,.2);
border: 1px solid var(--ms-line, #2a2a3a); border-radius: 12px; }
.ms-batch-section summary { cursor: pointer; font-weight: bold; color: var(--ms-text, #f0f0f5); }
.ms-batch-form { display: flex; flex-direction: column; gap: 10px; padding: 12px 0; }
.ms-batch-form label { display: flex; flex-direction: column; gap: 4px; font-size: 13px; }
.ms-batch-form input[type="range"] { width: 100%; }
.ms-batch-checkbox { flex-direction: row !important; align-items: center; gap: 8px; }
.ms-batch-checkbox input { width: auto; }
.ms-batch-estimate { font-size: 12px; color: var(--ms-muted, #a0a0b0); }
.ms-batch-progress { margin-top: 12px; padding: 12px; background: rgba(0,0,0,.3);
border-radius: 8px; }
.ms-batch-header { font-size: 13px; margin-bottom: 8px; }
.ms-batch-tracks { padding-left: 24px; font-size: 12px; }
.ms-batch-tracks li { margin: 2px 0; }
.ms-batch-tracks li.done { color: #86efac; }
.ms-batch-tracks li.current { color: var(--ms-accent, #38bdf8); font-weight: bold; }
.ms-batch-tracks li.pending { color: var(--ms-muted, #a0a0b0); }
.ms-batch-link { margin-top: 8px; font-size: 12px; color: var(--ms-muted, #a0a0b0); }
```
- [ ] **Step 5: Build + verify + commit + push + deploy**
```bash
cd web-ui && npm run build 2>&1 | tail -5
npx eslint src/pages/music/components/BatchProgress.jsx src/pages/music/MusicStudio.jsx 2>&1 | tail
```
```bash
git -C C:/Users/jaeoh/Desktop/workspace/web-ui add src/api.js \
src/pages/music/components/BatchProgress.jsx \
src/pages/music/MusicStudio.jsx \
src/pages/music/MusicStudio.css
git -C C:/Users/jaeoh/Desktop/workspace/web-ui commit -m "feat(web-ui): Create 탭 배치 생성 섹션 + BatchProgress"
git -C C:/Users/jaeoh/Desktop/workspace/web-ui push origin main
cd C:/Users/jaeoh/Desktop/workspace/web-ui && npm run release:nas
```
---
## Task 4: 수동 E2E 검증
- [ ] Create 탭 → 배치 생성 섹션 펼침 → genre=lo-fi, count=3 (테스트로 적게), duration=120s, auto_pipeline=on → "배치 생성 시작"
- [ ] BatchProgress에 Track 1/2/3 진행 표시 확인
- [ ] ~5분 후 Library에 3개 트랙 추가됨
- [ ] 컴파일 진행 확인 (status: compiling)
- [ ] 영상 파이프라인 시작됨 (status: piped) + pipeline_id 표시
- [ ] YouTube 탭 → 진행 탭에 새 카드, cover 단계 진행 중
- [ ] 텔레그램에 cover 알림 도착
- [ ] 일반 흐름대로 5단계 승인 후 발행
---
## Self-Review
**Spec coverage:**
- §3 사용자 흐름 → Task 3 (UI 섹션)
- §4 데이터 모델 → Task 1
- §5 백엔드 (random_pools, batch_generator) → Task 1, 2
- §6 API → Task 2
- §7 프론트엔드 → Task 3
- §8 에러 처리 → Task 2 (validation, try/except)
- §9 테스트 → Task 1, 2
- §10 산출물 → 4 task로 모두 커버
**Placeholder scan:** 없음.
**Type consistency:**
- `batch_id` int, `count` int, `genre` str — 일관
- `track_ids` list[int]
- `status` 7값 (queued/generating/generated/compiling/piped/failed/cancelled) 일관
**스펙 보정:** §5-2 batch_generator의 `_generate_one_track`에서 `db.create_task`/`db.get_task` 사용 — 이 함수들이 기존 db.py에 있는지 미확인. Task 2 Step 1 NOTE에 명시함.

505
docs/superpowers/specs/2026-05-10-batch-music-generation-design.md Normal file
View File

@@ -0,0 +1,505 @@
# 배치 음악 생성 + 자동 영상 파이프라인 설계
> 작성일: 2026-05-10
> 관련: `2026-05-09-essential-mix-pipeline-design.md` (영상 파이프라인 베이스)
---
## 1. 배경
현재 Create 탭은 사용자가 모든 파라미터(genre/mood/instruments/BPM/key/scale/duration/prompt) 수동 입력 후 1트랙 생성. 1시간+ mix 영상 만들려면 동일 장르 트랙 10개를 일일이 만들어야 함.
목표: **장르 1개만 입력 → 10트랙 자동 생성 → 자동 컴파일 → 자동 영상 파이프라인 시작 → 텔레그램 승인만 하면 발행 완료**.
전체 흐름:
```
[사용자] Create 탭 → 배치 모드 → 장르 + 트랙 수 선택 → 생성 시작
↓ Suno API 순차 호출 (트랙당 ~1-2분)
↓ Track 1: "{Genre} Mix Track 1", 랜덤 mood/instr/BPM/key
↓ Track 2: "{Genre} Mix Track 2", ...
↓ ... Track 10
↓ 모두 완료 → compile_job 자동 생성 (acrossfade 3s)
↓ compile 완료 → video_pipeline 자동 시작 (cover step)
↓ 텔레그램에 "🎵 [{Genre} Mix] 커버 검토" 알림
[사용자] 5번 승인으로 영상 발행
```
---
## 2. 비목표
- 병렬 음악 생성 — VRAM 부담 회피, 순차로 단순하게
- 트랙별 prompt 자동 작성(Claude) — Suno는 genre+mood+instruments만으로도 충분
- 트랙별 길이 가변 — 모든 트랙 동일 `target_duration_sec` (default 180s)
- 사용자가 진행 중 트랙 prompt 편집 — 한 번 시작하면 끝까지
---
## 3. 사용자 흐름
### 3-1. Create 탭의 신규 "배치 생성" 섹션
```
┌─ 🎲 배치 생성 (장르 + 자동 영상까지) ─────────────────┐
│ │
│ 장르 [▼ lo-fi ] │
│ 트랙 수 [● 1 — 10] (10) │
│ 트랙당 길이 [● 60 — 300s] (180s) │
│ ☑ 모든 트랙 생성 후 자동 영상 파이프라인 시작 │
│ │
│ 예상 시간: 약 15-25분 (트랙당 1-2분 × 10) │
│ 예상 비용: ~$0.10 (Suno 10트랙 + DALL·E + Claude) │
│ │
│ [🎵 배치 생성 시작] │
│ │
│ ── 진행 상태 ────────────────────────────────────── │
│ 배치 #3 — lo-fi · 7/10 완료 · 2:43 경과 │
│ ✓ Track 1: Lo-Fi Mix Track 1 (chill, piano+synth) │
│ ✓ Track 2: Lo-Fi Mix Track 2 (relaxing, piano+drums) │
│ ... │
│ ⏳ Track 8: 생성 중... │
│ ○ Track 9: 대기 │
│ ○ Track 10: 대기 │
└──────────────────────────────────────────────────────┘
```
### 3-2. 완료 후
10트랙 모두 Library에 저장됨. compile_job_id가 자동 생성되고 영상 파이프라인이 cover step부터 시작 → 텔레그램 알림. 진행 탭에 카드 1장 추가.
---
## 4. 데이터 모델
### 4-1. 신규 테이블 `music_batch_jobs`
```sql
CREATE TABLE music_batch_jobs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
genre TEXT NOT NULL,
count INTEGER NOT NULL, -- 1-10
target_duration_sec INTEGER NOT NULL DEFAULT 180,
auto_pipeline INTEGER NOT NULL DEFAULT 1, -- 0/1 boolean
completed INTEGER NOT NULL DEFAULT 0,
track_ids_json TEXT NOT NULL DEFAULT '[]',
current_track_index INTEGER NOT NULL DEFAULT 0, -- 진행 중 트랙 (1..count)
current_track_status TEXT, -- queued | generating | failed
status TEXT NOT NULL DEFAULT 'queued',
-- queued: 시작 전
-- generating: 트랙 생성 중
-- generated: 모든 트랙 생성 완료 (compile 시작 전)
-- compiling: compile 진행 중
-- piped: 영상 파이프라인 시작됨 (=cover_pending 상태)
-- failed: 어느 단계에서 실패
-- cancelled: 사용자 취소
error TEXT,
compile_job_id INTEGER,
pipeline_id INTEGER,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
```
`init_db()`에 `CREATE TABLE IF NOT EXISTS` 추가.
### 4-2. 헬퍼 함수 (`db.py` 추가)
- `create_batch_job(genre, count, target_duration_sec, auto_pipeline) -> int`
- `get_batch_job(id) -> dict | None`
- `update_batch_job(id, **fields)` — allowlist 검증
- `list_batch_jobs(active_only=False) -> list[dict]`
- `append_batch_track(batch_id, track_id)` — 완료된 트랙 ID 추가, completed++
---
## 5. 백엔드 — 랜덤 풀 + 배치 실행
### 5-1. `app/random_pools.py` (신규)
장르별 음악적으로 어울리는 랜덤 풀 정의:
```python
"""장르별 음악 파라미터 랜덤 풀."""
import random
POOLS = {
"lo-fi": {
"moods": ["chill", "relaxing", "dreamy", "melancholic", "mellow", "nostalgic", "peaceful"],
"instruments_pool": ["piano", "synth", "drums", "vinyl", "rhodes", "soft bass", "ambient pads"],
"instruments_count": (3, 4),
"bpm": (70, 90),
"keys": ["C", "D", "F", "G", "A"],
"scales": ["minor", "major"],
"prompt_modifiers": ["cozy bedroom vibes", "rainy night", "late night study", "cafe ambience"],
},
"phonk": {
"moods": ["dark", "aggressive", "moody", "intense", "hypnotic"],
"instruments_pool": ["808 bass", "hi-hat", "synth lead", "vocal chops", "bass drops", "trap drums"],
"instruments_count": (3, 4),
"bpm": (130, 160),
"keys": ["C", "D", "F", "G"],
"scales": ["minor"],
"prompt_modifiers": ["drift atmosphere", "dark neon", "midnight drive"],
},
"ambient": {
"moods": ["peaceful", "meditative", "ethereal", "spacious", "dreamy"],
"instruments_pool": ["pad synths", "atmospheric guitar", "soft strings", "field recordings", "drone bass"],
"instruments_count": (2, 3),
"bpm": (50, 75),
"keys": ["C", "D", "E", "G", "A"],
"scales": ["major", "minor"],
"prompt_modifiers": ["misty mountain morning", "deep space", "still water", "forest dawn"],
},
"pop": {
"moods": ["uplifting", "happy", "energetic", "romantic", "catchy"],
"instruments_pool": ["acoustic guitar", "piano", "drums", "bass", "synth", "vocals harmonies"],
"instruments_count": (3, 5),
"bpm": (95, 130),
"keys": ["C", "D", "E", "F", "G", "A"],
"scales": ["major"],
"prompt_modifiers": ["radio-ready", "summer vibe", "feel-good"],
},
"default": { # 알 수 없는 장르 fallback
"moods": ["chill", "relaxing", "uplifting", "mellow"],
"instruments_pool": ["piano", "synth", "drums", "guitar", "bass", "strings"],
"instruments_count": (3, 4),
"bpm": (80, 110),
"keys": ["C", "D", "F", "G", "A"],
"scales": ["minor", "major"],
"prompt_modifiers": [""],
},
}
def randomize(genre: str, rng: random.Random | None = None) -> dict:
"""랜덤 음악 파라미터 1세트 생성."""
rng = rng or random.Random()
pool = POOLS.get(genre.lower(), POOLS["default"])
n_instr = rng.randint(*pool["instruments_count"])
instruments = rng.sample(pool["instruments_pool"], min(n_instr, len(pool["instruments_pool"])))
return {
"moods": [rng.choice(pool["moods"])],
"instruments": instruments,
"bpm": rng.randint(*pool["bpm"]),
"key": rng.choice(pool["keys"]),
"scale": rng.choice(pool["scales"]),
"prompt_modifier": rng.choice(pool["prompt_modifiers"]),
}
```
향후(P3): 장르별 풀을 `youtube_setup`/별도 테이블로 옮겨 SetupTab에서 편집 가능하게.
### 5-2. `app/batch_generator.py` (신규) — 순차 실행 오케스트레이터
```python
"""배치 음악 생성 + 자동 컴파일·영상 파이프라인."""
import asyncio
import logging
import json
from . import db
from .suno_provider import run_suno_generation
from .random_pools import randomize
logger = logging.getLogger("music-lab.batch")
POLL_INTERVAL_S = 5
TRACK_GEN_TIMEOUT_S = 240 # 트랙당 최대 4분
async def run_batch(batch_id: int) -> None:
"""1) genre로 N트랙 순차 Suno 생성
2) 모두 완료 후 compile_job 자동 생성·실행
3) compile 완료 후 영상 파이프라인 시작 (cover step)
"""
job = db.get_batch_job(batch_id)
if not job:
return
genre = job["genre"]
count = job["count"]
duration = job["target_duration_sec"]
auto_pipe = bool(job["auto_pipeline"])
db.update_batch_job(batch_id, status="generating")
track_ids: list[int] = []
for i in range(1, count + 1):
title = f"{genre.title()} Mix Track {i}"
params = randomize(genre)
db.update_batch_job(batch_id,
current_track_index=i,
current_track_status="generating")
# Suno 호출 (기존 task 패턴 활용)
task_id = _start_suno(title=title, genre=genre,
duration_sec=duration, **params)
track_id = await _wait_for_track(task_id, timeout=TRACK_GEN_TIMEOUT_S)
if track_id:
track_ids.append(track_id)
db.append_batch_track(batch_id, track_id)
else:
logger.warning("배치 %d 트랙 %d 실패 — 계속 진행", batch_id, i)
db.update_batch_job(batch_id, current_track_status="failed")
# 정책: 실패한 트랙은 skip하고 계속 (나머지 9개라도 만든다)
if not track_ids:
db.update_batch_job(batch_id, status="failed",
error="모든 트랙 생성 실패")
return
db.update_batch_job(batch_id, status="generated")
if not auto_pipe:
return # 음악만 만들고 종료
# === 자동 compile ===
db.update_batch_job(batch_id, status="compiling")
compile_id = db.create_compile_job(
title=f"{genre.title()} Mix",
track_ids=track_ids,
crossfade_sec=3,
)
db.update_batch_job(batch_id, compile_job_id=compile_id)
# 기존 compiler 호출 (동기 → asyncio.to_thread)
from . import compiler
await asyncio.to_thread(compiler.run, compile_id)
job_after = db.get_compile_job(compile_id)
if not job_after or job_after.get("status") not in ("done", "succeeded"):
db.update_batch_job(batch_id, status="failed",
error=f"compile 실패 (status={job_after.get('status') if job_after else 'unknown'})")
return
# === 자동 영상 파이프라인 ===
pipeline_id = db.create_pipeline(compile_job_id=compile_id)
db.update_batch_job(batch_id, pipeline_id=pipeline_id, status="piped")
from .pipeline import orchestrator
await orchestrator.run_step(pipeline_id, "cover")
```
- `_start_suno(...)` — 기존 `run_suno_generation` 호출, task_id 반환
- `_wait_for_track(task_id, timeout)` — task 완료 폴링, 성공 시 music_library의 새 track id 반환
### 5-3. 변경되는 기존 모듈
`app/main.py`에 신규 endpoint 3개 + BackgroundTask. 변경 없는 기존 endpoint들은 그대로.
`db.py`에 헬퍼 함수 5개 추가 + `init_db()`에 `music_batch_jobs` CREATE 추가.
---
## 6. API 엔드포인트
### 6-1. `POST /api/music/generate-batch`
Request:
```json
{
"genre": "lo-fi",
"count": 10,
"target_duration_sec": 180,
"auto_pipeline": true
}
```
Validation:
- `count` 1-10
- `target_duration_sec` 60-300
- `genre` 필수
Response 201:
```json
{
"id": 3,
"status": "queued",
...
}
```
배치 작업은 BackgroundTask로 실행 (~15-25분 소요).
### 6-2. `GET /api/music/generate-batch/{id}`
진행 상태 조회. 응답 예:
```json
{
"id": 3,
"genre": "lo-fi",
"count": 10,
"completed": 7,
"current_track_index": 8,
"current_track_status": "generating",
"status": "generating",
"track_ids": [12, 13, 14, 15, 16, 17, 18],
"tracks": [
{"id": 12, "title": "Lo-Fi Mix Track 1", ...},
...
],
"compile_job_id": null,
"pipeline_id": null,
"created_at": "2026-05-10T17:00:00",
"updated_at": "2026-05-10T17:08:30"
}
```
`tracks` 필드는 LEFT JOIN으로 채워짐 (각 트랙 메타 포함).
### 6-3. `GET /api/music/generate-batch?status=active`
전체 배치 목록. `active`면 queued/generating/compiling/piped 만.
---
## 7. 프론트엔드 — Create 탭 배치 섹션
### 7-1. `MusicStudio.jsx` Create 영역에 신규 collapsible
Create form 위 또는 옆에 새 섹션 (`<details>` 또는 토글):
```jsx
<details className="ms-batch-section" open={batchOpen}>
<summary onClick={...}>🎲 배치 생성 (1-10트랙 + 자동 영상)</summary>
<div className="ms-batch-form">
<label>장르
<select value={batchGenre} onChange={...}>
<option value="lo-fi">Lo-Fi</option>
<option value="phonk">Phonk</option>
<option value="ambient">Ambient</option>
<option value="pop">Pop</option>
</select>
</label>
<label>트랙 수: {batchCount}
<input type="range" min={1} max={10} value={batchCount} onChange={...}/>
</label>
<label>트랙당 길이: {batchDuration}초
<input type="range" min={60} max={300} step={10} value={batchDuration} onChange={...}/>
</label>
<label>
<input type="checkbox" checked={autoPipeline} onChange={...}/>
모든 트랙 생성 후 자동 영상 파이프라인 시작
</label>
<p className="ms-batch-estimate">
예상: 약 {batchCount * 1.5 | 0}-{batchCount * 2}분 · 비용 ~${(batchCount * 0.005 + (autoPipeline ? 0.05 : 0)).toFixed(2)}
</p>
<button className="button primary" onClick={startBatch} disabled={generating}>
🎵 배치 생성 시작
</button>
</div>
{currentBatch && <BatchProgress batch={currentBatch} />}
</details>
```
### 7-2. 신규 컴포넌트 `BatchProgress.jsx`
```jsx
export default function BatchProgress({ batch }) {
return (
<div className="ms-batch-progress">
<div className="ms-batch-header">
배치 #{batch.id} — {batch.genre} ·
{' '}{batch.completed}/{batch.count} 완료 ·
{' '}status: <strong>{batch.status}</strong>
</div>
<ol className="ms-batch-tracks">
{Array.from({ length: batch.count }, (_, i) => i + 1).map(n => {
const completed = n <= batch.completed;
const current = n === batch.current_track_index && batch.status === 'generating';
const track = (batch.tracks || []).find(t => t._batch_index === n);
return (
<li key={n} className={completed ? 'done' : current ? 'current' : 'pending'}>
{completed ? '✓' : current ? '⏳' : '○'}
{' '}Track {n}: {track ? track.title : (current ? '생성 중...' : '대기')}
</li>
);
})}
</ol>
{batch.compile_job_id && <div>📀 컴파일 #{batch.compile_job_id}</div>}
{batch.pipeline_id && (
<div>
🎬 영상 파이프라인 #{batch.pipeline_id} —
<a href={`#youtube-pipeline-${batch.pipeline_id}`}> 진행 탭에서 확인</a>
</div>
)}
</div>
);
}
```
### 7-3. 폴링
배치 시작 시 5초 간격 `getBatchJob(id)` 호출. status가 `piped`/`failed`/`cancelled`되면 폴링 중지.
### 7-4. `api.js` 헬퍼
```javascript
export const startBatchGen = (payload) => apiPost('/api/music/generate-batch', payload);
export const getBatchJob = (id) => apiGet(`/api/music/generate-batch/${id}`);
export const listBatchJobs = (status='all') => apiGet(`/api/music/generate-batch?status=${status}`);
```
---
## 8. 에러 처리
| 시나리오 | 동작 |
|---------|------|
| Suno API 트랙 1개 실패 | 로그 + skip + 다음 트랙 진행. 최종 track_ids에 누락. |
| 모든 트랙 실패 | status=failed, error 기록 |
| compile 실패 | status=failed, compile_job_id 보존 |
| 영상 파이프라인 cover step 실패 | pipeline 자체에서 failed로 마크. batch는 piped 상태 그대로 (파이프라인 측에서 처리) |
| count > 10 또는 < 1 | 400 |
| genre 누락 | 400 |
| Suno API key 미설정 | 400 ("SUNO_API_KEY 미설정") |
---
## 9. 테스트 전략
### 9-1. 단위 테스트
- `random_pools.randomize(genre)` — 각 장르별 결과가 풀 안에 있는지, 시드 고정 시 재현 가능
- `db.create_batch_job` / `update_batch_job` / `append_batch_track` — 정상 흐름
- `_wait_for_track` — task 성공/실패/timeout mock
### 9-2. 통합 테스트
- `POST /api/music/generate-batch` 호출 → 201 반환 + 배치 row 생성
- `GET /api/music/generate-batch/{id}` 응답 schema
- `run_batch` mocked Suno + mocked compiler + mocked orchestrator → 전체 흐름 happy path
### 9-3. 수동 E2E
- Create 탭 → 배치 생성 → 장르 선택 → 시작 → 진행 표시 확인
- 10트랙 완료 → Library에 10개 추가 확인 → compile_job 자동 생성 확인 → 진행 탭에 새 카드 등장 확인
---
## 10. 산출물
| 영역 | 파일 |
|------|------|
| Spec/Plan | 본 문서 + plan |
| NAS music-lab | `db.py` (테이블/헬퍼), `random_pools.py` (신규), `batch_generator.py` (신규), `main.py` (3 endpoints) |
| Frontend | `MusicStudio.jsx` (Create 배치 섹션), `BatchProgress.jsx` (신규), `MusicStudio.css`, `api.js` 헬퍼 |
| 테스트 | NAS 단위 + 통합, 수동 E2E |
---
## 11. 후속 (P3)
- 장르별 풀 SetupTab에서 편집 가능
- 트랙별 prompt에 시나리오/카페 분위기 등 자동 추가 (트랙간 다양성 증대)
- 배치 일시정지/재개
- 한 배치 안에서 Track-N별 재생성 (실패한 트랙만)
- 트랙 길이 가변 (랜덤 분포)