| name | chatterbox-avatar-forge |
| description | ChatterBox 의상실에서 "PNG 1장 업로드 → 자동 리깅 → 인앱 Live2D 아바타 수령"을 세우는 배선·배포 런북(CHATTERBOX-RIG-PORT-001 P3). Vtube Modal 파이프라인을 ChatterBox Supabase(avatar_jobs·Storage·Realtime)에 잇는다 — vgen 잡 클론 + FAL→Modal 스왑. 트리거 — "채터박스 아바타 배선", "PNG to live2d 웹연동", "의상실 아바타 생성", "avatar forge", "Modal 웹엔드포인트 배포", "avatar_jobs". 2026-07-09 미미 서버본으로 수령/렌더 반쪽 실증. |
Avatar Forge 배선·배포 (CHATTERBOX-RIG-PORT-001 P3)
ChatterBox /atelier-forge(dev) → 자동 리깅 → 의상실 프리셋. 두 레포: Vtube(Modal 엔드포인트·발행) + ChatterBox(마이그·엣지·클라). 잡 뼈대는 ChatterBox VGEN(FAL 영상) 클론.
상태 (2026-07-09)
- ✅ 수령/렌더 반쪽 증명 — 서버 리그→
bake_storage_avatar.py→avatars/<id>/ 발행→네이티브 RigAvatar 로드·웹캠 구동(미미 서버본, avatars/mimi-smoke/, 의상실 프리셋 "미미(서버본)").
- ✅ 배선 코드 완료·검증 — 아래 파일들, type-check·lint·py_compile 통과.
- ✅ 자동 트리거 배포 완료(2026-07-09) — Modal
chatterbox-rig deploy(submit) + vtube-supabase 시크릿 + 마이그 push + supabase secrets + 엣지 create-avatar-job + CF 프론트. 스모크: 엣지 무인증 401·Modal 무시크릿 401. ChatterBox 의상실 커미션 UI 승격(features/avatar/CommissionCorner+useAvatarJobs, seed-and-drive E2E 17/17 — 시드 잡·Realtime 드라이브로 배포 없이도 UI 검증 가능).
- ⏳ 첫 $2 실런 대기 — 의상실 실 PNG 주문 1건으로 GPU 전 구간(analyzing→finishing→발행) 관찰. 남용 게이트(크레딧/레이트리밋)는 공개 전 필수(ChatterBox ROADMAP 등재).
신규/변경 파일 (SSOT)
| 레이어 | 파일 | 역할 |
|---|
| Vtube 발행 | scripts/bake_storage_avatar.py | 리그→project.json+parts/*.webp. _project_base_url=""(로더 파생용, 함정) |
| Vtube 엔드포인트 | scripts/modal_rig_app.py submit/run_pipeline/_publish_avatar/_supabase_patch | 웹 트리거 + 오케스트레이터(phase PATCH) + Storage 발행. web_image=경량 fastapi |
| CB DB | supabase/migrations/*_create_avatar_jobs.sql | 잡 테이블(vgen 복제 축소) + RLS + Realtime |
| CB Storage | supabase/migrations/*_avatar_uploads_bucket.sql | avatar-uploads(private) + 본인폴더 RLS. 발행처 avatars(public)는 기존 |
| CB 엣지 | supabase/functions/create-avatar-job/index.ts | trigger-vgen 복제, FAL POST→Modal 엔드포인트 |
| CB 클라 | src/lib/avatarJobs.ts·src/types/avatarJob.ts·src/pages/AvatarForgeDevPage.tsx | 업로드·트리거·Realtime + 버림 dev UI(/atelier-forge) |
배포 런북 (자동 트리거 세우기)
cd /Users/family/jason/Vtube
~/.venvs/modal/bin/modal secret create vtube-supabase \
SUPABASE_URL="<VITE_SUPABASE_URL>" \
SUPABASE_SERVICE_ROLE_KEY="<SUPABASE_SERVICE_ROLE_KEY>" \
AVATAR_TRIGGER_SECRET="<임의 강한 시크릿>"
~/.venvs/modal/bin/modal deploy scripts/modal_rig_app.py
cd /Users/family/jason/ChatterBox
supabase link --project-ref <ref>
supabase db push
supabase secrets set MODAL_ENDPOINT_URL="<submit URL>" MODAL_TRIGGER_SECRET="<위와 동일>"
supabase functions deploy create-avatar-job
무디버깅 계약 함정 (전부 실제로 확인)
| 함정 | 증상 | 해법 |
|---|
| 발행처 오리진 | 아바타 로드 시 origin 거부/404 | Supabase Storage avatars(공개) 만 — R2·타 CDN은 로더 화이트리스트(*.supabase.co) 밖 |
_project_base_url | parts webp 404(페이지 오리진에 붙음) | 발행 시 빈 문자열. 로더 `base |
| 업로드 키 오리진 | Storage RLS vs 엣지 검증 불일치 | 키 = <authUid>/uploads/<uuid>.png (auth.uid()). 엣지 isSafeObjectKey(key, authId, ["uploads"]) — users.id 아님 |
| Modal 인풋 취소 | 로컬 런처 kill이 원격 취소 | 웹엔드포인트는 .spawn()(비동기)이라 무관. CLI 경로는 [[autorig-upload-e2e]] nohup+disown |
| 프리셋 이름 충돌 | 구본 mimi와 신본 동명 | 매니페스트 name 구분(예: "미미(서버본)"). 최종 승격 시 avatars/mimi/ 덮어써 캐논화 |
티어 정책
run_pipeline = 프로덕션 안전 티어 build_rig(..., use_tha4=False, use_crown=False) = ARAP meet 감은눈(이물 원천 불가). THA4/crown 옵트인 근거·함정은 [[autorig-upload-e2e]]. 리깅 자체(P0 리롤·P2 게이트·표현력)는 그 스킬이 SSOT — 여기선 웹 배선만.
검증 (성역)
- Step 0(자동 이전, GPU 0원): 서버 리그 회수→
bake_storage_avatar.py --project <rig> --out <o>→avatars/<id>/ 업로드(service_role)→ChatterBox /avatar-inspect?project=<url> 네이티브 패널 렌더 확인(aria-player 우측 패널은 레거시라 빈 base 실패 — 무시). 프리셋 확인은 avatars/manifest.json 에 {id,name} 추가 후 의상실.
- 자동 E2E:
/atelier-forge PNG 업로드 → avatar_jobs queued→running→phase 진행→done + result_project_url. 첫 $2 실런은 함께 관찰. 웹캠 구동 판정은 사용자 카메라 몫.
크로스링크
- ChatterBox 계약(UI 빌더용):
docs/reference/patterns/avatar-forge-pipeline.md, docs/DATA-SCHEMA.md §1.9, docs/API-SURFACE.md Avatar Forge.
- 리깅 런북: [[autorig-upload-e2e]]. 정적 Vercel 웹앱 배포(다른 타깃): [[vtuber-deploy]].
