문제 해결
Connect 실패, 멈춘 영상, TTS와 아바타 생성 오류를 현재 로컬 설정에 맞춰 확인합니다.
먼저 서버 상태, 세션 상태, 음성 입력, 영상 재생을 차례로 나눠 확인합니다. 페이지가 열리는 것과 WebRTC 미디어가 연결되는 것은 별개의 단계입니다.
Connect가 되지 않을 때
- 서버 터미널이 실행 중인지 확인합니다.
- 관리 화면이나 아래 API가 응답하는지 확인합니다.
- 다른 재생 탭이 이미 연결되어 있다면 해당 탭에서 Disconnect를 누릅니다.
- Avatar ID가
data/avatars/의 실제 폴더 이름인지 확인합니다. - 서버 로그의 모델 로드 실패, 세션 한도와 오류 메시지를 확인합니다.
curl http://127.0.0.1:8010/api/admin/sessions현재는 max_session: 1이므로 한 탭의 테스트 연결만 있어도 다른 연결이 거절됩니다. 실제로 이 문제를 확인해 테스트 세션을 정리하고 연결 해제 API를 추가했습니다.
남아 있는 세션을 직접 정리해야 한다면 목록에서 종료할 세션을 확인한 뒤 아래 명령을 사용합니다. 현재 사용 중인 연결도 함께 끊기므로 해당 세션 ID를 정확히 지정합니다.
curl -X POST http://127.0.0.1:8010/disconnect \
-H 'Content-Type: application/json' \
-d '{"sessionid":"종료할_SESSION_ID"}'영상이 멈추거나 소리가 없을 때
- 영상의 재생 버튼을 누릅니다. 브라우저 자동 재생 제한이 원인일 수 있습니다.
- 탭, 시스템 출력 장치와 음소거 상태를 확인합니다.
- Text Driver를 Echo로 바꾸고 짧은 한국어 문장을 전송합니다.
- Ref Audio를
ko-KR-InJoonNeural또는ko-KR-SunHiNeural로 입력하고 재접속합니다. - Chat만 응답하지 않는다면 LLM의 설정·인증과 서버 로그를 확인합니다.
영상이 연결된 상태에서도 음성이 공급되지 않으면 인물은 대기 프레임을 반복합니다. 대기 화면을 보는 것만으로 TTS가 정상 동작한다고 판단하지 마세요.
TTS 시작이 느릴 때
현재 Edge TTS 어댑터는 문장의 전체 음성을 받은 뒤 재생을 시작합니다. 먼저 짧은 문장으로 테스트하고 인터넷 연결과 합성 로그를 확인합니다.
영상 추론 준비, 음성 합성, 재생 버퍼는 서로 다른 지연 요인입니다. 로그의 Edge TTS 시간만으로 전체 영상 응답 시간을 계산하지 않습니다. 스트리밍 합성이 필요한 경우 TTS 옵션을 확인하세요.
아바타 생성이 실패하거나 어색할 때
| 증상 | 확인할 항목 |
|---|---|
| 최초 모델 다운로드 실패 | 인터넷과 S3FD 가중치 다운로드 오류 |
| 메모리 사용 증가 | Face Detect Batch Size를 1로 낮추고 짧은 영상으로 시험 |
| 얼굴이 작거나 잘못 잘림 | 얼굴이 선명한 정면 구간 선택, 생성된 face_imgs 확인 |
| 입 주변 경계가 어색함 | 얼굴 크기 256, 좌표·여백, 입력 조명과 해상도 확인 |
| 움직임이 빨라짐 | 입력 영상을 25fps로 변환했는지 확인 |
| 이전 영상이 섞임 | 새로운 Avatar ID로 생성하고 재접속 |
| 고개 숙임이 반복됨 | 반복해도 자연스러운 정면 구간만 사용 |
Completed 이후에도 얼굴 이미지와 실제 립싱크를 확인합니다. 생성기는 얼굴 검출 실패 시 전체 화면을 얼굴 영역으로 대체할 수 있습니다.
다른 기기에서 접속되지 않을 때
현재 서버는 127.0.0.1에서만 요청을 받습니다. 다른 장비를 연결하려면 서버 바인딩, 서버 IP, HTTP·WebRTC 미디어 경로, 방화벽을 별도로 설정해야 합니다. 인터넷 원격 연결에서는 STUN/TURN과 NAT 경로도 확인합니다.
문서 사이트와 영상 서버는 서로 다른 포트입니다. 4321 포트의 문서가 열려도 8010 포트의 VisionAI이 실행 중이라는 뜻은 아닙니다.
로그와 확인 자료
현재 서버의 확인 자료는 다음 위치에 있습니다.
LiveTalking/
├── livetalking.log
├── output/mac-test/server-connect-fix.log
├── output/mac-test/person-camera-korean-lipsync.mp4
└── README-MAC-TEST.md# LiveTalking 디렉터리에서 실행
tail -n 60 livetalking.log로그 파일은 실행 방법에 따라 달라집니다. server-connect-fix.log는 이번 테스트 서버의 출력 파일이며 모든 실행에서 자동 생성되는 이름은 아닙니다.