主题

JavaScript SDK 快速开始 ​

用户点击开始后，浏览器请求麦克风权限，SDK 建立实时变声会话，并通过 <audio> 元素播放转换后的声音。

前置条件 ​

  • 已安装 @convbased/sdk 0.3；
  • 页面通过 HTTPS 或 localhost 访问，否则浏览器不允许使用麦克风；
  • 应用后端能为已登录用户签发短期 SDK 令牌；
  • 当前用户有权使用要调用的模型。

不要在浏览器端保存或发送 API Key。应用后端还没有签发令牌的接口时，先阅读鉴权。

页面元素 ​

html
<button id="start" type="button">开始变声</button>
<button id="stop" type="button">结束</button>
<audio id="output" autoplay></audio>

请求麦克风权限和开始播放，都应放在用户点击等操作的处理函数中。

建立会话 ​

ts
import {
  Convbased,
  type SdkAuthOptions,
  type VoiceSession,
} from "@convbased/sdk";

const auth: SdkAuthOptions = {
  clientId: "example.web",
  tokenProvider: async (request) => {
    const response = await fetch("/api/convbased/sdk-token", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(request),
    });

    if (!response.ok) throw new Error("SDK token request failed");
    return (await response.json()).access_token;
  },
};

const output = document.querySelector<HTMLAudioElement>("#output");
const start = document.querySelector<HTMLButtonElement>("#start");
const stop = document.querySelector<HTMLButtonElement>("#stop");

if (!output || !start || !stop) throw new Error("Missing voice controls");

let session: VoiceSession | undefined;

start.addEventListener("click", async () => {
  session = await Convbased.startVoiceChange({
    auth,
    modelId: "model_xxx",
    output,
    onStatus: (status) => console.log(status),
    onError: (error) => console.error(error),
  });
});

stop.addEventListener("click", async () => {
  await session?.stop();
  session = undefined;
});

/api/convbased/sdk-token 是应用自己的后端路由。SDK 会把本次调用需要的 clientId、scopes 和 resource 传给 tokenProvider；后端必须逐项确认当前用户有权使用，再签发令牌。

检查结果 ​

onStatus 报告 connecting、live 和 ended；成功并正常结束的会话按这个顺序变化。startVoiceChange() 在实时服务就绪后返回，但浏览器仍可能拦截音频播放。没有声音时，先在用户点击事件中调用 output.play()，再检查音频设备、模型、网络和令牌权限。

页面关闭或用户停止变声时调用 session.stop()，以关闭会话并释放 SDK 占用的麦克风。