CLAUDE.md

# CLAUDE.md

이 파일은 이 저장소에서 코드 작업을 할 때 Claude Code (claude.ai/code)에 지침을 제공합니다.

## 개발 명령어

### 환경 설정
```bash
pip install -r requirements.txt
```

### 코드 품질 도구
- **린팅**: `black --line-length 120 .` (코드 포맷팅)
- **임포트 정렬**: `isort .` (임포트 정렬)
- **타입 검사**: `mypy .` (정적 타입 분석)
- **린팅 검사**: `flake8 .` (코드 스타일 검사)
- **Pre-commit 훅**: `pre-commit run --all-files` (모든 검사 실행)

### 애플리케이션 실행
```bash
# 웹 인터페이스 (주요 인터페이스)
export HIFI_FOLEY_MODEL_PATH=PRETRAINED_MODEL_PATH_DIR
python3 app.py

# 직접 추론 (명령줄, 구현 필요)
# 참고: README에 언급된 infer.py와 gradio_app.py는 코드베이스에 존재하지 않음
```

## 아키텍처 개요

### 핵심 구성요소

**HunyuanVideo-Foley**는 비디오와 텍스트 입력으로부터 고품질 폴리 오디오를 생성하는 멀티모달 AI 모델입니다. 아키텍처는 다음으로 구성됩니다:

1. **메인 애플리케이션** (`app.py`): 대화형 오디오 생성을 위한 Gradio 기반 웹 인터페이스
2. **핵심 모델** (`hunyuanvideo_foley/models/hifi_foley/`): 메인 트랜스포머 기반 확산 모델
3. **오디오 처리** (`hunyuanvideo_foley/models/dac_vae/`): 48kHz 오디오 인코딩/디코딩을 위한 고품질 오디오 VAE
4. **시각적 동기화** (`hunyuanvideo_foley/models/synchformer/`): 오디오-비주얼 시간적 정렬 모듈
5. **유틸리티** (`hunyuanvideo_foley/utils/`): 특징 처리, 모델 로딩, 미디어 처리 유틸리티

### 주요 아키텍처 세부사항

- **오디오 VAE**: 48kHz 오디오 재구성을 위해 DAC (Descript Audio Codec) 사용
- **비주얼 특징**: SigLIP-2 (8 FPS)와 Synchformer (25 FPS)를 사용하여 25 FPS로 비디오 처리
- **텍스트 처리**: 768차원 임베딩을 가진 CLAP 기반 텍스트 인코더
- **확산 과정**: 선형 경로와 속도 예측을 통한 플로우 매칭
- **모델 규모**: 1536 히든 사이즈, 18개 트리플 블록, 36개 싱글 블록의 XXL 변형

### 구성

모델 구성은 `configs/hunyuanvideo-foley-xxl.yaml`에 정의되며 주요 매개변수는 다음과 같습니다:
- 오디오 샘플 레이트: 48kHz (2채널)
- 비디오 처리: 25 FPS, 최대 15초 지속시간
- 오디오 잠재 차원: 128
- 텍스트 길이: 최대 77 토큰
- 가이던스 스케일: 4.5 (기본값), 범위 1.0-10.0
- 추론 단계: 50 (기본값), 범위 10-100

### 모델 구성요소 위치

- `hunyuanvideo_foley/models/hifi_foley/`: 메인 확산 모델
- `hunyuanvideo_foley/models/dac_vae/`: 오디오 인코더/디코더
- `hunyuanvideo_foley/models/synchformer/`: 오디오-비주얼 동기화
- `hunyuanvideo_foley/utils/`: 모델 로딩, 특징 처리, 스케줄러

### 상수 및 제약사항

주요 제약사항은 `hunyuanvideo_foley/constants.py`에 정의되어 있습니다:
- 비디오 지속시간: 1-15초
- 지원되는 비디오 형식: .mp4, .avi, .mov, .mkv, .webm
- 지원되는 오디오 형식: .wav, .mp3, .flac, .aac
- 텍스트 프롬프트 최대 길이: 100자

### 모델 로딩

모델은 환경 변수 `HIFI_FOLEY_MODEL_PATH`를 통해 로드되거나 HuggingFace (`tencent/HunyuanVideo-Foley`)에서 `./pretrained_models/` 디렉토리로 자동 다운로드됩니다.

## 개발 참고사항

- 코드 스타일: 120자 줄 길이의 Black 포매터
- Python 버전: 3.8+ 지원
- CUDA 요구사항: 12.4 또는 11.8 권장
- 주요 배포: Gradio 인터페이스가 있는 HuggingFace Spaces
- 현재 코드베이스에 테스트 스위트 구현되지 않음