@realsee/vreo 2.4.6 → 2.5.0

package/lib/Player/modules/VideoAgent/VideoAgentMesh.d.ts

@@ -1,5 +1,8 @@
 import * as THREE from 'three';
 import AudioLike from '../../../shared-utils/AudioLike';
+/**
+ * 视频经纪人贴片的配置选项
+ */
 export interface VideoAgentMeshOptions {
     /**
      * 自定义视频实例。
@@ -17,31 +20,129 @@ export interface VideoAgentMeshOptions {
     preload?: boolean;
 }
 /**
- * 视频经纪人MESH
+ * 视频经纪人贴片类
+ *
+ * 基于 THREE.js 的网格对象，作为 VR 视频播放的核心媒体管理组件。
+ * 负责视频和音频的播放控制、时间同步、绿幕抠图渲染等功能。
+ *
+ * 主要特性：
+ * - 支持绿幕抠图渲染（ChromaKey）
+ * - 音视频同步播放管理
+ * - 媒体预载优化策略
+ * - 跨平台播放兼容性
+ *
+ * @example
+ * ```typescript
+ * const videoMesh = new VideoAgentMesh(1920, 1080, 32, 18, {
+ *   preload: true,
+ *   videoInstance: customVideoElement
+ * })
+ *
+ * // 播放视频
+ * await videoMesh.play('https://example.com/video.mp4', 0, 60)
+ *
+ * // 获取当前时间
+ * console.log(videoMesh.currentTime)
+ *
+ * // 销毁资源
+ * videoMesh.dispose()
+ * ```
  */
 export declare class VideoAgentMesh extends THREE.Mesh {
+    /** 配置选项 */
     options: VideoAgentMeshOptions;
+    /** 当前视频URL */
     videoUrl?: string;
+    /** 是否冻结状态 */
     freeze: boolean;
+    /** 是否暂停状态 */
     paused: boolean;
+    /** 音频实例 */
     audioInstance: HTMLAudioElement;
+    /** AudioLike 实例 */
     audioLikeInstance: AudioLike;
+    /** 移除事件监听器的函数 */
     $removeEventListener: () => void;
+    /**
+     * 获取当前的媒体实例
+     *
+     * 根据媒体类型自动返回对应的播放实例：
+     * - 无媒体时返回 AudioLike 实例
+     * - 音频文件返回 HTMLAudioElement
+     * - 视频文件返回 HTMLVideoElement
+     *
+     * @returns 当前活跃的媒体播放实例
+     */
     get mediaInstance(): HTMLAudioElement | HTMLVideoElement | AudioLike;
     /**
+     * 创建视频经纪人贴片实例
      *
-     * @param width
-     * @param height
-     * @param widthSegments
-     * @param heightSegments
-     * @param options
+     * @param width - 网格宽度
+     * @param height - 网格高度
+     * @param widthSegments - 宽度方向分段数
+     * @param heightSegments - 高度方向分段数
+     * @param options - 配置选项
+     *
+     * @example
+     * ```typescript
+     * const mesh = new VideoAgentMesh(1920, 1080, 32, 18, {
+     *   preload: true,
+     *   videoInstance: document.getElementById('video')
+     * })
+     * ```
      */
     constructor(width: number, height: number, widthSegments: number, heightSegments: number, options?: VideoAgentMeshOptions);
+    /**
+     * 更新媒体资源
+     *
+     * 内部方法，负责加载新的视频/音频资源，处理预载逻辑和着色器设置
+     * @param videoUrl - 媒体文件URL
+     * @private
+     */
     private update;
+    /**
+     * 播放媒体内容
+     *
+     * 支持多种播放模式：
+     * - 播放指定视频/音频文件
+     * - 仅设置时长（无媒体文件）
+     * - 继续播放当前媒体
+     *
+     * @param videoUrl - 媒体文件URL，默认为空字符串
+     * @param currentTime - 播放起始时间（秒），默认为 0
+     * @param duration - 媒体总时长（秒），可选
+     * @returns Promise<boolean> 播放是否成功
+     *
+     * @example
+     * ```typescript
+     * // 播放视频文件
+     * await mesh.play('video.mp4', 10, 120)
+     *
+     * // 仅设置时长（音频跟踪）
+     * await mesh.play('', 0, 60)
+     *
+     * // 继续播放当前媒体
+     * await mesh.play()
+     * ```
+     */
     play(videoUrl?: string, currentTime?: number, duration?: number): Promise<unknown>;
     /**
-     * 秒转成毫秒，保障精准度
+     * 获取当前播放时间（毫秒）
+     *
+     * 将媒体实例的秒级时间转换为毫秒，提供更高精度的时间控制
+     * @returns 当前播放时间戳（毫秒）
      */
     get currentTime(): number;
+    /**
+     * 销毁视频经纪人贴片实例
+     *
+     * 清理所有事件监听器、DOM元素和缓存实例，释放内存资源
+     *
+     * @example
+     * ```typescript
+     * // 在组件卸载时调用
+     * videoMesh.dispose()
+     * ```
+     */
     dispose(): void;
 }

package/lib/Player/modules/VideoAgent/VideoAgentMesh.js

@@ -27,19 +27,58 @@ var fragmentShaderTpl = function fragmentShaderTpl() {
   return "\nuniform int enable;\nuniform sampler2D map;\nvarying vec2 vUv;\nvarying vec2 vColorUv;\nvarying vec2 vMaskUv;\n\nvec3 hsv2rgb(vec3 c) {\n  const vec4 K = vec4(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);\n  vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www);\n  return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y);\n}\n\nvec3 rgb2hsv(vec3 c) {\n  const vec4 K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);\n  vec4 p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g));\n  vec4 q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r));\n\n  float d = q.x - min(q.w, q.y);\n  return vec3(abs(q.z + (q.w - q.y) / (6.0 * d + 0.001)), d / (q.x + 0.001), q.x);\n}\n\nvoid main(void) {\n  vec3 color = texture2D(map, vUv).xyz;\n  float amask = 1.0;\n\n  float ref = color.r;\n  if (ref < color.b) ref = color.b;\n  amask = color.g - ref + 0.1;\n  amask = smoothstep(0.1, 0.3, amask);\n  amask = 1.0 - amask;\n\n  vec3 target = rgb2hsv(vec3(0.0 / 255.0, 255.0 / 255.0, 0.0 / 255.0));\n  vec3 hsv = rgb2hsv(color);\n  float distance = abs(hsv.x - target.x);\n  if (distance < 0.15) {\n    hsv.y = 0.0;\n  }\n  color = hsv2rgb(hsv);\n\n  gl_FragColor = vec4(color.rgb, amask * float(enable));\n}\n";
 };
 var cacheInstance = {};
+
+/**
+ * 视频经纪人贴片的配置选项
+ */
 /**
- * 视频经纪人MESH
+ * 视频经纪人贴片类
+ * 
+ * 基于 THREE.js 的网格对象，作为 VR 视频播放的核心媒体管理组件。
+ * 负责视频和音频的播放控制、时间同步、绿幕抠图渲染等功能。
+ * 
+ * 主要特性：
+ * - 支持绿幕抠图渲染（ChromaKey）
+ * - 音视频同步播放管理
+ * - 媒体预载优化策略
+ * - 跨平台播放兼容性
+ * 
+ * @example
+ * ```typescript
+ * const videoMesh = new VideoAgentMesh(1920, 1080, 32, 18, {
+ *   preload: true,
+ *   videoInstance: customVideoElement
+ * })
+ * 
+ * // 播放视频
+ * await videoMesh.play('https://example.com/video.mp4', 0, 60)
+ * 
+ * // 获取当前时间
+ * console.log(videoMesh.currentTime)
+ * 
+ * // 销毁资源
+ * videoMesh.dispose()
+ * ```
  */
 var VideoAgentMesh = exports.VideoAgentMesh = /*#__PURE__*/function (_THREE$Mesh) {
   (0, _inherits2["default"])(VideoAgentMesh, _THREE$Mesh);
   var _super = _createSuper(VideoAgentMesh);
   /**
-   *
-   * @param width
-   * @param height
-   * @param widthSegments
-   * @param heightSegments
-   * @param options
+   * 创建视频经纪人贴片实例
+   * 
+   * @param width - 网格宽度
+   * @param height - 网格高度  
+   * @param widthSegments - 宽度方向分段数
+   * @param heightSegments - 高度方向分段数
+   * @param options - 配置选项
+   * 
+   * @example
+   * ```typescript
+   * const mesh = new VideoAgentMesh(1920, 1080, 32, 18, {
+   *   preload: true,
+   *   videoInstance: document.getElementById('video')
+   * })
+   * ```
    */
   function VideoAgentMesh(width, height, widthSegments, heightSegments) {
     var _this$options$videoIn, _this$options$videoIn2;
@@ -131,9 +170,41 @@ var VideoAgentMesh = exports.VideoAgentMesh = /*#__PURE__*/function (_THREE$Mesh
     };
     return _this;
   }
+
+  /**
+   * 更新媒体资源
+   * 
+   * 内部方法，负责加载新的视频/音频资源，处理预载逻辑和着色器设置
+   * @param videoUrl - 媒体文件URL
+   * @private
+   */
   (0, _createClass2["default"])(VideoAgentMesh, [{
     key: "mediaInstance",
-    get: function get() {
+    get: /** 配置选项 */
+
+    /** 当前视频URL */
+
+    /** 是否冻结状态 */
+
+    /** 是否暂停状态 */
+
+    /** 音频实例 */
+
+    /** AudioLike 实例 */
+
+    /** 移除事件监听器的函数 */
+
+    /**
+     * 获取当前的媒体实例
+     * 
+     * 根据媒体类型自动返回对应的播放实例：
+     * - 无媒体时返回 AudioLike 实例
+     * - 音频文件返回 HTMLAudioElement
+     * - 视频文件返回 HTMLVideoElement
+     * 
+     * @returns 当前活跃的媒体播放实例
+     */
+    function get() {
       if (!this.videoUrl) {
         return this.audioLikeInstance;
       }
@@ -146,7 +217,7 @@ var VideoAgentMesh = exports.VideoAgentMesh = /*#__PURE__*/function (_THREE$Mesh
     }
   }, {
     key: "update",
-    value: function () {
+    value: (function () {
       var _update = (0, _asyncToGenerator2["default"])(/*#__PURE__*/_regenerator["default"].mark(function _callee(videoUrl) {
         var _this2 = this;
         var uniforms, onStart;
@@ -215,9 +286,35 @@ var VideoAgentMesh = exports.VideoAgentMesh = /*#__PURE__*/function (_THREE$Mesh
       }
       return update;
     }()
+    /**
+     * 播放媒体内容
+     * 
+     * 支持多种播放模式：
+     * - 播放指定视频/音频文件
+     * - 仅设置时长（无媒体文件）
+     * - 继续播放当前媒体
+     * 
+     * @param videoUrl - 媒体文件URL，默认为空字符串
+     * @param currentTime - 播放起始时间（秒），默认为 0
+     * @param duration - 媒体总时长（秒），可选
+     * @returns Promise<boolean> 播放是否成功
+     * 
+     * @example
+     * ```typescript
+     * // 播放视频文件
+     * await mesh.play('video.mp4', 10, 120)
+     * 
+     * // 仅设置时长（音频跟踪）
+     * await mesh.play('', 0, 60)
+     * 
+     * // 继续播放当前媒体
+     * await mesh.play()
+     * ```
+     */
+    )
   }, {
     key: "play",
-    value: function () {
+    value: (function () {
       var _play = (0, _asyncToGenerator2["default"])(/*#__PURE__*/_regenerator["default"].mark(function _callee3() {
         var _this3 = this;
         var videoUrl,
@@ -311,13 +408,29 @@ var VideoAgentMesh = exports.VideoAgentMesh = /*#__PURE__*/function (_THREE$Mesh
       return play;
     }()
     /**
-     * 秒转成毫秒，保障精准度
+     * 获取当前播放时间（毫秒）
+     * 
+     * 将媒体实例的秒级时间转换为毫秒，提供更高精度的时间控制
+     * @returns 当前播放时间戳（毫秒）
      */
+    )
   }, {
     key: "currentTime",
     get: function get() {
       return this.mediaInstance.currentTime * 1000;
     }
+
+    /**
+     * 销毁视频经纪人贴片实例
+     * 
+     * 清理所有事件监听器、DOM元素和缓存实例，释放内存资源
+     * 
+     * @example
+     * ```typescript
+     * // 在组件卸载时调用
+     * videoMesh.dispose()
+     * ```
+     */
   }, {
     key: "dispose",
     value: function dispose() {

package/lib/Player/modules/keyframes/VideoEffect/index.js

@@ -28,7 +28,7 @@ var inlinePlay = function inlinePlay(videoInstance) {
   videoInstance.load();
 };
 
-// const emptyVideo = '//vrlab-static.ljcdn.com/release/web/leisure.69fd3522.mov'
+// const emptyVideo = '//vr-static.realsee-cdn.cn/release/web/leisure.69fd3522.mov'
 var PI = Math.PI;
 var PI_2 = PI * 2;
 function VideoEffect() {

package/lib/fivePlugins/CSS3DRenderPlugin/index.d.ts

@@ -12,16 +12,11 @@ export interface Vector3Position {
 export type CSS3DRenderPluginParameterType = undefined;
 export interface CSS3DRenderPluginExportType {
     /**
-     * @description: 根据传入的四个点位创建一个3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
-     * @param {Five} five
-     * @param {Vector3[] | Vector3Position[]} points: 矩形四个点坐标
-     * @param {number} config.ratio: 1px对应多少米，默认为 0.002，即1px对应2mm
-     * @param {number} config.dpr: dpr, 默认为1
-     * @param {HTMLElement} config.container: HTMLElement
-     * @param {number} config.autoRender: 默认为true，如果需要手动render则传false
-     * @param {'front' | 'behind'} config.mode: 两种模式
-     * @param {HTMLElement} config.behindFiveContainer: 如果config.mode为'behind'，需要传入容器，并确保此容器位five下方，且中间没有其他dom元素遮挡
-     * @return {{ container: HTMLElement; dispose: () => void }}: container: dom容器, dispose: 清理函数
+     * 根据传入的四个点位创建一个3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
+     *
+     * @param points - 矩形四个点坐标
+     * @param config - 配置项，包含ratio(像素比例)、dpr(设备像素比)、container(容器)、autoRender(自动渲染)、mode(渲染模式)等
+     * @returns 返回包含容器、销毁函数、CSS3D对象和可选渲染函数的对象
      */
     create3DDomContainer: (points: Vector3[] | Vector3Position[], config?: {
         ratio?: number;
@@ -41,8 +36,7 @@ export interface CSS3DRenderPluginExportType {
         render?: () => void;
     } | void;
     /**
-     * @description: 销毁所有的渲染内容
-     * @return {void}
+     * 销毁所有的渲染内容
      */
     disposeAll: () => void;
 }

package/lib/react/index.d.ts

@@ -1,10 +1,33 @@
 import * as React from 'react';
 import { PlayerConfigs } from '../Player/typings';
 import { VreoKeyframeEvent, VreoUnit } from '../typings/VreoUnit';
+/**
+ * VreoProvider 组件的属性接口
+ */
 export interface VreoProviderProps {
+    /** 播放器配置选项 */
     configs?: Partial<PlayerConfigs>;
+    /** 子组件 */
     children?: React.ReactNode;
 }
+/**
+ * Vreo 播放器 Provider 组件
+ *
+ * 为子组件提供 Vreo 播放器实例的 React Context Provider。
+ * 必须在 Five Provider 内部使用。
+ *
+ * @param props - 组件属性
+ * @returns React.FC 组件
+ *
+ * @example
+ * ```tsx
+ * <FiveProvider>
+ *   <VreoProvider configs={{ autoPreload: true }}>
+ *     <YourComponent />
+ *   </VreoProvider>
+ * </FiveProvider>
+ * ```
+ */
 export declare const VreoProvider: React.FC<VreoProviderProps>;
 /**
  * VreoPlayer 命令集合。
@@ -39,6 +62,35 @@ export interface VreoActionCallbacks {
      */
     dispose: () => void;
 }
+/**
+ * 获取 Vreo 播放器操作函数集合
+ *
+ * 返回一组经过优化的播放器操作函数，这些函数已经绑定了当前播放器实例。
+ * 使用 useCallback 进行性能优化，避免不必要的重新渲染。
+ *
+ * @returns VreoActionCallbacks 操作函数集合
+ *
+ * @example
+ * ```tsx
+ * function PlayerControls() {
+ *   const { load, play, pause, show, hide, dispose } = useVreoAction()
+ *
+ *   const handleLoadScript = async () => {
+ *     await load(vreoUnit, 0)
+ *     play()
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleLoadScript}>加载并播放</button>
+ *       <button onClick={pause}>暂停</button>
+ *       <button onClick={() => show()}>显示</button>
+ *       <button onClick={() => hide()}>隐藏</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export declare function useVreoAction(): {
     load: (vreoUnit: VreoUnit, currentTime?: number) => Promise<boolean>;
     pause: () => void;
@@ -47,5 +99,64 @@ export declare function useVreoAction(): {
     hide: () => void;
     dispose: () => void;
 };
+/**
+ * 监听 Vreo 播放器事件
+ *
+ * 用于注册和清理 Vreo 播放器事件监听器的 React Hook。
+ * 当组件卸载或依赖项变化时自动清理事件监听器。
+ *
+ * @param name - 事件名称
+ * @param callback - 事件回调函数
+ * @param deps - 依赖项数组（可选）
+ *
+ * @example
+ * ```tsx
+ * function EventListener() {
+ *   const [keyframes, setKeyframes] = React.useState([])
+ *
+ *   // 监听关键帧事件
+ *   useVreoEventCallback('CameraMovement', (keyframe) => {
+ *     console.log('相机运镜:', keyframe)
+ *   })
+ *
+ *   // 监听播放状态变化
+ *   useVreoEventCallback('playing', () => {
+ *     console.log('开始播放')
+ *   }, [])
+ *
+ *   return <div>事件监听组件</div>
+ * }
+ * ```
+ */
 export declare function useVreoEventCallback<T extends keyof VreoKeyframeEvent>(name: T, callback: VreoKeyframeEvent[T], deps?: React.DependencyList | undefined): void;
+/**
+ * 获取播放器暂停状态
+ *
+ * 返回当前播放器的暂停状态，并自动响应播放状态变化。
+ * 当播放器开始播放或暂停时，状态会自动更新。
+ *
+ * @returns boolean 是否处于暂停状态
+ *
+ * @example
+ * ```tsx
+ * function PlayButton() {
+ *   const isPaused = useVreoPausedState()
+ *   const { play, pause } = useVreoAction()
+ *
+ *   const handleToggle = () => {
+ *     if (isPaused) {
+ *       play()
+ *     } else {
+ *       pause()
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleToggle}>
+ *       {isPaused ? '播放' : '暂停'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export declare function useVreoPausedState(): boolean;

package/lib/react/index.js

@@ -15,6 +15,29 @@ var React = _interopRequireWildcard(require("react"));
 var _Player = require("../Player");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, "default": e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) { "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); } return f; })(e, t); }
 var VreoContext = /*#__PURE__*/React.createContext(null);
+
+/**
+ * VreoProvider 组件的属性接口
+ */
+
+/**
+ * Vreo 播放器 Provider 组件
+ * 
+ * 为子组件提供 Vreo 播放器实例的 React Context Provider。
+ * 必须在 Five Provider 内部使用。
+ * 
+ * @param props - 组件属性
+ * @returns React.FC 组件
+ * 
+ * @example
+ * ```tsx
+ * <FiveProvider>
+ *   <VreoProvider configs={{ autoPreload: true }}>
+ *     <YourComponent />
+ *   </VreoProvider>
+ * </FiveProvider>
+ * ```
+ */
 var VreoProvider = exports.VreoProvider = function VreoProvider(props) {
   var five = (0, _react.unsafe__useFiveInstance)();
   var _React$useState = React.useState(null),
@@ -35,6 +58,29 @@ var VreoProvider = exports.VreoProvider = function VreoProvider(props) {
     value: player
   }, props.children);
 };
+
+/**
+ * 获取 Vreo 播放器实例
+ * 
+ * 从 React Context 中获取当前的 Vreo 播放器实例。
+ * 必须在 VreoProvider 内部使用。
+ * 
+ * @returns Player 播放器实例
+ * @throws 如果未找到 VreoProvider 则抛出错误
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const player = useVreoInstance()
+ *   
+ *   const handleLoad = () => {
+ *     player.load(vreoUnit)
+ *   }
+ *   
+ *   return <button onClick={handleLoad}>Load Script</button>
+ * }
+ * ```
+ */
 function useVreoInstance() {
   var context = React.useContext(VreoContext);
   if (!context) {
@@ -47,6 +93,35 @@ function useVreoInstance() {
  * VreoPlayer 命令集合。
  */
 
+/**
+ * 获取 Vreo 播放器操作函数集合
+ * 
+ * 返回一组经过优化的播放器操作函数，这些函数已经绑定了当前播放器实例。
+ * 使用 useCallback 进行性能优化，避免不必要的重新渲染。
+ * 
+ * @returns VreoActionCallbacks 操作函数集合
+ * 
+ * @example
+ * ```tsx
+ * function PlayerControls() {
+ *   const { load, play, pause, show, hide, dispose } = useVreoAction()
+ *   
+ *   const handleLoadScript = async () => {
+ *     await load(vreoUnit, 0)
+ *     play()
+ *   }
+ *   
+ *   return (
+ *     <div>
+ *       <button onClick={handleLoadScript}>加载并播放</button>
+ *       <button onClick={pause}>暂停</button>
+ *       <button onClick={() => show()}>显示</button>
+ *       <button onClick={() => hide()}>隐藏</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 function useVreoAction() {
   var player = useVreoInstance();
   var load = React.useCallback(function (vreoUnit, currentTime) {
@@ -76,6 +151,36 @@ function useVreoAction() {
     dispose: dispose
   };
 }
+
+/**
+ * 监听 Vreo 播放器事件
+ * 
+ * 用于注册和清理 Vreo 播放器事件监听器的 React Hook。
+ * 当组件卸载或依赖项变化时自动清理事件监听器。
+ * 
+ * @param name - 事件名称
+ * @param callback - 事件回调函数
+ * @param deps - 依赖项数组（可选）
+ * 
+ * @example
+ * ```tsx
+ * function EventListener() {
+ *   const [keyframes, setKeyframes] = React.useState([])
+ *   
+ *   // 监听关键帧事件
+ *   useVreoEventCallback('CameraMovement', (keyframe) => {
+ *     console.log('相机运镜:', keyframe)
+ *   })
+ *   
+ *   // 监听播放状态变化
+ *   useVreoEventCallback('playing', () => {
+ *     console.log('开始播放')
+ *   }, [])
+ *   
+ *   return <div>事件监听组件</div>
+ * }
+ * ```
+ */
 function useVreoEventCallback(name, callback, deps) {
   var player = useVreoInstance();
   var dependencyList = [player, name];
@@ -91,6 +196,37 @@ function useVreoEventCallback(name, callback, deps) {
     };
   }, dependencyList);
 }
+
+/**
+ * 获取播放器暂停状态
+ * 
+ * 返回当前播放器的暂停状态，并自动响应播放状态变化。
+ * 当播放器开始播放或暂停时，状态会自动更新。
+ * 
+ * @returns boolean 是否处于暂停状态
+ * 
+ * @example
+ * ```tsx
+ * function PlayButton() {
+ *   const isPaused = useVreoPausedState()
+ *   const { play, pause } = useVreoAction()
+ *   
+ *   const handleToggle = () => {
+ *     if (isPaused) {
+ *       play()
+ *     } else {
+ *       pause()
+ *     }
+ *   }
+ *   
+ *   return (
+ *     <button onClick={handleToggle}>
+ *       {isPaused ? '播放' : '暂停'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 function useVreoPausedState() {
   var player = useVreoInstance();
   var _React$useState3 = React.useState(player.paused),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realsee/vreo",
-  "version": "2.4.6",
+  "version": "2.5.0",
   "description": "Vreo (VR Video 缩写) 是基于如视三维渲染引擎 Five 和 用户界面构建库 React 实现的如视 3D 空间剧本播放器。",
   "keywords": [
     "realsee",
@@ -14,7 +14,8 @@
     "lib",
     "stylesheets",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs"
   ],
   "scripts": {
     "dev": "vite --port=3088 --host 0.0.0.0",