아바타 생성 · VisionAI Docs

현재 설치에서는 영상으로 Wav2Lip 아바타를 생성할 수 있습니다. 별도 인물 학습 없이 영상 프레임, 얼굴 이미지와 좌표 파일을 준비하는 전처리 방식입니다. 생성 화면은 사진 한 장을 업로드하는 방식이 아닙니다.

영상 준비

권장 시작 조건은 얼굴이 선명한 정면 영상, 자연스럽게 다문 입, 일정한 조명입니다. 인물이 너무 작거나, 얼굴이 가려지거나, 고개를 크게 돌리는 장면은 피하세요.

처음에는 5~10초의 MP4로 시험합니다. 이는 시작을 위한 권장 길이이며 생성기의 고정 제한이 아닙니다.
현재 재생은 25fps이므로 입력 영상도 25fps로 정규화합니다. 생성기는 입력 프레임을 그대로 추출하며 자동으로 속도를 맞추지 않습니다.
소스 영상의 음성은 아바타 목소리로 복제되지 않습니다. TTS 음성과 얼굴은 별도로 설정합니다.
아바타의 대기·몸 움직임은 소스 프레임을 반복하므로, 반복해도 자연스러운 구간을 선택합니다.

생성 화면 사용

Avatar Creator를 엽니다.
Model에서 Wav2Lip을 선택합니다. 현재 설치에 MuseTalk 가중치는 준비되어 있지 않습니다.
Avatar ID에 my_avatar_001처럼 새 이름을 입력합니다. 영문·숫자·밑줄 조합을 권장합니다.
영상 파일을 선택합니다.
Advanced Settings에서 아래 값을 확인합니다.
Submit Task를 누르고 작업 상태가 Completed가 될 때까지 기다립니다.

옵션	현재 권장 시작값	의미
Image Size	`256`	현재 Wav2Lip 가중치에 사용하는 얼굴 크기
Face Detect Batch Size	`1` 또는 `4`	검출 한 번에 처리하는 프레임 수
Pads	`0 10 0 0`	얼굴 위·아래·왼쪽·오른쪽 여백
BBox Shift	`0`	MuseTalk용 옵션, Wav2Lip에서는 사용하지 않음

Mac의 얼굴 검출은 CPU에서 실행됩니다. 최초에는 S3FD 가중치 약 86MiB를 자동으로 내려받습니다. 영상 길이와 해상도에 따라 생성 시간이 달라집니다. Failed가 표시되면 오류 메시지를 확인하세요.

이미 사용한 Avatar ID를 덮어쓰면 이전 프레임과 서버 캐시가 남을 수 있습니다. 새 영상을 만들 때는 새 ID를 사용하세요.

실제 생성 예제

사용한 원본은 Person_looks_at_camera_20260917001709.mp4입니다. 8초, 1280×720, 24fps 영상으로, 중간에 고개를 깊게 숙이고 입을 여는 장면이 있었습니다.

정면을 보고 입을 다문 5.5~8초 구간을 골라 별도 25fps 무음 영상으로 변환했습니다. 원본 파일은 보존했습니다.

# LiveTalking 디렉터리에서 실행
ffmpeg -ss 5.5 \
  -i /Users/dimplejuno/Downloads/Person_looks_at_camera_20260917001709.mp4 \
  -t 2.5 -an -vf fps=25 -c:v libx264 -crf 18 -pix_fmt yuv420p \
  output/mac-test/person-camera-avatar-source-25fps.mp4

생성은 다음 명령으로 수행했습니다.

.venv/bin/python -m avatars.wav2lip.genavatar \
  --video_path output/mac-test/person-camera-avatar-source-25fps.mp4 \
  --avatar_id person_camera_20260917 \
  --img_size 256 \
  --face_det_batch_size 1

63개 프레임 모두에서 얼굴 영역을 검출했고, 256×256 얼굴 이미지와 좌표를 생성했습니다. 한국어 InJoon 음성으로 1280×720, 약 25fps WebRTC 재생을 확인했습니다. 시연 녹화 보기. 원본의 Veo 워터마크는 유지했습니다.

생성되는 파일

data/avatars/person_camera_20260917/
├── full_imgs/       # 원본 인물·배경 프레임
├── face_imgs/       # 256×256 얼굴 프레임
└── coords.pkl       # 얼굴을 원본에 붙이는 좌표

세 데이터의 프레임 수가 일치해야 합니다. 생성기의 얼굴 검출 실패 처리는 전체 화면을 얼굴 영역으로 대체할 수 있어, Completed만으로 모든 프레임의 얼굴 검출 성공이 보장되지는 않습니다. 얼굴 이미지도 확인하세요.

새 인물 연결

재생 화면에서 Disconnect → Avatar ID 입력 → Ref Audio 입력 → Connect 순서로 설정합니다. 새 ID를 추가하고 연결하는 데는 서버 재시작이 필요 없습니다.

현재 사용할 수 있는 인물	Avatar ID	권장 한국어 음성
새로 만든 정장 남성	`person_camera_20260917`	`ko-KR-InJoonNeural`
안경 남성 샘플	`wav2lip_avatar_glass_man`	`ko-KR-InJoonNeural`
공식 여성 샘플	`wav2lip256_avatar1`	`ko-KR-SunHiNeural`

남성 샘플의 배포 출처는 AIAvatar Hugging Face입니다. 해당 샘플은 정적 프레임을 확인했으며 실시간 FPS를 따로 측정하지 않았습니다.

API로 생성

생성 화면 외에 POST /api/avatar/task로 로컬 영상 경로나 업로드 파일을 제출할 수 있습니다. 작업 ID로 진행률과 오류를 조회합니다. 아바타 API 예제를 참고하세요.

코드 기준: server/avatar_routes.py, server/task_manager.py, avatars/wav2lip/genavatar.py. 원본 생성 코드.