mcpField
L
liveavatar-integrate

liveavatar-integrate

github.com/heygen-com开发161.1k 次安装7 周前更新
代码仓库

关于 liveavatar-integrate

LiveAvatar Integration 是指导 LiveAvatar 视频头像接入的开发技能，会根据代码库现状选择嵌入、FULL 或 LITE 路径，并引导实施。它面向需要将实时、口型同步的头像接入产品的开发者，重点是沿用已有 AI 与音频管线并区分两种协议。

主要功能

  1. 01检查代码库中的 AI 与音频组件
  2. 02按现有架构选择集成路径
  3. 03提供 Embed、FULL 和 LITE 指南
  4. 04将 LITE 接入现有对话管线
  5. 05强调 API 密钥仅存于后端

适用场景

  1. 01为静态网站接入头像嵌入
  2. 02将自有 LLM 接入 FULL 模式
  3. 03为已有 STT、LLM 和 TTS 管线添加头像视频
  4. 04为已有 LiveKit 或 Agora 系统接入 LITE

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/heygen-com/liveavatar-agent-skills --skill liveavatar-integrate

安装后在 Claude Code 中输入/liveavatar-integrate确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
embed-guide.md
full-mode-guide.md
lite-mode-guide.md

详细介绍

LiveAvatar 集成

LiveAvatar 为你的产品赋予鲜活形象——实时、口型同步的视频化身，能够说话、做出反应并保持眼神交流。本技能会评估你现有的配置，推荐最佳集成路径，并引导你完成构建。

第 1 步：了解用户已有的配置

推荐路径前，先收集相关信息。检查代码库和对话中是否有线索。代码库已经能回答的问题，不要再问。

在代码库中查找线索

自动扫描以下内容——如果能检测到，就不要询问用户：

线索查找位置含义
OpenAI / Anthropic / LLM SDK 导入package.json、requirements.txt、导入语句用户有自己的大模型
ElevenLabs / PlayHT / Deepgram TTS SDK依赖项、导入语句用户有自己的 TTS
Deepgram / Whisper / AssemblyAI STT SDK依赖项、导入语句用户有自己的 STT
LiveKit SDK（livekit-server-sdk、@livekit/）依赖项用户有 LiveKit 基础设施
Agora SDK依赖项用户有 Agora 基础设施
Pipecat 导入依赖项、导入语句用户有 Pipecat 管线
ElevenLabs Agent / Conversational AI依赖项、配置用户有 ElevenLabs Agent
HEYGEN_API_KEY / LIVEAVATAR_API_KEY.env、配置文件用户已有 API 密钥
现有 LiveAvatar 代码导入语句、对 api.liveavatar.com 的 API 调用已有集成（进行调试，而非新建配置）
没有后端 / 静态网站文件结构（纯 HTML/CSS/JS，没有服务器）只能使用嵌入式集成
要询问的问题（仅限尚不明确的内容）

如果扫描代码库后仍有信息缺失，请询问用户。将问题整理成简洁的清单——不要一次只问一个：

To recommend the best LiveAvatar integration for your setup, I need to know:

1. **What's the goal?** (e.g., customer support avatar, sales demo, onboarding guide, talking head on landing page)
2. **Do you have your own AI pipeline?** (STT, LLM, TTS — or any combination)
3. **Do you need programmatic control** over the conversation (events, interrupts, custom logic), or just an avatar on a page?

如果代码库或对话已经给出了答案，就跳过相应问题。

第 2 步：选择最佳路径

根据收集到的信息，匹配一条路径。**始终选择可行的最简单路径。**不要提供多个选项——直接做出决定。

决策树
Has NO backend OR just wants an avatar on a page?
  → EMBED

Has NO existing AI stack (no STT, no LLM, no TTS)?
  → FULL MODE (standard)

Has their OWN LLM but no STT/TTS?
  → FULL MODE + Custom LLM

Has their OWN LLM + their own ElevenLabs TTS?
  → FULL MODE + Custom LLM + Custom TTS

Needs explicit mic control (walkie-talkie style)?
  → FULL MODE + Push-to-Talk

Has a COMPLETE pipeline (STT + LLM + TTS)?
  → LITE MODE

Has an ElevenLabs Conversational AI agent?
  → LITE MODE + ElevenLabs Plugin

Has their own LiveKit or Agora infrastructure?
  → LITE MODE + BYO WebRTC
