# Higgsfield Shorts Engine

> ADO2 마케팅 자동화 파이프라인의 **어텐션 트랙(Attention Track)** 영상 생성 엔진.
> 펜션 사진 3~5장 → 8초 임팩트 숏츠/릴스 (Higgsfield API 기반).

---

## 1. Project Goal

**한 줄 목표**
> 펜션 마케팅의 신뢰 기반 콘텐츠를 깨지 않고, **의도적 비현실(Intentional Unreal)** 영상으로 SNS 피드의 Pattern Interrupt를 만들어 평균 시청유지율을 2배 이상 끌어올린다.

**왜 지금인가 (Why Now)**
- 기존 Creatomate 슬라이드쇼는 "실사 보존" 원칙 덕분에 신뢰는 높지만, Instagram/TikTok 피드에서 평균 1.5초 안에 스킵됨
- 펜션 SNS 피드의 90%는 실사 사진/영상 → 차별화 여지 없음
- Higgsfield의 카메라 무브·드림시퀀스·시네마틱 모션은 "AI가 만든 티"가 나도 오히려 **궁금증 → 스와이프 정지 → 프로필 진입** 의 깔때기를 형성

**전략적 포지셔닝**
| 트랙 | 엔진 | 역할 | 사용자 인식 |
|---|---|---|---|
| Trust Track | `engine/semantic_video/` + Creatomate | 실사 슬라이드쇼·정보 전달 | "이 펜션은 진짜 이렇게 생겼다" |
| **Attention Track** | **`engine/higgsfield_shorts/` (본 모듈)** | **8초 시네마틱·드림시퀀스** | **"뭐지? 가보고 싶다"** |

두 트랙은 **상호 보완** 관계. 어텐션 트랙으로 유입 → 트러스트 트랙으로 전환(예약).

---

## 2. Success Criteria (KPI)

### Primary (어텐션 성과)
- **평균 시청 유지율** ≥ 65% (8초 기준, 5.2초 이상 시청)
- **Hook Rate** (3초 시청률) ≥ 35% (업계 평균 15~20%)
- **저장률** ≥ 2% (Instagram Reels 기준)

### Secondary (전환 깔때기)
- 영상 → 프로필 클릭률 ≥ 4%
- 프로필 → 예약 페이지 이동 ≥ 1%

### Production (운영 효율)
- 사진 5장 입력 → 8초 영상 출력까지 **자동 파이프라인 ≤ 5분**
- 1편당 Higgsfield API 비용 ≤ $2 (목표 단가)
- 클라이언트 1곳당 월 12편 생산 가능 (주 3편 ×4주)

### Phase 1 KPI (6주, 2026-05-28 ~ 2026-07-09)
- **3개 펜션 클라이언트로 파일럿 운영**
- **편당 평균 도달 ≥ 10,000회 / 평균 시청유지율 ≥ 65% 검증**
- **컨셉 라이브러리 5종 검증 → 2종 표준화**

---

## 3. Scope

### In Scope (Phase 1)
- 펜션 정사진 3~5장 → 8초 9:16 (Reels/Shorts) 영상 생성
- Higgsfield API 연동 (Image-to-Video, Camera Control)
- 컨셉 라이브러리 (시네마틱·드림시퀀스·하이퍼리얼·트레일러·글리치 등)
- 한국어 자막/타이포그래피 모션 (Remotion 후처리)
- Creatomate Trust Track 자산과의 메타데이터 연결 (같은 펜션 = 같은 자산 ID)

### Out of Scope (Phase 1)
- 16:9 가로 영상 (Phase 2: 유튜브 시청자대상)
- 30초/60초 장형 (Phase 2: 광고 캠페인)
- 사람(인물) 영상 생성 — 초상권/딥페이크 리스크
- 음악 자동 매칭 — Phase 1은 큐레이션된 라이브러리에서 수동 선택

### Hard Constraints (절대 위반 금지)
- ❌ **펜션의 위치·구조·시설을 왜곡하지 않는다** (예: 산속 펜션을 바닷가로 합성 X)
- ❌ **존재하지 않는 어메니티를 합성하지 않는다** (수영장 없는데 수영장 X)
- ✅ **분위기·시간대·날씨·카메라 무브는 자유롭게 과장 가능** (이게 어텐션 핵심)
- ✅ **추상화·드림시퀀스·픽션화는 OK** — 단, 영상 후반/캡션에 펜션명 명시

> Why: 펜션은 신뢰 기반 마케팅이 필수. "분위기 과장"은 광고 관행 안에 있지만, "사실 왜곡"은 부정경쟁방지법·표시광고법 위반.

