# LivekitDev 시작 가이드

> 작성일: 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. 일괄 실행기

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

```bat
start_all.bat
```

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

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

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

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

### 2. Avatar Bot 수동 기동

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

```powershell
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 웹을 빌드합니다.

```powershell
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` |

## 아바타 영상 교체

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

### Wav2Lip 실행 예시

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

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

## 문서 사이트 (Astro)

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

```powershell
cd docs-site
npm install
npm run dev
```

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

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

```powershell
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 드라이브 경로가 남아 있는지 확인 |