十一Labs JavaScript 客户端库

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

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

安装

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

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

使用量

这个图书馆主要用于香草JavaScript项目的发展,或者作为适合特定框架的图书馆的基础. 建议检查您的特定框架是否有自己的库. 然而,您可以在任何基于JavaScript的项目中使用此库.

连接类型

对话可以通过两种连接类型之一开始:WebSockets(默认)或WebRTC.

初始化对话

首先,初始化对话实例:

const conversation = await Conversation.startSession(options);

这将踢出websocket连接,并开始使用麦克风与"11Labs"对话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
}

会话配置

转至 startSession 如何确定会话 。 开始开会有三种方式:

公共代理人

不需要任何认证的代理可以通过使用代理ID和连接类型开始对话. 代理ID可以通过 十一实验室。 。 。 .

对于公务人员,您可直接使用身份证明:

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  connectionType: "webrtc", // 'websocket' is also accepted
});

私人代理人

如果对话需要授权,您需要在您的服务器上添加一个专门的端点,该端点将请求一个签名的url(如果使用WebSockets连接类型)或者一个使用WebRTC的谈话符号(如果使用WebRTC) 十一实验室 API 还给客户.

以下是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);
);

一旦你拿到信物,提供它给 startSession 将使用 WebRTC 启动对话.

// Client

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

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

可选回调

转至 startSession 也可以用于注册可选回调:

• 连接 - 处理器在对话网口连接建立时打过电话.
• 断开连接 - 处理器在对话结束时打过电话.
• 新闻 - 收到新短信后,处理器打电话来。 这些可以是用户声音的暂定或最后的抄录,由LLM制作的答复. 主要用于处理谈话抄录.
• 错误 - 遇到错误时呼叫处理器.
• 现状变化 - 当连接状态发生变化时,处理器会呼叫。 可能会 connected, (中文(简体) ), connecting 财务报告和审定财务报表 disconnected (初次发言).
• 模式变化 - 处理器在状态变化时呼叫,例如代理交换器从 speaking 改为 listening或者换个角度.
• 在CanSendFeed Back Change上发布 - 发送反馈时呼叫的处理器可供使用或无法使用.

客户端工具

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

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

const conversation = await Conversation.startSession({
  clientTools: {
    displayMessage: async (parameters: { text: string }) => {
      alert(text);

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

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

对话覆盖

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

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

用户识别

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

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

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  userId: "user-123", // Optional user identifier
  connectionType: "webrtc",
});

只有文本

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

const conversation = await Conversation.startSession({
  textOnly: true,
});

IOS 设备首选耳机

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

const conversation = await Conversation.startSession({
  preferHeadphonesForIosDevices: true,
});

连接延迟

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

const conversation = await Conversation.startSession({
  connectionDelay: {
    android: 3_000,
    ios: 0,
    default: 0,
  },
});

获取醒锁

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

const conversation = await Conversation.startSession({
  useWakeLock: false,
});

返回值

startSession 返回 a Conversation 实例可用于控制会话。 如果会话无法确定, 方法会出错 。 如果用户拒绝麦克风访问, 或者如果websocket连接 失败.

会议结束

手动结束对话的方法. 该方法会结束与websocket的交谈和断开. 之后,对话将无法使用,可以安全地放弃.

await conversation.endSession();

发送回信

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

conversation.sendFeedback(true);

发送文本更新

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

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

发送用户信息

向代理人发送短信.

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

sendButton.addEventListener("click", e => {
  conversation.sendUserMessage(textInput.value);
  textInput.value = "";
});

发送用户活动

通知代理用户活动.

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

textInput.addEventListener("input", () => {
  conversation.sendUserActivity();
});

获取文件

一种还原对话身份的方法.

const id = conversation.getId();

设置

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

await conversation.setVolume({ volume: 0.5 });

哑弹Mic

哑/解麦克风的方法.

// Mute the microphone
conversation.setMicMuted(true);

// Unmute the microphone
conversation.setMicMuted(false);

获取输出卷/ 获取输出卷

从中按比例返回当前输入/输出量的方法 0 改为 1 地点 0 -100分贝和 1 -30分贝.

const inputVolume = await conversation.getInputVolume();
const outputVolume = await conversation.getOutputVolume();

获取输入ByteFrequencyData / 获取输出ByteFrequencyData

返回的方法 Uint8Arrays 包含当前输入/输出频率数据。 见 分析器 Node.getByteFrequencyData 更多信息.

发展

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

捐款

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

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