@happy-oyster/js-sdk
Happy Oyster SDK 提供 Web 端实时音视频流播放与交互控制能力。SDK 通过 Travel ticket 创建 Travel,会话 ID、RTC 配置和后续生命周期操作都封装在 Travel 实例中。
安装
npm install @happy-oyster/js-sdk
aliyun-rtc-sdk 已作为依赖自动安装,版本要求 7.3.4。
快速上手
<video id="player" playsinline></video>
import { HappyOysterEngine } from "@happy-oyster/js-sdk";
const happyOyster = new HappyOysterEngine({
APIHost: "open-platform.example.com",
model: "happyoyster-1.0-adventure", // 必填;此处以 Adventure 模型为例
});
happyOyster.updateToken("open-platform-http-token");
const videoElement = document.getElementById("player") as HTMLVideoElement;
const travel = happyOyster.createTravel({
ticket: "travel-ticket",
videoElement,
maxExperienceTimeSec: 90, // 可选,仅 Adventure 生效:60 / 90 / 120
});
travel.on("statusChanged", (status) => console.log("状态变更:", status));
travel.on("travelInfoReady", (info) =>
console.log("进房信息已就绪:", info.mode, info.aspectRatio),
);
travel.on("firstFrameGenerated", (firstFrame) =>
console.log("首帧已生成:", firstFrame),
);
travel.onError((err) => console.error("连接异常:", err));
const startResult = await travel.start();
console.log("Travel 已启动:", startResult);
travel.sendCommand({
translation: "Front",
rotation: "Mouse_Left",
interaction: "Jump",
});
await travel.sendInstruct({ content: "镜头转向城堡,主角开始奔跑" });
await travel.pause();
await travel.resume();
await travel.rewind({ rewindToSec: 12 });
await travel.end();
API
new HappyOysterEngine(config)
创建 SDK client。config.APIHost 为必填裸 host(不含 https:// 和路径);config.model 必填,用于指定 Open Platform 模型,无默认值;config.token 可选,也可后续通过 updateToken() 设置或刷新。config.logLevel 控制 SDK 内部日志。
必须显式传入目标 model。一个 Engine 固定对应 APIHost + model,同一模型的多次 Travel 可复用该 Engine;切换模型前先结束当前 Travel,再使用目标模型的 Engine。World 和 ticket 应来自同一服务目标;SDK 不根据体验 mode 自动选择模型,也不会解析 ticket 来推断模型。
HappyOysterEngine 方法
| 方法 | 说明 |
|---|---|
updateToken(token) | 刷新 Open Platform HTTP API 的 Bearer token |
createTravel(config) | 创建 Travel,返回尚未启动的 Travel |
当前实现每个 SDK 实例只允许一个 active Travel。如需创建下一次 Travel,请先调用 await travel.end()。
设置 token(构造时或
updateToken)后,SDK 内部会自动拉取功能开关(Feature Gate),用于远程关停 SDK 或强制升级旧版本。该逻辑为 SDK 内部实现,无需调用方介入;请求失败时 fail-open。
Travel.start() 返回值
start() resolve 后返回 StartTravelResult:
| 字段 | 说明 |
|---|---|
encryptedTravelId | 当前 Travel 会话 ID |
mode | Travel 模式:1 = Adventure、2 = Directing、3 = Acting |
creationModel | Travel 创建模型 |
firstFrame | Open Platform 返回的首帧 URL |
maxExperienceTimeSec | Adventure 最大体验时间;Directing、Acting 或老服务未返回时为 null |
aspectRatio | Acting 画幅:9:16 / 16:9;其他模式或老服务未返回时为 null |
Travel 方法
| 方法 | 说明 |
|---|---|
start() | 启动当前 Travel,返回 Promise<StartTravelResult> |
can(action) | 判断当前状态、模式和版本下是否可以调用指定 Travel 方法 |
getInfo() | 获取 enter-travel 已返回的 TravelInfo;尚未返回时为 null |
sendCommand(params) | 通过 RTC DataChannel 发送操控指令 |
sendInstruct({ content }) | 发送导演/提示词,自动携带当前 encryptedTravelId |
pause() | 暂停当前会话 |
resume() | 恢复已暂停的会话 |
rewind({ rewindToSec }) | 仅支持回退的 Directing 会话可用;回退秒数仅支持 4 的整数倍,非整数倍由服务端向下取整 |
end() | 结束会话并释放 RTC 资源 |
can(action) 支持的 action:start / sendCommand / sendInstruct / pause / resume / rewind / end。
Acting 支持 sendInstruct、pause、resume 和 end;暂停、恢复取决于会话能力,不支持 sendCommand 与 rewind。
暂停和恢复同时以 videoElement 的视频帧变化和后端 rtcStatus 确认状态:
pause():暂停接口成功后,等待视频连续 500ms 没有新帧,并等待后端确认rtcStatus=PAUSED(兼容大小写)。两项均满足且当前为running,才变为paused;随后调用 CoreleaveChannel(),离会完成后完成 Promise。每个新帧都会重新开始计时;离会失败时 Promise 拒绝,状态保留为已经确认的paused。resume():本地能力检查通过后,先触发一次 status 查询(若已有请求则复用),只有rtcStatus=PAUSED(兼容大小写)才调用恢复接口。尚未暂停或出现临时查询失败时,等待现有每秒一次的 status 轮询继续确认,本地保持paused。等待阶段使用 resume 超时配置(默认 15 秒);超时返回RESUME_STREAM_TIMEOUT,会话结束则取消等待;can("resume")只检查本地条件。恢复接口成功后开始等待新帧和后端rtcStatus=STREAMING,并通过 Coreconnect()重新入会(内部调用 RTCjoinChannel())。入会完成、收到新帧且后端确认 STREAMING 后,当前状态为paused时变为running并完成 Promise。接口成功前的帧和残留的readyState不作为恢复依据。- 优先使用
requestVideoFrameCallback,不支持时检查getVideoPlaybackQuality()的已显示帧计数增量。后台页面不累计暂停的无帧确认时间;无法观察帧或等待超时会使操作失败,保留原状态。 - 后端状态轮询继续处理完成和失败,
rtcStatus=paused/streaming不直接变更暂停或恢复状态。会话结束会取消帧等待。
事件
通过 travel.on(event, callback) 订阅当前 Travel 的事件。
| 事件名 | 回调签名 | 说明 |
|---|---|---|
statusChanged | (status: TravelStatus) => void | 会话状态变更 |
travelInfoReady | (info: TravelInfo) => void | enter-travel 返回后、RTC 连接前触发一次 |
firstFrameGenerated | (firstFrame: string) => void | start() 过程中收到首帧 URL |
error | (error: unknown) => void | 发生连接/播放错误 |
firstFrameGenerated 为兼容事件:当 TravelInfo.firstFrame 非空时,它会紧随 travelInfoReady 继续触发。晚订阅方可用 travel.getInfo() 补读元信息。
控制指令取值
sendCommand 的 translation、rotation、interaction 都是选填字段;未传字段会按 None 发送。
translation(移动方向):Front / Back / Left / Right / Up / Down / Front_Left / Front_Right / Back_Left / Back_Right / None
rotation(视角旋转):Mouse_Up / Mouse_Down / Mouse_Left / Mouse_Right / Mouse_Up_Left / Mouse_Up_Right / Mouse_Down_Left / Mouse_Down_Right / None
interaction(交互动作):Jump / Attack / Crouch / Sprint / None
开发
npm install
npm run build # 输出到 lib/
npm test # 运行 jest
许可
本 SDK 为专有软件,版权归 Alibaba Group 所有,保留所有权利。授予用户有限的、不可转让的权利,仅用于集成调用本 SDK 的公开接口;禁止反编译、逆向工程、提取源码或二次分发。详见根目录 LICENSE 文件。