README in English

Makes your AI vtuber.

让 AI 成为虚拟主播：看懂弹幕，妙语连珠，悲欢形于色，以一种简单的实现

• 不定期的测试直播：http://live.bilibili.com/26949229
• QQ 交流群：569686683
• 介绍文章：知乎 - 写个AI虚拟主播：看懂弹幕，妙语连珠，悲欢形于色，以一种简单的实现
• We're currently developing this project for the Chinese Bilibili platform. We're still working on integrating it with YouTube, Twitch, and other platforms. Stay tuned for updates, and we welcome your contributions.

[TOC]

非服务模块：

v0.3.0 版本已实现了完全 Docker 化，所以应该支持任意常用操作系统了。现在只需要几个命令即可启动整个项目：

0. 安装 Docker 以及 Docker Compose。

1. 拉取代码：

# 拉取代码
git clone --recursive https://github.com/cdfmlr/muvtuber.git
cd muvtuber

⚠️ 由于使用了 git 子模块，一定要递归拉取。不能下载 zip，或不带 --recursive 参数的 clone。

🚧 默认的 main 分支是开发中的最新版本，不保证能运行。请使用打了 tag 个版本：点这里。

2. 修改配置：（详见 配置详解）

vim docker-compose.yml
# 按照你的实际情况修改 HTTP_PROXY、HTTPS_PROXY、API_URL 的配置

vim configs/externalsayer/config.yaml
# 配置 TTS 文本语音合成: 
# 配置 azure 语音合成服务的 key、region 和 role (SSML 模板)

vim configs/muvtuberdriver/config.yaml
# 主程序的配置:
#  你的房间号（roomid）、ChatGPT 的 apiKey 以及 initialprompt.
#  口型同步的策略：lipsyncstrategy
# 各种 server 的地址都不用改，已经配合 docker-compose.yml 设好了.

3. 启动服务：

docker compose up -d      # 自动下载或构建、启动各种服务

# docker compose ps       # 查看服务状态
# docker compose logs -f  # 查看日志（Ctrl+C 停止）

• 可以直接从 Docker Hub 拉取镜像啦 🎉
  • 在 v0.3.5 中，加入了 CI 机制。所有 Docker 镜像均由 GitHub Actions 自动构建，并推送到 Docker Hub （所有镜像都在 murchinroom 名下）。
  • 镜像较多，请保持网络通畅。在较差的网络情况下测试（校园网直连 Docker Hub），需要约 252.4s 拉取全部镜像。
• 亦可在本地自行构建各种镜像：
  • 请确保网络环境能访问 Docker Hub 和 GitHub.
  • 在中国大陆或其他网络环境受限的地区，请使用 Dockerfile。其他地区推荐使用 gh.Dockerfile。
• 请保证至少有 1 GB 可用硬盘空间。
• 如果遇到问题，可以先看一看 Troubleshooting。

4. 配置 OBS，开始直播：（下面三个都是新建浏览器源）
   • 主播 Live2DView：http://localhost:51070/#/?driver=ws://localhost:51071/live2d
   • 语音 AudioView：http://127.0.0.1:51082/?controller=ws://127.0.0.1:51081/
   • 弹幕 Blivechat：先用浏览器打开 http://localhost:51060，按需配置，然后复制粘贴链接和样式。

你可以为 ChatGPTChatbot 配置替代的 Chat API 和 HTTP 代理。其关系如下：

ChatGPTChatbot <--> HTTP Proxy <--> Chat API
                    默认: 无        默认: api.openai.com

ChatGPTChatbot 默认使用 OpenAI 的 Chat 接口: https://api.openai.com/v1/chat/completions （接口文档）

但也支持使用任何类似 ChatGPT的 API 接口。所以你可以使用一些本地的模型（例如 GPT4All）或者一些代理 OpenAI 的服务。

如果要使用这种替代接口，请修改 docker-compose.yml：

 chatgpt_chatbot:
   ...
   environment:
     - API_URL=https://api.openai.com/v1/chat/completions

将 API_URL 替换为你的 API 端点。

If you can access ChatGPT (api.openai.com) directly, please remove all lines about HTTP(S)_PROXY in the docker-compose.yml and skip following steps.

如果你的网络环境不好，直连 ChatGPT 或你配置的替代 Chat API 服务有困难，就需要做一些代理配置。

预先条件：你拥有一个可以让网络变好的魔法道具（行业黑话：代理）。

