CLAUDE.md

CLAUDE.md

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

개발 명령어

환경 설정

pip install -r requirements.txt

코드 품질 도구

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

애플리케이션 실행

# 웹 인터페이스 (주요 인터페이스)
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
• 현재 코드베이스에 테스트 스위트 구현되지 않음