@galacean/effects-plugin-multimedia 2.9.0-alpha.2 → 2.9.1-beta.0

package/dist/index.js

@@ -3,7 +3,7 @@
  * Description: Galacean Effects player multimedia plugin
  * Author: Ant Group CO., Ltd.
  * Contributors: 云垣
- * Version: v2.9.0-alpha.2
+ * Version: v2.9.1-beta.0
  */
 
 'use strict';
@@ -580,25 +580,50 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var _this;
         _this = MaskableGraphic.call(this, engine) || this;
         /**
-   * 播放标志位
-   */ _this.played = false;
-        _this.pendingPause = false;
-        _this.threshold = 0.03;
-        /**
-   * 解决 video 暂停报错问题
-   *
-   * video.play(); // <-- This is asynchronous!
-   *
-   * video.pause();
-   *
-   * @see https://developer.chrome.com/blog/play-request-was-interrupted
-   */ _this.isPlayLoading = false;
-        /**
    * 视频元素是否激活
    */ _this.isVideoActive = false;
         /**
    * 是否为透明视频
    */ _this.transparent = false;
+        /**
+   * 是否由用户手动控制播放速率（覆盖合成的播放速率）
+   */ _this.manualPlaybackRate = false;
+        /**
+   * 是否由用户手动控制循环播放（覆盖合成的结束行为）
+   */ _this.manualLoop = false;
+        /**
+   * 是否由用户手动暂停视频
+   */ _this.manualPause = false;
+        /**
+   * 视频是否已开始播放
+   */ _this.playTriggered = false;
+        /**
+   * 上一次的视频时间，用于检测重播
+   */ _this.lastVideoTime = -1;
+        /**
+   * 视频是否已经销毁（用于 destroy 结束行为，确保只重置一次）
+   */ _this.videoDestroyed = false;
+        /**
+   * 视频是否处于 seek 中
+   * seek 期间禁止上传帧，避免 destroy 后 seek 回 0 期间渲染旧帧
+   */ _this.videoSeeking = false;
+        /**
+   * 待执行的 seek 目标时间，延迟到 onUpdate 中处理以避免竞态。
+   * 值为 null 表示没有待执行的 seek。
+   */ _this.pendingSeekTime = null;
+        /**
+   * 是否正在处理 gotoAndStop 的 seek
+   * 用于跳过 pause 事件触发的 pauseVideoElement，等 seek 完成后再暂停
+   */ _this.isGotoAndStopSeeking = false;
+        /**
+   * 是否刚收到 goto 事件，等待后续 play/pause 事件来区分场景
+   */ _this.isWaitingForGotoResult = false;
+        /**
+   * 当前正在执行的 play() Promise，用于串行化 play 调用，避免上的竞态
+   */ _this.playPromise = null;
+        /**
+   * 存储事件监听器的移除函数，用于销毁时清理
+   */ _this.eventDisposers = [];
         _this.name = "MVideo" + seed++;
         return _this;
     }
@@ -612,6 +637,11 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
                     case 0:
                         oldTexture = _this.renderer.texture;
                         composition = _this.item.composition;