在你的代理设置中（可能还藏的比较深，如高级设置中），可以找到类似「本机 http 监听端口」之类的值，下面假设这个值为 http://0.0.0.0:1000。

接下来根据你的实际情况：

1. 你使用 Docker Desktop：

   • 在 Docker Desktop 里 Settings -> Resources -> Proxies 设置代理地址（宿主机以太网下的本地 IPv4 地址+代理软件设置的端口）
   • 把 doccker-compose.yml 文件中的有关 proxy 的内容注释掉或删除。

   （这个方法在 Windows 和 macOS 下验证可用，详见 #51 和 #30 的讨论，感谢 @RAINighty 和 @JackChow6 的帮助。）

2. 你使用 Docker 服务器环境或 Colima 之类的其他容器运行环境：

   • docker-compose.yml 中：

     chatgpt_chatbot:
       ...
       environment:
         - HTTP_PROXY=http://host.docker.internal:1000
         - HTTPS_PROXY=http://host.docker.internal:1000

   请按照自己的实际情况，替换掉端口号 1000。也有可能需要将 host.docker.internal 修改为容器眼里宿主机的 IP，具体要看你的运行时是否为你提供了一个容器访问宿主的域名或地址。如果你发现操作中有困难无法解决，建议尝试 Docker Desktop。

这里将配置使用免费、高质量的 Azure 的 TTS 服务。（目前也只支持这一种。） 该服务的介绍: https://azure.microsoft.com/zh-cn/products/cognitive-services/text-to-speech/

这一块的配置在 configs/externalsayer/config.yaml 中：

SrvAddr: "localhost:50010"
EnabledSayer: "azure"
AzureSayer:
  SpeechKey: "your-key"
  SpeechRegion: "eastus"
  FormatMicrosoft: "audio-16khz-32kbitrate-mono-mp3"
  FormatMimeSubtype: "mp3"
  Roles:
    "default": '<speak version="1.0" xml:lang="zh-CN"><voice name="zh-CN-XiaoxiaoNeural">{{.}}</voice></speak>'

你需要更改：SpeechKey, SpeechRegion 以及 Roles。

• SpeechKey, SpeechRegion： 你在 Azure 上申请的 TTS 服务的 key 和 region。
  • 具体的申请流程可以参考文档：快速入门：将文本转换为语音
• Roles：<voice name="xx-XX-Xxx">这里的 name 应该填写 voice，即“发音人”的名字。具体的列表可以通过以下命令获取：

curl https://eastus.tts.speech.microsoft.com/cognitiveservices/voices/list --header 'Ocp-Apim-Subscription-Key: xxx'

我把请求的结果格式化放到了这个文件里，方便查找：externalsayer/azuresayer/voices /voices-list.json。

你可以在网页上的「Speech Studio」里试听、选择声音。然后在文件里找到对应 voice 的 "ShortName": "xx-XX-Xxx" 填写到 <voice name="xx-XX-Xxx">。

🌟 更推荐的一种方式是，在「Speech Studio」中随便写点内容，选择声音让它说，并微调各种参数，满意之后，把 SSML 导出出来，把内容替换为 {{.}}，去掉换行（我写了个脚本帮助做这件事，可以点这里找到）写到配置里。

有三种 Live2D 口型同步策略可选：

• audio_analyze: 基于音频分析的口型同步。此法对 Live2D 模型的要求更少，更加通用，推荐。
• keep_motion: 在说话期间反复播放预制 live2d 动作，以达到类似“说话”的效果。此法要求预先为模型制作一些“说话”的 motion。
• none: 不进行口型同步。

在配置文件 configs/muvtuberdriver/config.yaml 中进行配置，从上述种策略中任选一个作为 sayer 下面的 lipsyncstrategy 的值：

sayer:
    ...
    lipsyncstrategy: audio_analyze

给新手的 OBS 配置详解：

• 虚拟形象（Live2DView）：来源 > + > 浏览器 > 新建 > URL: http://localhost:9000/#/
  • 注意把「通过 OBS 控制音频」勾上哦，然后把那条声音关掉，不然有机会听到可爱捏鬼畜日语。
• 弹幕框（blivechat）：来源 > + > 浏览器 > 新建 > URL:
  • 先用浏览器打开 http://localhost:12450
  • 首页 > 房间号：设置为你的房间号 > 进入房间
  • 弹出的窗口 -> 拷贝地址
  • 粘贴到 OBS 的 URL
