11Labs 反应库

一个SDK库,用于在基于React的应用程序中使用"11Lab". 如果你想找一个Node.js图书馆,请参考 十一拉布斯节点js 图书馆。 。 。 .

请注意,这个图书馆的启动主要是为了支持对话AI. 今后计划支持语音综合和其他更通用的用法案例.

安装

通过软件包管理器在您的工程中安装软件包 .

npm install @elevenlabs/react
# or
yarn add @elevenlabs/react
# or
pnpm install @elevenlabs/react

使用量

使用组合

用于管理WebSocket和WebRTC的连接和音频使用,用于11Labs对话AI.

初始化对话

首先,初始化对话实例.

const conversation = useConversation();

注意对话AI需要麦克风访问. 考虑解释和允许麦克风进入您的应用程序 UI 在对话开始前。 麦克风也可能默认被屏蔽当前页面,导致允许的提示完全不出现. 您应当在应用程序中处理此用途, 并向用户显示适当的消息 :

// call after explaning to the user why the microphone access is needed
// handle errors and show appropriate message to the user
try {
  await navigator.mediaDevices.getUserMedia();
} catch {
  // handle error
}

选项

对话可以通过某些选项初始化. 这些都是可选的.

const conversation = useConversation({
  /* options object */
});

• 客户端工具 - 代理人可以引用的客户端工具的对象定义. 见下文 详细情况.
• 覆盖 - 对象定义对话设置覆盖. 见下文 详细情况.
• 文本仅 - 对话是否应当以文本模式运行. 见下文 详细情况.
• 连接 - 接线员打电话来.
• 断开连接 - 接线员在谈话结束的时候打电话来.
• 新闻 - 收到新消息后,处理者打电话来 这些可以是用户语音的暂定或最终的抄录,由LLM生成的回覆,也可以是调试选项启用后调试消息.
• 错误 - 遇到错误时调用处理器.

客户端工具

客户端工具是一种使代理能够引用客户端功能的方法. 这可用于触发客户端中的动作,例如打开一个模式或者代表用户进行API呼叫.

客户工具定义是函数的对象,需要与您的配置在 十一实验室,其中可以命名和描述不同的工具,也可以设置代理传递的参数.

const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(text);

      return "Message displayed";
    },
  },
});

在万一函数返回一个值时,它会被传递回代理作为响应. 请注意,该工具需要被明确设定为在"十一律所UI"中阻断对话,以便代理等待并响应响应,否则代理就假定成功并继续进行对话.

对话覆盖

您可以选择覆盖对话的各种设置, 并按动态设置其他用户互动 . 我们支持超越各种环境. 这些设置是可选的,可用于自定义对话体验. 以下设置可供使用:

const conversation = useConversation({
  overrides: {
    agent: {
      prompt: {
        prompt: "My custom prompt",
      },
      firstMessage: "My custom first message",
      language: "en",
    },
    tts: {
      voiceId: "custom voice id",
    },
    conversation: {
      textOnly: true,
    },
  },
});

用户识别

您可以选择通过用户ID来识别对话中的用户. 这可以是你自己的客户识别码. 这将包含在发送给服务器的对话启动数据中:

跟踪这个ID可以帮助过滤对话,跟踪用户层面的分析等.

// Or pass it when starting the session
const conversationId = await conversation.startSession({
  agentId: "<your-agent-id>",
  userId: "user-123",
  connectionType: "webrtc",
});

只有文本

如果您的代理被配置为只以文本模式运行, 即它不发送或接收音频消息, 您可以使用此旗帜来使用较轻版本的对话。 在这种情况下 用户不会被请求麦克风权限,也不会创建音频上下文.

const conversation = useConversation({
  textOnly: true,
});

IOS 设备首选耳机

虽然这个SDK将音频输入/输出设备的选择留给了浏览器/系统,但iOS Safari似乎更喜欢内置的扬声器而不是耳机,即使蓝牙设备正在被使用. 如果您想要在iOS设备可用时"强制"使用耳机,可以使用以下选项. 请记住,由于浏览器不提供这种功能,所以不能保证这一点. 系统音频应该是默认的选择.

const conversation = useConversation({
  preferHeadphonesForIosDevices: true,
});

连接延迟

您可以在麦克风启动到连接建立之间配置额外的延迟 . 在Android上,延迟默认被设定为3秒,以确保设备有时间切换到正确的音频模式. 没有它,你可能会遇到问题 随着第一个消息的开头被切断.

const conversation = useConversation({
  connectionDelay: {
    android: 3_000,
    ios: 0,
    default: 0,
  },
});

