시작 가이드

원본 다운로드: Markdown · PDF

작성일: 2026-07-19 · 한글 복구: 2026-09-07

사전 요구 사항

Windows와 Caddy (기존 일괄 실행기는 WSL Ubuntu 사용)
LiveKit 실행 파일: livekit/bin/livekit-server.exe
Flutter: 웹 클라이언트 빌드에 사용
Python 3.x: Avatar Bot 및 Wav2Lip 실행에 사용
GPU 권장: 립싱크 영상 생성 및 얼굴 복원에 사용

빠른 기동

1. 일괄 실행기

프로젝트 루트에서 실행합니다.

start_all.bat

이 실행기는 WSL의 Caddy 설정을 복사하고 다시 불러온 뒤, LiveKit 서버를 시작합니다. Avatar Bot 실행 부분은 주석 처리되어 있어 별도로 실행해야 합니다.

경로 확인: 현재 start_all.bat에는 D:\LivekitDev와 /mnt/d/LivekitDev가 남아 있습니다. 사용하기 전에 실제 작업 경로인 C:\Developments\LivekitDev에 맞게 수정해야 합니다.

LiveKit만 직접 실행하려면 프로젝트 루트에서 다음 명령을 사용합니다.

cd livekit
.\bin\livekit-server.exe --config config.yaml --bind 0.0.0.0

2. Avatar Bot 수동 기동

환경 변수를 설정한 뒤 봇을 실행합니다. 다음 명령은 필요한 패키지가 설치된 기존 환경을 전제로 합니다.

cd avatar_bot
$env:LIVEKIT_URL = "ws://localhost:7880"
$env:LIVEKIT_API_KEY = "devkey"
$env:LIVEKIT_API_SECRET = "secret"
$env:ROOM_NAME = "my-room"
uv run python avatar_bot.py

avatar_bot은 requirements.txt를 사용하는 기존 프로젝트입니다. 의존성 관리 방식을 변경할 때는 uv 마이그레이션 여부를 먼저 확인합니다.

3. 웹 클라이언트

배포 주소: https://meet.dev.tictechtoeai.com/videocall/

프로젝트 루트에서 Flutter 웹을 빌드합니다.

cd livekit_video_call
flutter build web

Caddy의 정적 파일 루트는 실제 livekit_video_call/build/web 경로와 일치해야 합니다. 기존 설정에 D:\LivekitDev 또는 /mnt/d/LivekitDev가 남아 있는지 확인합니다.

접속 정보 (개발 환경)

항목	값
LiveKit WebSocket (로컬)	`ws://localhost:7880`
LiveKit WSS (외부)	`wss://meet.dev.tictechtoeai.com:7443`
API Key	`devkey`
API Secret	`secret`
기본 Room	`my-room`

아바타 영상 교체

Wav2Lip 등으로 새 영상을 생성합니다.
avatar_bot/videos/avatar.mp4를 새 영상으로 교체합니다.
봇이 파일 수정 시간의 변경을 감지하면 영상을 다시 불러옵니다.

Wav2Lip 실행 예시

필요한 모델과 의존성이 준비된 환경에서 실행합니다.

cd Wav2Lip
uv run python full_pipeline.py --face ..\videos\whd.mp4 --audio ..\videos\rodu.wav --output ..\avatar_bot\videos\avatar.mp4

문서 사이트 (Astro)

프로젝트 루트에서 실행합니다.

cd docs-site
npm install
npm run dev

기본 주소: http://localhost:4321

정적 사이트 빌드 및 미리보기:

npm run build
npm run preview

문서는 docs-site에 통합되어 있습니다.

Markdown 및 PDF 원본: docs-site/public/downloads/
Astro 페이지: docs-site/src/content/docs/
원본 동기화: npm run sync:docs (개발 서버 실행 및 빌드 전에 자동 수행)

문제 해결 체크리스트

증상	확인 사항
방 접속 실패	LiveKit 실행 상태, Caddy의 7443 포트 설정, 방화벽
아바타가 보이지 않음	봇 실행 상태, 영상 파일 존재, 방 이름 일치 여부
아바타 제어 문제	DataChannel의 avatar-control 및 avatar-status 토픽
정적 파일 404	Flutter 빌드 경로와 Caddy의 파일 루트 일치 여부
경로 오류	이전 D 드라이브 경로가 남아 있는지 확인