@music-lyric-player/base 0.9.0 → 0.12.0

package/dist/index.ecma.d.ts

@@ -1,25 +1,30 @@
 import { ConfigManager } from '@music-lyric-player/utils';
+import { DeepRequired } from '@music-lyric-player/utils';
 import { Event as Event_2 } from '@music-lyric-player/utils';
-import { Info } from '@music-lyric-kit/lyric';
-import { Line } from '@music-lyric-kit/lyric';
+import { Lyric } from '@music-lyric-kit/lyric';
+import { NestedKeys } from '@music-lyric-player/utils';
 
 export declare class BaseLyricPlayer {
-    readonly config: ConfigManager<Options, {
-        driver?: "timer" | "animation" | undefined;
-    }, "driver">;
+    readonly config: BaseLyricPlayerConfig.RootManager;
     readonly event: Event_2<BaseLyricPlayerEventMap>;
     private state;
     private active;
     private time;
+    private offset;
     private info;
     constructor();
+    private onConfigUpdate;
     private handleGetCurrentTime;
+    private handleGetEffectiveTime;
+    private handleRefreshOffset;
     private handleGetLineTime;
     private handleGetActiveIndex;
+    private handleBridgeActive;
+    private handleEmitLinesUpdate;
     private handleSyncTime;
     private handleUpdateActiveLines;
     private onTick;
-    updateLyric(info: Info): void;
+    updateLyric(info: Lyric.Info): void;
     /**
      * Start playback
      * @param time Optional time in ms to seek to before starting playback. If not provided, playback will start from the current position.
@@ -33,14 +38,27 @@ export declare class BaseLyricPlayer {
      * Stop playback
      */
     dispose(): void;
+    /**
+     * Update the temp offset in ms (the user's temporary adjustment).
+     * Stacked on top of the global config offset and the lyric's meta offset, then resyncs immediately.
+     * @param value temp offset in ms; non-finite values are treated as 0.
+     */
+    updateTempOffset(value: number): void;
     /**
      * Find all active lines at the given time (ms). Does not mutate internal state.
+     * Assumes `info.lines` is sorted by `time.start` ascending.
      * @param time time in ms to find active lines for.
      */
     matchLinesWithTime(time: number): {
-        lines: Line[];
+        lines: Lyric.Line[];
         index: number[];
     };
+    /**
+     * Convert a content (lyric) time to the playback clock by removing the active offset.
+     * Seeking playback to the returned time makes a line at `contentTime` become active.
+     * @param contentTime content time in ms (e.g. a line's start).
+     */
+    convertContentTime(contentTime: number): number;
     /**
      * Whether the player is currently playing.
      */
@@ -48,7 +66,7 @@ export declare class BaseLyricPlayer {
     /**
      * Current active lines.
      */
-    get currentLines(): Line[];
+    get currentLines(): Lyric.Line[];
     /**
      * Indices of currently active lines.
      */
@@ -60,11 +78,27 @@ export declare class BaseLyricPlayer {
     /**
      * The current lyric info object.
      */
-    get currentInfo(): Info;
+    get currentInfo(): Lyric.Info;
     /**
      * The current playback time in ms.
      */
     get currentTime(): number;
+    /**
+     * The current effective lyric offset in ms (config offset + lyric meta offset + temp offset).
+     */
+    get currentOffset(): number;
+}
+
+export declare namespace BaseLyricPlayerConfig {
+    export {
+        Offset,
+        Root,
+        RootRequired,
+        RootKeys,
+        RootKeySet,
+        RootManager,
+        DEFAULT
+    }
 }
 
 export declare interface BaseLyricPlayerEventMap {
@@ -82,7 +116,7 @@ export declare interface BaseLyricPlayerEventMap {
      * When the entire lyric information is updated (e.g., loading a new lyric/song).
      * @param info The newly loaded lyric information object.
      */
-    lyricUpdate: (info: Info) => void;
+    lyricUpdate: (info: Lyric.Info) => void;
     /**
      * When the currently active lyric lines change during playback.
      * @param lines An array of the currently active lyric lines.
@@ -90,17 +124,75 @@ export declare interface BaseLyricPlayerEventMap {
      * @param firstIndex The index of the first currently active lyric line (-1 if none).
      * @param isSeek Is seek.
      */
-    linesUpdate: (lines: Line[], indexs: number[], index: number, isSeek: boolean) => void;
+    linesUpdate: (lines: Lyric.Line[], indexs: number[], index: number, isSeek: boolean) => void;
 }
 
-declare interface Options {
+declare const DEFAULT: Root;
+
+declare interface Offset {
+    /**
+     * Global offset in ms, applied to every song.
+     *
+     * @default 0
+     */
+    global?: number;
+    /**
+     * Whether to apply the offset carried by the lyric's own meta (`MetaType.Offset`).
+     *
+     * @default true
+     */
+    useMeta?: boolean;
+    /**
+     * Whether loading a new lyric via `updateLyric` resets the temp offset (set via `updateTempOffset`) back to 0.
+     *
+     * @default true
+     */
+    resetTempOnLyricChange?: boolean;
+}
+
+declare interface Root {
     /**
      * Driver type for playback scheduling.
      * - `animation`: use requestAnimationFrame
      * - `timer`: use setTimeout
-     * @default animation
+     *
+     * @default 'animation'
+     */
+    driver?: 'timer' | 'animation';
+    /**
+     * Whether to bridge gaps between simultaneously active lines.
+     *
+     * Active lines may not be consecutive — a line in the middle could have already ended (`played`) while its neighbors are still active, producing a `[active, played, active]` pattern.
+     *
+     * Enabling this promotes the sandwiched lines back to active so the visual reads as one continuous `[active, active, active]` block.
+     *
+     * @default true
      */
-    driver: 'timer' | 'animation';
+    bridgeActive?: boolean;
+    /**
+     * Lyric time offset settings.
+     */
+    offset?: Offset;
 }
 
+/**
+ * All config keys
+ */
+declare type RootKeys = NestedKeys<Root>;
+
+/**
+ * Set of config key paths that changed since the previous value, as emitted by `ConfigManager.event['update']`.
+ */
+declare type RootKeySet = Set<RootKeys>;
+
+/**
+ * Runtime config manager bound to this module's {@link Config} shape.
+ */
+declare type RootManager = ConfigManager<RootRequired, Root>;
+
+/**
+ * Fully‑resolved config in which every field is required, produced by deep‑requiring the user‑facing {@link Config}.
+ */
+declare type RootRequired = DeepRequired<Root>;
+
 export { }