주요 콘텐츠로 건너뛰기
AI 튜토리얼

처음부터 구축하는 AI 실시간 라이브 방송실: 디지털 휴먼, 댓글 조정 및 OBS 송출 실전

이 글에서는 AI 실시간 라이브 방송실을 설치하고 Vidu, 캐릭터, 의상실과 음성을 설정한 뒤, 댓글 필터링 및 조정을 연동하고 OBS 또는 내장 방식을 통해 라이브 화면을 출력하는 방법을 안내합니다.

약 15분 소요
처음부터 구축하는 AI 실시간 라이브 방송실: 디지털 휴먼, 댓글 조정 및 OBS 송출 실전

프로젝트 소개

AI 실시간 라이브 방송은 AI 디지털 휴먼이 자율적으로 라이브 방송을 진행할 수 있도록 하는 오픈 소스 프로젝트입니다. 시청자가 댓글을 보내면 시스템이 먼저 내용을 필터링한 다음, 현재 음성과 동작 상태에 따라 대기열에 넣어 처리하므로 한 문장이 끝나기도 전에 다음 명령이 끼어드는 것을 방지합니다.

이 프로젝트는 Vidu S2 실시간 디지털 휴먼으로 화면, 음성 및 답변을 생성하며, 댓글 필터링과 스케줄링, 캐릭터 프로필, 의상실, 라이브 방송 오버레이, 로컬 워크벤치, OBS 출력 또는 직접 스트리밍을 담당합니다.

코드는 MIT 라이선스를 따릅니다. 저장소에는 작성자 본인의 캐릭터 이미지, 캐릭터 설정, 음색 및 소재 라이브러리가 포함되어 있지 않으므로 배포 후 자체 캐릭터 자산을 준비해야 하며, 콘텐츠 저작권 및 규정 준수에 대한 책임은 사용자가 부담해야 합니다.

기능 및 제한 사항

현재 지원하는 기능

  • 사용자 지정 캐릭터 설정에 따른 채팅 답변 및 오프닝 멘트 설정.
  • 미리 제작한 의상실에서 한 벌의 의상 전체를 전환하며, 한 번의 의상 변경에 약 6초가 필요합니다.
  • 키워드로 하트 보내기, 손 흔들기, 눈 깜빡이기 등의 간단한 동작을 실행합니다.
  • 시청자 발언이 없을 때 캐릭터 주제 풀에서 자동으로 분위기를 띄워 한 주제가 끝나기 전에 반복되는 것을 방지합니다.
  • 저속한 댓글과 외부 유도 댓글을 자동으로 필터링하며, 선물은 대기열을 건너뛰지 않습니다.
  • Vidu가 방송 중 연결을 끊은 후 자동으로 방송을 다시 시작하는 기능을 선택할 수 있습니다.

주의해야 할 제한 사항

  • 실시간 재생성으로 캐릭터 의상이 변형될 수 있으므로 배경 변경, 먹고 마시기 및 소품 사용은 기본적으로 활성화되지 않습니다.
  • 현재 프로젝트는 노래, 음악 재생, 서 있기, 전신 동작, 큰 동작의 춤 또는 상품 판매 방송에 적합하지 않습니다.
  • 이전 라이브 방송의 기존 시청자를 기억하지 않습니다.
  • 더우인 댓글 수집 기능은 내장되어 있지 않으므로 플랫폼 공식 오픈 API를 사용해야 하며, 라이브 방송 웹페이지를 수집해서는 안 됩니다.

배경 및 소품 기능은 기본적으로 비활성화되어 있습니다. 비공개 테스트에만 사용하는 경우 config.json에서 {"safety":{"live_visual_edits":true}}로 설정할 수 있습니다. 공개 라이브 방송에서는 활성화하지 않는 것을 권장합니다.

실행 환경 준비

시작하기 전에 다음 환경과 계정을 준비하세요.

  • macOS 또는 Linux.
  • Python 3.11 이상 버전. 작성자는 Python 3.13을 사용합니다.
  • libx264 및 aac가 포함된 ffmpeg.
  • Vidu 오픈 플랫폼 API Key. 키는 vda_로 시작하며 계정에 사용 가능한 포인트가 있어야 합니다.
  • 선택 사항인 Evolink API Key. 이미지, 의상, 소품 및 배경 생성에 사용하며, 음성 복제 시 오디오 업로드에도 사용할 수 있습니다.
  • 선택 사항인 OBS 30 이상 버전. 카메라, 오버레이 및 스트리밍에 사용합니다.
  • 선택 사항인 YouTube 스트림 키. 내장 스트리밍을 사용할 때만 필요합니다.