---

## 4. Architecture (How it plugs in)

```
[Tenant Photo Library]
        │
        ▼
┌────────────────────────────────────┐
│ ADO2 Agent Orchestrator             │
│  ├─ Content Agent: 컨셉 선택        │
│  └─ Media Agent: 사진 큐레이션      │
└──────────────┬─────────────────────┘
               │
        ┌──────┴──────┐
        ▼             ▼
┌──────────────┐  ┌──────────────────────┐
│ Trust Track  │  │ Attention Track      │
│ semantic_    │  │ higgsfield_shorts    │
│ video +      │  │ (this engine)        │
│ Creatomate   │  │                      │
└──────┬───────┘  └──────────┬───────────┘
       │                     │
       │   ┌─────────────────┘
       ▼   ▼
┌────────────────────┐
│ Distribution Agent │ → Instagram / TikTok / Naver
└────────────────────┘
```

**모듈 내부 흐름**
```
inputs/{tenant}/{shoot_id}/*.jpg
        │
        ▼
src/curation/      # 3~5장 선별 (구도·색감·서사 점수)
        │
        ▼
src/concepts/      # 컨셉 라이브러리에서 매칭
        │
        ▼
src/prompts/       # Higgsfield 프롬프트 빌더
        │
        ▼
src/rendering/     # Higgsfield API 호출 + 비동기 큐
        │
        ▼
src/post/          # Remotion 자막·로고·CTA 합성
        │
        ▼
outputs/{tenant}/{shoot_id}/{concept}.mp4
```

---

## 5. Folder Structure

```
engine/higgsfield_shorts/
├── README.md                       # 본 문서 (Project Charter)
├── _brief/
│   ├── 01_creative-direction.md    # 크리에이티브 디렉션 (가짜OK 전략)
│   ├── 02_goals-kpis.md            # 상세 KPI 및 측정 방법
│   └── 03_scope-constraints.md     # 법적·브랜드 제약
├── concepts/                       # 컨셉 라이브러리
│   ├── README.md
│   ├── 01_cinematic-trailer.md
│   ├── 02_dream-sequence.md
│   ├── 03_hyperreal-luxury.md
│   ├── 04_time-warp.md
│   └── 05_anime-painterly.md
├── prompts/                        # Higgsfield 프롬프트 템플릿
│   └── README.md
├── inputs/                         # 테스트용 펜션 사진 셋
│   └── .gitkeep
├── outputs/                        # 렌더링 결과
│   └── .gitkeep
├── configs/                        # Higgsfield API·렌더 파라미터
│   └── higgsfield.yaml
├── docs/
│   └── pipeline-integration.md     # ADO2 파이프라인 연동 스펙
└── tests/
    └── README.md
```

---

## 6. Phase 1 Roadmap (6 weeks)

| Week | 마일스톤 |
|---|---|
| W1 (5/28-6/3) | 컨셉 라이브러리 5종 작성 + Higgsfield API 계정 셋업 + 첫 사진셋 수집 |
| W2 (6/4-6/10) | 프롬프트 템플릿 v0.1 + 수동 렌더 3편 (컨셉별 PoC) |
| W3 (6/11-6/17) | 파일럿 펜션 3곳 선정 + 사진 큐레이션 SOP |
| W4 (6/18-6/24) | 9편 발행 (펜션 3 × 컨셉 3) + 측정 |
| W5 (6/25-7/1) | 결과 분석 + 컨셉 2종 표준화 |
| W6 (7/2-7/9) | 자동화 파이프라인 v0.1 (Content Agent 통합) |

---

## 7. Stakeholders

- **Creative Director / Head of Marketing Ops**: 컨셉 디렉션, KPI 책임 (= 사용자)
- **Engineering**: 엔진 구현, API 연동
- **Pilot Clients**: 펜션 3곳 (5월 KPI Success Case와 연계)

---

## 8. Open Questions

이 프로젝트가 출발하려면 다음 결정이 필요합니다 (`_brief/01_creative-direction.md` 참고):

1. **Phase 1에서 우선 검증할 컨셉 2~3종은?** (라이브러리 5종 중)
2. **사진 큐레이션 기준** — AI 자동 큐레이션 vs 사람 큐레이션 vs 하이브리드?
3. **펜션명/CTA 노출 시점** — 영상 마지막 1초 vs 캡션에만 vs 둘 다?
4. **음악 라이브러리 선택** — Epidemic Sound vs Artlist vs SUNO 자동 생성?