@twick/2d 0.15.16 → 0.15.18

package/dist/index.d.cts

@@ -58,6 +58,10 @@ interface MediaProps extends RectProps {
     play?: boolean;
     awaitCanPlay?: SignalValue<boolean>;
     allowVolumeAmplificationInPreview?: SignalValue<boolean>;
+    /** Timeline time when this clip starts; when set, syncToCurrentTime(globalTime) uses clip-relative time. */
+    clipStart?: number;
+    /** Start offset in the media file (e.g. trim); used with clipStart for sync. */
+    trimStart?: number;
 }
 declare abstract class Media extends Rect {
     readonly src: SimpleSignal<string, this>;
@@ -75,6 +79,10 @@ declare abstract class Media extends Rect {
     }>;
     protected lastTime: number;
     private isSchedulingPlay;
+    /** When set, syncToCurrentTime(globalTime) converts to clip-relative time. */
+    protected clipStart: number | undefined;
+    /** Used with clipStart for sync (trim offset in source). */
+    protected trimStart: number;
     constructor(props: MediaProps);
     isPlaying(): boolean;
     getCurrentTime(): number;
@@ -86,8 +94,23 @@ declare abstract class Media extends Rect {
     protected abstract mediaElement(): HTMLMediaElement;
     protected abstract seekedMedia(): HTMLMediaElement;
     protected abstract fastSeekedMedia(): HTMLMediaElement;
+    /**
+     * Sync the underlying media element to the given time (e.g. draw/playback time).
+     * Used for both Video and Audio. When `time` is passed (e.g. from Scene2D.draw), that
+     * value is used so sync does not depend on the node's time signal.
+     * If this node has clipStart set, global time is converted to clip-relative time:
+     * syncTime = trimStart + (time - clipStart) * playbackRate.
+     * When omitted, falls back to this.time().
+     * When waitForSeek is true, returns a promise that resolves when the seek completes so
+     * the draw can wait and show the correct frame/sample when paused.
+     */
+    syncToCurrentTime(time?: number, options?: {
+        waitForSeek?: boolean;
+    }): void | Promise<void>;
     protected abstract draw(context: CanvasRenderingContext2D): Promise<void>;
-    protected setCurrentTime(value: number): void;
+    protected setCurrentTime(value: number, options?: {
+        skipCollectPromise?: boolean;
+    }): Promise<void>;
     setVolume(volume: number): void;
     protected amplify(node: HTMLMediaElement, volume: number): void;
     protected setPlaybackRate(playbackRate: number): void;
@@ -2528,6 +2551,12 @@ declare class Scene2D extends GeneratorScene<View2D> implements Inspectable {
     getNode(key: any): Node | null;
     getDetachedNodes(): Generator<Node, void, unknown>;
     getMediaAssets(): Array<AssetInfo>;
+    /**
+     * Seek all registered Media nodes (Video and Audio) to the current playback time.
+     * Passes draw time; nodes with clipStart convert it to clip-relative time.
+     * When waitForSeek is true, waits for each media seek to complete so the next draw shows the correct frame/sample.
+     */
+    private syncAllMediaToCurrentTime;
     stopAllMedia(): void;
     adjustVolume(volumeScale: number): void;
     protected recreateView(): void;

package/dist/index.d.ts

@@ -58,6 +58,10 @@ interface MediaProps extends RectProps {
     play?: boolean;
     awaitCanPlay?: SignalValue<boolean>;
     allowVolumeAmplificationInPreview?: SignalValue<boolean>;
+    /** Timeline time when this clip starts; when set, syncToCurrentTime(globalTime) uses clip-relative time. */
+    clipStart?: number;
+    /** Start offset in the media file (e.g. trim); used with clipStart for sync. */
+    trimStart?: number;
 }
 declare abstract class Media extends Rect {
     readonly src: SimpleSignal<string, this>;
@@ -75,6 +79,10 @@ declare abstract class Media extends Rect {
     }>;
     protected lastTime: number;
     private isSchedulingPlay;
+    /** When set, syncToCurrentTime(globalTime) converts to clip-relative time. */
+    protected clipStart: number | undefined;
+    /** Used with clipStart for sync (trim offset in source). */
+    protected trimStart: number;
     constructor(props: MediaProps);
     isPlaying(): boolean;
     getCurrentTime(): number;
@@ -86,8 +94,23 @@ declare abstract class Media extends Rect {
     protected abstract mediaElement(): HTMLMediaElement;
     protected abstract seekedMedia(): HTMLMediaElement;
     protected abstract fastSeekedMedia(): HTMLMediaElement;
+    /**
+     * Sync the underlying media element to the given time (e.g. draw/playback time).
+     * Used for both Video and Audio. When `time` is passed (e.g. from Scene2D.draw), that
+     * value is used so sync does not depend on the node's time signal.
+     * If this node has clipStart set, global time is converted to clip-relative time:
+     * syncTime = trimStart + (time - clipStart) * playbackRate.
+     * When omitted, falls back to this.time().
+     * When waitForSeek is true, returns a promise that resolves when the seek completes so
+     * the draw can wait and show the correct frame/sample when paused.
+     */
+    syncToCurrentTime(time?: number, options?: {
+        waitForSeek?: boolean;
+    }): void | Promise<void>;
     protected abstract draw(context: CanvasRenderingContext2D): Promise<void>;
-    protected setCurrentTime(value: number): void;
+    protected setCurrentTime(value: number, options?: {
+        skipCollectPromise?: boolean;
+    }): Promise<void>;
     setVolume(volume: number): void;
     protected amplify(node: HTMLMediaElement, volume: number): void;
     protected setPlaybackRate(playbackRate: number): void;
@@ -2528,6 +2551,12 @@ declare class Scene2D extends GeneratorScene<View2D> implements Inspectable {
     getNode(key: any): Node | null;
     getDetachedNodes(): Generator<Node, void, unknown>;
     getMediaAssets(): Array<AssetInfo>;
+    /**
+     * Seek all registered Media nodes (Video and Audio) to the current playback time.
+     * Passes draw time; nodes with clipStart convert it to clip-relative time.
+     * When waitForSeek is true, waits for each media seek to complete so the next draw shows the correct frame/sample.
+     */
+    private syncAllMediaToCurrentTime;
     stopAllMedia(): void;
     adjustVolume(volumeScale: number): void;
     protected recreateView(): void;

package/dist/index.js

@@ -5401,13 +5401,17 @@ var Media = class extends Rect {
     super(props);
     this.lastTime = -1;
     this.isSchedulingPlay = false;
+    /** Used with clipStart for sync (trim offset in source). */
+    this.trimStart = 0;
     if (!this.awaitCanPlay()) {
-      this.scheduleSeek(this.time());
+      setTimeout(() => this.scheduleSeek(this.time()), 0);
     }
     if (props.play) {
       this.play();
     }
     this.volume = props.volume ?? 1;
+    this.clipStart = props.clipStart;
+    this.trimStart = props.trimStart ?? 0;
     if (!this.awaitCanPlay()) {
       this.setVolume(this.volume);
     }
@@ -5447,25 +5451,72 @@ var Media = class extends Rect {
   completion() {
     return this.clampTime(this.time()) / this.getDuration();
   }
-  setCurrentTime(value) {
+  /**
+   * Sync the underlying media element to the given time (e.g. draw/playback time).
+   * Used for both Video and Audio. When `time` is passed (e.g. from Scene2D.draw), that
+   * value is used so sync does not depend on the node's time signal.
+   * If this node has clipStart set, global time is converted to clip-relative time:
+   * syncTime = trimStart + (time - clipStart) * playbackRate.
+   * When omitted, falls back to this.time().
+   * When waitForSeek is true, returns a promise that resolves when the seek completes so
+   * the draw can wait and show the correct frame/sample when paused.
+   */
+  syncToCurrentTime(time, options) {
+    let syncTime;
+    if (time !== void 0 && this.clipStart !== void 0) {
+      syncTime = this.trimStart + (time - this.clipStart) * this.playbackRate();
+    } else {
+      syncTime = time ?? this.time();
+    }
+    const promise = this.setCurrentTime(syncTime, {
+      skipCollectPromise: options?.waitForSeek ?? true
+    });
+    if (options?.waitForSeek) {
+      return promise;
+    }
+  }
+  setCurrentTime(value, options) {
     try {
       const media = this.mediaElement();
-      if (media.readyState < 2) return;
-      media.currentTime = value;
-      this.lastTime = value;
-      if (media.seeking) {
-        DependencyContext4.collectPromise(
-          new Promise((resolve) => {
-            const listener = () => {
+      const key = this.key ?? "media";
+      if (media.readyState < 2) {
+        this.lastTime = value;
+        this.time(value);
+        return new Promise((resolve) => {
+          this.waitForCanPlay(media, () => {
+            media.currentTime = value;
+            this.lastTime = value;
+            this.time(value);
+            const onSeeked = () => {
+              media.removeEventListener("seeked", onSeeked);
               resolve();
-              media.removeEventListener("seeked", listener);
             };
-            media.addEventListener("seeked", listener);
-          })
-        );
+            if (media.seeking) {
+              media.addEventListener("seeked", onSeeked);
+            } else {
+              resolve();
+            }
+          });
+        });
+      }
+      media.currentTime = value;
+      this.lastTime = value;
+      this.time(value);
+      const seekPromise = media.seeking ? new Promise((resolve) => {
+        const listener = () => {
+          resolve();
+          media.removeEventListener("seeked", listener);
+        };
+        media.addEventListener("seeked", listener);
+      }) : Promise.resolve();
+      if (media.seeking && !options?.skipCollectPromise) {
+        DependencyContext4.collectPromise(seekPromise);
       }
+      return seekPromise;
     } catch (error) {
       this.lastTime = value;
+      this.time(value);
+      return Promise.resolve();
     }
   }
   setVolume(volume) {
@@ -10397,11 +10448,13 @@ var Video = class extends Media {
   fastSeekedVideo() {
     const video = this.video();
     const time = this.clampTime(this.time());
+    const playing = this.playing() && time < video.duration && video.playbackRate > 0;
+    const wouldResetToZero = time < 0.5 && video.currentTime > 1 && Math.abs(video.currentTime - this.lastTime) < 0.5;
+    const outOfSyncBig = Math.abs(video.currentTime - time) > 1;
     video.playbackRate = this.playbackRate();
     if (this.lastTime === time) {
       return video;
     }
-    const playing = this.playing() && time < video.duration && video.playbackRate > 0;
     if (playing) {
       if (video.paused) {
         DependencyContext8.collectPromise(video.play());
@@ -10411,10 +10464,11 @@ var Video = class extends Media {
         video.pause();
       }
     }
-    if (Math.abs(video.currentTime - time) > 1) {
+    if (wouldResetToZero) {
+    } else if (outOfSyncBig) {
       this.setCurrentTime(time);
     } else if (!playing) {
-      video.currentTime = time;
+      this.setCurrentTime(time);
     }
     return video;
   }
@@ -10641,6 +10695,9 @@ var Scene2D = class extends GeneratorScene {
     context.save();
     this.renderLifecycle.dispatch([SceneRenderEvent.BeginRender, context]);
     this.getView().playbackState(this.playback.state).globalTime(this.playback.time).fps(this.playback.fps);
+    if (this.playback.state === PlaybackState5.Paused) {
+      await this.syncAllMediaToCurrentTime(true);
+    }
     await this.getView().render(context);
     this.renderLifecycle.dispatch([SceneRenderEvent.FinishRender, context]);
     context.restore();
@@ -10771,6 +10828,34 @@ var Scene2D = class extends GeneratorScene {
     );
     return returnObjects;
   }
+  /**
+   * Seek all registered Media nodes (Video and Audio) to the current playback time.
+   * Passes draw time; nodes with clipStart convert it to clip-relative time.
+   * When waitForSeek is true, waits for each media seek to complete so the next draw shows the correct frame/sample.
+   */
+  async syncAllMediaToCurrentTime(waitForSeek) {
+    const drawTime = this.playback.time;
+    const mediaNodes = Array.from(this.registeredNodes.values()).filter(
+      (node) => node instanceof Media
+    );
+    const results = mediaNodes.map((media) => {
+      try {
+        return media.syncToCurrentTime(drawTime, { waitForSeek });
+      } catch (e) {
+        this.logger.warn({
+          message: `syncAllMediaToCurrentTime: skipped node ${media.key ?? "unknown"}`,
+          object: e
+        });
+        return void 0;
+      }
+    });
+    if (waitForSeek) {
+      const promises = results.filter(
+        (p) => p !== void 0
+      );
+      await Promise.all(promises);
+    }
+  }
   stopAllMedia() {
     const playingMedia = Array.from(this.registeredNodes.values()).filter((node) => node instanceof Media).filter((video) => video.isPlaying());
     for (const media of playingMedia) {