Vidu 실시간 디지털 휴먼은 사용 시간에 따라 요금이 부과됩니다. README에 제시된 공식 가격은 초당 1.5포인트이며, 1포인트는 0.03125위안으로 한 시간에 약 169위안이 필요합니다. 먼저 드라이런 모드와 로컬 모의 서비스를 사용해 흐름을 검증하는 것을 권장합니다.

키 안전하게 저장하기

키는 로컬 파일에만 저장하고 서버에서 읽어야 하며, 브라우저로 전송되지 않습니다. 먼저 기본 디렉터리를 생성합니다.

mkdir -p ~/.deepsea/vidu ~/.deepsea/evolink && chmod 700 ~/.deepsea/vidu ~/.deepsea/evolink

macOS에서는 클립보드의 Vidu Key를 기본 경로에 저장할 수 있습니다.

pbpaste > ~/.deepsea/vidu/api.key && chmod 600 ~/.deepsea/vidu/api.key

Evolink Key는 ~/.deepsea/evolink/api.key에 저장합니다. YouTube 내장 스트리밍을 사용하는 경우 스트림 키는 ~/.deepsea/youtube/stream.key에, OBS WebSocket 비밀번호는 ~/.deepsea/obs/ws.password에 저장합니다. 기본 경로는 config.json에서 변경할 수도 있습니다.

프로젝트 설치

GitHub에서 저장소를 복제하고 프로젝트 디렉터리로 이동합니다.

git clone https://github.com/garycaogan/ai-live-avatar.git
cd ai-live-avatar

Python 가상 환경을 생성하고 의존성을 설치합니다.

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

스테이지 페이지는 Alibaba Cloud RTC 웹 SDK에 의존합니다. 프로젝트는 해당 SDK를 재배포하지 않고, 스크립트를 통해 공식 CDN에서 다운로드한 뒤 검증합니다.

./tools/fetch_vendor.sh

마지막으로 예시 설정 파일을 복사합니다.

cp config.example.json config.json

워크벤치 시작

서비스를 실행합니다.

.venv/bin/python server.py

서비스는 기본적으로 로컬 컴퓨터에서만 수신 대기합니다. 시작한 후 브라우저에서 http://127.0.0.1:28900/workbench를 열면 워크벤치로 들어갈 수 있습니다.

당분간 Vidu 포인트를 사용하고 싶지 않다면 라이브 방송 페이지에서 드라이런 방송 시작을 사용할 수 있습니다. 이 모드에서는 Vidu를 호출하지 않고 댓글 필터링, 대기열 및 오버레이만 시연합니다. 프로젝트에는 tests/dev_mock_stack.py도 제공되며, 로컬에서 모의 Vidu에 연결하여 제어 흐름을 전체적으로 테스트할 수 있습니다.

자신만의 디지털 휴먼 캐릭터 만들기

1. 이미지 준비

소재 페이지에서 이미지 한 장을 업로드하거나 Evolink를 사용해 생성할 수 있습니다. 기본 이미지는 캐릭터의 외모, 의상, 방 및 기본 표정에 영향을 줍니다. README에서는 한 사람의 근접 촬영, 테이블 위에 양손을 올린 자연스러운 표정의 이미지를 권장합니다.

가로 구도는 더우인 세로 라이브 방송 페이지와 유사한 화면 상단의 작은 프레임에 배치되고 1.2:1 비율로 잘리므로, 기본 이미지의 구도는 미리 이에 맞추는 것이 좋습니다.

2. 캐릭터 프로필 생성

캐릭터 페이지에서 새 캐릭터를 만들고 이미지의 기본 이미지를 선택한 다음 이름, 캐릭터 설정 및 오프닝 멘트를 입력합니다. 캐릭터 설정에는 말투를 중점적으로 설명하고 완전한 예시 문장은 작성하지 마세요. 그렇지 않으면 모델이 예시를 그대로 읽을 수 있습니다.

3. 의상실 추가

의상실 페이지에서 여러 벌의 의상을 추가합니다. 각 의상은 완성된 사진 한 장이어야 하며, 방, 조명 및 구도는 기본 이미지와 최대한 일치해야 합니다. 그렇지 않으면 의상 변경 시 화면이 크게 튈 수 있습니다.

4. 음성 설정

