@realsee/vreo 2.4.7 → 2.5.0

package/lib/Player/Controller.d.ts

@@ -4,7 +4,28 @@ import { VreoKeyframe, VreoKeyframeEnum, VreoKeyframeEvent, VreoUnit, VreoVideo
 import { VideoAgentScene } from './modules/VideoAgent/VideoAgentScene';
 import { Appearance, PlayerConfigs, WaveAppearance } from './typings';
 /**
- * 逻辑控制器：内部状态。
+ * Vreo 播放器逻辑控制器
+ *
+ * 负责管理播放器的内部状态、事件处理、UI 控制和剧本执行。
+ * 提供播放控制、外观设置、弹窗管理、抽屉控制等功能。
+ *
+ * @example
+ * ```typescript
+ * const controller = new Controller({
+ *   five: fiveInstance,
+ *   container: document.getElementById('container'),
+ *   configs: playerConfigs
+ * })
+ *
+ * // 设置播放状态
+ * controller.setPlaying(true)
+ *
+ * // 打开弹窗
+ * controller.openPopUp('弹窗内容')
+ *
+ * // 打开抽屉
+ * controller.openDrawer({ content: '抽屉内容', height: 300 })
+ * ```
  */
 export declare class Controller extends Subscribe<VreoKeyframeEvent> {
     five: Five;
@@ -25,39 +46,122 @@ export declare class Controller extends Subscribe<VreoKeyframeEvent> {
     appearance: Appearance;
     avatar: VreoVideo['avatar'];
     visible: boolean;
+    /**
+     * 获取当前播放媒体的类型
+     * @returns 'video' | 'avatar' | 'none' - 媒体类型
+     */
     get agentType(): "video" | "none" | "avatar";
     popUp: string | JSX.Element | null;
+    /**
+     * 打开或关闭弹窗
+     * @param popUp - 弹窗内容，可以是字符串、JSX元素或false（关闭弹窗）
+     */
     openPopUp(popUp: string | JSX.Element | false): void;
+    /**
+     * 设置加载状态
+     * @param loading - 加载状态：true（加载中）、false（加载完成）、null（加载失败）
+     */
     setLoading(loading: boolean | null): void;
     drawerConfig: {
         content: string | JSX.Element;
         height?: number | string;
     } | null;
+    /**
+     * 设置虚拟形象配置
+     * @param avatar - 虚拟形象配置对象
+     */
     setAvatar(avatar: VreoVideo['avatar']): void;
+    /**
+     * 设置容器尺寸
+     * @param width - 容器宽度
+     * @param height - 容器高度
+     */
     setContainerSize(width: number, height: number): void;
+    /**
+     * 设置播放器可见性
+     * @param v - 是否可见
+     */
     setVisible(v: boolean): void;
+    /**
+     * 设置播放状态
+     * @param playing - 是否正在播放
+     */
     setPlaying(playing: boolean): void;
+    /**
+     * 设置结束状态
+     * @param ended - 是否已结束
+     */
     setEnded(ended: boolean): void;
+    /**
+     * 设置播放器外观
+     * @param appearance - 外观配置对象
+     */
     setAppearance(appearance: Appearance): void;
+    /**
+     * 打开或关闭抽屉
+     * @param drawerConfig - 抽屉配置对象，false表示关闭抽屉
+     */
     openDrawer(drawerConfig?: false | {
         content: string | JSX.Element;
         height?: number | string;
     }): void;
+    /**
+     * 创建 Controller 实例
+     * @param params - 构造参数对象
+     * @param params.five - Five 渲染引擎实例
+     * @param params.container - DOM 容器元素
+     * @param params.configs - 播放器配置
+     */
     constructor({ five, container, configs }: {
         five: Five;
         container: Element;
         configs: PlayerConfigs;
     });
+    /**
+     * 获取播放器是否准备就绪
+     * @returns 是否有可用的视频代理场景
+     */
     get ready(): boolean;
+    /**
+     * 获取当前播放时间（毫秒）
+     * @returns 当前播放时间戳
+     */
     get currentTime(): number;
+    /**
+     * 获取当前时间点应该触发的关键帧
+     * @returns 当前应该执行的关键帧数组
+     */
     get currentKeyframes(): VreoKeyframe[];
+    /**
+     * 获取当前媒体实例（音频或视频元素）
+     * @returns HTML媒体元素实例
+     */
     get mediaInstance(): HTMLVideoElement | HTMLAudioElement | import("../shared-utils/AudioLike").AudioLike | undefined;
     /**
-     * 逐帧任务
+     * 逐帧任务循环处理
+     *
+     * 在每个动画帧中检查播放状态、处理关键帧触发等
+     * @param callback - 关键帧触发时的回调函数
      */
     requestAnimationFrameLoop(callback: (type: VreoKeyframeEnum, keyframe: VreoKeyframe, currentTime: number) => void): void;
+    /**
+     * 开始运行播放器逻辑循环
+     *
+     * 启动帧循环，持续监听并处理关键帧事件
+     * @param callback - 关键帧触发时的回调函数
+     */
     run(callback: (type: VreoKeyframeEnum, keyframe: VreoKeyframe) => void): void;
+    /**
+     * 清理播放器状态
+     *
+     * 停止播放、重置关键帧状态、清理数据和定时器
+     */
     clear(): void;
+    /**
+     * 销毁控制器实例
+     *
+     * 清理所有状态和资源，释放内存
+     */
     dispose(): void;
 }
 declare const ControllerContext: React.Context<Controller | null>;

package/lib/Player/Controller.js

@@ -27,11 +27,39 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 function _createSuper(t) { var r = _isNativeReflectConstruct(); return function () { var e, o = (0, _getPrototypeOf2["default"])(t); if (r) { var s = (0, _getPrototypeOf2["default"])(this).constructor; e = Reflect.construct(o, arguments, s); } else e = o.apply(this, arguments); return (0, _possibleConstructorReturn2["default"])(this, e); }; }
 function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); }
 /**
- * 逻辑控制器：内部状态。
+ * Vreo 播放器逻辑控制器
+ * 
+ * 负责管理播放器的内部状态、事件处理、UI 控制和剧本执行。
+ * 提供播放控制、外观设置、弹窗管理、抽屉控制等功能。
+ * 
+ * @example
+ * ```typescript
+ * const controller = new Controller({
+ *   five: fiveInstance,
+ *   container: document.getElementById('container'),
+ *   configs: playerConfigs
+ * })
+ * 
+ * // 设置播放状态
+ * controller.setPlaying(true)
+ * 
+ * // 打开弹窗
+ * controller.openPopUp('弹窗内容')
+ * 
+ * // 打开抽屉
+ * controller.openDrawer({ content: '抽屉内容', height: 300 })
+ * ```
  */
 var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
   (0, _inherits2["default"])(Controller, _Subscribe);
   var _super = _createSuper(Controller);
