从零搭建 AI 实时直播间：数字人、弹幕调度与 OBS 推流实战

项目简介

AI 实时直播间是一个让 AI 数字人自主直播的开源项目。观众发送弹幕后，系统会先进行内容过滤，再根据当前语音和动作状态排队处理，避免一句话还没说完就插入下一条指令。

项目使用Vidu S2 实时数字人生成画面、声音和回复，本项目负责弹幕过滤与调度、角色资料、衣柜、直播间叠层、本地工作台，以及输出到 OBS 或直接推流。

代码采用 MIT 许可。仓库不包含作者自己的角色形象、人设、音色和素材库，因此部署后需要准备自己的角色资产，并自行承担内容版权与合规责任。

功能与限制

当前支持的能力

• 根据自定义人设进行聊天回复，并配置开场白。
• 从预先制作的衣柜中切换整套服装，单次换装大约需要 6 秒。
• 通过关键词触发比心、挥手、眨眼等小动作。
• 没有观众发言时，从角色话题池中自动暖场，避免一轮话题说完前重复。
• 自动过滤低俗和引流弹幕，礼物不会插队。
• 可选开启 Vidu 中途挂断后的自动重新开播。

需要注意的限制

• 默认不启用换背景、吃喝和拿道具，因为实时重绘可能导致角色衣服变形。
• 项目目前不适合唱歌、放歌、站立、全身动作、大幅度跳舞或带货。
• 不会跨直播场次记住老观众。
• 抖音弹幕没有内置抓取功能，应使用平台官方开放接口，不要抓取直播间网页。

换背景和道具功能默认关闭。如果只在私下测试，可以在 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

舞台页面依赖阿里云 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 排除，不会提交到仓库。

理解弹幕处理流程

工作台直播间页面支持手动发送模拟弹幕。真实弹幕则可以通过以下接口提交：

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/danmaku。

编辑直播间说明卡

舞台页面左右上角的说明卡用于展示本场直播能做什么、暂时不能做什么，以及如何发送更有效的弹幕。内容来自 assets/stage_panel.json；如果该文件不存在，则使用 assets/stage_panel.example.json。

复制示例文件后即可修改为自己的内容。舞台页面会在一分钟内自动刷新，内置推流的叠层会立即使用新内容。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 实时接口、弹幕识别、衣柜、素材生成、内置推流和工作台接口。
• static/：工作台、舞台页和旧版控制台。
• WORKBENCH_API.md：工作台使用的全部接口。
• tests/：测试代码和本地模拟服务。

结语

这个项目把 Vidu 实时数字人、弹幕规则、角色资产和直播输出连接成了一套本地工作流。推荐先用空跑模式熟悉过滤、排队、衣柜和叠层，再配置自己的形象、声音和 OBS 场景，最后接入真实平台。

公开直播时应关闭可能导致画面变形的实时背景和道具编辑，使用平台官方互动接口，并保留 AI 生成标识。同时，真人声音、角色形象、音乐和其他素材都应提前确认授权。