metahuman-stream 实时交互流式数字人引擎从零部署 Wav2Lip/MuseTalk 数字人与音视频同步对话【免费下载链接】metahuman-streamReal time interactive streaming digital human项目地址: https://gitcode.com/GitHub_Trending/me/metahuman-stream导读metahuman-streamLiveTalking是一个实时交互流式数字人引擎实现文本/语音 → LLM 对话 → TTS 合成 → 实时口型推理 → 音视频推流的全链路音视频同步对话能力据项目说明已在业内获得广泛商用。本文以仓库根目录 README.md 为骨架结合 app.py、config.py、registry.py、avatars/base_avatar.py、server/routes.py 等源码与 docs/api.md 等接口文档完整讲解环境安装、模型部署、服务启动、系统架构、API 调用与性能评估读完可直接从零跑起一路数字人直播/客服/讲解服务并掌握如何扩展 TTS、Avatar、输出通道等插件模块。一、项目概览与核心特性metahuman-stream 是一个基于 Python 的实时交互流式数字人服务端支持多种数字人模型、多路并发会话并提供了 Web 页面与 HTTP/WebRTC 接口供前端对接。其核心特性如下来自 README.md支持多种数字人模型ernerf、musetalk、wav2lip、Ultralight-Digital-Human支持声音克隆通过参考音频/参考文本配置音色支持数字人说话被打断用户可随时插话数字人立即响应支持全身视频拼接推理生成的口型区域可平滑贴回原始高清全身视频支持 WebRTC、RTMP、虚拟摄像头输出低延迟浏览器推流、标准直播协议、系统摄像头设备三种通道支持动作编排不说话时播放自定义视频静音状态下的待机动作/循环视频支持多并发每个连接分配唯一 sessionid可同时服务多个会话支持自定义数字人形象上传视频即可自动生成专属数字人 Avatar提供前端 API 接口对接文本驱动、音频驱动、录制、状态查询等 HTTP 接口。从源码结构看这些特性由avatars/数字人模型、tts/语音合成、server/WebRTC 会话与路由、streamout/输出通道四组模块协同实现模块间通过 registry.py 的注册表解耦。二、典型使用场景LiveTalking 基于实时流式数字人技术通过文本或语音驱动虚拟形象说话结合 LLM 实现智能对话。README 中列举的主要场景如下场景说明虚拟主播/直播带货24 小时无人直播通过 LLM 自动生成带货话术配合动作编排实现自然表现AI 数字人客服接入企业知识库用户语音提问数字人实时回答支持打断重说在线教育/培训教师数字分身录制课程或通过 API 驱动数字人讲师实时授课智能语音助手结合智能音箱或 APP调用/human接口驱动数字人进行语音对话交互大屏讲解数字人讲解员在展厅大屏、活动现场等场景进行内容讲解和互动短视频批量制作通过 API 批量提交文案生成数字人出镜视频无需真人拍摄调用/human/record接口核心流程用户输入文字/音频 → LLM 生成回复可选→ TTS 合成语音 → 数字人实时口型同步 → 音视频推流输出。这条链路中的每一步在源码中都有对应模块LLM 见 llm.pyTTS 见 tts/口型推理见 avatars/推流见 streamout/。三、环境安装3.1 测试环境与前置条件项目已在Ubuntu 22.04、Python 3.12、PyTorch 2.9.1、CUDA 12.8环境下测试通过。Windows 与 macOS 也可运行依赖项大多为跨平台包但实时推理强烈建议使用 NVIDIA GPU。3.2 安装步骤# 1. 克隆仓库本仓库即为 LiveTalking 的开源实现 git clone https://gitcode.com/GitHub_Trending/me/metahuman-stream.git # 2. 创建并激活 conda 虚拟环境 conda create -n livetalking python3.12 conda activate livetalking # 3. 安装与 CUDA 版本匹配的 PyTorch。 # 如果 CUDA 版本不为 12.8用 nvidia-smi 确认请根据 PyTorch 官网 previous-versions # 页选择对应版本安装例如 cu121/cu124 对应版本 pip install torch2.9.1 torchvision0.24.1 torchaudio2.9.1 --index-url https://download.pytorch.org/whl/cu128 # 4. 进入仓库目录并安装其余依赖 cd metahuman-stream pip install -r requirements.txt依赖清单见 requirements.txt其中值得注意的关键依赖包括推理与媒体处理torch、numpy、opencv-python-headless、soundfile0.12.1、resampy、librosa、einopsWebRTC 服务aiortc、aiohttp_cors、websockets12.0LLM 客户端openai、dashscope兼容 DashScope/OpenAI 兼容网关TTSedge_tts默认、transformers配置与工具pyyaml、python-dotenv、flask、tqdm、scipy、accelerate、diffusers。注requirements.txt中funasr、modelscope等本地 ASR 依赖默认被注释如需启用本地 SenseVoice/FunASR 语音识别接口/api/asr需手动安装详见 server/routes.py。四、快速开始下载模型并启动服务4.1 下载并放置模型Wav2Lip 快速体验需要两个文件将wav2lip256.pth拷贝到项目的models/目录下并重命名为wav2lip.pthapp.py 中固定以./models/wav2lip.pth路径加载模型将wav2lip256_avatar1.tar.gz解压后整个文件夹拷贝到data/avatars/目录下即最终路径为data/avatars/wav2lip256_avatar1/。Avatar 目录的标准结构可从 avatars/wav2lip_avatar.py 的load_avatar看出包含full_imgs/全身视频帧序列、face_imgs/人脸裁剪帧序列以及coords.pkl每帧人脸框坐标。项目根目录models/下另有占位说明文件models/put models here.txt提示模型放置位置。模型文件体积较大README 提供了夸克云盘与 Google Drive 下载渠道可从项目官方发布渠道获取。4.2 启动服务python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1注意服务端需开放端口TCP:8010Web 服务与 WebRTC 信令以及UDP:1-65536WebRTC 媒体流。从 app.py 的主流程可以看到启动时发生的关键步骤通过 config.py 的parse_args()解析命令行参数与 YAML 配置根据--model动态导入对应的 Avatar 插件模块musetalk/wav2lip/ultralight并调用其load_model()、load_avatar()、warm_up()完成模型加载、Avatar 预载与 GPU 预热初始化session_manager设置最大并发会话数与RTCManager管理 WebRTC 连接若--transport为virtualcam或rtmp则额外创建 session0并启动后台渲染线程把数字人画面直接渲染到虚拟摄像头或 RTMP 流启动 aiohttp 服务注册/offer、/whep、/human等路由server/routes.py 中的setup_routes。4.3 客户端接入方式方式说明浏览器打开http://serverip:8010/index.html点击开始连接播放数字人视频在文本框输入文字提交即可API 调用参考 API 文档 通过 HTTP 接口驱动桌面客户端从项目官方渠道下载 Windows 桌面客户端4.4 Web 管理页面服务内置三组前端页面静态资源位于web/目录页面地址说明首页/index.htmlWebRTC 连接 文本/音频驱动 录制控制Avatar 生成/avatar.html上传视频自动生成数字人形象管理后台/admin.html实时监控会话状态与全局配置4.5 快速体验路径可使用官方提供的一键镜像创建云端 GPU 实例直接运行AutoDL、UCloud 等平台均有预置镜像也有 Windows 整合包可免配置直接运行从项目官方渠道获取完整的参数化使用说明见仓库 README.md 及配套文档。五、系统架构5.1 数据流总览系统整体划分为 API 层、逻辑层、渲染层、推流层与插件系统五部分数据流如下5.2 各层职责说明API 层/human接收文本支持echo直接复读与chatLLM 对话两种模式/humanaudio接收音频文件直接播放每个连接分配唯一sessionid支持多用户并发。会话的构建逻辑在 app.py 的build_avatar_session中可根据请求参数动态指定avatar数字人形象、refaudio/reftext音色克隆、custom_config动作编排配置。逻辑层LLM 引擎对接 Qwen 等大模型生成对话回复。源码 llm.py 中定义了LLM_PROVIDERS内置 DashScopedashscope默认模型qwen-plus与 OrcaRouterorcarouter默认模型orcarouter/auto两个 OpenAI 兼容网关通过--llm_provider切换API Key 分别从DASHSCOPE_API_KEY、ORCAROUTER_API_KEY环境变量读取。llm_response()使用流式输出按标点切分句子后逐句喂给数字人显著降低首句延迟日志中记录 Time to first chunk 指标TTS 引擎模块化设计支持 EdgeTTS、GPT-SoVITS、腾讯云、豆包、Azure TTS、Qwen TTS 等多种方案通过--tts参数选择特征提取同步提取音频的声学特征用于口型推理三种模型分别使用 Mel 频谱avatars/audio_features/mel.py、Whisper 特征avatars/audio_features/whisper.py与 Hubert 特征avatars/audio_features/hubert.py。渲染层模型推理使用深度学习模型Wav2Lip、MuseTalk、Ultralight 等根据音频特征批量生成口型画面。以 Wav2Lip 为例avatars/wav2lip_avatar.py 的inference_batch将人脸帧下半部分掩码后与原始帧拼接成 6 通道输入交由模型推理生成带口型的嘴部区域后处理将生成的口型区域按coords.pkl中的人脸框坐标缩放后平滑贴回原始高清视频帧avatars/wav2lip_avatar.py 的paste_back_frame。MuseTalk 则采用 VAE latent UNet 去噪 掩码融合的管线见 avatars/musetalk_avatar.py。推流层WebRTC低延迟浏览器端推流支持 JSON SDP/offer与 WHEP 协议/whep两种接入方式RTMP标准直播协议支持推流到 B 站/YouTube 等直播平台streamout/rtmp.py虚拟摄像头输出为系统摄像头设备供会议软件等直接调用streamout/virtualcam.py。插件系统基于 registry.py 的去中心化注册机制开发者可自行扩展 TTS、Avatar、Output 模块详见第七节。5.3 单会话内部流水线从 avatars/base_avatar.py 的render()可以看到单个会话内部由三线程异步流水线构成TTS 线程self.tts.render(quit_event)持续消费文本队列并合成音频推理线程inference从特征队列取音频特征按batch_size批量执行模型推理生成口型帧静音时跳过推理、直接取待机帧从而把 GPU 让给真正说话的会话渲染/推流线程process_frames将推理帧贴回全身图、叠加 LiveTalking 水印后通过统一输出接口self.output.push_video_frame()/push_audio_frame()推送音视频并同步写入录制管道。推理线程每满 100 帧会打印实际平均推理帧率actual avg infer fps与 README 中的inferfps指标对应。六、API 接口总览服务以http://host:listenport为基础路径所有接口统一返回{ code: 0, msg: ok, data: {} }格式code为 0 表示成功。接口分为三组对应三份独立文档文档说明docs/api.md通用业务 API — WebRTC、文本/音频驱动、录制、动作编排docs/avatar_api.mdAvatar 生成 API — 创建任务、查询进度、删除任务docs/admin_api.mdAdmin 管理 API — 全局配置、会话监控、强制停止6.1 通用业务 API核心接口接口方法说明/offerPOST交换 SDP 建立 WebRTC 连接JSON支持avatar、refaudio、reftext、custom_config扩展参数响应返回sdp/type/sessionid/whepPOSTWHEP 协议接入SDP 以裸文本传输参数走 query string响应头X-Session-ID携带会话 ID/humanPOST文本驱动typeecho直接复读typechat触发 LLM 回答支持interrupt打断当前播报与tts参数透传如voice、emotion/humanaudioPOST上传音频文件multipart字段sessionidfile直接驱动数字人/interrupt_talkPOST立即清空当前会话音频队列打断播报/is_speakingPOST查询数字人是否正在说话返回data: true/false/recordPOST录制控制typestart_record开始、typeend_record停止并合成 MP4/record/{sessionid}GET下载录制完成的 MP4 文件不存在返回 404/set_audiotypePOST设置动作编排状态audiotype为预定义动作/状态索引/sse?sessionidGETServer-Sent Events 事件流接收服务器推送的播报状态如{status: start}这些路由的注册与实现集中在 server/routes.py其中/human的chat模式会通过run_in_executor异步执行 LLM 调用避免阻塞事件循环server/routes.py。文本驱动示例curl# echo 模式直接复读 curl -X POST http://serverip:8010/human \ -H Content-Type: application/json \ -d {sessionid: xxx, text: 你好世界, type: echo} # chat 模式触发 LLM 回答 curl -X POST http://serverip:8010/human \ -H Content-Type: application/json \ -d {sessionid: xxx, text: 介绍一下你自己, type: chat, interrupt: true}SSE 状态监听示例JavaScriptconst es new EventSource(/sse?sessionid${sessionid}); es.onmessage (event) { const data JSON.parse(event.data); // data 为服务器推送的播报状态/事件 }; es.close(); // 断开6.2 Avatar 生成 API通过POST /api/avatar/task上传视频即可自动生成数字人形象支持wav2lip与musetalk两种模型常用参数model必填wav2lip/musetalkavatar_id必填Avatar 唯一标识符video_file/video_path上传视频或指定服务器本地路径img_size默认 256、nosmooth、face_det_batch_size默认 16等为 wav2lip 专属参数bbox_shift、extra_margin默认 10、parsing_mode默认jaw、versionv1/v15为 musetalk 专属参数。任务状态流转为pending → running → completed/failed可通过GET /api/avatar/task/{task_id}轮询进度也支持notifyurl回调通知GET /api/avatar/tasks按start_time降序列出全部任务仅pending状态的任务可DELETE删除。生成的 Avatar 数据保存为full_imgs/、face_imgs/、coords.pkl及模型特定文件如 musetalk 的latents.pt、mask/完成后即可通过--avatar_id avatar_id直接启动使用。生成逻辑分别位于 avatars/wav2lip/genavatar.py 与 avatars/musetalk/genavatar.py。七、配置详解CLI 参数与 YAML 配置文件项目支持命令行参数 YAML 配置双重配置方式优先级为CLI 参数 YAML 配置文件 代码默认值。配置解析实现在 config.py 的parse_args()中先做一次临时解析拿到--config路径读取 YAML 后将 key 转换为 argparse 兼容的--key形式并set_defaults最后正式解析 CLI 参数完成覆盖。默认配置文件为根目录 config.yaml内容如下# -------- Audio ---------------------------------------------------------- l: 10 m: 8 r: 10 # -------- Avatar Model ---------------------------------------------------------- model: wav2lip # musetalk / wav2lip / ultralight avatar_id: wav2lip256_avatar1 batch_size: 16 # -------- Custom Actions ---------------------------------------------------------- customvideo_config: # -------- TTS ---------------------------------------------------------- tts: edgetts # edgetts / gpt-sovits / cosyvoice / fishtts / tencent / doubao / indextts2 / azuretts / qwentts REF_FILE: # voice name or reference audio file path (wav, 16kHz, mono) REF_TEXT: # reference text for voice cloning (English or Chinese) TTS_SERVER: # TTS server URL, no trailing slash # -------- LLM ---------------------------------------------------------- llm_provider: dashscope # dashscope / orcarouter llm_model: # model override, empty provider default (qwen-plus / orcarouter/auto) # -------- Transport ---------------------------------------------------------- transport: webrtc # rtcpush / webrtc / rtmp / virtualcam stun: stun:stun.freeswitch.org:3478 # stun server URL push_url: # push URL for rtcpush/rtmp (not needed for webrtc/virtualcam) max_session: 5 # max concurrent sessions listenport: 80107.1 核心参数说明参数默认值可选值/说明--modelwav2lipmusetalk/wav2lip/ultralight数字人推理模型--avatar_idwav2lip256_avatar1data/avatars下的数字人 ID--batch_size16推理批大小影响 GPU 吞吐与显存占用--fps25视频帧率固定为 25--ttsedgettsTTS 插件edgetts/gpt-sovits/cosyvoice/fishtts/tencent/doubao/indextts2/azuretts/qwentts--REF_FILEzh-CN-YunxiaNeural参考音色名或参考音频文件路径wav16kHz单声道--REF_TEXT空声音克隆参考文本中英文均可--TTS_SERVERhttp://127.0.0.1:9880TTS 服务地址GPT-SoVITS 等自建服务--llm_providerdashscopedashscope/orcarouter--llm_model空模型覆盖为空则用提供商默认qwen-plus/orcarouter/auto--transportwebrtcrtcpush/webrtc/rtmp/virtualcam--stunstun:stun.freeswitch.org:3478STUN 服务器地址NAT 穿透--push_url空rtcpush/rtmp 的推流地址--max_session5最大并发会话数--listenport8010Web 服务监听端口--customvideo_config空动作编排 JSON 配置路径--audio_output_deviceNone虚拟摄像头模式的音频输出设备索引可用list_audio_devices.py查看7.2 声音克隆与参考音频声音克隆通过在会话请求中携带refaudio参考音频wav 16kHz 单声道与reftext参考文本实现见 app.py请求参数配置了参考音频时会话级参数REF_FILE/REF_TEXT会被覆盖。不同 TTS 插件对该参数的解释不同如 EdgeTTS 下REF_FILE是音色名GPT-SoVITS 下是参考音频路径。7.3 动作编排Custom Actions--customvideo_config指向一个 JSON 文件配置不说话时播放自定义视频的待机动作。JSON 中每个条目包含audiotype状态索引1表示静音、imgpath图片序列目录文件名按数字递增排序与可选的audiopath循环音频。加载逻辑在 avatars/base_avatar.py 的__loadcustom()运行时由process_frames根据静音状态切换到自定义画面并通过/set_audiotype接口在多个预定义动作间切换。八、插件系统注册表机制与模块扩展registry.py 实现了基于装饰器的去中心化注册机制内置五类插件槽位_REGISTRY { stt: {}, llm: {}, tts: {}, avatar: {}, output: {} }开发者通过register(category, name)装饰器注册插件运行时用registry.create(category, name, **kwargs)按名称创建实例。各模块的映射关系可在源码中确认Avatar 模型模块app.py名称模块特征提取musetalkavatars/musetalk_avatar.pyWhisperaudio_features.whisperwav2lipavatars/wav2lip_avatar.pyMel 频谱audio_features.melultralightavatars/ultralight_avatar.pyHubertaudio_features.hubertTTS 模块avatars/base_avatar.pyedgetts→ tts/edge.py、gpt-sovits→ tts/sovits.py、xtts→ tts/xtts.py、tencent→ tts/tencent.py、doubao→ tts/doubao.py、azuretts→ tts/azure.py、qwentts→ tts/qwentts.py、omnitts→ tts/omnitts.py。输出通道模块avatars/base_avatar.pywebrtc/rtcpush→ streamout/webrtc.py、rtmp→ streamout/rtmp.py、virtualcam→ streamout/virtualcam.py。扩展一个新 TTS 或输出通道只需实现对应的基类接口如BaseTTS、输出模块的start/push_video_frame/push_audio_frame/stop用register装饰并确保模块被 import 即可无需改动主流程代码。九、Docker 运行项目提供预置 Docker 镜像支持一键拉起完整环境适用于云端 GPU 服务器快速部署AutoDL 镜像一键镜像创建实例后直接运行UCloud 镜像支持开放任意端口便于对外提供服务。镜像内已包含 Python 环境与依赖运行后同样以python app.py ...方式启动服务端口 8010 与 WebRTC 所需的 UDP 端口按前述要求开放。十、性能指标与实时性评估10.1 关键指标解读每路视频压缩消耗 CPU分辨率越高 CPU 消耗越大每路口型推理消耗 GPU不说话时并发数取决于 CPU同时说话并发数取决于 GPU后端日志中的inferfps GPU 推理帧率finalfps 最终推流帧率两者均需 ≥25 才算实时对应 25fps 视频帧率。10.2 实时推理性能参考来自 README 官方数据模型显卡FPSwav2lip256RTX 306060wav2lip256RTX 3080Ti120musetalkRTX 3080Ti42musetalkRTX 309045musetalkRTX 409072硬件选型建议wav2lip256推荐 RTX 3060 及以上性价比高单卡可支撑多路说话会话musetalk推荐 RTX 3080Ti 及以上效果更自然但显存与算力要求更高。10.3 并发与调优实践从 app.py 与 config.yaml 可推导出以下调优要点max_session控制最大并发会话数超出后新连接会被拒绝batch_size越大单批吞吐越高但显存占用也越大需结合显卡显存调整静音时推理线程自动跳过推理、直接输出待机帧avatars/base_avatar.py因此不说话会话多、说话会话少时主要瓶颈在 CPU视频编码可通过降低输出分辨率或升级 CPU 缓解直播场景建议--transport rtmp配合--push_url避免浏览器端 WebRTC 编解码开销。十一、版权声明与引用基于本项目开发并发布在 B 站、视频号、抖音等平台上的视频需带上LiveTalking 水印和标识水印由 avatars/base_avatar.py 在渲染阶段自动叠加。项目采用 Apache 2.0 开源协议见 LICENSE引用方式来自 READMEsoftware{livetalking, author {Hengzhong Li}, title {LiveTalking: Real-Time Interactive Streaming Digital Human Framework}, year {2025}, publisher {GitHub}, url {https://github.com/lipku/livetalking} }十二、总结metahuman-stream 以文本/语音 → LLM → TTS → 实时口型 → 多通道推流为主线通过注册表机制将 Avatar 模型、TTS、输出通道解耦为可插拔插件既支持 Wav2Lip/MuseTalk/Ultralight 三种模型的快速切换也支持 WebRTC/RTMP/虚拟摄像头三种交付形态配合动作编排与打断能力可覆盖直播、客服、教育、大屏讲解、短视频批量制作等实时数字人场景。后续深入研究可继续阅读 docs/api.md、docs/avatar_api.md、docs/admin_api.md 三份接口文档以及 avatars/ 与 tts/ 下的各插件实现。【免费下载链接】metahuman-streamReal time interactive streaming digital human项目地址: https://gitcode.com/GitHub_Trending/me/metahuman-stream创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考