• 主播说话的音频（audioview）：
  • 来源 > + > 浏览器 > 新建 > URL
  • 填入 http://127.0.0.1:51082/?controller=ws://127.0.0.1:51081/
  • 建议把「通过 OBS 控制音频」勾上，方便按需调节音量。
• 其他音频（BGM）：来源 > + >音频输入采集 > 新建 > 设备：BlackHole 2ch
  • 要先安装一个虚拟声卡，这里以 mac 系统使用 BlackHole 为例。
  • 在开始直播前，控制中心 > 声音> 右边 AirPlay 图标 > 选 BlackHole。
  • 然后电脑输出的声音就会 -> BlackHole -> OBS。
• B 站推流：设置（Preferences）> 直播 > 服务：选 Bilibili Live ...，推流码填「B 站首页 > 头像 > 推荐服务 > 直播中心 > 左侧“我的直播间”> 填好直播分类、房间标题 > 开始直播，然后会显示的串流密钥」

暂无。

有的时候，可能希望人工介入运行流程。比如测试时，没开直播，就读不到弹幕，但是希望能触发对话。 这时就可以通过 API 介入。

常用 API：

• 输入对话（相当于后台发虚空弹幕）：

$ curl -X POST localhost:51080 --data '{"author": "tester", "content": "主包，讲个地狱数学笑话喵"}' -i

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 27 Aug 2024 13:13:52 GMT
Content-Length: 15

{"status":"ok"}

• 触发 Live2D 动作：

$ curl -X POST localhost:51072/live2d -H 'Content-Type: application/json' --data '{"motion": "tap_body"}' -i

HTTP/1.1 200 OK
Date: Tue, 27 Aug 2024 13:14:28 GMT
Content-Length: 0

• 触发 Live2D 说话口型（与给定音频）同步：

$ curl -X POST localhost:51072/live2d -H 'Content-Type: application/json' -d '{"speak": {"audio": "https://cdn.jsdelivr.net/gh/RaSan147/pixi-live2d-display@v1.0.3/playground/test.mp3"}}' -i

HTTP/1.1 200 OK
Date: Tue, 27 Aug 2024 13:16:27 GMT
Content-Length: 0

• 调用 Chatbot：(详见 chatgpt chatbot 的 README)：

grpcurl -d '...' -plaintext localhost:51052 ...

• 调用 TTS：（注意这个会返回输出完整 base64 编码的音频二进制到标准输出，慎用！）

$ grpcurl -d '{"role": "xiao", "text": "test"}' -plaintext localhost:51065  muvtuber.sayer.v1.SayerService.Say

{
  "format": "mp3",
  "audio": "//NIxAA....一..大..段..人..类..不..可..睹..的..东..西..qqqqqqqqq"
}

（好像常用的也就这些了，其他暂时没想到，旧酱。）

目前仍不支持用 docker 作为开发环境。需要在本地开发，然后 docker 构建部署。

-1. 本地开发环境：

$ uname -mrs
Darwin 22.3.0 arm64
# 目前 TTS 模块还依赖于 macOS，其他系统可能不行。
$ go version  
go version go1.20.1 darwin/arm64
$ python3 --version
Python 3.9.16  # blivechat
Python 3.10.10 # others
$ poetry --version
Poetry (version 1.4.0)
$ node --version
v18.14.2
$ pyenv --version
pyenv 2.3.14
$ pnpm --version
7.29.0

Node.js 和 Python 的包管理配置：

# 前端统一使用 pnpm (珍爱硬盘，远离 npm)
pnpm config set auto-install-peers true -g
# python统一使用 pyenv + poetry
poetry config virtualenvs.prefer-active-python true
poetry config virtualenvs.in-project true  # 只是个人的保守偏好

0. 现在可用 git submodule 一次性拉取整个项目，无需手动 clone 各个模块了:

git clone --recursive https://github.com/cdfmlr/muvtuber.git

接下来编译运行各个模块，可以预先开 7 个终端页，然后：

1. blivechat

cd blivechat

# 编译前端
cd frontend
pnpm install
pnpm run build
cd ..

# 运行服务
pyenv local 3.9.16
poetry install
poetry run python main.py
# 服务运行在 http://localhost:12450，会自动在默认浏览器打开

2. Emotext

cd emotext

pyenv local 3.10.10
poetry install
poetry run python emotext/httpapi.py --port 9003
# emotext server: http://localhost:9003

3. ChatGPTChatbot

cd chatgpt_chatbot