음성 페이지에서 시스템 음색을 선택하거나 10~20초 길이의 깨끗한 음성을 업로드해 복제합니다. Vidu 음성 복제는 유료이므로 소재를 업로드하기 전에 해당 음성을 사용할 권한이 있는지 확인해야 합니다.

5. 동작 설정

동작 페이지에서 댓글 키워드에 대응하는 동작을 수정할 수 있습니다. 캐릭터 설정에서는 새 댓글이 없을 때 화면을 더 자연스럽게 만드는 대기 동작도 편집할 수 있습니다.

캐릭터 프로필은 assets/avatars/profiles.json에, 캐릭터 설정은 personas/에 저장됩니다. 이 파일들은 이미 .gitignore에서 제외되어 저장소에 커밋되지 않습니다.

댓글 처리 흐름 이해하기

워크벤치 라이브 방송 페이지에서는 모의 댓글을 수동으로 보낼 수 있습니다. 실제 댓글은 다음 API를 통해 제출할 수 있습니다.

curl -s -X POST http://127.0.0.1:28900/api/danmaku \
  -H 'Content-Type: application/json' \
  -d '{"user":"观众A","text":"换件衣服","gift":0}'

댓글이 시스템에 들어오면 먼저 moderation.json의 필터 단어를 검사한 다음, live/router.py가 규칙에 따라 채팅, 의상 변경, 소품, 배경, 동작 또는 복원으로 분류합니다. 이 분류 과정에서는 대규모 언어 모델을 호출하지 않으므로 추가 지연이나 비용이 발생하지 않습니다.

기본적으로 소품 및 배경 요청은 일반 채팅으로 처리됩니다. 댓글 인식은 간단하고 명확한 표현에 더 적합합니다. 예를 들어 방송자 주변의 사소한 일을 묻거나, 의상실에 있는 의상 이름으로 의상을 변경하거나, 한 번에 하나의 동작만 요청하는 방식입니다.

다음과 같은 내용은 일반적으로 결과에 영향을 줍니다. 한 문장에 여러 작업을 포함하는 경우, 실시간 뉴스나 날씨를 묻는 경우, 노래를 부르거나 음악을 재생하도록 요구하는 경우입니다. 복잡한 요구는 여러 개의 간단한 댓글로 나누는 것을 권장합니다.

OBS 연결

워크벤치의 스트리밍 페이지에서 출력 방식을 OBS로 전환한 다음 OBS에서 브라우저 소스를 추가합니다. 필요에 따라 다음 주소를 선택하세요.

  • 디지털 휴먼만 표시: http://127.0.0.1:28900/stage?obs=1&role=obs&layer=avatar
  • 투명 오버레이만 표시: http://127.0.0.1:28900/stage?overlay=1
  • 디지털 휴먼과 오버레이 표시: http://127.0.0.1:28900/stage?obs=1&role=obs&layer=all

전체 화면은 너비 1080, 높이 1920으로 설정하는 것을 권장합니다. 브라우저 소스에서 “OBS를 통해 오디오 제어”를 선택해야 합니다. 서비스가 로컬 컴퓨터에서만 수신 대기하므로 OBS와 프로젝트 서비스는 반드시 같은 컴퓨터에서 실행해야 합니다.

OBS 장면을 자동으로 만들고 싶다면 tools/obs_control.py를 사용할 수 있습니다. 오버레이에는 “AI 실시간 생성 화면” 표시가 항상 나타납니다. 이는 AI 디지털 휴먼 라이브 방송에 대한 플랫폼 요구 사항이므로 유지해야 합니다.

더우인 라이브 방송 화면 설정

더우인에서 흔히 사용하는 디지털 휴먼 라이브 방송은 가로 화면이며, 모바일에서는 화면이 위쪽 영역에 표시되고 댓글은 아래쪽에 표시됩니다. 다음 명령을 실행하면 “더우인 라이브 방송” 장면을 만들 수 있습니다.

.venv/bin/python tools/obs_control.py setup douyin --camera FaceTime

이 명령은 OBS 캔버스를 1296×1080, 즉 1.2:1 비율로 설정하고 디지털 휴먼, 안내 카드, 자막 및 실제 카메라를 구성합니다. --camera 뒤에는 카메라 이름의 일부를 입력합니다. 생략하면 검색된 첫 번째 실제 카메라가 사용됩니다.

처음 실행할 때 macOS에서 OBS의 카메라 사용 권한을 요청할 수 있습니다. 허용한 후 한 번 더 실행해야 카메라 자르기가 올바르게 적용됩니다. 가로 화면과 세로 화면 장면은 언제든 전환할 수 있으며, 동일한 디지털 휴먼 레이어를 공유하므로 추가 입장 인원을 사용하지 않습니다.