+                        if (!composition) {
+                            return [
+                                2
+                            ];
+                        }
                         if (!(typeof input === "string")) return [
                             3,
                             2
@@ -630,11 +660,6 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
                         texture = input;
                         _state.label = 3;
                     case 3:
-                        if (!composition) {
-                            return [
-                                2
-                            ];
-                        }
                         composition.textures.forEach(function(cachedTexture, index) {
                             if (cachedTexture === oldTexture) {
                                 composition.textures[index] = texture;
@@ -658,21 +683,15 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
         if (!composition) {
             return;
         }
-        this.handleGoto = function(option) {
-            _this.setCurrentTime(_this.item.time);
-        };
-        this.handlePause = function() {
-            _this.pauseVideo();
-        };
-        this.handlePlay = function(option) {
-            if (_this.item.time < 0) {
-                return;
-            }
-            _this.playVideo();
-        };
-        composition.on("goto", this.handleGoto);
-        composition.on("pause", this.handlePause);
-        composition.on("play", this.handlePlay);
+        this.eventDisposers.push(composition.on("goto", function() {
+            return _this.handleGoto();
+        }), composition.on("play", function() {
+            return _this.handleCompositionPlay();
+        }), composition.on("pause", function() {
+            return _this.handleCompositionPause();
+        }), composition.on("end", function() {
+            return _this.handleCompositionEnd();
+        }));
     };
     _proto.fromData = function fromData(data) {
         MaskableGraphic.prototype.fromData.call(this, data);
@@ -688,94 +707,504 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
             var videoAsset = this.engine.findObject(video);
             if (videoAsset) {
                 this.video = videoAsset.data;
-                this.setPlaybackRate(playbackRate);
+                this.video.playbackRate = playbackRate;
                 this.setVolume(volume);
                 this.setMuted(muted);
                 var endBehavior = this.item.definition.endBehavior;
-                // 如果元素设置为 destroy
                 if (endBehavior === EFFECTS.spec.EndBehavior.destroy || endBehavior === EFFECTS.spec.EndBehavior.freeze) {
-                    this.setLoop(false);
+                    this.video.loop = false;
                 } else if (endBehavior === EFFECTS.spec.EndBehavior.restart) {
-                    this.setLoop(true);
+                    this.video.loop = true;
                 }
             }
         }
         this.interaction = interaction;
-        this.pauseVideo();
         if (this.transparent) {
             this.material.enableMacro("TRANSPARENT_VIDEO", this.transparent);
         }
         this.material.setColor("_Color", new EFFECTS.math.Color().setFromArray(startColor));
     };
-    _proto.render = function render(renderer) {
-        MaskableGraphic.prototype.render.call(this, renderer);
-        this.renderer.texture.uploadCurrentVideoFrame();
-    };
     _proto.onUpdate = function onUpdate(dt) {
         MaskableGraphic.prototype.onUpdate.call(this, dt);
-        var _this_item = this.item, videoTime = _this_item.time, videoDuration = _this_item.duration, videoEndBehavior = _this_item.endBehavior, composition = _this_item.composition;
-        EFFECTS.assertExist(composition);
-        var _composition_rootItem = composition.rootItem, rootEndBehavior = _composition_rootItem.endBehavior, rootDuration = _composition_rootItem.duration;
-        // 判断是否处于"结束状态"：
-        // - 视频时间为 0（未开始）
-        // - 合成时间已达最大时长（播放完毕）
-        // - 视频时间接近或等于其总时长（考虑容差阈值）
-        var isEnd = videoTime === 0 || Math.abs(composition.time - rootDuration) <= this.threshold || Math.abs(videoTime - videoDuration) <= this.threshold;
-        // 如果视频时间大于等于 0，且未到结束状态，并且尚未触发播放，则开始播放视频
-        if (videoTime >= 0 && !isEnd && !this.played && this.isVideoActive) {
-            this.playVideo();
-        }
-        // 当视频播放时间接近或超过其总时长时，根据其结束行为进行处理
-        if (videoTime + this.threshold >= videoDuration) {
-            if (videoEndBehavior === EFFECTS.spec.EndBehavior.freeze) {
-                var _this_video;
-                if (!((_this_video = this.video) == null ? void 0 : _this_video.paused)) {
-                    this.pauseVideo();
-                }
+        if (!this.video || this.video.readyState < 2) {
+            return;
+        }
+        // 处理延迟 seek（避免与 forwardTime 同步调用产生竞态）
+        if (this.processPendingSeek()) {
+            return;
+        }
+        // 检测当前是否为重播状态
+        this.detectCompositionRestart();
+        // 根据结束行为决定视频状态
+        if (this.shouldFreezeVideo()) {
+            this.freezeVideo();
+            return;
+        }
+        if (this.shouldStartVideo()) {
+            this.startVideo();
+        }
+        this.updatePlaybackRate();
+        this.ensureLoopFlag();
+        this.handleDestroyBehavior();
+        // 上传当前视频帧
+        if (!this.videoSeeking) {
+            this.renderer.texture.uploadCurrentVideoFrame();
+        }
+    };
+    _proto.onDestroy = function onDestroy() {
+        this.eventDisposers.forEach(function(dispose) {
+            return dispose();
+        });
+        this.eventDisposers = [];
+        MaskableGraphic.prototype.onDestroy.call(this);
+        this.playTriggered = false;
+        this.playPromise = null;
+        if (this.video) {
+            this.video.pause();
+            this.video.src = "";
+            this.video.load();
+        }
+    };
+    _proto.onDisable = function onDisable() {
+        MaskableGraphic.prototype.onDisable.call(this);
+        this.isVideoActive = false;
+        this.playTriggered = false;
+        this.pauseVideoElement();
+    };
+    _proto.onEnable = function onEnable() {
+        MaskableGraphic.prototype.onEnable.call(this);
+        this.isVideoActive = true;
+        this.playTriggered = false;
+        this.syncVideoToItemTime();
+    };
+    /**
+   * 处理 goto 事件：重置播放状态，记录待 seek 时间
+   */ _proto.handleGoto = function handleGoto() {
+        // 通过后续事件区分 gotoAndPlay 和 gotoAndStop
+        this.isWaitingForGotoResult = true;
+        this.playTriggered = false;
+        this.manualPause = false;
+        this.pendingSeekTime = this.getItemSeekTime();
+    };
+    /**
+   * 处理合成 pause 事件
+   * 如果刚收到 goto 事件且等待结果，说明是 gotoAndStop 场景
+   */ _proto.handleCompositionPause = function handleCompositionPause() {
+        // gotoAndStop 场景
+        if (this.isWaitingForGotoResult) {
+            this.isWaitingForGotoResult = false;
+            if (this.video && this.video.readyState >= 2) {
+                this.isGotoAndStopSeeking = true;
+                this.performSeek(this.getItemSeekTime(), false, true);
+            }
+            return;
+        }
+        // 普通 pause 事件：暂停视频
+        this.pauseVideoElement();
+    };
+    /**
+   * 处理合成 play 事件（合成开始/重播/恢复时触发）
+   */ _proto.handleCompositionPlay = function handleCompositionPlay() {
+        // 如果正在等待 goto 结果，说明是 gotoAndPlay 场景
+        if (this.isWaitingForGotoResult) {
+            this.isWaitingForGotoResult = false;
+        }
+        // 合成未结束时（暂停后恢复），恢复视频播放
+        if (!this.checkCompositionEnded()) {
+            var _this_video;
+            // 如果正在 seeking，不恢复播放，等 seek 完成后再恢复
+            if (this.canPlayCurrentItem() && ((_this_video = this.video) == null ? void 0 : _this_video.paused)) {
+                this.safePlay();
+            }
+            return;
+        }
+        this.playTriggered = false;
+        this.manualPause = false;
+        var videoEndBehavior = this.item.endBehavior;
+        if (videoEndBehavior === EFFECTS.spec.EndBehavior.freeze && this.video) {
+            this.pendingSeekTime = 0;
+        } else if (videoEndBehavior === EFFECTS.spec.EndBehavior.destroy) {
+            this.videoDestroyed = false;
+        }
+    };
+    /**
+   * 根据合成结束行为决定视频的后续处理
+   */ _proto.handleCompositionEnd = function handleCompositionEnd() {
+        var _this_item_composition;
+        var rootEndBehavior = (_this_item_composition = this.item.composition) == null ? void 0 : _this_item_composition.rootItem.endBehavior;
+        if (rootEndBehavior === EFFECTS.spec.EndBehavior.restart) {
+            // 合成 restart：所有视频都需要 seek 回 0，和合成时间对齐
+            if (!this.videoSeeking) {
+                this.pendingSeekTime = 0;
+            }
+            this.playTriggered = false;
+            this.videoDestroyed = false;
+            return;
+        }
+        if (rootEndBehavior === EFFECTS.spec.EndBehavior.forward) {
+            // forward：合成时间继续往前走，视频也继续播
+            return;
+        }
+        // freeze / destroy：合成真正结束，暂停视频
+        this.playTriggered = false;
+        this.pauseVideoElement();
+    };
+    /**
+   * 视频是否已播放到末尾
+   */ _proto.checkVideoEnded = function checkVideoEnded() {
+        var videoEndBehavior = this.item.endBehavior;
+        // restart 行为的视频永远不会"结束"（由浏览器原生 loop 处理）
+        if (videoEndBehavior === EFFECTS.spec.EndBehavior.restart) {
+            return false;
+        }
+        return this.video.currentTime + VideoComponent.threshold >= this.video.duration;
+    };
+    /**
+   * 合成是否已到达结束时间
+   */ _proto.checkCompositionEnded = function checkCompositionEnded() {
+        var composition = this.item.composition;
+        if (!composition) {
+            return false;
+        }
+        return composition.time + VideoComponent.threshold >= composition.rootItem.duration;
+    };
+    /**
+   * 是否应该冻结视频（暂停在当前帧）
+   */ _proto.shouldFreezeVideo = function shouldFreezeVideo() {
+        var _this_item_composition;
+        var isVideoEnded = this.checkVideoEnded();
+        var isCompositionEnded = this.checkCompositionEnded();
+        var videoEndBehavior = this.item.endBehavior;
+        var rootEndBehavior = (_this_item_composition = this.item.composition) == null ? void 0 : _this_item_composition.rootItem.endBehavior;
+        // 合成结束且合成行为是 freeze 时冻结视频
+        var isCompositionFrozen = isCompositionEnded && rootEndBehavior === EFFECTS.spec.EndBehavior.freeze;
+        // 合成结束且视频行为是 freeze，除合成 restart 外均冻结视频
+        var isCompositionEndedForVideo = rootEndBehavior !== EFFECTS.spec.EndBehavior.restart && isCompositionEnded;
+        var isVideoFrozen = (isVideoEnded || isCompositionEndedForVideo) && videoEndBehavior === EFFECTS.spec.EndBehavior.freeze;
+        return isVideoFrozen || isCompositionFrozen;
+    };
+    /**
+   * 是否应该启动视频播放
+   */ _proto.shouldStartVideo = function shouldStartVideo() {
+        if (this.playTriggered || !this.canPlayCurrentItem()) {
+            return false;
+        }
+        return true;
+    };
+    /**
+   * 处理延迟 seek，返回 true 表示本帧已处理 seek，应跳过后续逻辑
+   */ _proto.processPendingSeek = function processPendingSeek() {
+        if (this.pendingSeekTime === null) {
+            return false;
+        }
+        var seekTime = this.pendingSeekTime;
+        this.pendingSeekTime = null;
+        this.performSeek(seekTime);
+        return true;
+    };
+    /**
+   * 检测合成是否发生了 restart，并重置相关状态
+   */ _proto.detectCompositionRestart = function detectCompositionRestart() {
+        var videoTime = this.item.time;
+        if (this.lastVideoTime > 0 && videoTime < this.lastVideoTime) {
+            var _this_item_composition;
+            this.playTriggered = false;
+            this.videoDestroyed = false;
+            this.manualPause = false;
+            this.lastVideoTime = -1;
+            var rootEndBehavior = (_this_item_composition = this.item.composition) == null ? void 0 : _this_item_composition.rootItem.endBehavior;
+            var videoEndBehavior = this.item.endBehavior;
+            // 视频 restart 时，浏览器 loop 处理；合成 restart 时，前面函数已经 seek 回 0
+            if (rootEndBehavior !== EFFECTS.spec.EndBehavior.restart && videoEndBehavior !== EFFECTS.spec.EndBehavior.restart) {
+                this.pendingSeekTime = 0;
+            }
+        }
+        this.lastVideoTime = videoTime;
+    };
+    /**
+   * 冻结视频：停止播放，保持当前帧
+   */ _proto.freezeVideo = function freezeVideo() {
+        this.playTriggered = false;
+        if (!this.video.paused) {
+            this.pauseVideoElement();
+        }
+    };
+    /**
+   * 确保 restart 行为的视频设置了 loop 标志
+   * 手动模式下不自动设置，保持用户设置的值
+   */ _proto.ensureLoopFlag = function ensureLoopFlag() {
+        if (this.manualLoop) {
+            return;
+        }
+        if (this.item.endBehavior === EFFECTS.spec.EndBehavior.restart && !this.video.loop) {
+            this.video.loop = true;
+        }
+    };
+    /**
+   * 处理 destroy 结束行为：视频播放到末尾后，seek 回 0 并清空纹理
+   * 确保合成 restart 时视频已在第 0 帧，不会闪最后一帧
+   */ _proto.handleDestroyBehavior = function handleDestroyBehavior() {
+        if (this.videoDestroyed || this.videoSeeking) {
+            return;
+        }
+        var isVideoEnded = this.checkVideoEnded();
+        if (isVideoEnded && this.item.endBehavior === EFFECTS.spec.EndBehavior.destroy) {
+            this.videoDestroyed = true;
+            this.playTriggered = false;
+            this.performSeek(0, true);
+        }
+    };
+    /**
+   * 开始播放视频
+   */ _proto.startVideo = function startVideo() {
+        if (!this.video || this.playTriggered && !this.video.paused) {
+            return;
+        }
+        this.playTriggered = true;
+        this.safePlay();
+    };
+    /**
+   * 安全地调用 video.play()，串行化调用
+   */ _proto.safePlay = function safePlay() {
+        var _this = this;
+        if (!this.video) {
+            return;
+        }
+        // 已有 play() 在执行中，不重复调用，避免 AbortError
+        if (this.playPromise) {
+            return;
+        }
+        var promise = this.video.play();
+        this.playPromise = promise;
+        void promise.then(function() {
+            if (_this.playPromise === promise) {
+                _this.playPromise = null;
+            }
+            _this.updatePlaybackRate();
+        }).catch(function(error) {
+            if (_this.playPromise === promise) {
+                _this.playPromise = null;
             }
+            if (error.name === "AbortError") {
+                _this.playTriggered = false;
+            }
+            _this.engine.renderErrors.add(error);
+        });
+    };
+    /**
+   * 暂停底层视频元素
+   */ _proto.pauseVideoElement = function pauseVideoElement() {
+        var _this = this;
+        // gotoAndStop 场景：跳过暂停，等 seek 完成后再暂停
+        if (this.isGotoAndStopSeeking) {
+            return;
         }
-        // 判断整个合成是否接近播放完成
-        // composition.time + threshold >= rootDuration 表示即将结束
-        if (composition.time + this.threshold >= rootDuration) {
-            if (rootEndBehavior === EFFECTS.spec.EndBehavior.freeze) {
-                var _this_video1;
-                if (!((_this_video1 = this.video) == null ? void 0 : _this_video1.paused)) {
-                    this.pauseVideo();
+        if (!this.video || this.video.paused) {
+            return;
+        }
+        this.video.pause();
+        if (this.playPromise) {
+            void this.playPromise.then(function() {
+                if (_this.video && !_this.video.paused) {
+                    _this.video.pause();
+                }
+            });
+        }
+    };
+    /**
+   * seek 期间设置 videoSeeking=true，阻止 uploadCurrentVideoFrame 上传旧帧
+   * @param time 目标时间
+   * @param clearTexture 是否在 seek 期间清空纹理
+   * @param isGotoAndStop 是否为 gotoAndStop 场景
+   */ _proto.performSeek = function performSeek(time, clearTexture, isGotoAndStop) {
+        var _this = this;
+        if (clearTexture === void 0) clearTexture = false;
+        if (isGotoAndStop === void 0) isGotoAndStop = false;
+        time = this.getClampedSeekTime(time);
+        var wasPlaying = !this.video.paused;
+        var isNoopSeek = function() {
+            return !clearTexture && Math.abs(_this.video.currentTime - time) <= VideoComponent.threshold;
+        };
+        var finishNoopSeek = function() {
+            _this.videoSeeking = false;
+            _this.isGotoAndStopSeeking = false;
+            if (isGotoAndStop) {
+                _this.video.pause();
+            } else if (wasPlaying && !_this.manualPause) {
+                _this.safePlay();
+            }
+        };
+        var doSeek = function() {
+            if (isNoopSeek()) {
+                finishNoopSeek();
+                return;
+            }
+            _this.videoSeeking = true;
+            if (clearTexture) {
+                _this.material.setTexture("_MainTex", _this.engine.transparentTexture);
+            }
+            _this.video.addEventListener("seeked", function() {
+                _this.videoSeeking = false;
+                _this.isGotoAndStopSeeking = false;
+                if (clearTexture) {
+                    _this.material.setTexture("_MainTex", _this.renderer.texture);
+                }
+                if (_this.video) {
+                    _this.renderer.texture.uploadCurrentVideoFrame();
+                    // gotoAndStop 场景：seek 完成后暂停
+                    if (isGotoAndStop) {
+                        _this.video.pause();
+                    } else if (wasPlaying && !_this.manualPause) {
+                        // 如果视频之前在播放（包括 goto 前在播放），seek 完成后恢复播放
+                        _this.safePlay();
+                    }
                 }
-            } else if (rootEndBehavior === EFFECTS.spec.EndBehavior.restart) {
-                this.setCurrentTime(0);
+            }, {
+                once: true
+            });
+            _this.video.currentTime = time;
+        };
+        if (isGotoAndStop) {
+            if (wasPlaying) {
+                // 视频正在播放，直接 seek
+                doSeek();
+            } else if (isNoopSeek()) {
+                finishNoopSeek();
+            } else {
+                // 视频暂停，先 play() 再 seek
+                this.video.play().then(function() {
+                    doSeek();
+                }).catch(function() {
+                    // play 失败时也尝试 seek
+                    doSeek();
+                });
             }
+        } else {
+            if (wasPlaying) {
+                this.video.pause();
+            }
+            doSeek();
+        }
+    };
+    /**
+   * 更新视频播放速率
+   * 手动模式下保持用户设置的速率不变，自动模式下根据 engine.speed * composition.speed 计算
+   */ _proto.updatePlaybackRate = function updatePlaybackRate() {
+        // 手动模式下不自动更新速率
+        if (this.manualPlaybackRate) {
+            return;
+        }
+        if (!this.video) {
+            return;
+        }
+        var composition = this.item.composition;
+        if (!composition) {
+            return;
+        }
+        var playbackRate = this.engine.speed * composition.speed;
+        if (this.video.playbackRate !== playbackRate) {
+            this.video.playbackRate = playbackRate;
+        }
+    };
+    /**
+   * 当前 item 可播放的本地视频时间。
+   * item.time 在 delay 前为负数，视频时间需要从 0 开始。
+   */ _proto.getItemSeekTime = function getItemSeekTime() {
+        return Math.max(0, this.getItemLocalTime());
+    };
+    /**
+   * 获取 item 的本地时间。优先使用 timeline 写入的 item.time，
+   * 未写入时使用合成时间和 item delay 做兜底。
+   */ _proto.getItemLocalTime = function getItemLocalTime() {
+        if (this.item.time >= 0) {
+            return this.item.time;
+        }
+        var composition = this.item.composition;
+        if (!composition) {
+            return this.item.time;
+        }
+        var _this_item_definition_delay;
+        return composition.time - ((_this_item_definition_delay = this.item.definition.delay) != null ? _this_item_definition_delay : 0);
+    };
+    /**
+   * 将 seek 目标限制到视频有效时间范围内。
+   */ _proto.getClampedSeekTime = function getClampedSeekTime(time) {
+        var _this_video;
+        var seekTime = Math.max(0, time);
+        var duration = (_this_video = this.video) == null ? void 0 : _this_video.duration;
+        if (!duration || !isFinite(duration)) {
+            return seekTime;
         }
+        return Math.min(seekTime, duration);
+    };
+    /**
+   * 组件重新启用时将视频时间对齐到 item 本地时间，但不直接触发播放。
+   */ _proto.syncVideoToItemTime = function syncVideoToItemTime() {
+        if (!this.video) {
+            return;
+        }
+        var seekTime = this.getItemSeekTime();
+        var clampedSeekTime = this.getClampedSeekTime(seekTime);
+        if (Math.abs(this.video.currentTime - clampedSeekTime) > VideoComponent.threshold) {
+            this.pendingSeekTime = clampedSeekTime;
+        }
+    };
+    /**
+   * 当前 item 已经进入自己的时间区间，且视频允许自动播放。
+   */ _proto.canPlayCurrentItem = function canPlayCurrentItem() {
+        if (!this.video || !this.isVideoActive || this.getItemLocalTime() < 0) {
+            return false;
+        }
+        if (this.manualPause || this.videoDestroyed || this.videoSeeking || this.pendingSeekTime !== null) {
+            return false;
+        }
+        return !this.checkVideoEnded();
     };
     /**
    * 获取当前视频时长
-   * @returns 视频时长
    */ _proto.getDuration = function getDuration() {
         return this.video ? this.video.duration : 0;
     };
     /**
    * 获取当前视频播放时刻
-   * @returns 当前视频播放时刻
    */ _proto.getCurrentTime = function getCurrentTime() {
         return this.video ? this.video.currentTime : 0;
     };
     /**
    * 设置当前视频播放时刻
-   * @param time 视频播放时刻
+   * @param time 目标时间，会被限制在 [0, duration] 范围内
    */ _proto.setCurrentTime = function setCurrentTime(time) {
-        if (this.video) {
-            this.video.currentTime = time;
+        if (!this.video) {
+            return;
+        }
+        var duration = this.video.duration;
+        // 如果 duration 无效（如视频未加载），直接使用原值
+        if (!duration || !isFinite(duration)) {
+            this.pendingSeekTime = Math.max(0, time);
+            return;
         }
+        this.pendingSeekTime = Math.max(0, Math.min(time, duration));
     };
     /**
-   * 设置视频是否循环播放
+   * 设置视频是否循环播放，调用后会覆盖合成的结束行为，改为由用户手动控制循环。
+   * 调用 {@link resetLoop} 可恢复为由合成结束行为自动控制。
    * @param loop 是否循环播放
    */ _proto.setLoop = function setLoop(loop) {
+        this.manualLoop = true;
         if (this.video) {
             this.video.loop = loop;
         }
     };
     /**
+   * 重置循环播放为合成自动控制模式
+   */ _proto.resetLoop = function resetLoop() {
+        this.manualLoop = false;
+        // 将 video.loop 同步回合成应有的值，避免残留用户手动设置的状态
+        if (this.video) {
+            this.video.loop = this.item.endBehavior === EFFECTS.spec.EndBehavior.restart;
+        }
+    };
+    /**
    * 设置视频是否静音
    * @param muted 是否静音
    */ _proto.setMuted = function setMuted(muted) {
@@ -806,115 +1235,37 @@ exports.VideoComponent = /*#__PURE__*/ function(MaskableGraphic) {
         this.transparent = transparent;
     };
     /**
-   * 设置视频播放速率
+   * 设置视频播放速率，调用后会覆盖合成的速率，改为由用户手动控制速率。
+   * 调用 {@link resetPlaybackRate} 可恢复为由合成速率自动控制。
    * @param rate 视频播放速率
    */ _proto.setPlaybackRate = function setPlaybackRate(rate) {
-        if (!this.video || this.video.playbackRate === rate) {
-            return;
+        this.manualPlaybackRate = true;
+        if (this.video) {
+            this.video.playbackRate = rate;
         }
-        this.video.playbackRate = rate;
     };
     /**
-   * 播放视频
+   * 重置播放速率为合成自动控制模式
+   */ _proto.resetPlaybackRate = function resetPlaybackRate() {
+        this.manualPlaybackRate = false;
+    };
+    /**
+   * 播放视频，同时取消手动暂停状态
    * @since 2.3.0
    */ _proto.playVideo = function playVideo() {
-        var _this = this;
-        if (this.played) {
-            return;
-        }
-        if (this.video) {
-            this.played = true;
-            this.isPlayLoading = true;
-            this.pendingPause = false;
-            this.video.play().then(function() {
-                _this.isPlayLoading = false;
-                // 如果在 play pending 期间被请求了 pause，则立即暂停并复位 played
-                if (!_this.played || _this.pendingPause) {
-                    var _this_video;
-                    _this.pendingPause = false;
-                    _this.played = false;
-                    (_this_video = _this.video) == null ? void 0 : _this_video.pause();
-                }
-            }).catch(function(error) {
-                // 复位状态
-                _this.isPlayLoading = false;
-                _this.played = false;
-                _this.pendingPause = false;
-                if (error.name !== "AbortError") {
-                    _this.engine.renderErrors.add(error);
-                }
-            });
-        }
+        this.manualPause = false;
+        this.startVideo();
     };
     /**
-   * 暂停视频
+   * 手动暂停视频
    * @since 2.3.0
    */ _proto.pauseVideo = function pauseVideo() {
-        if (this.played) {
-            this.played = false;
-        }
-        if (!this.video) {
-            return;
-        }
-        if (this.isPlayLoading) {
-            this.pendingPause = true;
-            return;
-        }
-        this.video.pause();
-    };
-    _proto.onDestroy = function onDestroy() {
-        var _this_item;
-        MaskableGraphic.prototype.onDestroy.call(this);
-        // 清理播放状态
-        this.played = false;
-        this.isPlayLoading = false;
-        this.pendingPause = false;
-        this.isVideoActive = false;
-        // 清理video资源
-        if (this.video) {
-            // 暂停视频
-            this.video.pause();
-            // 移除video源，帮助垃圾回收
-            this.video.removeAttribute("src");
-            this.video.load();
-            // 清理video引用
-            this.video = undefined;
-        }
-        // 清理事件监听
-        var composition = (_this_item = this.item) == null ? void 0 : _this_item.composition;
-        if (composition) {
-            if (this.handleGoto) {
-                composition.off("goto", this.handleGoto);
-            }
-            if (this.handlePause) {
-                composition.off("pause", this.handlePause);
-            }
-            if (this.handlePlay) {
-                composition.off("play", this.handlePlay);
-            }
-        }
-        // 清理处理器引用
-        this.handleGoto = undefined;
-        this.handlePause = undefined;
-        this.handlePlay = undefined;
-    };
-    _proto.onDisable = function onDisable() {
-        MaskableGraphic.prototype.onDisable.call(this);
-        this.isVideoActive = false;
-        this.pauseVideo();
-    };
-    _proto.onEnable = function onEnable() {
-        MaskableGraphic.prototype.onEnable.call(this);
-        this.isVideoActive = true;
-        this.played = false;
-        // 重播时确保视频同步到当前时间
-        if (this.video && this.item.composition) {
-            this.setCurrentTime(Math.max(0, this.item.time));
-        }
-        this.playVideo();
+        this.manualPause = true;
+        this.pauseVideoElement();
     };
     return VideoComponent;
 }(EFFECTS.MaskableGraphic);
+exports.VideoComponent.threshold = 0.01;
 exports.VideoComponent = __decorate([
     EFFECTS.effectsClass(EFFECTS.spec.DataType.VideoComponent)
 ], exports.VideoComponent);
@@ -1258,7 +1609,7 @@ exports.AudioComponent = __decorate([
 
 /**
  * 插件版本号
- */ var version = "2.9.0-alpha.2";
+ */ var version = "2.9.1-beta.0";
 EFFECTS.registerPlugin("video", VideoLoader);
 EFFECTS.registerPlugin("audio", AudioLoader);
 EFFECTS.logger.info("Plugin multimedia version: " + version + ".");