pyenv local 3.10.10
poetry install
poetry run python chatgpt
# ChatGPTChatbot gRPC server: localhost:50052

4. MusharingChatbot

cd musharing_chatbot

pyenv local 3.10.10
poetry install
poetry run python -m spacy download en_core_web_sm  # 一个执行不到的依赖，但是不装跑不起来。
PYTHONPATH=$PYTHONPATH:. poetry run python musharing_chatbot
# MusharingChatbot gRPC server: localhost:50051

5. Live2dDriver

#git clone https://github.com/cdfmlr/live2ddriver.git
cd live2ddriver

go run . -shizuku localhost:9004 -verbose
# live2d shizuku driver: localhost:9004
# websocket message forwarder: localhost:9001 # 前端会连这个

# 不开发该模块也可以 build 出来再运行

6. Live2dView

#git clone https://github.com/cdfmlr/live2dview.git
cd live2dview

pnpm install
pnpm exec quasar dev
# 浏览器访问: 调试(戏)页: http://localhost:9000/#/debug
# 生产环境: OBS 添加浏览器源: http://localhost:9000/

# 如果不开发这个模块可以 build & serve:
pnpm exec quasar build
httpstatic -d dist/spa/ -l :9000  # 你的某种静态网页服务工具，如 python -m http.server，如果开发环境最好有宽松的 CROS。这里用的是 https://github.com/cdfmlr/tools/#httpstatic

7. audioview

cd audioview

pnpm install
pnpm run dev
# pnpm run build

8. externalsayer

cd externalsayer

go run . -h

9. muvtuberdriver

muvtuberdriver 必须在前面所有服务正确启动后才能启动，否则会 panic 退出。

#git clone https://github.com/cdfmlr/muvtuberdriver.git
cd muvtuberdriver

go run . -c config.yaml
# chatgpt_access_token: 浏览器访问https://chat.openai.com/api/auth/session获取
# roomid 你的 b 站直播间 id，https://live.bilibili.com/000000?... 中的000000

# 不开发该模块也可以 build 出来再运行

10. OBS

brew install obs
# 或：https://obsproject.com

# 启动 OBS，设置：
# - blivechat 的弹幕框：localhost:12450/...
# - Live2DView：localhost:9000
# - 音频（say）的输出：你使用的音频设备
# 【开始直播】

从 v0.3.5 开始，本项目各个服务模块均采用 GitHub Actions 自动完成镜像构建、推送，终端用户直接从 Docker Hub 拉取镜像即可。

如果出于开发或其他理由，需要手动构建镜像的话：

cd muvtuberdriver   # 或其他服务
docker build -t cdfmlr/muvtuber-muvtuberdriver:v0.0.12-alpha.0 .

• ⚠️ The default Dockerfile is designed for Chinese mainland users. Please use gh.Dockerfile instead if you are in other regions.
• 💥 构建 musharing_chatbot 镜像时如果出现 ProxyError，或者 Cannot connect to proxy: Name or service not known.，之类的网络代理问题，请参考 [#网络环境配置] 修改 musharing_chatbot/Dockerfile 中的代理设置。这个东西必须访问 GitHub，如果你的网络环境不允许直接访问 GitHub，可以使用代理。

然后在 docker-compose.yml 里将对应镜像修改成新构建镜像的 tag 即可。

使用前文的 docker compose 方式部署。不再提供散装微服务的部署文档了。

我（个人/商业/以及任意情况）可以使用这个项目嘛？

• 可以。在 MIT 协议下开放源代码，没有任何限制。
  • Permissions：✅ Commercial use ✅ Modification ✅ Distribution ✅ Private use
  • Limitations：❌ Liability ❌ Warranty

在 Microsoft Windows 系统中可以运行嘛？

• 可以。v0.3.0 完成了完全 Docker 化，只要宿主机能装 docker 就行：所有服务都跑在容器中，所有客户端都是浏览器（可以嵌入 OBS）。

作者寻求合作嘛？

• ✅ 你要和我一起写代码（贡献）
• ✅ 你要给我钱让我写我想写的东西（捐赠）
• ❌ 你要给我钱让我写你想要的东西（外包）
  • 非常抱歉，我的时间精力和能力有限。

为何如此复杂？|| 这个项目的意义是什么？

• Just for fun.

• Issues
• project-muvtuber

所有下属项目除非特别说明，一律在 MIT 协议下开放源代码。

欢迎任何有关 Issue 问题、PR 贡献以及讨论。