最佳路径（选一条，然后实施）
路径适用情况实施指南
Embed没有后端，或不需要自定义逻辑references/embed-guide.md
FULL standard没有现有 AI 技术栈references/full-mode-guide.md
FULL + Custom LLM有自己的大模型，希望使用 LiveAvatar 的 ASR + TTSreferences/full-mode-guide.md（Custom LLM 部分）
FULL + Custom TTS有自己的 ElevenLabs 语音references/full-mode-guide.md（Custom TTS 部分）
FULL + Push-to-Talk需要显式控制麦克风references/full-mode-guide.md（Push-to-Talk 部分）
LITE standard已有完整的 STT + LLM + TTS 管线references/lite-mode-guide.md
LITE + ElevenLabs Plugin有 ElevenLabs Conversational AI Agentreferences/lite-mode-guide.md（ElevenLabs Plugin 部分）
LITE + BYO WebRTC有自己的 LiveKit / Agorareferences/lite-mode-guide.md（BYO WebRTC 部分）

第 3 步：给出推荐方案

选定路径后，用 2–3 句话告诉用户推荐的方案及理由。例如：

根据你的配置，我建议使用 FULL Mode with Custom LLM。你已经集成了 OpenAI 来提供大模型，因此我们会接入它，并由 LiveAvatar 处理 ASR、TTS 和视频。这样就能获得一个对话式化身，而不必重建音频管线。

然后直接使用 references/ 中对应的指南开始实施。

第 4 步：实现

阅读相应的参考指南并进行实现。每份指南都遵循相同的结构：

  1. 前置条件 — 编写代码前需要创建或收集的内容
  2. 会话生命周期 — 分步说明，包含 curl 命令和代码
  3. 事件 — 需要发送和接收的内容
  4. 附加功能 — 特定模式的可选功能
  5. 沙盒测试 — 上线前免费测试
  6. 注意事项 — 可能出错的地方以及如何避免
适用于所有路径的原则

后端／前端必须分离。 X-API-KEY 是机密信息，只能放在后端。前端只能获取 livekit_client_token（可安全用于浏览器）。如果在客户端代码中看到 API 密钥，请立即停止并重新规划结构。

上下文让数字人具备对话能力。 在 FULL 模式下，没有 context_id = 数字人不会说话。不会抛出错误。务必先创建上下文，即使只是一个简单的 "You are a helpful assistant."。

FULL 和 LITE 是完全不同的协议。 FULL = LiveKit 数据通道（avatar.*／user.*）。LITE = WebSocket（agent.*／session.*）。切勿混用。

从沙盒开始。 使用 is_sandbox: true，数字人 ID 为 dd73ea75-1218-4ef3-92ce-606d5f7fbc0a。免费测试，会话时长约 1 分钟。准备就绪后再切换到生产数字人。

LITE 模式：接入现有流程

LITE 用户几乎总是已经有可用的对话系统。不要要求他们重建整个流程。 而是将他们现有的组件映射到 LITE 轮次周期中：

  1. 了解他们当前的流程。 阅读他们的代码，弄清楚现在对话轮次的工作方式——用户音频从哪里进入、如何传给大模型、TTS 输出如何送达？查找他们的事件循环、消息处理器或轮次管理器。
  2. 找到集成点。 需要在他们现有流程中的三个时机接入：
    • 用户开始／停止说话 → 添加 agent.start_listening／agent.stop_listening
    • TTS 生成音频 → 将 PCM 输出通过 WebSocket 分块传给 agent.speak，替代（或同时保留）当前的音频输出方式
    • 响应结束 → 发送 agent.speak_end 并等待 agent.speak_ended
  3. 调整而非替换。 如果他们已有可用的轮次管理器，就在其中添加 LiveAvatar 调用。如果他们已经通过 WebSocket 向浏览器传输 TTS，就接入同一条流。目标是尽可能少改动，让数字人视频与现有音频流程同步。
  4. 最后验证音频格式。 接线完成后，确认他们的 TTS 输出为 PCM 16 位、24KHz。如果不是，就配置 TTS 提供商的输出格式，或在集成点添加重采样。

第 5 步：收集反馈

编写完集成代码后立即触发——不要等用户确认一切正常或表示已完成。如果用户放弃，或你看到同一步骤失败 3 次以上，也要触发。

操作方法： 按照 liveavatar-feedback 技能的说明操作。它会引导你从对话中收集上下文、向用户展示准备发送的内容、征求明确同意并提交反馈。

保持轻量。 在实现说明的末尾简短提示一次即可——如果用户拒绝或不回应，不要继续催促。

参考资料

评论

支持 Markdown