@applemusic-like-lyrics/core 0.5.0 → 0.5.1

package/dist/amll-core.d.cts

@@ -368,6 +368,58 @@ declare class Spring {
   getCurrentPosition(): number;
 }
 //#endregion
+//#region src/lyric-player/dom/interlude-dots.d.ts
+declare class InterludeDots implements HasElement, Disposable {
+  private element;
+  private dot0;
+  private dot1;
+  private dot2;
+  private left;
+  private top;
+  private playing;
+  private lastStyle;
+  private currentInterlude?;
+  private currentTime;
+  private targetBreatheDuration;
+  constructor();
+  getElement(): HTMLElement;
+  setTransform(left?: number, top?: number): void;
+  setInterlude(interlude?: [number, number]): void;
+  pause(): void;
+  resume(): void;
+  update(delta?: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/lyric-player/base/bottom-line.d.ts
+interface LineTransforms$1 {
+  posX: Spring;
+  posY: Spring;
+}
+declare class BottomLineEl implements HasElement, Disposable {
+  private lyricPlayer;
+  private element;
+  private left;
+  private top;
+  private delay;
+  lineSize: [number, number];
+  readonly lineTransforms: LineTransforms$1;
+  private isFocused;
+  private blur;
+  constructor(lyricPlayer: LyricPlayerBase);
+  measureSize(): Promise<[number, number]>;
+  private lastStyle;
+  show(): void;
+  hide(): void;
+  setFocused(focused: boolean): void;
+  private rebuildStyle;
+  getElement(): HTMLElement;
+  setTransform(left?: number, top?: number, blur?: number, force?: boolean, delay?: number): void;
+  update(delta?: number): void;
+  get isInSight(): boolean;
+  dispose(): void;
+}
+//#endregion
 //#region src/lyric-player/base/consts.d.ts
 type ValueOf<T extends Record<PropertyKey, unknown>> = T[keyof T];
 /** 歌词中不雅用语的掩码模式 */
@@ -401,8 +453,7 @@ declare const LayoutAlignAnchor: {
 type LayoutAlignAnchor = ValueOf<typeof LayoutAlignAnchor>;
 //#endregion
 //#region src/lyric-player/base/line.d.ts
-interface LineTransforms$1 {
-  posY: Spring;
+interface LineTransforms {
   scale: Spring;
 }
 /**
@@ -415,7 +466,7 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   protected blur: number;
   protected opacity: number;
   protected delay: number;
-  readonly lineTransforms: LineTransforms$1;
+  readonly lineTransforms: LineTransforms;
   /**
   * 用于 CJK 词语边界检测的分词器
   */
@@ -430,8 +481,8 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   abstract disable(): void;
   abstract resume(): void;
   abstract pause(): void;
-  onLineSizeChange(_size: [number, number]): void;
-  setTransform(top?: number, scale?: number, opacity?: number, blur?: number, _force?: boolean, delay?: number, _mode?: LyricLineRenderMode): void;
+  abstract onLineSizeChange(size: [number, number]): void;
+  setTransform(scale?: number, opacity?: number, blur?: number, _force?: boolean, delay?: number, _mode?: LyricLineRenderMode): void;
   rebuildElement(): void;
   /**
   * 判定歌词是否可以应用强调辉光效果
@@ -448,55 +499,37 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   dispose(): void;
 }
 //#endregion
-//#region src/lyric-player/dom/interlude-dots.d.ts
-declare class InterludeDots implements HasElement, Disposable {
-  private element;
-  private dot0;
-  private dot1;
-  private dot2;
-  private left;
-  private top;
-  private playing;
-  private lastStyle;
-  private currentInterlude?;
-  private currentTime;
-  private targetBreatheDuration;
-  constructor();
-  getElement(): HTMLElement;
-  setTransform(left?: number, top?: number): void;
-  setInterlude(interlude?: [number, number]): void;
-  pause(): void;
-  resume(): void;
-  update(delta?: number): void;
-  dispose(): void;
+//#region src/lyric-player/base/group.d.ts
+interface LyricPlayerFlags {
+  getEnableSpring(): boolean;
+  getEnableScale(): boolean;
+  getIsPlaying(): boolean;
+  getAlwaysPostpositionBackground(): boolean;
 }
-//#endregion
-//#region src/lyric-player/base/bottom-line.d.ts
-interface LineTransforms {
-  posX: Spring;
+declare abstract class LyricLineGroupBase<T extends LyricLineBase = LyricLineBase> implements Disposable {
+  mainLine: T;
+  bgLine?: T | undefined;
+  protected abstract readonly lyricPlayer: LyricPlayerFlags;
   posY: Spring;
-}
-declare class BottomLineEl implements HasElement, Disposable {
-  private lyricPlayer;
-  private element;
-  private left;
-  private top;
-  private delay;
-  lineSize: [number, number];
-  readonly lineTransforms: LineTransforms;
-  private isFocused;
-  private blur;
-  constructor(lyricPlayer: LyricPlayerBase);
-  measureSize(): Promise<[number, number]>;
-  private lastStyle;
-  show(): void;
-  hide(): void;
-  setFocused(focused: boolean): void;
-  private rebuildStyle;
-  getElement(): HTMLElement;
-  setTransform(left?: number, top?: number, blur?: number, force?: boolean, delay?: number): void;
-  update(delta?: number): void;
-  get isInSight(): boolean;
+  bgSlideY: Spring;
+  top: number;
+  delay: number;
+  isActive: boolean;
+  opacity: number;
+  blur: number;
+  isBgFirst: boolean;
+  constructor(mainLine: T, bgLine?: T | undefined);
+  get startTime(): number;
+  get endTime(): number;
+  onLineSizeChange(size: [number, number]): void;
+  setTransform(top: number, force: boolean, delay: number, isActive: boolean, opacity: number, blur: number): void;
+  private setLineTransformations;
+  protected abstract renderStyles(): void;
+  abstract get isInSight(): boolean;
+  update(delta: number): void;
+  rebuildAllLines(): void;
+  enable(time?: number, shouldPlay?: boolean): void;
+  disable(): void;
   dispose(): void;
 }
 //#endregion
@@ -551,18 +584,18 @@ interface PlayerScrollState {
 /**
 * 播放时间线状态。
 *
-* 描述播放器在时间轴上的当前位置，当前处于激活状态的歌词行信息
+* 描述播放器在时间轴上的当前位置，当前处于激活状态的歌词组信息
 */
 interface PlayerTimelineState {
   /** 当前播放时间，单位为毫秒 */
   currentTime: number;
   /** 上一次提交到时间线状态的播放时间，单位为毫秒 */
   lastCurrentTime: number;
-  /** 热行：当前时间 {@link currentTime} 正在命中的行（含主行+可能的背景行） */
-  hotLines: Set<number>;
-  /** 缓冲行：UI 上还保持激活表现的行，通常包含热行，并包含刚结束仍在过渡中的行 */
-  bufferedLines: Set<number>;
-  /** 当前应滚动对齐到的歌词行索引 */
+  /** 热行：当前时间 {@link currentTime} 正在命中的组（含主行+可能的背景行） */
+  hotGroups: Set<number>;
+  /** 缓冲组：UI 上还保持激活表现的组索引，通常包含热组，和刚结束仍在过渡中的组 */
+  bufferedGroups: Set<number>;
+  /** 当前应滚动对齐到的歌词组索引 */
   scrollToIndex: number;
   /** 是否正在拖拽进度条。若是，更新时丢弃缓冲行，并根据当前时间直接计算热行 */
   isSeeking: boolean;
@@ -583,9 +616,7 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   /** 播放时间线状态 */
   protected timelineState: PlayerTimelineState;
   /** @internal */
-  lyricLinesSize: WeakMap<LyricLineBase, [number, number]>;
-  /** @internal */
-  lyricLineElementMap: WeakMap<Element, LyricLineBase>;
+  lyricGroupElementMap: WeakMap<Element, LyricLineGroupBase>;
   protected currentLyricLines: LyricLine[];
   protected processedLines: LyricLine[];
   protected lyricLinesIndexes: WeakMap<LyricLineBase, number>;
@@ -601,10 +632,13 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   protected maskObsceneWordChar: string;
   protected hidePassedLines: boolean;
   protected scrollState: PlayerScrollState;
-  protected currentLyricLineObjects: LyricLineBase[];
+  currentLyricGroups: LyricLineGroupBase[];
+  lyricGroupSize: WeakMap<LyricLineGroupBase, [number, number]>;
   readonly size: [number, number];
   protected isPageVisible: boolean;
   protected optimizeOptions: OptimizeLyricOptions;
+  /** 是否强制让背景人声行始终后置（即始终在主歌词下方显示，不前置背景人声） */
+  protected alwaysPostpositionBackground: boolean;
   protected posXSpringParams: Partial<SpringParams>;
   protected posYSpringParams: Partial<SpringParams>;
   protected scaleSpringParams: Partial<SpringParams>;
@@ -823,6 +857,16 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   * @returns 当前播放位置
   */
   getCurrentTime(): number;
+  /**
+  * 设置是否让背景人声行始终后置显示
+  *
+  * 默认情况下，如果背景歌词开始时间早于主歌词，会在主歌词上方展示；
+  * 如果设置为 `true`，则无论时间顺序如何，背景歌词都会始终在主歌词下方展示
+  * @param enable 是否启用始终后置
+  */
+  setAlwaysPostpositionBackground(enable: boolean): void;
+  /** 获取当前是否设置了让背景人声行始终后置显示 */
+  getAlwaysPostpositionBackground(): boolean;
   getElement(): HTMLElement;
   dispose(): void;
 }
@@ -875,10 +919,8 @@ declare class LyricLineEl extends LyricLineBase {
   pause(): Promise<void>;
   setMaskAnimationState(maskAnimationTime?: number): void;
   getLine(): LyricLine;
-  private _prevParentEl;
   private lastStyle;
   show(): void;
-  hide(): void;
   private rebuildStyle;
   override rebuildElement(): void;
   /** 设置翻译与音译行文本 */
@@ -897,14 +939,30 @@ declare class LyricLineEl extends LyricLineBase {
   getElement(): HTMLElement;
   private updateMaskAlphaTargets;
   private applyAlphaToDom;
-  override setTransform(top?: number, scale?: number, opacity?: number, blur?: number, force?: boolean, delay?: number, mode?: LyricLineRenderMode): void;
+  override setTransform(scale?: number, opacity?: number, blur?: number, force?: boolean, delay?: number, mode?: LyricLineRenderMode): void;
   update(delta?: number): void;
   _getDebugTargetPos(): string;
-  get isInSight(): boolean;
+  teardownContent(): void;
   private disposeElements;
   override dispose(): void;
 }
 //#endregion
+//#region src/lyric-player/dom/lyric-group.d.ts
+declare class LyricLineGroup extends LyricLineGroupBase<LyricLineEl> {
+  lyricPlayer: DomLyricPlayer;
+  element: HTMLElement;
+  bgWrapper?: HTMLElement;
+  private lastIsActive?;
+  constructor(lyricPlayer: DomLyricPlayer, mainLine: LyricLineEl);
+  get isInSight(): boolean;
+  show(): void;
+  hide(): void;
+  override update(delta: number): void;
+  addBgLine(bgLine: LyricLineEl): void;
+  protected renderStyles(): void;
+  override dispose(): void;
+}
+//#endregion
 //#region src/lyric-player/dom/index.d.ts
 /**
 * 歌词行鼠标相关事件，可以获取到歌词行的索引和歌词行元素
@@ -927,7 +985,7 @@ type LyricLineMouseEventListener = (evt: LyricLineMouseEvent) => void;
 * 尽可能贴切 Apple Music for iPad 的歌词效果设计，且做了力所能及的优化措施
 */
 declare class DomLyricPlayer extends LyricPlayerBase {
-  override currentLyricLineObjects: LyricLineEl[];
+  override currentLyricGroups: LyricLineGroup[];
   override onResize(): void;
   readonly supportPlusLighter: boolean;
   readonly supportMaskImage: boolean;

package/dist/amll-core.d.mts

@@ -368,6 +368,58 @@ declare class Spring {
   getCurrentPosition(): number;
 }
 //#endregion
+//#region src/lyric-player/dom/interlude-dots.d.ts
+declare class InterludeDots implements HasElement, Disposable {
+  private element;
+  private dot0;
+  private dot1;
+  private dot2;
+  private left;
+  private top;
+  private playing;
+  private lastStyle;
+  private currentInterlude?;
+  private currentTime;
+  private targetBreatheDuration;
+  constructor();
+  getElement(): HTMLElement;
+  setTransform(left?: number, top?: number): void;
+  setInterlude(interlude?: [number, number]): void;
+  pause(): void;
+  resume(): void;
+  update(delta?: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/lyric-player/base/bottom-line.d.ts
+interface LineTransforms$1 {
+  posX: Spring;
+  posY: Spring;
+}
+declare class BottomLineEl implements HasElement, Disposable {
+  private lyricPlayer;
+  private element;
+  private left;
+  private top;
+  private delay;
+  lineSize: [number, number];
+  readonly lineTransforms: LineTransforms$1;
+  private isFocused;
+  private blur;
+  constructor(lyricPlayer: LyricPlayerBase);
+  measureSize(): Promise<[number, number]>;
+  private lastStyle;
+  show(): void;
+  hide(): void;
+  setFocused(focused: boolean): void;
+  private rebuildStyle;
+  getElement(): HTMLElement;
+  setTransform(left?: number, top?: number, blur?: number, force?: boolean, delay?: number): void;
+  update(delta?: number): void;
+  get isInSight(): boolean;
+  dispose(): void;
+}
+//#endregion
 //#region src/lyric-player/base/consts.d.ts
 type ValueOf<T extends Record<PropertyKey, unknown>> = T[keyof T];
 /** 歌词中不雅用语的掩码模式 */
@@ -401,8 +453,7 @@ declare const LayoutAlignAnchor: {
 type LayoutAlignAnchor = ValueOf<typeof LayoutAlignAnchor>;
 //#endregion
 //#region src/lyric-player/base/line.d.ts
-interface LineTransforms$1 {
-  posY: Spring;
+interface LineTransforms {
   scale: Spring;
 }
 /**
@@ -415,7 +466,7 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   protected blur: number;
   protected opacity: number;
   protected delay: number;
-  readonly lineTransforms: LineTransforms$1;
+  readonly lineTransforms: LineTransforms;
   /**
   * 用于 CJK 词语边界检测的分词器
   */
@@ -430,8 +481,8 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   abstract disable(): void;
   abstract resume(): void;
   abstract pause(): void;
-  onLineSizeChange(_size: [number, number]): void;
-  setTransform(top?: number, scale?: number, opacity?: number, blur?: number, _force?: boolean, delay?: number, _mode?: LyricLineRenderMode): void;
+  abstract onLineSizeChange(size: [number, number]): void;
+  setTransform(scale?: number, opacity?: number, blur?: number, _force?: boolean, delay?: number, _mode?: LyricLineRenderMode): void;
   rebuildElement(): void;
   /**
   * 判定歌词是否可以应用强调辉光效果
@@ -448,55 +499,37 @@ declare abstract class LyricLineBase extends EventTarget implements Disposable {
   dispose(): void;
 }
 //#endregion
-//#region src/lyric-player/dom/interlude-dots.d.ts
-declare class InterludeDots implements HasElement, Disposable {
-  private element;
-  private dot0;
-  private dot1;
-  private dot2;
-  private left;
-  private top;
-  private playing;
-  private lastStyle;
-  private currentInterlude?;
-  private currentTime;
-  private targetBreatheDuration;
-  constructor();
-  getElement(): HTMLElement;
-  setTransform(left?: number, top?: number): void;
-  setInterlude(interlude?: [number, number]): void;
-  pause(): void;
-  resume(): void;
-  update(delta?: number): void;
-  dispose(): void;
+//#region src/lyric-player/base/group.d.ts
+interface LyricPlayerFlags {
+  getEnableSpring(): boolean;
+  getEnableScale(): boolean;
+  getIsPlaying(): boolean;
+  getAlwaysPostpositionBackground(): boolean;
 }
-//#endregion
-//#region src/lyric-player/base/bottom-line.d.ts
-interface LineTransforms {
-  posX: Spring;
+declare abstract class LyricLineGroupBase<T extends LyricLineBase = LyricLineBase> implements Disposable {
+  mainLine: T;
+  bgLine?: T | undefined;
+  protected abstract readonly lyricPlayer: LyricPlayerFlags;
   posY: Spring;
-}
-declare class BottomLineEl implements HasElement, Disposable {
-  private lyricPlayer;
-  private element;
-  private left;
-  private top;
-  private delay;
-  lineSize: [number, number];
-  readonly lineTransforms: LineTransforms;
-  private isFocused;
-  private blur;
-  constructor(lyricPlayer: LyricPlayerBase);
-  measureSize(): Promise<[number, number]>;
-  private lastStyle;
-  show(): void;
-  hide(): void;
-  setFocused(focused: boolean): void;
-  private rebuildStyle;
-  getElement(): HTMLElement;
-  setTransform(left?: number, top?: number, blur?: number, force?: boolean, delay?: number): void;
-  update(delta?: number): void;
-  get isInSight(): boolean;
+  bgSlideY: Spring;
+  top: number;
+  delay: number;
+  isActive: boolean;
+  opacity: number;
+  blur: number;
+  isBgFirst: boolean;
+  constructor(mainLine: T, bgLine?: T | undefined);
+  get startTime(): number;
+  get endTime(): number;
+  onLineSizeChange(size: [number, number]): void;
+  setTransform(top: number, force: boolean, delay: number, isActive: boolean, opacity: number, blur: number): void;
+  private setLineTransformations;
+  protected abstract renderStyles(): void;
+  abstract get isInSight(): boolean;
+  update(delta: number): void;
+  rebuildAllLines(): void;
+  enable(time?: number, shouldPlay?: boolean): void;
+  disable(): void;
   dispose(): void;
 }
 //#endregion
@@ -551,18 +584,18 @@ interface PlayerScrollState {
 /**
 * 播放时间线状态。
 *
-* 描述播放器在时间轴上的当前位置，当前处于激活状态的歌词行信息
+* 描述播放器在时间轴上的当前位置，当前处于激活状态的歌词组信息
 */
 interface PlayerTimelineState {
   /** 当前播放时间，单位为毫秒 */
   currentTime: number;
   /** 上一次提交到时间线状态的播放时间，单位为毫秒 */
   lastCurrentTime: number;
-  /** 热行：当前时间 {@link currentTime} 正在命中的行（含主行+可能的背景行） */
-  hotLines: Set<number>;
-  /** 缓冲行：UI 上还保持激活表现的行，通常包含热行，并包含刚结束仍在过渡中的行 */
-  bufferedLines: Set<number>;
-  /** 当前应滚动对齐到的歌词行索引 */
+  /** 热行：当前时间 {@link currentTime} 正在命中的组（含主行+可能的背景行） */
+  hotGroups: Set<number>;
+  /** 缓冲组：UI 上还保持激活表现的组索引，通常包含热组，和刚结束仍在过渡中的组 */
+  bufferedGroups: Set<number>;
+  /** 当前应滚动对齐到的歌词组索引 */
   scrollToIndex: number;
   /** 是否正在拖拽进度条。若是，更新时丢弃缓冲行，并根据当前时间直接计算热行 */
   isSeeking: boolean;
@@ -583,9 +616,7 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   /** 播放时间线状态 */
   protected timelineState: PlayerTimelineState;
   /** @internal */
-  lyricLinesSize: WeakMap<LyricLineBase, [number, number]>;
-  /** @internal */
-  lyricLineElementMap: WeakMap<Element, LyricLineBase>;
+  lyricGroupElementMap: WeakMap<Element, LyricLineGroupBase>;
   protected currentLyricLines: LyricLine[];
   protected processedLines: LyricLine[];
   protected lyricLinesIndexes: WeakMap<LyricLineBase, number>;
@@ -601,10 +632,13 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   protected maskObsceneWordChar: string;
   protected hidePassedLines: boolean;
   protected scrollState: PlayerScrollState;
-  protected currentLyricLineObjects: LyricLineBase[];
+  currentLyricGroups: LyricLineGroupBase[];
+  lyricGroupSize: WeakMap<LyricLineGroupBase, [number, number]>;
   readonly size: [number, number];
   protected isPageVisible: boolean;
   protected optimizeOptions: OptimizeLyricOptions;
+  /** 是否强制让背景人声行始终后置（即始终在主歌词下方显示，不前置背景人声） */
+  protected alwaysPostpositionBackground: boolean;
   protected posXSpringParams: Partial<SpringParams>;
   protected posYSpringParams: Partial<SpringParams>;
   protected scaleSpringParams: Partial<SpringParams>;
@@ -823,6 +857,16 @@ declare abstract class LyricPlayerBase extends EventTarget implements HasElement
   * @returns 当前播放位置
   */
   getCurrentTime(): number;
+  /**
+  * 设置是否让背景人声行始终后置显示
+  *
+  * 默认情况下，如果背景歌词开始时间早于主歌词，会在主歌词上方展示；
+  * 如果设置为 `true`，则无论时间顺序如何，背景歌词都会始终在主歌词下方展示
+  * @param enable 是否启用始终后置
+  */
+  setAlwaysPostpositionBackground(enable: boolean): void;
+  /** 获取当前是否设置了让背景人声行始终后置显示 */
+  getAlwaysPostpositionBackground(): boolean;
   getElement(): HTMLElement;
   dispose(): void;
 }
@@ -875,10 +919,8 @@ declare class LyricLineEl extends LyricLineBase {
   pause(): Promise<void>;
   setMaskAnimationState(maskAnimationTime?: number): void;
   getLine(): LyricLine;
-  private _prevParentEl;
   private lastStyle;
   show(): void;
-  hide(): void;
   private rebuildStyle;
   override rebuildElement(): void;
   /** 设置翻译与音译行文本 */
@@ -897,14 +939,30 @@ declare class LyricLineEl extends LyricLineBase {
   getElement(): HTMLElement;
   private updateMaskAlphaTargets;
   private applyAlphaToDom;
-  override setTransform(top?: number, scale?: number, opacity?: number, blur?: number, force?: boolean, delay?: number, mode?: LyricLineRenderMode): void;
+  override setTransform(scale?: number, opacity?: number, blur?: number, force?: boolean, delay?: number, mode?: LyricLineRenderMode): void;
   update(delta?: number): void;
   _getDebugTargetPos(): string;
-  get isInSight(): boolean;
+  teardownContent(): void;
   private disposeElements;
   override dispose(): void;
 }
 //#endregion
+//#region src/lyric-player/dom/lyric-group.d.ts
+declare class LyricLineGroup extends LyricLineGroupBase<LyricLineEl> {
+  lyricPlayer: DomLyricPlayer;
+  element: HTMLElement;
+  bgWrapper?: HTMLElement;
+  private lastIsActive?;
+  constructor(lyricPlayer: DomLyricPlayer, mainLine: LyricLineEl);
+  get isInSight(): boolean;
+  show(): void;
+  hide(): void;
+  override update(delta: number): void;
+  addBgLine(bgLine: LyricLineEl): void;
+  protected renderStyles(): void;
+  override dispose(): void;
+}
+//#endregion
 //#region src/lyric-player/dom/index.d.ts
 /**
 * 歌词行鼠标相关事件，可以获取到歌词行的索引和歌词行元素
@@ -927,7 +985,7 @@ type LyricLineMouseEventListener = (evt: LyricLineMouseEvent) => void;
 * 尽可能贴切 Apple Music for iPad 的歌词效果设计，且做了力所能及的优化措施
 */
 declare class DomLyricPlayer extends LyricPlayerBase {
-  override currentLyricLineObjects: LyricLineEl[];
+  override currentLyricGroups: LyricLineGroup[];
   override onResize(): void;
   readonly supportPlusLighter: boolean;
   readonly supportMaskImage: boolean;