@music-lyric-player/base 0.10.0 → 0.12.0

package/dist/index.ecma.d.ts

@@ -1,8 +1,7 @@
 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 {
@@ -11,9 +10,13 @@ export declare class BaseLyricPlayer {
     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;
@@ -21,7 +24,7 @@ export declare class BaseLyricPlayer {
     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.
@@ -35,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.
      */
@@ -50,7 +66,7 @@ export declare class BaseLyricPlayer {
     /**
      * Current active lines.
      */
-    get currentLines(): Line[];
+    get currentLines(): Lyric.Line[];
     /**
      * Indices of currently active lines.
      */
@@ -62,15 +78,20 @@ 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,
@@ -95,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.
@@ -103,11 +124,32 @@ 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 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.
@@ -127,6 +169,10 @@ declare interface Root {
      * @default true
      */
     bridgeActive?: boolean;
+    /**
+     * Lyric time offset settings.
+     */
+    offset?: Offset;
 }
 
 /**