narraleaf-react 0.21.1 → 0.22.0

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

@@ -44,7 +44,8 @@ export interface ISoundUserConfig {
      *
      * 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.
+     * rather than just a starting offset — unless {@link ISoundUserConfig.loopStart} moves the
+     * repeat's in point somewhere else.
      * @default 0
      */
     seek: number;
@@ -53,15 +54,35 @@ export interface ISoundUserConfig {
      * 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.
+     * {@link ISoundUserConfig.loopStart}, or to {@link ISoundUserConfig.seek} when no loop in point
+     * was given — 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;
+    /**
+     * Position in seconds the clip returns to on every repeat — the **loop in point**.
+     *
+     * Only meaningful together with `loop` and {@link ISoundUserConfig.endTime}: it is the start of
+     * the region that repeats, while {@link ISoundUserConfig.seek} stays the position the *first*
+     * pass begins at. Leaving it out makes each repeat return to `seek`, which is the behaviour of
+     * a clip that has no separate intro.
+     *
+     * Separating the two is what expresses the standard "intro then loop" piece of background
+     * music — play from the top once, then repeat only the body forever:
+     *
+     * ```ts
+     * Sound.bgm({src: "theme.mp3", loop: true, seek: 0, loopStart: 12, endTime: 90});
+     * ```
+     *
+     * A value outside `[seek, endTime)` describes no playable region and falls back to `seek`.
+     * @default undefined
+     */
+    loopStart?: number;
     /**
      * The type of the sound
      * @default SoundType.Sound
@@ -97,6 +118,14 @@ export declare class Sound extends Actionable<SoundDataRaw, Sound> {
     constructor(arg0: Partial<ISoundUserConfig> | string);
     /**
      * Start playing the sound and wait for it to finish.
+     *
+     * A clip of any {@link SoundType} may be played this way. `type` selects which volume slider
+     * governs the clip and nothing else, so putting an ambience track on `bgm` so the player's music
+     * slider controls it, and then playing it from an ordinary line, is a legitimate thing to want.
+     *
+     * It is *not* the same as {@link Scene.setBackgroundMusic}: a clip played here is not in the
+     * scene's background-music slot, so leaving the scene will not stop it and no cross-fade is
+     * arranged for it. That is true of every clip played this way, on any bus.
      * @param duration - Optional fade duration in milliseconds.
      * @chainable
      * @example

package/dist/game/nlcore/game/liveGame.d.ts

@@ -128,6 +128,14 @@ export declare class LiveGame {
     notify(message: string, duration?: number | null): NotificationToken;
     /**
      * Play a sound immediately and return the SoundToken.
+     *
+     * The clip starts at the volume its {@link Sound} was configured with — `Sound.voice({src, volume:
+     * 0.4})` starts at 0.4, not at full volume. There is no fade: the token's volume is already
+     * settled when this resolves and no ramp is left running, so a `setVolume` or a fade driven on
+     * the returned token afterwards wins outright.
+     *
+     * A source given as a string or `URL` becomes a default `Sound`, which is full volume — pass a
+     * `Sound` to say otherwise.
      */
     playSound(sound: Sound | string | URL): Promise<SoundToken>;
     /**

package/dist/game/player/elements/scene/backgroundMusic.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -28,7 +28,28 @@ export declare class AudioManager {
      * Doing it here avoids "AudioContext is not defined" on the server.
      */
     initialize(): void;
+    /**
+     * The volume a clip started with no explicit target should reach.
+     *
+     * Full volume was never a sensible default here: a `Sound` carries the volume it was configured
+     * with, so a caller that says nothing about volume is asking for *that*, not for 1. Reading
+     * `state` rather than the user config is deliberate - it is the same value {@link SoundElement.play}
+     * and {@link SoundElement.resume} put in their `FadeOptions`, so a clip replayed after
+     * {@link AudioManager.setVolume} comes back at the volume it was last set to instead of jumping
+     * back to whatever the author first wrote down.
+     */
+    private static defaultFade;
     play(sound: SoundElement, options?: FadeOptions): Awaitable<void>;
+    /**
+     * Start a clip and hand the token back once playback is under way.
+     *
+     * With no `duration` the target volume is written to the token *synchronously* before this
+     * returns, and nothing is left running: no gain automation is in flight when the caller gets the
+     * token. That is what makes an explicit `token.setVolume` or a fade the caller drives itself
+     * afterwards the last writer, which several hosts rely on. Defaulting `duration` to anything
+     * above 0 would break that - `token.fade` below is deliberately not awaited, so a non-zero
+     * default would leave a ramp running past the return and over whatever the caller did next.
+     */
     playSoundToken(sound: SoundElement, options?: FadeOptions): Promise<SoundToken>;
     stop(sound: SoundElement, duration?: number): Awaitable<void>;
     setVolume(sound: SoundElement, volume: number, duration?: number): Awaitable<void>;
@@ -42,13 +63,51 @@ export declare class AudioManager {
      */
     seek(sound: SoundElement, time: number): Awaitable<void>;
     /**
-     * The in/out points of a clip as the sound backend's play options.
+     * The in/out points of a clip.
      *
      * `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;
+    /**
+     * The region as the sound backend's play options.
+     *
+     * A looping clip deliberately hands over **no** `endTime`. The backend turns `endTime` into a
+     * timer that stops the token after one pass, whether or not the clip loops, so passing it here
+     * is what kept the loop region from ever repeating. The region reaches a looping clip through
+     * {@link AudioManager.applyLoopRegion} instead; for a one-shot `endTime` *is* the out point and
+     * the backend's timer is exactly the right mechanism.
+     */
+    private static playRegionOf;
+    /**
+     * Write a looping clip's region onto the Web Audio node the backend is playing it through.
+     *
+     * **This is a shim against `@narraleaf/sound@0.1.0`'s internals, and the only place in this
+     * repo that reaches into them.** Two things in that version make the region unusable from the
+     * outside:
+     *
+     * - `SoundToken`'s constructor arms `setTimeout(stop, duration * 1000)` whenever a duration was
+     *   given, without consulting `loop` — so a looping clip with an out point hard-stops after its
+     *   first pass through the region.
+     * - `Sound.createToken` pins `loopStart` to the playback start offset, so "play the intro from
+     *   0s, then repeat 12s→90s forever" cannot be expressed at all.
+     *
+     * The fix belongs upstream and is small: honour `loop` before arming the duration timer, and
+     * accept an independent `loopStart` in `PlayOptions`. Until that ships, this manager withholds
+     * `endTime` from a looping clip's play options (which is what disarms the timer) and sets the
+     * loop region here.
+     *
+     * `SoundToken.sourceController` is TypeScript-`private` while `AudioSourceController.getSource`
+     * is public, so the node is reachable at runtime but not through the types — hence the cast and
+     * the shape check. If a later backend changes that shape this returns silently and the clip
+     * degrades to the behaviour it has today: the region plays once and the clip stops.
+     *
+     * Seeking survives this. `SoundToken.seek` rebuilds the buffer source and copies `loop`,
+     * `loopStart` and `loopEnd` off the old node onto the new one, so a jump inside a looping track
+     * keeps the region.
+     */
+    private static applyLoopRegion;
     private static clampToRegion;
     setRate(sound: SoundElement, rate: number): Awaitable<void>;
     getPosition(sound: SoundElement): number;