개발 환경
코드를 고치기 전에 알아야 할 Python 환경, 핵심 패키지, 설정 우선순위, 모델 위치와 로컬 변경 사항.
이 페이지는 현재 Mac에 구성된 VisionAI 개발 환경을 정리합니다. 버전과 경로는 2026-09-18에 로컬 소스와 가상 환경에서 직접 확인한 값입니다. 서버 실행 절차는 빠른 시작을 참고하세요.
한눈에 보기
| 항목 | 현재 값 |
|---|---|
| 소스 위치 | GithubDev/LiveTalking |
| 기준 커밋 | b3e7490 (upstream lipku/LiveTalking) + 로컬 변경 |
| Python | 3.12.13, uv로 만든 .venv (약 1.1GB) |
| PyTorch | 2.9.1, torchvision 0.24.1, torchaudio 2.9.1 |
| 추론 장치 | MPS (Apple M3 Pro) |
| 웹 서버 | aiohttp + aiortc, 127.0.0.1:8010 |
| 실행 설정 | config-mac.yaml |
| 립싱크 가중치 | models/wav2lip.pth (약 205MB) |
| 시스템 도구 | ffmpeg 9.0.1 (Homebrew) |
| 테스트 | unittest, 2개 통과 |
Python 가상 환경
가상 환경은 LiveTalking/.venv에 있습니다. pyvenv.cfg에 uv = 0.10.12가 기록되어 있으며, Python은 uv가 관리하는 cpython-3.12-macos-aarch64 빌드입니다. 시스템 Python이나 Homebrew Python을 쓰지 않습니다.
이 가상 환경에는 pip가 없습니다. .venv/bin/python -m pip는 No module named pip로 실패합니다. 패키지를 추가하거나 바꿀 때는 uv를 사용합니다.
cd LiveTalking
uv pip install --python .venv/bin/python <패키지>항상 .venv/bin/python으로 실행하세요. run-mac.command도 이 경로를 직접 호출합니다. source .venv/bin/activate 없이도 동작합니다.
requirements 파일 두 개
| 파일 | 역할 |
|---|---|
requirements.txt |
upstream 원본. 버전을 대부분 고정하지 않았고, 많은 줄이 주석 처리되어 있습니다. |
requirements-mac-lock.txt |
이 Mac에서 실제로 실행에 성공한 110개 패키지의 정확한 버전입니다. |
환경을 다시 만들 때는 lock 파일을 기준으로 삼으세요. requirements.txt로 설치하면 최신 버전이 들어와 동작이 달라질 수 있습니다. 아래 명령은 재구성할 때의 예시이며, 이 순서로 처음부터 다시 만들어 보지는 않았습니다.
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements-mac-lock.txt핵심 패키지
requirements-mac-lock.txt에서 동작에 직접 관여하는 패키지를 골랐습니다.
| 영역 | 패키지 |
|---|---|
| 추론 | torch 2.9.1, torchvision 0.24.1, torchaudio 2.9.1, numpy 2.5.3, scipy 1.18.1, einops 0.8.2 |
| 영상 | opencv-python-headless 5.0.0.93, av 17.1.0 |
| 음성 | librosa 1.0.0, soundfile 0.12.1, resampy 0.4.3 |
| 전송·서버 | aiortc 1.15.0, aiohttp 3.14.3, aiohttp-cors 0.8.1, flask 3.1.3 |
| TTS·LLM | edge-tts 7.2.8, dashscope 1.27.5, openai 3.14.1, websockets 12.0 |
| 모델 부가 | transformers 5.17.0, diffusers 0.40.0, accelerate 1.15.0 |
| 설정 | pyyaml 6.0.3, python-dotenv |
websockets==12.0과 soundfile==0.12.1은 upstream requirements.txt에서도 버전이 고정되어 있습니다. 올리기 전에 해당 TTS 어댑터가 계속 동작하는지 확인하세요.
추론 장치
utils/device.py는 CUDA → MPS → CPU 순서로 첫 번째 사용 가능한 장치를 고릅니다. 이 Mac에서는 torch.backends.mps.is_available()이 True이므로 Wav2Lip 추론이 MPS에서 실행됩니다.
아바타 생성 전처리의 S3FD 얼굴 검출은 CPU에서 실행했습니다. MPS 추론과 CPU 전처리의 성능 차이를 감안해 생성 시간을 잡으세요.
같은 코드가 NVIDIA GPU 장비에서는 자동으로 CUDA를 사용합니다. 하지만 이 .venv는 macOS arm64용 휠로 구성되어 있으므로 다른 운영체제로 복사할 수 없습니다.
설정 우선순위
config.py의 parse_args()는 세 곳의 값을 다음 순서로 적용합니다.
- 명령줄 인자 (
--batch_size 4등) - YAML 파일 (
--config로 지정, 기본값config.yaml) add_argument(default=...)기본값
YAML 파일은 하나만 읽습니다. config-mac.yaml로 실행하면 config.yaml은 전혀 읽지 않습니다. 그래서 config-mac.yaml에 없는 항목은 config.yaml의 값이 아니라 코드의 기본값을 따릅니다. 예를 들어 TTS_SERVER는 http://127.0.0.1:9880, llm_provider는 dashscope가 됩니다.
YAML 키는 batch_size와 batch-size 두 표기를 모두 받습니다. 하이픈은 밑줄로 바뀝니다.
Mac 설정과 기본값 비교
| 옵션 | config-mac.yaml |
코드 기본값 | 의미 |
|---|---|---|---|
model |
wav2lip |
wav2lip |
립싱크 모델 (musetalk, wav2lip, ultralight) |
avatar_id |
wav2lip256_avatar1 |
wav2lip256_avatar1 |
시작 시 미리 불러올 아바타 |
batch_size |
2 |
16 |
한 번에 추론할 프레임 수 |
fps |
25 |
25 |
25로 고정해야 합니다 |
tts |
edgetts |
edgetts |
TTS 어댑터 |
REF_FILE |
ko-KR-SunHiNeural |
zh-CN-YunxiaNeural |
음성 ID 또는 참조 음성 경로 |
transport |
webrtc |
webrtc |
출력 방식 |
max_session |
1 |
5 |
동시 접속 세션 수 |
listenhost |
127.0.0.1 |
0.0.0.0 |
바인딩 주소 (로컬 추가 옵션) |
listenport |
8010 |
8010 |
웹 서버 포트 |
stun |
"" |
stun:stun.freeswitch.org:3478 |
빈 값이면 ICE 서버 없이 연결 |
listenhost: 127.0.0.1이므로 다른 컴퓨터에서는 접속할 수 없습니다. 원격 접속 조건은 연결과 설정을 참고하세요.
비밀 키와 .env
app.py는 시작할 때 load_dotenv()를 호출합니다. LiveTalking/.env 파일이 있으면 그 값을 환경 변수로 읽습니다. 현재는 .env.example만 있고 .env는 없습니다.
.gitignore에 .env가 없습니다. 키를 넣은 .env를 만들면 git add . 한 번에 커밋될 수 있습니다. 파일을 만들기 전에 .gitignore에 .env를 추가하세요.
| 환경 변수 | 사용하는 곳 |
|---|---|
DASHSCOPE_API_KEY |
LLM(dashscope), qwentts |
ORCAROUTER_API_KEY |
LLM(orcarouter) |
AZURE_SPEECH_KEY, AZURE_TTS_ENDPOINT |
azuretts |
DOUBAO_API_KEY |
doubao |
TENCENT_APPID, TENCENT_SECRET_ID, TENCENT_SECRET_KEY |
tencent |
현재 설정의 Edge TTS와 Echo 모드는 키 없이 동작합니다. Chat 모드는 LLM을 호출하므로 DASHSCOPE_API_KEY 또는 ORCAROUTER_API_KEY가 필요합니다. 두 제공자 모두 OpenAI 호환 엔드포인트를 사용하며 llm.py의 LLM_PROVIDERS에 정의되어 있습니다.
모델과 아바타 데이터
| 경로 | 내용 |
|---|---|
models/wav2lip.pth |
Wav2Lip 가중치. app.py가 이 경로를 코드에 고정해서 읽습니다. |
data/avatars/<avatar_id>/ |
아바타 한 개 (full_imgs/, face_imgs/, coords.pkl) |
data/avatars/ 전체 |
약 504MB, 아바타 3개 |
output/mac-test/ |
테스트 녹화·로그·입력 음성 |
--modelfile 옵션이 있지만 Wav2Lip 경로에서는 사용하지 않습니다. 다른 가중치를 시험하려면 models/wav2lip.pth를 교체하거나 app.py의 해당 줄을 수정해야 합니다.
아바타는 서버 시작 시 avatar_id 하나를 미리 불러오고, 다른 아바타는 연결할 때 불러옵니다. 폴더 구조는 아바타 생성에서 만든 결과와 같습니다. data/avatars/__MACOSX는 압축 해제 부산물이므로 무시해도 됩니다.
models/와 data/는 .gitignore로, .venv/는 uv가 만든 자체 .gitignore로 git에서 제외됩니다. 다른 장비로 옮길 때는 따로 복사해야 합니다.
코드 구조
| 디렉터리·파일 | 역할 |
|---|---|
app.py |
진입점. 설정을 읽고 모델과 아바타를 불러온 뒤 aiohttp 서버를 시작합니다. |
config.py |
명령줄 인자와 YAML 설정 처리 |
registry.py |
플러그인 등록부 (stt, llm, tts, avatar, output) |
avatars/ |
립싱크 모델별 구현 (wav2lip, musetalk, ultralight) |
tts/ |
TTS 어댑터 8개 |
streamout/ |
출력 방식 (webrtc, rtmp, virtualcam) |
server/ |
HTTP 라우트, WebRTC 세션, 아바타 생성 작업, ASR |
web/ |
브라우저 페이지. / 경로에 정적 파일로 제공됩니다. |
llm.py |
Chat 모드의 LLM 호출 |
새 TTS 엔진이나 출력 방식은 @register("tts", "이름")처럼 데코레이터로 등록합니다. 등록된 이름을 설정의 tts: 값으로 지정하면 registry.create()가 인스턴스를 만듭니다. 기존 어댑터의 구조는 TTS 옵션에서 설명합니다.
app.py는 torch.multiprocessing의 시작 방식을 spawn으로 설정합니다. 자식 프로세스는 모듈을 새로 import하므로 모듈 최상단에 무거운 초기화 코드를 두지 마세요.
upstream과 다른 로컬 변경
기준 커밋 b3e7490 이후 다음 파일을 이 Mac에서 수정했습니다. 커밋하지 않은 상태이므로 git pull이나 git checkout . 전에 백업하세요.
| 파일 | 변경 내용 |
|---|---|
config.py |
--listenhost 옵션 추가 |
app.py |
바인딩 주소를 listenhost로 변경, /disconnect 라우트 추가 |
server/rtc_manager.py |
빈 stun 값 처리, 세션별 연결 추적, handle_disconnect() 추가 |
web/index.html, web/index-en.html |
Disconnect 및 페이지 종료 시 세션 해제 요청 |
run-mac.command, config-mac.yaml, requirements-mac-lock.txt, README-MAC-TEST.md, output/은 새로 추가했으며 git에 추적되지 않습니다.
/disconnect가 없으면 max_session: 1 환경에서 닫힌 탭이 세션 슬롯을 계속 차지합니다. upstream을 병합할 때 이 변경이 빠지지 않았는지 확인하세요.
테스트
tests/에는 로컬 ASR 서버의 단위 테스트 한 개 파일이 있습니다. 외부 모듈을 가짜 객체로 대체하므로 모델 없이 실행됩니다.
cd LiveTalking
.venv/bin/python -m unittest discover -s tests2026-09-18 실행 결과는 Ran 2 tests ... OK입니다. 립싱크 추론, TTS, WebRTC 연결은 자동 테스트가 없으므로 빠른 시작의 순서로 브라우저에서 직접 확인합니다.
시스템 도구
ffmpeg는 Python 패키지가 아니라 명령줄 도구로 호출됩니다. avatars/base_avatar.py의 녹화 기능이 영상·음성을 따로 기록한 뒤 ffmpeg로 합칩니다. 현재 /opt/homebrew/bin/ffmpeg 9.0.1을 사용합니다. PATH에 ffmpeg가 없으면 서버는 시작되지만 녹화가 실패합니다.
Dockerfile
저장소의 Dockerfile은 CUDA 11.6, Python 3.10, PyTorch 1.12.1을 기준으로 한 Linux용 upstream 파일입니다. 현재 Mac 환경(Python 3.12, PyTorch 2.9.1, MPS)과 맞지 않으며 이 Mac에서 사용하지 않았습니다. NVIDIA GPU 서버를 구성할 때 참고용으로만 보세요.
이 문서 사이트
이 문서는 GithubDev/Docs의 Astro 7.3.3 사이트입니다. 페이지는 src/content/docs/*.md이고, 메뉴와 검색 요약은 src/data/navigation.ts에서 관리합니다.
cd Docs
npm run dev # http://localhost:4351, 백그라운드로 실행
npm run stop # 개발 서버 종료
npm run check # 타입·문법 검사
npm run build # dist/에 정적 사이트 생성포트 4351은 astro.config.mjs에 고정되어 있습니다. 명령줄에 --port를 넘기면 설정 파일보다 우선하므로 넘기지 마세요.