@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.3。

快速上手

<video id="player" playsinline></video>

import { HappyOysterEngine } from "@happy-oyster/js-sdk";

const happyOyster = new HappyOysterEngine({
  APIHost: "open-platform.example.com",
});

happyOyster.updateToken("open-platform-http-token");

const videoElement = document.getElementById("player") as HTMLVideoElement;
const travel = happyOyster.createTravel({
  ticket: "travel-ticket",
  videoElement,
  maxExperienceTimeSec: 90, // 可选，仅 Wander 生效：60 / 90 / 120
});

travel.on("statusChanged", (status) => console.log("状态变更:", status));
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.token 可选，也可后续通过 updateToken() 设置或刷新。config.logLevel 控制 SDK 内部日志。

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 模式 | | creationModel | Travel 创建模型 | | firstFrame | Open Platform 返回的首帧 URL | | maxExperienceTimeSec | Wander 最大体验时间；Story 或老服务未返回时为 null |

Travel 方法

| 方法 | 说明 | | --------------------------- | -------------------------------------------------------------------------------------------------- | | start() | 启动当前 Travel，返回 Promise<StartTravelResult> | | can(action) | 判断当前状态、模式和版本下是否可以调用指定 Travel 方法 | | sendCommand(params) | 通过 RTC DataChannel 发送操控指令 | | sendInstruct({ content }) | 发送导演/提示词，自动携带当前 encryptedTravelId | | pause() | 暂停当前会话 | | resume() | 恢复已暂停的会话 | | rewind({ rewindToSec }) | 回退到指定秒数；rewindToSec 仅支持 4 的整数倍，非整数倍由服务端向下取整 | | end() | 结束会话并释放 RTC 资源 |

can(action) 支持的 action：start / sendCommand / sendInstruct / pause / resume / rewind / end。

事件

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

| 事件名 | 回调签名 | 说明 | | --------------------- | -------------------------------- | ------------------------------- | | statusChanged | (status: TravelStatus) => void | 会话状态变更 | | firstFrameGenerated | (firstFrame: string) => void | start() 过程中收到首帧 URL | | error | (error: unknown) => void | 发生连接/播放错误 |

控制指令取值

sendCommand 的 translation、rotation、interaction 都是选填字段；未传字段会按 None 发送。

translation（移动方向）：Front / Back / Left / Right / 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 文件。