더우인 라이브 방송 도우미에 연결하는 방법은 두 가지입니다. OBS 가상 카메라를 켠 다음 라이브 방송 도우미에서 OBS Virtual Camera를 선택하거나, 라이브 방송 도우미에서 창 소스를 추가해 OBS 프로젝션 창을 캡처할 수 있습니다. 가상 카메라는 화면만 전송하고 소리는 전송하지 않으므로, 라이브 방송 도우미가 “더우인 라이브 방송” 장면의 컴퓨터 오디오를 수집할 수 있는지도 확인해야 합니다.

계정에 타사 스트리밍 권한이 있다면 OBS에서 플랫폼이 제공한 스트리밍 주소를 직접 입력할 수도 있습니다. 더우인 댓글은 프로젝트에 자동으로 들어오지 않으므로 더우인 오픈 플랫폼의 라이브 방송 기능 API를 통해 권한을 신청한 후 데이터를 /api/danmaku로 전송해야 합니다.

라이브 방송 안내 카드 편집

스테이지 페이지 왼쪽과 오른쪽 상단의 안내 카드는 이번 라이브 방송에서 가능한 작업과 일시적으로 불가능한 작업, 더 효과적인 댓글을 보내는 방법을 표시하는 데 사용됩니다. 내용은 assets/stage_panel.json에서 가져오며, 이 파일이 없으면 assets/stage_panel.example.json을 사용합니다.

예시 파일을 복사한 후 원하는 내용으로 수정할 수 있습니다. 스테이지 페이지는 1분 이내에 자동으로 새로 고쳐지며, 내장 스트리밍의 오버레이는 새 내용을 즉시 사용합니다. outfit_hint를 사용하면 캐릭터별로 의상 변경 안내를 설정할 수 있습니다.

자동 방송 재시작 활성화

Vidu는 라이브 방송 중 간혹 연결이 끊길 수 있습니다. 자동 복구를 활성화하면 프로젝트가 3초 동안 기다린 후 방송을 다시 시작하며, 한 시간에 최대 6회 시도합니다. 단, 포인트 부족이나 콘텐츠 심사로 인해 연결이 끊긴 경우에는 자동으로 다시 시작하지 않습니다.

API를 통해 활성화합니다.

curl -s -X POST http://127.0.0.1:28900/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"auto_recover":true}'

config.json에서 설정할 수도 있습니다.

{"schedule":{"auto_recover":true}}

장시간 라이브 방송을 시작하기 전에 계정 잔액, 캐릭터 소재 및 네트워크 상태를 확인하고, 드라이런 또는 로컬 모의 서비스를 사용해 복구 흐름을 검증하는 것을 권장합니다.

테스트 및 프로젝트 구조

프로젝트 테스트는 로컬에서 모의 Vidu를 사용하므로 비용이 발생하지 않습니다. 다음을 실행할 수 있습니다.

python -m unittest tests.test_logic tests.test_workbench tests.test_e2e

주요 디렉터리와 파일의 용도는 다음과 같습니다.

  • server.py: 서비스 진입점 및 기본 설정.
  • live/: 라이브 방송 일정 관리, Vidu 실시간 API, 댓글 인식, 옷장, 소재 생성, 내장 스트리밍 및 워크벤치 API.
  • static/: 워크벤치, 스테이지 페이지 및 구형 콘솔.
  • WORKBENCH_API.md: 워크벤치에서 사용하는 모든 API.
  • tests/: 테스트 코드 및 로컬 모의 서비스.

맺음말

이 프로젝트는 Vidu 실시간 디지털 휴먼, 댓글 규칙, 캐릭터 에셋 및 라이브 방송 출력을 하나의 로컬 워크플로로 연결합니다. 먼저 실제 실행 없이 필터링, 대기열, 옷장 및 레이어를 익힌 다음, 자신의 이미지와 음성 및 OBS 장면을 설정하고 마지막으로 실제 플랫폼에 연결하는 것을 권장합니다.

공개 라이브 방송에서는 화면 왜곡을 일으킬 수 있는 실시간 배경 및 소품 편집을 비활성화하고, 플랫폼 공식 상호작용 API를 사용하며, AI 생성 표시를 유지해야 합니다. 또한 실제 사람의 음성, 캐릭터 이미지, 음악 및 기타 소재는 모두 사전에 사용 권한을 확인해야 합니다.