# APNG Lip Sync Tool 개발 진행 기록

## 프로젝트 개요

**기간**: 2024년 12월 8일
**목적**: Gemini AI를 활용한 APNG 기반 립싱크 애니메이션 시스템 구축

---

## Phase 1: 프로젝트 설정 및 기본 구조

### 완료 항목
1. 프로젝트 디렉토리 구조 생성
2. Python 환경 설정 (uv, pyproject.toml)
3. .env 설정 (GOOGLE_API_KEY)
4. 기본 모듈 구현:
   - `src/config.py` - Viseme 정의, 음소 매핑
   - `src/gemini_client.py` - Gemini API 클라이언트
   - `src/apng_generator.py` - APNG 생성기
   - `src/text_to_viseme.py` - 한글 텍스트→Viseme 변환
   - `src/face_detector.py` - 얼굴/입 영역 감지
   - `src/tts_engine.py` - TTS 엔진 (gTTS)
   - `src/lipsync_player.py` - 립싱크 재생 관리
   - `src/api.py` - Flask API

---

## Phase 2: 웹 인터페이스 구현

### 완료 항목
1. `public/index.php` - 메인 웹 인터페이스
2. 이미지 업로드 기능
3. Viseme 이미지 생성 (Gemini 2.5 Flash)
4. 캐릭터 선택 및 립싱크 재생

### 해결한 문제들
- PHP에서 Python 실행 시 경로 문제 → `realpath()` + `escapeshellarg()` 적용
- Python 실행 권한 문제 → `chmod o+x` 적용
- JSON 파싱 오류 (stderr 혼합) → `2>/dev/null` 적용
- 캐릭터 이미지 404 → symlink 생성

---

## Phase 3: 블로그 문서화

### APNG Lip Sync Tool 시리즈 (v1-v16)
- v1: 프로젝트 소개 및 기술 스택
- v2: Gemini API 연동
- v3: Viseme 시스템 설계
- v4: 한글 음소 분해
- v5: 이미지 분석 (얼굴/입 감지)
- v6: Gemini 이미지 생성
- v7: APNG 생성
- v8: TTS 통합
- v9: 립싱크 동기화
- v10: 웹 인터페이스 (PHP)
- v11: API 설계
- v12: 에러 처리
- v13: 성능 최적화
- v14: 테스트
- v15: 보안
- v16: 문서화 및 배포

### Streaming Avatar 시리즈 (v1-v10)
- v1: 기술 리서치 (AKOOL, HeyGen 분석)
- v2: 시스템 아키텍처 설계
- v3: 기술 스택 선정 (LiveKit, MuseTalk 등)
- v4: MuseTalk 립싱크 엔진
- v5: WebRTC 실시간 스트리밍
- v6: TTS + LLM 통합
- v7: 인터랙티브 대화 시스템
- v8: 성능 최적화 (1280ms → 490ms)
- v9: UI/UX 및 배포
- v10: 최종 통합 및 문서화

---

## Phase 4: 고급 솔루션 검토

### SadTalker 논문 분석
- 3DMM 기반 얼굴 모델링
- ExpNet (오디오→표정), PoseVAE (오디오→포즈)
- GPU 없이 적용 가능한 아이디어 도출

### OpenAvatarChat + LiteAvatar 검토
- **핵심 발견**: CPU만으로 30fps 실행 가능
- Gemini LLM 통합 가능 (LiteLLM 프록시)
- 월 $30-50 비용으로 운영 가능
- APNG 대비 큰 품질 향상

---

## 다음 단계

OpenAvatarChat + LiteAvatar를 활용한 새 프로젝트 시작
→ `20251208-make-open-avatar-chat-demo/`

---

## 파일 구조

```
20251208-make-apng-tool/
├── .env                    # API 키
├── pyproject.toml          # Python 의존성
├── .venv/                  # 가상환경
├── src/                    # Python 백엔드
│   ├── config.py
│   ├── gemini_client.py
│   ├── face_detector.py
│   ├── apng_generator.py
│   ├── text_to_viseme.py
│   ├── tts_engine.py
│   ├── lipsync_player.py
│   └── api.py
├── public/                 # 프론트엔드
│   └── index.php
├── uploads/                # 업로드된 이미지
├── characters/             # 생성된 캐릭터
├── output/                 # 생성된 파일
├── docs/                   # 블로그 문서
│   ├── make-apng-tool-v1.md ~ v16.md
│   └── make-streaming-avatar-v1.md ~ v10.md
├── progress.md             # 이 파일
└── prompts.md              # 프롬프트 기록
```

---

## 주요 기술 스택

- **백엔드**: Python 3.11, Flask, uv
- **프론트엔드**: PHP, HTML/CSS/JS
- **AI**: Gemini 2.0 Flash (이미지 생성/분석)
- **TTS**: gTTS
- **애니메이션**: APNG (apng 라이브러리)

---

## 참고 자료

- [Gemini API Documentation](https://ai.google.dev/docs)
- [Preston Blair Phoneme Set](https://en.wikipedia.org/wiki/Phoneme)
- [SadTalker Paper](https://arxiv.org/abs/2211.12194)
- [OpenAvatarChat GitHub](https://github.com/HumanAIGC-Engineering/OpenAvatarChat)
- [LiteAvatar GitHub](https://github.com/HumanAIGC/lite-avatar)