+  /**
+   * 创建 Controller 实例
+   * @param params - 构造参数对象
+   * @param params.five - Five 渲染引擎实例
+   * @param params.container - DOM 容器元素
+   * @param params.configs - 播放器配置
+   */
   function Controller(_ref) {
     var _this;
     var five = _ref.five,
@@ -163,11 +191,20 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
     });
     return _this;
   }
+
+  /**
+   * 获取播放器是否准备就绪
+   * @returns 是否有可用的视频代理场景
+   */
   (0, _createClass2["default"])(Controller, [{
     key: "agentType",
     get:
     // null 表示加载失败
 
+    /**
+     * 获取当前播放媒体的类型
+     * @returns 'video' | 'avatar' | 'none' - 媒体类型
+     */
     function get() {
       var _this$videoAgentScene, _this$avatar;
       var type = (0, _getMediaInfo.getMediaType)((_this$videoAgentScene = this.videoAgentScene) === null || _this$videoAgentScene === void 0 ? void 0 : _this$videoAgentScene.videoAgentMesh.videoUrl);
@@ -177,13 +214,23 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
     }
   }, {
     key: "openPopUp",
-    value: function openPopUp(popUp) {
+    value:
+    /**
+     * 打开或关闭弹窗
+     * @param popUp - 弹窗内容，可以是字符串、JSX元素或false（关闭弹窗）
+     */
+    function openPopUp(popUp) {
       if (!popUp) {
         this.popUp = null;
         return;
       }
       this.popUp = popUp;
     }
+
+    /**
+     * 设置加载状态
+     * @param loading - 加载状态：true（加载中）、false（加载完成）、null（加载失败）
+     */
   }, {
     key: "setLoading",
     value: function setLoading(loading) {
@@ -191,9 +238,20 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
     }
   }, {
     key: "setAvatar",
-    value: function setAvatar(avatar) {
+    value:
+    /**
+     * 设置虚拟形象配置
+     * @param avatar - 虚拟形象配置对象
+     */
+    function setAvatar(avatar) {
       this.avatar = avatar;
     }
+
+    /**
+     * 设置容器尺寸
+     * @param width - 容器宽度
+     * @param height - 容器高度
+     */
   }, {
     key: "setContainerSize",
     value: function setContainerSize(width, height) {
@@ -202,26 +260,51 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
         height: height
       };
     }
+
+    /**
+     * 设置播放器可见性
+     * @param v - 是否可见
+     */
   }, {
     key: "setVisible",
     value: function setVisible(v) {
       this.visible = v;
     }
+
+    /**
+     * 设置播放状态
+     * @param playing - 是否正在播放
+     */
   }, {
     key: "setPlaying",
     value: function setPlaying(playing) {
       this.playing = playing;
     }
+
+    /**
+     * 设置结束状态
+     * @param ended - 是否已结束
+     */
   }, {
     key: "setEnded",
     value: function setEnded(ended) {
       this.ended = ended;
     }
+
+    /**
+     * 设置播放器外观
+     * @param appearance - 外观配置对象
+     */
   }, {
     key: "setAppearance",
     value: function setAppearance(appearance) {
       this.appearance = _objectSpread(_objectSpread({}, this.appearance), appearance);
     }
+
+    /**
+     * 打开或关闭抽屉
+     * @param drawerConfig - 抽屉配置对象，false表示关闭抽屉
+     */
   }, {
     key: "openDrawer",
     value: function openDrawer(drawerConfig) {
@@ -240,12 +323,22 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
     get: function get() {
       return !!this.videoAgentScene;
     }
+
+    /**
+     * 获取当前播放时间（毫秒）
+     * @returns 当前播放时间戳
+     */
   }, {
     key: "currentTime",
     get: function get() {
       var _this$videoAgentScene2;
       return ((_this$videoAgentScene2 = this.videoAgentScene) === null || _this$videoAgentScene2 === void 0 ? void 0 : _this$videoAgentScene2.videoAgentMesh.currentTime) || 0;
     }
+
+    /**
+     * 获取当前时间点应该触发的关键帧
+     * @returns 当前应该执行的关键帧数组
+     */
   }, {
     key: "currentKeyframes",
     get: function get() {
@@ -265,6 +358,11 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
         return dur <= 100 && dur >= 0;
       });
     }
+
+    /**
+     * 获取当前媒体实例（音频或视频元素）
+     * @returns HTML媒体元素实例
+     */
   }, {
     key: "mediaInstance",
     get: function get() {
@@ -273,7 +371,10 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
     }
 
     /**
-     * 逐帧任务
+     * 逐帧任务循环处理
+     * 
+     * 在每个动画帧中检查播放状态、处理关键帧触发等
+     * @param callback - 关键帧触发时的回调函数
      */
   }, {
     key: "requestAnimationFrameLoop",
@@ -314,6 +415,13 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
         }
       });
     }
