@twick/2d 0.15.17 → 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;
@@ -88,16 +96,21 @@ declare abstract class Media extends Rect {
     protected abstract fastSeekedMedia(): HTMLMediaElement;
     /**
      * Sync the underlying media element to the given time (e.g. draw/playback time).
-     * When `time` is passed (e.g. from Scene2D.draw), that value is used so sync
-     * does not depend on the node's time signal (which may only update on projectData change).
+     * 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().
-     * Uses skipCollectPromise so we don't leave a promise in DependencyContext.
+     * 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): void;
+    syncToCurrentTime(time?: number, options?: {
+        waitForSeek?: boolean;
+    }): void | Promise<void>;
     protected abstract draw(context: CanvasRenderingContext2D): Promise<void>;
     protected setCurrentTime(value: number, options?: {
         skipCollectPromise?: boolean;
-    }): void;
+    }): Promise<void>;
     setVolume(volume: number): void;
     protected amplify(node: HTMLMediaElement, volume: number): void;
     protected setPlaybackRate(playbackRate: number): void;
@@ -2539,8 +2552,9 @@ declare class Scene2D extends GeneratorScene<View2D> implements Inspectable {
     getDetachedNodes(): Generator<Node, void, unknown>;
     getMediaAssets(): Array<AssetInfo>;
     /**
-     * Seek all registered Media nodes to the current playback time.
-     * Passes draw time (playback.time) so media sync does not depend on node time signal.
+     * 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;

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;
@@ -88,16 +96,21 @@ declare abstract class Media extends Rect {
     protected abstract fastSeekedMedia(): HTMLMediaElement;
     /**
      * Sync the underlying media element to the given time (e.g. draw/playback time).
-     * When `time` is passed (e.g. from Scene2D.draw), that value is used so sync
-     * does not depend on the node's time signal (which may only update on projectData change).
+     * 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().
-     * Uses skipCollectPromise so we don't leave a promise in DependencyContext.
+     * 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): void;
+    syncToCurrentTime(time?: number, options?: {
+        waitForSeek?: boolean;
+    }): void | Promise<void>;
     protected abstract draw(context: CanvasRenderingContext2D): Promise<void>;
     protected setCurrentTime(value: number, options?: {
         skipCollectPromise?: boolean;
-    }): void;
+    }): Promise<void>;
     setVolume(volume: number): void;
     protected amplify(node: HTMLMediaElement, volume: number): void;
     protected setPlaybackRate(playbackRate: number): void;
@@ -2539,8 +2552,9 @@ declare class Scene2D extends GeneratorScene<View2D> implements Inspectable {
     getDetachedNodes(): Generator<Node, void, unknown>;
     getMediaAssets(): Array<AssetInfo>;
     /**
-     * Seek all registered Media nodes to the current playback time.
-     * Passes draw time (playback.time) so media sync does not depend on node time signal.
+     * 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;

package/dist/index.js

@@ -5401,6 +5401,8 @@ 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()) {
       setTimeout(() => this.scheduleSeek(this.time()), 0);
     }
@@ -5408,6 +5410,8 @@ var Media = class extends Rect {
       this.play();
     }
     this.volume = props.volume ?? 1;
+    this.clipStart = props.clipStart;
+    this.trimStart = props.trimStart ?? 0;
     if (!this.awaitCanPlay()) {
       this.setVolume(this.volume);
     }
@@ -5449,14 +5453,27 @@ var Media = class extends Rect {
   }
   /**
    * Sync the underlying media element to the given time (e.g. draw/playback time).
-   * When `time` is passed (e.g. from Scene2D.draw), that value is used so sync
-   * does not depend on the node's time signal (which may only update on projectData change).
+   * 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().
-   * Uses skipCollectPromise so we don't leave a promise in DependencyContext.
+   * 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) {
-    const syncTime = time ?? this.time();
-    this.setCurrentTime(syncTime, { skipCollectPromise: true });
+  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 {
@@ -5465,30 +5482,41 @@ var Media = class extends Rect {
       if (media.readyState < 2) {
         this.lastTime = value;
         this.time(value);
-        this.waitForCanPlay(media, () => {
-          media.currentTime = value;
-          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();
+            };
+            if (media.seeking) {
+              media.addEventListener("seeked", onSeeked);
+            } else {
+              resolve();
+            }
+          });
         });
-        return;
       }
       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(
-          new Promise((resolve) => {
-            const listener = () => {
-              resolve();
-              media.removeEventListener("seeked", listener);
-            };
-            media.addEventListener("seeked", listener);
-          })
-        );
+        DependencyContext4.collectPromise(seekPromise);
       }
+      return seekPromise;
     } catch (error) {
       this.lastTime = value;
       this.time(value);
+      return Promise.resolve();
     }
   }
   setVolume(volume) {
@@ -10668,7 +10696,7 @@ var Scene2D = class extends GeneratorScene {
     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) {
-      this.syncAllMediaToCurrentTime();
+      await this.syncAllMediaToCurrentTime(true);
     }
     await this.getView().render(context);
     this.renderLifecycle.dispatch([SceneRenderEvent.FinishRender, context]);
@@ -10801,23 +10829,31 @@ var Scene2D = class extends GeneratorScene {
     return returnObjects;
   }
   /**
-   * Seek all registered Media nodes to the current playback time.
-   * Passes draw time (playback.time) so media sync does not depend on node time signal.
+   * 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.
    */
-  syncAllMediaToCurrentTime() {
+  async syncAllMediaToCurrentTime(waitForSeek) {
     const drawTime = this.playback.time;
     const mediaNodes = Array.from(this.registeredNodes.values()).filter(
       (node) => node instanceof Media
     );
-    for (const media of mediaNodes) {
+    const results = mediaNodes.map((media) => {
       try {
-        media.syncToCurrentTime(drawTime);
+        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() {