LiveTalking（metahuman-stream）实时交互流式数字人引擎：架构解析、部署配置与 API 集成实战

LiveTalkingmetahuman-stream实时交互流式数字人引擎架构解析、部署配置与 API 集成实战【免费下载链接】metahuman-streamReal time interactive streaming digital human项目地址: https://gitcode.com/GitHub_Trending/me/metahuman-streamLiveTalking 是一款面向商用场景的实时交互流式数字人引擎本仓库metahuman-stream即其完整实现通过文本或语音驱动虚拟形象说话可结合 LLM 实现智能对话并支持 WebRTC、RTMP、虚拟摄像头三种音视频输出方式。读完本文你将掌握 LiveTalking 的端到端运行链路文本/音频 → LLM → TTS → 口型推理 → 推流能够独立完成环境搭建、模型与 Avatar 准备、服务启动、参数配置并通过 HTTP API 将数字人能力集成进自己的业务系统。项目定位与核心特性LiveTalking 实现的是音视频同步对话的实时交互体验——数字人在说话时口型与语音严格对齐并且说话可以被随时打断。其核心特性如下与 README-EN.md 保持一致多数字人模型支持ernerf、musetalk、wav2lip、Ultralight-Digital-Human 四类模型可选声音克隆通过参考音频16kHz 单声道 WAV与参考文本克隆指定音色说话打断数字人说话过程中可随时清空音频队列、中断播报全身视频拼接将生成的口型区域平滑贴回原始高清视频支持全身出镜多输出方式WebRTC、RTMP、虚拟摄像头virtual camera动作编排不说话时自动播放自定义视频/音频实现不冷场的表现力多并发通过唯一sessionid隔离会话支持多用户同时访问自定义数字人形象上传视频即可自动生成专属 Avatar前端 API 对接提供完整的 HTTP/WebRTC 接口体系。典型应用场景与核心流程场景说明虚拟主播 / 直播带货24 小时无人直播LLM 自动生成带货话术配合动作编排实现自然表现AI 数字人客服接入企业知识库用户语音提问、数字人实时回答支持打断重说在线教育 / 培训教师数字分身录制课程或通过 API 驱动数字人讲师实时授课智能语音助手结合智能音箱或 APP调用/human接口驱动数字人语音对话大屏讲解数字人讲解员在展厅大屏、活动现场进行内容讲解与互动短视频批量制作通过 API 批量提交文案生成数字人出镜视频调用/human/record接口核心流程用户输入文字/音频 → LLM 生成回复可选→ TTS 合成语音 → 数字人实时口型同步 → 音视频推流输出。这条链路在源码层面由 avatars/base_avatar.py 中的render()方法统一编排它依次启动 TTS 渲染、GPU 口型推理线程inference与推流处理线程process_frames三者通过有界队列解耦res_frame_queue音频按 20ms/帧16kHz 下每帧 320 个采样点即self.chunk sample_rate // (fps*2)流水化流转从而保证低延迟。系统架构四层 插件系统LiveTalking 的整体数据流如下引自 assets/dataflow.pngAPI 层/human接收文本支持echo直接复读与chatLLM 对话两种模式/humanaudio接收音频文件直接播放每个连接分配唯一sessionid支持多用户并发。逻辑层LLM 引擎对接 Qwen 等大模型生成对话回复也可通过 OpenAI 兼容网关接入启动参数--llm_provider orcarouterTTS 引擎模块化设计支持 EdgeTTS、GPT-SoVITS、CosyVoice、腾讯云、豆包、Azure、QwenTTS 等多种方案仓库 tts/ 目录下对应edge.py、sovits.py、tencent.py、doubao.py、azure.py、qwentts.py、omnitts.py、xtts.py特征提取同步提取音频声学特征如 Mel 频谱供口型推理模型使用。渲染层模型推理使用 Wav2Lip、MuseTalk 等深度学习模型根据音频特征生成口型画面后处理将生成的口型区域平滑贴回原始高清视频实现全身视频拼接。推流层WebRTC低延迟浏览器端推流server/webrtc.pyRTMP标准直播协议支持推流到 B 站 / YouTube 等平台streamout/rtmp.py虚拟摄像头将数字人画面输出为系统摄像头设备streamout/virtualcam.py。插件系统LiveTalking 采用去中心化注册机制核心实现在 registry.py。注册表按stt / llm / tts / avatar / output五个分类管理插件通过register(category, name)装饰器登记类、create(category, name, **kwargs)按名实例化# registry.py 核心逻辑 register(tts, edgetts) class EdgeTTS(BaseTTS): ... tts registry.create(tts, edgetts, optopt)Avatar 基类在初始化时依据opt.tts与opt.transport动态importlib.import_module对应模块并注册实例见 avatars/base_avatar.py开发者据此可自行扩展新的 TTS、Avatar 与 Output 插件无需改动核心代码。环境安装与依赖官方在Ubuntu 24.04、Python 3.12、PyTorch 2.9.1、CUDA 12.8环境下完成测试。安装步骤如下git clone https://github.com/lipku/LiveTalking.git conda create -n livetalking python3.12 conda activate livetalking # 如果 CUDA 版本不是 12.8运行 nvidia-smi 确认请根据 PyTorch 官网历史版本页安装对应版本 pip install torch2.9.1 torchvision0.24.1 torchaudio2.9.1 --index-url https://download.pytorch.org/whl/cu128 cd LiveTalking pip install -r requirements.txt提示本仓库即该工程的完整镜像可直接在仓库根目录执行pip install -r requirements.txt依赖清单见 requirements.txt。Linux CUDA 环境搭建可参考社区常见问题文档与 FAQ 页面见 assets/faq.md。快速开始模型下载、服务启动与客户端接入下载模型与 Avatar模型与 Avatar 文件需从项目 README 提供的网盘地址夸克云盘 / Google Drive见 README-EN.md 第 2.1 节下载本地放置方式如下将wav2lip256.pth拷贝到项目models/目录并重命名为wav2lip.pth仓库 models/ 目录当前为占位说明文件需自行放入权重将wav2lip256_avatar1.tar.gz解压把整个文件夹拷贝到data/avatars/目录下即默认的data_path可在配置中修改。启动服务python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1注意服务端需开放端口TCP:8010与UDP:1-65536WebRTC 媒体传输使用。启动时 app.py 会依据--model加载对应模型musetalk 加载./models权重并预热warm_upwav2lip 加载./models/wav2lip.pth并以 256 分辨率预热ultralight 则使用 160 分辨率预热。随后初始化 RTC 管理器RTCManager并注册 HTTP 路由/offer、/record/{sessionid}及 server/routes.py 中的通用 API。若指定virtualcam/rtmp传输方式还会额外启动一个后台渲染线程。客户端接入方式说明浏览器打开http://serverip:8010/index.html点击开始连接播放数字人视频在文本框输入文字提交即可API 调用通过 HTTP 接口驱动详见下文 API 章节桌面客户端从项目 README 提供的网盘地址下载Windows 整合包Web 页面页面地址说明首页/index.htmlWebRTC 连接 文本/音频驱动 录制控制Avatar 生成/avatar.html上传视频自动生成数字人形象管理后台/admin.html实时监控会话状态与全局配置配置详解CLI 参数、YAML 与优先级LiveTalking 的配置解析实现在 config.py 中采用三层优先级CLI 命令行参数 YAML 配置文件 代码内置默认值parse_args()先以默认值构建 argparse 解析器若--config默认config.yaml指向的 YAML 文件存在则读取并写入parser.set_defaults最后解析 CLI 参数覆盖。默认配置见 config.yaml核心字段如下字段类型默认值说明fpsint25视频帧率需为 25l/m/rint10 / 8 / 10音频缓冲参数影响延迟与稳定性modelstringwav2lipAvatar 模型musetalk/wav2lip/ultralightavatar_idstringwav2lip256_avatar1默认 Avatar 标识位于data_path下batch_sizeint16口型推理批大小modelresint192模型分辨率modelfilestring自定义模型文件路径customvideo_configstring自定义动作编排 JSON 文件路径ttsstringedgettsTTS 插件edgetts/gpt-sovits/cosyvoice/fishtts/tencent/doubao/indextts2/azuretts/qwenttsREF_FILEstringzh-CN-YunxiaNeural参考音频文件路径或语音模型 IDwav、16kHz、单声道REF_TEXTstring声音克隆参考文本中英文均可TTS_SERVERstringhttp://127.0.0.1:9880TTS 服务地址无末尾斜杠llm_providerstringdashscopeLLM 提供方dashscope/orcarouterllm_modelstring模型覆盖为空使用提供方默认qwen-plus/orcarouter/autotransportstringwebrtc输出方式rtcpush/webrtc/rtmp/virtualcamstunstringstun:stun.freeswitch.org:3478STUN 服务器地址push_urlstringrtcpush/rtmp 推流地址webrtc/virtualcam 不需要max_sessionint5最大并发会话数listenportint8010HTTP 监听端口动作编排配置customvideo_config指向一个 JSON 文件其中每一项包含imgpath静态图片序列目录、audiotype动作状态索引、可选audiopath循环音频由 avatars/base_avatar.py 的__loadcustom()在会话初始化时加载为图像/音频循环队列当检测到该状态的静音帧时渲染线程会从循环队列取帧替换口型推理结果见process_frames实现不说话时播放自定义视频的效果。API 接口实战所有业务接口的基础路径为http://host:listenport统一返回格式{ code: 0, msg: ok, data: {} }code为 0 表示成功非 0 表示错误。路由注册与处理逻辑见 server/routes.py。1. WebRTC OfferJSON—POST /offer交换 SDP 建立 WebRTC 连接扩展参数放在 JSON body 中。参数必填类型默认值说明sdp是string—WebRTC Offer SDPtype是string—必须为offeravatar否string启动参数值指定数字人 IDrefaudio否string—参考音频音色reftext否string—参考文本custom_config否string—动作编排配置 JSON 字符串响应中包含sdpanswer、type与sessionid。每个连接获得唯一sessionid后续所有操作都以此会话 ID 为标识若请求中携带了avatar/refaudio/custom_configapp.py 的build_avatar_session()会为本次会话深度拷贝全局配置并覆盖对应项实现单会话级别的个性化。2. WebRTC OfferWHEP—POST /whep符合 WHEPWebRTC HTTP Egress Protocol协议SDP offer 以application/sdp裸文本发送扩展参数通过 query string 传递额外支持tts、tts_server、tts_speed参数。响应Content-Type为application/sdp会话 ID 通过X-Session-ID响应头返回。3. 文本驱动 —POST /human参数必填类型默认值说明sessionid是string—会话 IDtext是string—输入文本type是string—echo直接复读chat触发 LLM 回答interrupt否boolfalse是否打断当前播报tts否object—透传给 TTS 的配置如voice、emotion源码中echo模式直接调用put_msg_txt交由 TTS 合成chat模式则将llm_response提交到线程池异步执行避免阻塞请求见 server/routes.py。4. 音频驱动 —POST /humanaudiomultipart/form-data上传音频文件字段sessionid、file。服务端会将音频解码并重采样至 16kHz按 20ms 分块送入推理流水线见 avatars/base_avatar.py同时自动附加start/end事件标记。5. 打断播报 —POST /interrupt_talk参数sessionid。立即调用会话的flush_talk()清空当前音频队列实现数字人说话被打断。6. 查询说话状态 —POST /is_speaking参数sessionid返回data为布尔值表示当前是否正在说话。7. 录制控制 —POST /record参数必填类型说明sessionid是string会话 IDtype是stringstart_record开始录制end_record停止并合成录制实现依赖 ffmpeg视频以 rawvideo 管道写入、音频以 16kHz 单声道 s16le 写入结束时自动合成 MP4 并清理临时文件见 avatars/base_avatar.py。8. 下载录像 —GET /record/{sessionid}返回录制完成的 MP4 文件流文件不存在时返回 404文件位于data/record/目录。9. 设置动作编排 —POST /set_audiotype参数sessionid与audiotype预定义动作/状态索引切换到对应的自定义视频/音频循环状态。10. SSE 事件流 —GET /sse?sessionidsessionid基于 Server-Sent Events 接收服务器 → 客户端的异步状态推送播报开始/结束等事件每条事件为一行 JSONdata: {status: start}。服务端实现为每连接注册一个消息队列渲染线程通过notify()广播状态变更见 server/routes.py 与 avatars/base_avatar.py。Avatar 生成 API上传视频自动创建数字人通过POST /api/avatar/task上传一段人物视频即可自动生成可用 Avatar生成产物保存在data_path/avatar_id/目录含full_imgs/、face_imgs/、coords.pkl及模型特定文件生成完成后直接用--avatar_id avatar_id启动服务即可。核心参数详见 docs/avatar_api.md参数必填默认值说明model是—wav2lip/musetalkavatar_id是—Avatar 唯一标识符video_file否—上传的视频文件multipart保存到./data/tmp/video_path条件—视频本地路径未上传文件时必填img_size否256输出图像尺寸nosmooth否false禁用人脸检测平滑wav2lipbbox_shift否0人脸框偏移musetalkextra_margin否10人脸裁剪额外边距musetalkpads否0 10 0 0填充上 下 左 右空格分隔parsing_mode否jaw人脸解析模式musetalkversion否v15MuseTalk 版本v1/v15face_det_batch_size否16人脸检测批大小wav2liptask_id否自动 UUID自定义任务 IDnotifyurl否—回调 URL任务状态变更时 POST 通知配套接口还包括GET /api/avatar/task/{task_id}查询状态status取值pending → running → completed/failedprogress为 0-100 整数、GET /api/avatar/tasks按start_time降序列出全部任务、DELETE /api/avatar/task/{task_id}仅pending状态可删除。对应实现位于 server/avatar_routes.py模型专属生成模块为 avatars/wav2lip/genavatar.py 与 avatars/musetalk/genavatar.py。Admin 管理 API全局配置与会话监控GET /api/admin/config返回服务启动时的全局配置来自 CLI 参数与 YAMLdata.config即vars(opt)包括模型、Avatar、TTS、传输方式、max_session、listenport等全部字段GET /api/admin/sessions返回当前所有活跃会话列表每条记录含sessionid、speaking、recording、model、avatar_id、REF_FILE、transport、batch_size、customopt字段可用于监控面板实时展示对应前端 web/admin.html。字段完整说明见 docs/admin_api.md。性能指标与实时性保障每路视频压缩消耗 CPU分辨率越高 CPU 消耗越大每路口型推理消耗 GPU不说话时的并发数取决于 CPU此时仅做画面循环与编码同时说话的并发数取决于 GPU每路都要跑口型推理后端日志中的inferfps GPU 推理帧率finalfps 最终推流帧率两者均需 ≥ 25 才算达到实时。inference()线程每累计 100 帧会在日志输出实际平均推理帧率。官方在指定显卡上实测的实时推理性能模型显卡FPSwav2lip256RTX 306060wav2lip256RTX 3080Ti120musetalkRTX 3080Ti42musetalkRTX 309045musetalkRTX 409072wav2lip256 推荐 RTX 3060 及以上musetalk 推荐 RTX 3080Ti 及以上。Docker 与快速体验项目提供现成的 Docker 镜像AutoDL 与 UCloud 云平台均有预置镜像UCloud 镜像支持开放任意端口创建实例即可运行无需本地搭环境。Windows 用户也可直接使用整合包版本快速体验。仓库根目录的 Dockerfile 可作为自定义镜像的构建参考。开源协议与使用声明本项目基于 Apache 2.0 协议开源见 LICENSE开源版定位为社区版支持快速体验、二次开发与学习研究商用付费版在开源版基础上提供性能加速、自适应动作与实时语音互动等增强能力。需要特别注意的是基于本项目开发并发布在 B 站、视频号、抖音等平台上的视频需附带 LiveTalking 水印与标识该水印在 avatars/base_avatar.py 的process_frames中自动叠加。至此你已掌握 LiveTalking 从架构到 API 集成的完整链路先按config.yaml与--model/--avatar_id等参数启动服务再通过/offer或/whep建立 WebRTC 连接用/humanecho/chat、/humanaudio驱动说话用/interrupt_talk、/set_audiotype实现打断与动作编排最后用/record沉淀短视频内容——这套组合足以支撑直播带货、数字人客服、大屏讲解等绝大多数商用落地场景。【免费下载链接】metahuman-streamReal time interactive streaming digital human项目地址: https://gitcode.com/GitHub_Trending/me/metahuman-stream创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考