+
+    /**
+     * 开始运行播放器逻辑循环
+     * 
+     * 启动帧循环，持续监听并处理关键帧事件
+     * @param callback - 关键帧触发时的回调函数
+     */
   }, {
     key: "run",
     value: function run(callback) {
@@ -323,6 +431,12 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
         return _this4.requestAnimationFrameLoop(callback);
       });
     }
+
+    /**
+     * 清理播放器状态
+     * 
+     * 停止播放、重置关键帧状态、清理数据和定时器
+     */
   }, {
     key: "clear",
     value: function clear() {
@@ -343,6 +457,12 @@ var Controller = exports.Controller = /*#__PURE__*/function (_Subscribe) {
       (_this$stopInterval = this.stopInterval) === null || _this$stopInterval === void 0 ? void 0 : _this$stopInterval.call(this);
       this.stopInterval = undefined;
     }
+
+    /**
+     * 销毁控制器实例
+     * 
+     * 清理所有状态和资源，释放内存
+     */
   }, {
     key: "dispose",
     value: function dispose() {

package/lib/Player/index.d.ts

@@ -1,18 +1,121 @@
 import { Five, Subscribe } from '@realsee/five';
 import { VreoKeyframeEvent, VreoUnit } from '../typings/VreoUnit';
 import { Appearance, PlayerConfigs } from './typings';
+/**
+ * Vreo 播放器核心类
+ *
+ * 提供 VR 视频播放、剧本执行、相机运镜等功能的主要接口。
+ * 基于 Five 渲染引擎和 React 构建的 3D 空间剧本播放器。
+ *
+ * @example
+ * ```typescript
+ * import { Five } from '@realsee/five'
+ * import { Player } from '@realsee/vreo'
+ *
+ * const five = new Five({
+ *   // Five 配置选项
+ * })
+ * const player = new Player(five, {
+ *   autoPreload: true,
+ *   imageOptions: { size: 1024 }
+ * })
+ *
+ * await player.load(vreoUnit)
+ * player.play()
+ * ```
+ */
 export declare class Player extends Subscribe<VreoKeyframeEvent> {
+    /** Five 渲染引擎实例 */
     $five: Five;
+    /** 内部控制器 */
     private controller;
+    /** 播放器配置（只读） */
     configs: Readonly<PlayerConfigs>;
+    /**
+     * 创建 Vreo 播放器实例
+     *
+     * @param five - Five 渲染引擎实例
+     * @param configs - 播放器配置选项
+     */
     constructor(five: Five, configs?: Partial<PlayerConfigs>);
+    /**
+     * 加载剧本数据
+     *
+     * 加载 VreoUnit 剧本数据，准备播放器状态，预载资源，并初始化播放环境。
+     *
+     * @param vreoUnit - 剧本数据对象，包含视频信息和关键帧序列
+     * @param currentTime - 起始播放时间（毫秒），默认为 0
+     * @param preload - 是否预载相关资源，默认为 false
+     * @param force - 是否强制重新载入（深拷贝数据），默认为 false
+     * @returns Promise<boolean> 返回加载是否成功
+     *
+     * @example
+     * ```typescript
+     * // 基本加载
+     * await player.load(vreoUnit)
+     *
+     * // 从指定时间开始加载，并预载资源
+     * await player.load(vreoUnit, 5000, true)
+     *
+     * // 强制重新加载
+     * await player.load(vreoUnit, 0, false, true)
+     * ```
+     */
     load(vreoUnit: VreoUnit, currentTime?: number, preload?: boolean, force?: boolean): Promise<boolean>;
+    /**
+     * 获取播放器是否处于暂停状态
+     * @returns 是否暂停中
+     */
     get paused(): boolean;
+    /**
+     * 开始播放
+     *
+     * @param currentTime - 可选的播放起始时间（毫秒）
+     * @returns 是否开始播放成功
+     *
+     * @example
+     * ```typescript
+     * // 从当前位置播放
+     * player.play()
+     *
+     * // 从指定时间开始播放
+     * player.play(10000) // 从10秒处开始
+     * ```
+     */
     play(currentTime?: number): boolean;
+    /**
+     * 设置播放器外观
+     * @param appearance - 外观配置对象
+     *
+     * @example
+     * ```typescript
+     * player.setAppearance({
+     *   waveStyle: 'solid'
+     * })
+     * ```
+     */
     setAppearance(appearance: Appearance): void;
+    /**
+     * 暂停播放
+     */
     pause(): void;
+    /**
+     * 显示播放器界面
+     */
     show(): void;
+    /**
+     * 隐藏播放器界面
+     */
     hide(): void;
+    /**
+     * 获取当前播放时间
+     * @returns 当前播放时间（毫秒）
+     */
     getCurrentTime(): number;
+    /**
+     * 销毁播放器实例
+     *
+     * 清理所有资源、事件监听器和DOM元素
+     */
     dispose(): void;
 }

package/lib/Player/index.js

@@ -30,9 +30,45 @@ function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.
 var DefaultAudioCacheLength = 3;
 var id = "vreo-app-dhjskadhksahdjskahdjksa";
 var audioCacheLength = Number((_location$search$matc = (_location$search$matc2 = location.search.match(/audio_cache=(\d+)/)) === null || _location$search$matc2 === void 0 ? void 0 : _location$search$matc2[1]) !== null && _location$search$matc !== void 0 ? _location$search$matc : DefaultAudioCacheLength);
+
+/**
+ * Vreo 播放器核心类
+ * 
+ * 提供 VR 视频播放、剧本执行、相机运镜等功能的主要接口。
+ * 基于 Five 渲染引擎和 React 构建的 3D 空间剧本播放器。
+ * 
+ * @example
+ * ```typescript
+ * import { Five } from '@realsee/five'
+ * import { Player } from '@realsee/vreo'
+ * 
+ * const five = new Five({
+ *   // Five 配置选项
+ * })
+ * const player = new Player(five, {
+ *   autoPreload: true,
+ *   imageOptions: { size: 1024 }
+ * })
+ * 
+ * await player.load(vreoUnit)
+ * player.play()
+ * ```
+ */
 var Player = exports.Player = /*#__PURE__*/function (_Subscribe) {
   (0, _inherits2["default"])(Player, _Subscribe);
   var _super = _createSuper(Player);
+  /** Five 渲染引擎实例 */
+
+  /** 内部控制器 */
+
+  /** 播放器配置（只读） */
+
+  /**
+   * 创建 Vreo 播放器实例
+   * 
+   * @param five - Five 渲染引擎实例
+   * @param configs - 播放器配置选项
+   */
   function Player(five) {
     var _this;
     var configs = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -106,9 +142,33 @@ var Player = exports.Player = /*#__PURE__*/function (_Subscribe) {
     });
     return _this;
   }
+
+  /**
+   * 加载剧本数据
+   * 
+   * 加载 VreoUnit 剧本数据，准备播放器状态，预载资源，并初始化播放环境。
+   * 
+   * @param vreoUnit - 剧本数据对象，包含视频信息和关键帧序列
+   * @param currentTime - 起始播放时间（毫秒），默认为 0
+   * @param preload - 是否预载相关资源，默认为 false
+   * @param force - 是否强制重新载入（深拷贝数据），默认为 false
+   * @returns Promise<boolean> 返回加载是否成功
+   * 
+   * @example
+   * ```typescript
+   * // 基本加载
+   * await player.load(vreoUnit)
+   * 
+   * // 从指定时间开始加载，并预载资源
+   * await player.load(vreoUnit, 5000, true)
+   * 
+   * // 强制重新加载
+   * await player.load(vreoUnit, 0, false, true)
+   * ```
+   */
   (0, _createClass2["default"])(Player, [{
     key: "load",
-    value: function () {
+    value: (function () {
       var _load = (0, _asyncToGenerator2["default"])(/*#__PURE__*/_regenerator["default"].mark(function _callee(vreoUnit) {
         var _this$controller$medi,
           _this$configs$imageOp,
@@ -222,11 +282,32 @@ var Player = exports.Player = /*#__PURE__*/function (_Subscribe) {
       }
       return load;
     }()
+    /**
+     * 获取播放器是否处于暂停状态
+     * @returns 是否暂停中
+     */
+    )
   }, {
     key: "paused",
     get: function get() {
       return !this.controller.playing;
     }
+
+    /**
+     * 开始播放
+     * 
+     * @param currentTime - 可选的播放起始时间（毫秒）
+     * @returns 是否开始播放成功
+     * 
+     * @example
+     * ```typescript
+     * // 从当前位置播放
+     * player.play()
+     * 
+     * // 从指定时间开始播放
+     * player.play(10000) // 从10秒处开始
+     * ```
+     */
   }, {
     key: "play",
     value: function play(currentTime) {
@@ -247,31 +328,66 @@ var Player = exports.Player = /*#__PURE__*/function (_Subscribe) {
       });
       return true;
     }
+
+    /**
+     * 设置播放器外观
+     * @param appearance - 外观配置对象
+     * 
+     * @example
+     * ```typescript
+     * player.setAppearance({
+     *   waveStyle: 'solid'
+     * })
+     * ```
+     */
   }, {
     key: "setAppearance",
     value: function setAppearance(appearance) {
       this.controller.setAppearance(appearance);
     }
+
+    /**
+     * 暂停播放
+     */
   }, {
     key: "pause",
     value: function pause() {
       this.controller.setPlaying(false);
     }
+
+    /**
+     * 显示播放器界面
+     */
   }, {
     key: "show",
     value: function show() {
       this.controller.setVisible(true);
     }
+
+    /**
+     * 隐藏播放器界面
+     */
   }, {
     key: "hide",
     value: function hide() {
       this.controller.setVisible(false);
     }
+
+    /**
+     * 获取当前播放时间
+     * @returns 当前播放时间（毫秒）
+     */
   }, {
     key: "getCurrentTime",
     value: function getCurrentTime() {
       return this.controller.currentTime;
     }
+
+    /**
+     * 销毁播放器实例
+     * 
+     * 清理所有资源、事件监听器和DOM元素
+     */
   }, {
     key: "dispose",
     value: function dispose() {