# APNG Lip Sync Tool 개발기 - v1: 프로젝트 구조 설계

## 개요

AI 챗봇이나 가상 캐릭터가 "말하는" 듯한 느낌을 주는 것은 사용자 경험에 큰 영향을 미칩니다. 이 프로젝트에서는 **Gemini 2.5 Flash Image (Nano Banana)** 모델을 활용하여, 정적인 인물 이미지를 기반으로 다양한 입모양(viseme)을 생성하고, 이를 APNG 애니메이션으로 만들어 텍스트와 동기화된 립싱크를 구현합니다.

## 왜 APNG인가?

- **GIF보다 나은 품질**: APNG는 24비트 색상과 알파 채널을 지원
- **브라우저 호환성**: 모든 주요 브라우저에서 지원
- **작은 파일 크기**: 개별 입모양 이미지를 미리 생성해두면, 실시간으로 조합 가능
- **스트리밍 효과**: 마치 AI가 실시간으로 말하는 듯한 느낌 연출 가능

## 시스템 아키텍처

```
┌─────────────────────────────────────────────────────────────┐
│                        APNG Lip Sync Tool                     │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│   [입력 파트]                      [출력 파트]                 │
│   ┌─────────────┐                 ┌─────────────┐             │
│   │ 인물 이미지 │                 │ 캐릭터 선택 │             │
│   │   업로드    │                 └──────┬──────┘             │
│   └──────┬──────┘                        │                    │
│          │                               │                    │
│          ▼                               ▼                    │
│   ┌─────────────┐                 ┌─────────────┐             │
│   │ Gemini로    │                 │ 텍스트 입력 │             │
│   │ 얼굴 분석   │                 └──────┬──────┘             │
│   └──────┬──────┘                        │                    │
│          │                               ▼                    │
│          ▼                        ┌─────────────┐             │
│   ┌─────────────┐                 │ TTS + 타이밍│             │
│   │ 입모양 세트 │                 │   동기화    │             │
│   │   생성      │                 └──────┬──────┘             │
│   └──────┬──────┘                        │                    │
│          │                               ▼                    │
│          ▼                        ┌─────────────┐             │
│   ┌─────────────┐                 │ 립싱크 APNG │             │
│   │ APNG 파일   │  ──────────▶    │   재생      │             │
│   │   저장      │                 └─────────────┘             │
│   └─────────────┘                                             │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

## 프로젝트 구조

```
20251208-make-apng-tool/
├── .env                    # API 키 설정
├── .gitignore
├── pyproject.toml          # Python 의존성 (uv)
├── src/
│   ├── __init__.py
│   ├── config.py           # 설정 및 Viseme 정의
│   ├── gemini_client.py    # Gemini API 클라이언트
│   ├── apng_generator.py   # APNG 생성 로직
│   └── text_to_viseme.py   # 텍스트→입모양 변환
├── public/
│   └── index.php           # 간단한 PHP 프론트엔드
├── uploads/                # 업로드된 이미지
├── characters/             # 저장된 캐릭터 프로필
├── output/                 # 생성된 APNG 파일
└── docs/
    └── make-apng-tool-v1.md  # 이 문서
```

## Viseme (입모양) 세트

애니메이션 업계에서 널리 사용되는 Preston Blair 음소 세트를 기반으로 10가지 기본 입모양을 정의했습니다:

| Viseme | 설명 | 해당 발음 |
|--------|------|----------|
| rest | 다문 입 | 묵음 |
| A | 크게 벌린 입 | ㅏ, ㅑ, 아 |
| E | 옆으로 벌린 입 | ㅔ, ㅐ, 에 |
| I | 미소 형태 | ㅣ, 이 |
| O | 둥근 입 | ㅗ, ㅛ, 오 |
| U | 오므린 입 | ㅜ, ㅠ, 우 |
| C | 닫힌 이빨 | ㅅ, ㅈ, 스 |
| F | 아랫입술 위 이빨 | F, V |
| L | 혀가 보이는 | ㄹ, L |
| M | 다문 입술 | ㅁ, ㅂ, M, B, P |

## 기술 스택

- **AI**: Google Gemini 2.5 Flash Image (Nano Banana)
- **Backend**: Python 3.10+ with uv 패키지 관리
- **이미지 처리**: Pillow, APNG 라이브러리
- **TTS**: Google TTS (gTTS)
- **Frontend**: PHP (추후 Next.js 마이그레이션 예정)

## 다음 단계 (v2)

다음 포스트에서는 Gemini API 연동을 테스트하고, 실제로 이미지를 분석하는 기능을 구현합니다.

```python
# v2에서 테스트할 코드 미리보기
from src.gemini_client import test_connection, analyze_face_image

# API 연결 테스트
test_connection()

# 얼굴 이미지 분석
result = analyze_face_image("uploads/sample_face.png")
print(result["analysis"])
```

---

*이 시리즈는 총 16개의 포스트로 구성되어 있습니다. 전체 코드는 프로젝트 저장소에서 확인할 수 있습니다.*