获取醒锁

默认情况下,对话将试图获得 唤醒锁 防止设备在谈话中入睡. 通过设置 useWakeLock 选项到 false数字 :

const conversation = useConversation({
  useWakeLock: false,
});

方法

开始集合

startConversation 方法可以踢出WebSocket或WebRTC连接,并开始使用麦克风与"十一实验室"对话AI代理通信. 该方法接受一个选项对象,其中 signedUrl, (中文(简体) ), conversationToken 或者说 agentId 需要选项.

代理ID可以通过 十一实验室 总是必要的.

const conversation = useConversation();

// For public agents, pass in the agent ID and the connection type
const conversationId = await conversation.startSession({
  agentId: "<your-agent-id>",
  connectionType: "webrtc", // either 'webrtc' or 'websocket'
});

对于公共代理人(即没有启用认证的代理人),定义 agentId - 不需要签名的链接生成.

如果谈话需要授权,使用REST API生成WebSocket连接的签名链接或WebRTC连接的谈话符.

startSession 返回承诺 conversationId。该值是一个全球独特的对话ID,您可以用来识别单独的对话.

用于 WebSocket 连接 :

// Node.js server

app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
    }
  );

  if (!response.ok) {
    return res.status(500).send("Failed to get signed URL");
  }

  const body = await response.json();
  res.send(body.signed_url);
});

// Client

const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();

const conversation = await Conversation.startSession({
  signedUrl,
  connectionType: "websocket",
});

对于 WebRTC 连接 :

// Node.js server

app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.ELEVENLABS_API_KEY,
      }
    }
  );

  if (!response.ok) {
    return res.status(500).send("Failed to get conversation token");
  }

  const body = await response.json();
  res.send(body.token);
);

// Client

const response = await fetch("/conversation-token", yourAuthHeaders);
const conversationToken = await response.text();

const conversation = await Conversation.startSession({
  conversationToken,
  connectionType: "webrtc",
});

会议结束

手动结束对话的方法. 该方法会结束与websocket的交谈和断开.

await conversation.endSession();

发送回信

一个向代理发送二进制反馈的方法. 该方法接受布尔值,其中 true 表示积极的反馈 false 负面反馈. 反馈总是与最近的代理响应相关,每次响应只能发送一次. 检查 canSendFeedback 状态,以查看能否在特定时刻发送反馈.

const { sendFeedback } = useConversation();

sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback

发送文本更新

向代理发送背景更新的方法 . 这可以用来告知代理商与对话没有直接关联的用户动作,但可能影响代理商的反应.

const { sendContextualUpdate } = useConversation();

sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);

发送用户信息

向代理人发送短信.

可用于让用户在信件中输入而不是使用麦克风. 与 sendContextualUpdate,这将会被当作一个用户消息,并会促使代理商在对话中自行决定.

const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");

return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue(value);
      }}
    >
      SEND
    </button>
  </>
);

发送用户活动

通知代理用户活动.

该代理在检测到用户活动后至少2秒内不会尝试发言. 这可以用来防止代理在打字时打断用户.

const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");

return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue(value);
      }}
    >
      SEND
    </button>
  </>
);

设置

设置对话输出量的方法 。 接受体积字段在0到1之间的对象.

const [volume, setVolume] = useState(0.5);
const conversation = useConversation({ volume });

// Set the volume
setVolume(0.5);

哑弹Mic

哑/解麦克风的方法.

const [micMuted, setMicMuted] = useState(false);
const conversation = useConversation({ micMuted });

// Mute the microphone
setMicMuted(true);

// Unmute the microphone
setMicMuted(false);

状态

包含当前对话状态的反应状态 .

const { status } = useConversation();
console.log(status); // "connected" or "disconnected"

说话

一个反应状态,包含该代理是否正在说话的信息. 用于在您的 UI 中显示模式 .

const { isSpeaking } = useConversation();
console.log(isSpeaking); // boolean

发送后退

一个反应状态,代表用户是否可以向代理发送反馈. 假的,打给 sendFeedback 将被忽略. 这样做有助于有条件地在您的用户界面中显示反馈按钮 .

const { canSendFeedback } = useConversation();
console.log(canSendFeedback); // boolean

发展

请参考此寄存器根中的 README. md 文件 .

捐款

请先创建一个问题来讨论提议的修改。 欢迎任何贡献!

记住,如果合并,你的代码将作为麻省理工学院许可项目的一部分使用. 通过提交"拉出请求",你同意将您的代码整合到这个库中.