narraleaf-react 0.20.0 → 0.21.0

package/dist/game/nlcore/action/actionTypes.d.ts

@@ -98,9 +98,10 @@ export declare const SoundActionTypes: {
     readonly pause: "sound:pause";
     readonly resume: "sound:resume";
     readonly mute: "sound:mute";
+    readonly seek: "sound:seek";
 };
 export type SoundActionContentType = {
-    [K in typeof SoundActionTypes[keyof typeof SoundActionTypes]]: K extends "sound:play" ? [FadeOptions] : K extends "sound:stop" ? [FadeOptions] : K extends "sound:setVolume" ? [volume: number, duration: number] : K extends "sound:setRate" ? [number] : K extends "sound:pause" ? [FadeOptions] : K extends "sound:resume" ? [FadeOptions] : K extends "sound:mute" ? [boolean] : any;
+    [K in typeof SoundActionTypes[keyof typeof SoundActionTypes]]: K extends "sound:play" ? [FadeOptions] : K extends "sound:stop" ? [FadeOptions] : K extends "sound:setVolume" ? [volume: number, duration: number] : K extends "sound:setRate" ? [number] : K extends "sound:pause" ? [FadeOptions] : K extends "sound:resume" ? [FadeOptions] : K extends "sound:mute" ? [boolean] : K extends "sound:seek" ? [time: number] : any;
 };
 export declare const ControlActionTypes: {
     readonly action: "control:action";

package/dist/game/nlcore/action/actions/soundAction.d.ts

@@ -15,6 +15,7 @@ export declare class SoundAction<T extends typeof SoundActionTypes[keyof typeof
         readonly pause: "sound:pause";
         readonly resume: "sound:resume";
         readonly mute: "sound:mute";
+        readonly seek: "sound:seek";
     };
     executeAction(state: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
     stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;

package/dist/game/nlcore/elements/sound.d.ts

@@ -40,10 +40,28 @@ export interface ISoundUserConfig {
      */
     streaming: boolean;
     /**
-     * Initial position in seconds
+     * Initial position in seconds - the clip's **in point**.
+     *
+     * When {@link ISoundUserConfig.loop} is set together with {@link ISoundUserConfig.endTime},
+     * this is also where each repeat restarts from, so the two together describe a loop region
+     * rather than just a starting offset.
      * @default 0
      */
     seek: number;
+    /**
+     * Position in seconds where the clip ends - its **out point**. Omit (or `undefined`) to play
+     * through to the end of the file.
+     *
+     * Without `loop` the clip simply stops there. With `loop` it jumps back to
+     * {@link ISoundUserConfig.seek}, which is how a piece of background music with an intro loops
+     * only its body. The jump is sample-accurate (it is the Web Audio node's own loop), so there is
+     * no gap and no drift over long sessions.
+     *
+     * Ignored for a clip that is streamed rather than decoded: an `<audio>` element has no loop
+     * region, only a plain repeat.
+     * @default undefined
+     */
+    endTime?: number;
     /**
      * The type of the sound
      * @default SoundType.Sound
@@ -133,6 +151,20 @@ export declare class Sound extends Actionable<SoundDataRaw, Sound> {
      * @chainable
      */
     resume(duration?: number): ChainedSound;
+    /**
+     * Jump to a position in the clip, in seconds, and keep playing from there.
+     *
+     * A no-op on a sound that is not currently playing - there is nothing to move. The loop region
+     * (see {@link ISoundUserConfig.endTime}) survives the jump, so seeking inside a looping track
+     * does not turn it into a one-shot.
+     * @param time - Position in seconds, measured from the start of the file (not from the in point).
+     * @chainable
+     * @example
+     * ```ts
+     * sound.seek(30);
+     * ```
+     */
+    seek(time: number): ChainedSound;
     /**
      * Create a sound with the same configuration
      */

package/dist/game/player/lib/AudioManager.d.ts

@@ -35,6 +35,21 @@ export declare class AudioManager {
     mute(sound: SoundElement, muted?: boolean): Awaitable<void>;
     pause(sound: SoundElement, duration?: number): Awaitable<void>;
     resume(sound: SoundElement, duration?: number): Awaitable<void>;
+    /**
+     * Move the play head of a sound that is currently playing. A sound this manager is not holding
+     * has no play head to move, so this is a no-op rather than an error - the same shape every other
+     * transport method here takes.
+     */
+    seek(sound: SoundElement, time: number): Awaitable<void>;
+    /**
+     * The in/out points of a clip as the sound backend's play options.
+     *
+     * `endTime` is left off entirely when the author set none: passing `undefined` explicitly is the
+     * same thing to the backend, but omitting it keeps `{...region}` spreads from writing a key that
+     * reads as "there is a region here" to anything inspecting the object.
+     */
+    private static clipRegionOf;
+    private static clampToRegion;
     setRate(sound: SoundElement, rate: number): Awaitable<void>;
     getPosition(sound: SoundElement): number;
     isPlaying(sound: SoundElement): boolean;