@happy-oyster/js-sdk

中文文档
0.1.5发布于 2026/10/09SEE LICENSE IN LICENSETypeScriptES Module近 30 天下载 5169

快乐牡蛎RTC 网络玩家 SDK.

中文使用文档
文档目录11 节
  1. 安装
  2. 快速上手
  3. API
  4. new HappyOysterEngine(config)
  5. HappyOysterEngine 方法
  6. Travel.start() 返回值
  7. Travel 方法
  8. 事件
  9. 控制指令取值
  10. 开发
  11. 许可

@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
modeTravel 模式:1 = Adventure、2 = Directing、3 = Acting
creationModelTravel 创建模型
firstFrameOpen Platform 返回的首帧 URL
maxExperienceTimeSecAdventure 最大体验时间;Directing、Acting 或老服务未返回时为 null
aspectRatioActing 画幅: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;随后调用 Core leaveChannel(),离会完成后完成 Promise。每个新帧都会重新开始计时;离会失败时 Promise 拒绝,状态保留为已经确认的 paused。
  • resume():本地能力检查通过后,先触发一次 status 查询(若已有请求则复用),只有 rtcStatus=PAUSED(兼容大小写)才调用恢复接口。尚未暂停或出现临时查询失败时,等待现有每秒一次的 status 轮询继续确认,本地保持 paused。等待阶段使用 resume 超时配置(默认 15 秒);超时返回 RESUME_STREAM_TIMEOUT,会话结束则取消等待;can("resume") 只检查本地条件。恢复接口成功后开始等待新帧和后端 rtcStatus=STREAMING,并通过 Core connect() 重新入会(内部调用 RTC joinChannel())。入会完成、收到新帧且后端确认 STREAMING 后,当前状态为 paused 时变为 running 并完成 Promise。接口成功前的帧和残留的 readyState 不作为恢复依据。
  • 优先使用 requestVideoFrameCallback,不支持时检查 getVideoPlaybackQuality() 的已显示帧计数增量。后台页面不累计暂停的无帧确认时间;无法观察帧或等待超时会使操作失败,保留原状态。
  • 后端状态轮询继续处理完成和失败,rtcStatus=paused/streaming 不直接变更暂停或恢复状态。会话结束会取消帧等待。

事件

通过 travel.on(event, callback) 订阅当前 Travel 的事件。

事件名回调签名说明
statusChanged(status: TravelStatus) => void会话状态变更
travelInfoReady(info: TravelInfo) => voidenter-travel 返回后、RTC 连接前触发一次
firstFrameGenerated(firstFrame: string) => voidstart() 过程中收到首帧 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 文件。

版本与发布记录

@happy-oyster/js-sdk 共发布 6 个版本,首次发布于 2026/06/26;过去 12 个月发布了 6 个版本。

版本发布日期距今
0.1.5latest2026/10/091 个月前
0.1.42026/08/043 个月前
0.1.4-beta.1beta2026/07/243 个月前
0.1.32026/07/154 个月前
0.1.12026/06/294 个月前
0.1.02026/06/264 个月前

关于 @happy-oyster/js-sdk 的常见问题

@happy-oyster/js-sdk 是什么?

快乐牡蛎RTC 网络玩家 SDK.

如何安装 @happy-oyster/js-sdk?

在项目目录运行 npm install @happy-oyster/js-sdk,或使用 pnpm add / yarn add / bun add。

@happy-oyster/js-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happy-oyster/js-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happy-oyster/js-sdk 可以商用吗?

@happy-oyster/js-sdk 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@happy-oyster/js-sdk 的下载量有多少?

根据 npm 官方下载统计,@happy-oyster/js-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,169 次,日均约 172 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happy-oyster/js-sdk 还在维护吗?

最新版本 0.1.5 发布于 2026/10/09(1 个月前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/06/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。