`. In AMLL, common types are:
+
+1. `ttm:*` metadata (TTML standard)
+2. `amll:meta` metadata (AMLL extension)
+
+Example:
+
+```xml
+
+ Song Title
+
+
+ Singer A
+
+
+
+```
+
+Common `amll:meta` keys:
+
+- `musicName`, `artists`, `album`, `isrc`
+- Platform IDs: `ncmMusicId`, `qqMusicId`, `spotifyId`, `appleMusicId`
+- Contributors: `ttmlAuthorGithub`, `ttmlAuthorGithubLogin`
+
+## Timing and Modes
+
+Timing is typically expressed by `begin` / `end` / `dur`. Supported units:
+
+- Clock format: `MM:SS.fff`, `HH:MM:SS.fff` (fractional digits 0-3)
+- Seconds format: `12.3s`
+
+With `itunes:timing="Word"`:
+
+- `` is one lyric line
+- Timestamped inline `` elements represent words/syllables
+
+With `itunes:timing="Line"`:
+
+- Primarily uses `whole line text
`
+- Inline word timing spans are usually not used
+
+## Body Structure and Extension Roles
+
+Typical body structure:
+
+```xml
+
+
+
+```
+
+Common attributes and conventions:
+
+- `itunes:key="L1"`: unique line ID (`L1`, `L2`, ...)
+- `ttm:agent="v1"`: points to ``
+- `itunes:song-part`: section info (`Verse`, `Chorus`, etc.)
+
+Inline assistant content uses `ttm:role`:
+
+- `x-translation`: translation
+- `x-roman`: transliteration / romanization
+- `x-bg`: background vocal
+
+Example:
+
+```xml
+
+ コーラス
+ です
+
+
+ (背景)
+ Background
+ haikei
+
+
+```
+
+## Apple Music Style Translation/Transliteration Sidecar
+
+In addition to inline spans, translation/transliteration can be stored in ``:
+
+```xml
+
+
+
+ First line translation
+
+
+
+
+ dai ichi gyou
+
+
+
+```
+
+`for="L1"` links to `itunes:key="L1"` in the body.
+
+## Ruby Annotation
+
+AMLL supports TTML Ruby (`tts:ruby`) for furigana, pinyin, etc.:
+
+- `tts:ruby="container"`: ruby container
+- `tts:ruby="base"`: base text
+- `tts:ruby="textContainer"`: ruby text container
+- `tts:ruby="text"`: ruby text (can carry timing)
+
+```xml
+
+ 所
+
+ しょ
+
+
+
+ 詮
+
+ せ
+ ん
+
+
+```
+
+## Implementation Behavior in This Library
+
+Current parse/export behavior includes:
+
+- Accepts both `itunes:songPart` and `itunes:song-part`; export prefers `song-part`
+- Parses and preserves `amll:obscene` and `amll:empty-beat`
+- Background vocal text can be with/without parentheses; parser normalizes it
+- Can merge inline translations with Head Sidecar translations (same language may duplicate; dedupe in business layer)
+- If word-level timing is absent but line timing exists, it can fallback to placeholder word entries to avoid information loss
diff --git a/amll-local/packages/docs/src/content/docs/en/guides/overview/eco.md b/amll-local/packages/docs/src/content/docs/en/guides/overview/eco.md
new file mode 100644
index 0000000..ebb0a07
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/en/guides/overview/eco.md
@@ -0,0 +1,61 @@
+---
+title: Ecosystem
+---
+
+After continuous development, AMLL has built an open-source ecosystem around word-by-word lyrics, including lyric databases, editors, and music players.
+
+## First-party Ecosystem
+
+First-party projects are repositories under the [amll-dev](https://github.com/amll-dev/) GitHub organization. Content and docs for each project are maintained independently. Please report issues in the corresponding repository.
+
+### AMLL TTML Database
+
+[AMLL TTML Database](https://github.com/amll-dev/amll-ttml-db) is a high-quality open word-by-word lyrics database. Lyrics are community-contributed and reviewed, and published under [CC0-1.0](https://github.com/amll-dev/amll-ttml-db/blob/main/LICENSE).
+
+If you are building a player, you can use it as your lyric source. You can also contribute lyrics back to the database. For submission and usage details, see its [repository wiki](https://github.com/amll-dev/amll-ttml-db/wiki).
+
+### AMLL TTML Tool
+
+[AMLL TTML Tool](https://github.com/amll-dev/amll-ttml-tool) is a React-based word-by-word lyrics editor with lyric editing and timing capabilities. Most lyrics in the database were created using this tool.
+
+
+
+It is deployed at
+
diff --git a/amll-local/packages/docs/src/content/docs/guides/component/background.md b/amll-local/packages/docs/src/content/docs/guides/component/background.md
new file mode 100644
index 0000000..640e678
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/component/background.md
@@ -0,0 +1,218 @@
+---
+title: 动态背景
+---
+
+AMLL Core 提供了独立的背景渲染组件 [`BackgroundRender`](/reference/core/classbackgroundrender)。它负责把专辑图或专辑视频渲染成 Apple Music 风格的动态背景；歌词组件仍然只负责歌词视图本身，音频播放、资源加载与图层挂载需要由宿主环境管理。
+
+本文主要使用原生 Core API 说明背景集成方式，如果你使用 React 或 Vue 绑定，请直接转到 [绑定部分](#react-与-vue-绑定)。
+
+## 基本结构
+
+背景组件由两部分组成：
+
+- [`BackgroundRender`](/reference/core/classbackgroundrender)：统一的包装器，提供设置专辑图、帧率、渲染比例、暂停恢复等方法。
+- 渲染器：目前 Core 提供 [`MeshGradientRenderer`](/reference/core/classmeshgradientrenderer) 和 [`PixiRenderer`](/reference/core/classpixirenderer)。
+
+创建背景时需要选择其中一个渲染器：
+
+```ts
+// 使用 Mesh Gradient
+import {
+ BackgroundRender,
+ MeshGradientRenderer,
+} from "@applemusic-like-lyrics/core";
+const meshBackground = BackgroundRender.new(MeshGradientRenderer);
+
+// 使用 Pixi
+import { BackgroundRender, PixiRenderer } from "@applemusic-like-lyrics/core";
+const pixiBackground = BackgroundRender.new(PixiRenderer);
+```
+
+## 与歌词组件叠放
+
+背景元素是一个 ``。通常把它和歌词组件放在同一个容器中，并放置在歌词元素之前。
+
+```ts
+import {
+ BackgroundRender,
+ DomLyricPlayer,
+ MeshGradientRenderer,
+} from "@applemusic-like-lyrics/core";
+import "@applemusic-like-lyrics/core/style.css";
+
+const background = BackgroundRender.new(MeshGradientRenderer);
+const lyricPlayer = new DomLyricPlayer();
+
+function mountPlayer(host: HTMLElement) {
+ const backgroundElement = background.getElement();
+ const lyricElement = lyricPlayer.getElement();
+
+ host.appendChild(backgroundElement);
+ host.appendChild(lyricElement);
+}
+
+const host = document.querySelector("#player");
+if (!host) throw new Error("missing #player");
+
+mountPlayer(host);
+```
+
+背景的 canvas 尺寸由 CSS 决定，内部会通过 `ResizeObserver` 按设备像素比和渲染比例调整实际绘制尺寸。因此，宿主容器应有明确宽高。
+
+AMLL 本身不会定义背景组件与歌词组件的定位与层级样式，这部分样式应由宿主定义。
+
+## 设置专辑资源
+
+调用 [`setAlbum`](/reference/core/classbackgroundrender#setalbum) 设置背景来源。它可以接收图片或视频 URL、`HTMLImageElement` 或 `HTMLVideoElement`。
+
+如果传入字符串 URL 且资源是视频，需要把第二个参数设为 `true`：
+
+```ts
+// 图片 URL
+await background.setAlbum("/album-cover.jpg");
+
+// 视频 URL
+await background.setAlbum("/album-video.webm", true);
+```
+
+若你已经持有 `File` 或 `Blob` 对象，可以使用 [`URL.createObjectURL`](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/createObjectURL_static) 创建对象 URL 并提供给 `setAlbum`。
+
+背景渲染会把资源绘制到 canvas / WebGL 纹理中。
+
+## 同步播放状态
+
+背景组件拥有自己的动画循环，不需要像 `DomLyricPlayer` 一样手动逐帧调用 `update(delta)`。只需要在播放、暂停时调用 `resume()` 与 `pause()`：
+
+```ts
+audio.addEventListener("play", () => {
+ lyricPlayer.resume();
+ background.resume();
+});
+
+audio.addEventListener("pause", () => {
+ lyricPlayer.pause();
+ background.pause();
+});
+```
+
+背景动画的播放状态与歌词动画独立，你也可以只控制背景动画。
+
+```ts
+function setBackgroundPlaying(playing: boolean) {
+ if (playing) background.resume();
+ else background.pause();
+}
+```
+
+## 应用渲染设置
+
+常用设置可以在初始化后或用户调整选项时应用，设置后即时生效。
+
+```ts
+function applyBackgroundSettings() {
+ background.setFPS(60);
+ background.setRenderScale(1);
+ background.setFlowSpeed(0.2);
+ background.setStaticMode(false);
+ background.setLowFreqVolume(1);
+}
+```
+
+| 方法 | 说明 |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| [`setFPS(fps)`](/reference/core/classbackgroundrender#setfps) | 设置背景动画帧率 |
+| [`setRenderScale(scale)`](/reference/core/classbackgroundrender#setrenderscale) | 设置渲染比例，数值越高越清晰，也越消耗性能 |
+| [`setFlowSpeed(speed)`](/reference/core/classbackgroundrender#setflowspeed) | 设置背景流动速度 |
+| [`setStaticMode(enable)`](/reference/core/classbackgroundrender#setstaticmode) | 开启后，背景在资源切换动画结束后可以停在静态状态，以节省性能 |
+| [`setLowFreqVolume(volume)`](/reference/core/classbackgroundrender#setlowfreqvolume) | 传入低频音量提示，部分渲染器可能会据此调整动态效果 |
+| [`setHasLyric(hasLyric)`](/reference/core/classbackgroundrender#sethaslyric) | 告诉渲染器当前歌曲是否有歌词，部分渲染器可能会据此调整动态效果 |
+
+`setRenderScale` 的值通常在 `0.5` 到 `1` 之间取舍。移动端或低性能设备可以降低渲染比例和帧率；播放器全屏展示时可以提高渲染比例。
+
+## 更换渲染器
+
+`BackgroundRender` 创建后不能替换内部渲染器。如果用户从 `MeshGradientRenderer` 切换到 `PixiRenderer`，应该释放旧实例并创建新实例：
+
+```ts
+type PlayerBackground =
+ | BackgroundRender
+ | BackgroundRender;
+
+function switchToPixiRenderer(
+ host: HTMLElement,
+ lyricPlayer: DomLyricPlayer,
+ currentBackground: PlayerBackground,
+) {
+ currentBackground.dispose();
+
+ const nextBackground = BackgroundRender.new(PixiRenderer);
+ host.insertBefore(nextBackground.getElement(), lyricPlayer.getElement());
+ return nextBackground;
+}
+```
+
+## 清理
+
+页面卸载、播放器销毁或永久切换实现时，需要释放背景实例：
+
+```ts
+background.dispose();
+lyricPlayer.dispose();
+```
+
+`dispose()` 会释放渲染器内部资源，并移除背景 canvas。若你自己创建了 `ObjectURL`、音频事件监听或其他异步加载状态，也需要在宿主代码中一并清理。
+
+## React 与 Vue 绑定
+
+背景组件没有歌词组件那么复杂的中间状态维护，因此组件化轻松许多。
+
+React 与 Vue 是类似的，均通过 props 设置选项与维护状态。是否播放使用 `playing` 属性指定，专辑图片或视频资源使用 `album` 属性指定。你可以在 API 参考中查看完整的属性列表。
+
+- React 属性列表参考：[BackgroundRenderProps](/reference/react/interfacebackgroundrenderprops)
+- Vue 属性列表参考：[BackgroundRender](/reference/vue/classbackgroundrender)
+
+组件在卸载时会自动释放内部资源。但你自行定义的监听器、Object URL 等仍需你自行释放。
+
+下面是一个 React 的最小示例：
+
+```tsx
+import { LyricPlayer, BackgroundRender } from "@applemusic-like-lyrics/react";
+
+function app() {
+ const albumUrl = "/album-cover.jpg";
+ return (
+ <>
+
+
+
+
+```
+
+## 检查清单
+
+- 宿主容器有明确尺寸。
+- 背景 canvas 插入在歌词元素之前，且歌词层级高于背景层级。
+- 图片或视频资源允许跨域读取，或与页面同源。
+- 视频 URL 调用 `setAlbum(source, true)`。
+- 播放状态同步到 `resume()` / `pause()`。
+- 切换渲染器时先 `dispose()` 旧背景，再创建新背景。
+- 卸载时释放背景、歌词组件和宿主代码创建的资源。
diff --git a/amll-local/packages/docs/src/content/docs/guides/component/quickstart.mdx b/amll-local/packages/docs/src/content/docs/guides/component/quickstart.mdx
new file mode 100644
index 0000000..6709a7c
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/component/quickstart.mdx
@@ -0,0 +1,286 @@
+---
+title: 快速开始
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
+import PackageInstall from "#components/PackageInstall.astro";
+
+下面快速介绍如何将 AMLL 歌词组件集成到你的项目中。请注意，AMLL 不提供 CDN 引入方式，必须使用 bundler。
+
+有关除组件库之外的其他周围工具包，请直接查阅 [API 参考](/reference)。
+
+## 依赖
+
+安装 AMLL 核心库：
+
+
+
+
+## 使用原生方式引入
+
+AMLL 核心库是框架无关的。无论是否使用框架，均可使用此方法引入。
+
+下面假设：
+
+- 页面中已有 `` 和 ``，并给歌词容器设置了明确高度
+- TTML 歌词文件在 `/lyrics/song.ttml` 上提供
+
+```js
+import { LyricPlayer } from "@applemusic-like-lyrics/core";
+import { parseTTML } from "@applemusic-like-lyrics/lyric";
+
+// 一般地，打包器会处理 CSS 导入；如果出现异常，请查阅你使用的打包器文档
+import "@applemusic-like-lyrics/core/style.css";
+
+const audio = document.querySelector("#audio");
+const playerHost = document.querySelector("#lyric-player");
+const player = new LyricPlayer();
+
+playerHost.appendChild(player.getElement());
+
+async function loadLyric() {
+ const ttml = await fetch("/lyrics/song.ttml").then((res) => res.text());
+ const currentTime = Math.round(audio.currentTime * 1000);
+ player.setLyricLines(parseTTML(ttml).lines, currentTime);
+ player.setCurrentTime(currentTime, true);
+}
+
+// 播放时持续同步音频进度
+let lastFrameTime = -1;
+function onFrame(frameTime) {
+ const delta = lastFrameTime === -1 ? 0 : frameTime - lastFrameTime;
+ lastFrameTime = frameTime;
+
+ if (!audio.paused) {
+ player.setCurrentTime(Math.round(audio.currentTime * 1000));
+ }
+
+ player.update(delta);
+ requestAnimationFrame(onFrame);
+}
+
+audio.addEventListener("play", () => player.resume());
+audio.addEventListener("pause", () => player.pause());
+audio.addEventListener("seeked", () => {
+ // 跳转后立即对齐歌词位置
+ player.setCurrentTime(Math.round(audio.currentTime * 1000), true);
+});
+
+loadLyric();
+requestAnimationFrame(onFrame);
+```
+
+有关更详细的时序管理，请转到 [时序与生命周期](./sequence)。
+
+你可以前往 [API 参考：Core 核心](/reference/core) 获取详细的接口文档。
+
+## 使用 React 绑定
+
+确保你已安装 `react` 和 `react-dom` 包。然后安装 AMLL React 绑定包：
+
+
+
+React 绑定包拥有具名导出 [`LyricPlayer`](/reference/react/variablelyricplayer) 作为核心组件。下面是一段示例，假设 TTML 歌词文件在 `/lyrics/song.ttml` 上提供、音频文件在 `/music/song.m4a` 上提供。
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import type { LyricLine } from "@applemusic-like-lyrics/core";
+import { LyricPlayer } from "@applemusic-like-lyrics/react";
+import { parseTTML } from "@applemusic-like-lyrics/lyric";
+
+// 一般地，打包器会处理 CSS 导入；如果出现异常，请查阅你使用的打包器文档
+import "@applemusic-like-lyrics/core/style.css";
+
+function App() {
+ const audioRef = useRef
(null);
+ const [lyricLines, setLyricLines] = useState([]);
+ const [currentTime, setCurrentTime] = useState(0);
+ const [playing, setPlaying] = useState(false);
+
+ function syncCurrentTime() {
+ const audio = audioRef.current;
+ if (audio) setCurrentTime(Math.round(audio.currentTime * 1000));
+ }
+
+ useEffect(() => {
+ let canceled = false;
+
+ // parseTTML 返回包含元数据的对象，组件只需要其中的 lines
+ fetch("/lyrics/song.ttml")
+ .then((res) => res.text())
+ .then((ttml) => {
+ if (!canceled) setLyricLines(parseTTML(ttml).lines);
+ });
+
+ return () => {
+ canceled = true;
+ };
+ }, []);
+
+ useEffect(() => {
+ let frameId = 0;
+ const onFrame = () => {
+ const audio = audioRef.current;
+ if (audio && !audio.paused) {
+ setCurrentTime(Math.round(audio.currentTime * 1000));
+ }
+ frameId = requestAnimationFrame(onFrame);
+ };
+
+ frameId = requestAnimationFrame(onFrame);
+ return () => cancelAnimationFrame(frameId);
+ }, []);
+
+ return (
+ <>
+ setPlaying(true)}
+ onPause={() => setPlaying(false)}
+ onEnded={() => setPlaying(false)}
+ onSeeked={syncCurrentTime}
+ />
+
+ );
+}
+
+export default App;
+```
+
+你可以前往 [API 参考：React 绑定](/reference/react) 获取详细的接口文档。
+
+## 使用 Vue 绑定
+
+确保你已安装 Vue。然后安装 AMLL Vue 绑定包：
+
+
+
+
+
+
+
+```
+
+你可以前往 [API 参考：Vue 绑定](/reference/vue) 获取详细的接口文档。
diff --git a/amll-local/packages/docs/src/content/docs/guides/component/sequence.md b/amll-local/packages/docs/src/content/docs/guides/component/sequence.md
new file mode 100644
index 0000000..94031f5
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/component/sequence.md
@@ -0,0 +1,209 @@
+---
+title: 时序与生命周期
+---
+
+下面介绍歌词组件的时序与生命周期管理。
+
+歌词组件只负责歌词视图本身，**不负责音频播放**。因此 **宿主环境（也就是你的代码）需要管理音频播放，并把音频播放状态与 AMLL 的组件状态桥接起来。**
+
+如果你使用 React 或 Vue 绑定，组件会代管一部分生命周期；如果直接使用原生方式，则需要自己管理完整流程。本文主要介绍原生方式引入的周期管理，并介绍绑定托管的状态。
+
+## 初始化
+
+初始化时需要完成：
+
+1. 创建歌词组件，并把它的元素挂载到一个 **有明确尺寸的** 容器里。
+2. （可选）设置自定义歌词优化选项。[`setOptimizeOptions`](/reference/core/classlyricplayerbase#setoptimizeoptions) 方法接受 [`OptimizeLyricOptions`](/reference/core/interfaceoptimizelyricoptions)。
+3. 设置歌词数据。[`setLyricLines`](/reference/core/classlyricplayerbase#setlyriclines) 方法接受 [`LyricLine[]`](/reference/core/interfacelyricline)，传入后不应再修改这些对象。
+4. 用当前播放进度对齐一次歌词位置。
+
+原生方式的典型顺序如下：
+
+```ts
+import { LyricPlayer } from "@applemusic-like-lyrics/core";
+
+const player = new LyricPlayer();
+host.appendChild(player.getElement());
+
+const currentTime = Math.round(audio.currentTime * 1000);
+player.setOptimizeOptions({}); // 可选
+player.setLyricLines(lines, currentTime);
+player.setCurrentTime(currentTime, true);
+player.update(0);
+```
+
+在设置歌词时会执行歌词优化处理，因此这部分选项如需调整，应在 `setLyricLines` 之前调用 `setOptimizeOptions`。在 `setLyricLines` 之后修改不会自动重新处理已有歌词，需要重新设置歌词。
+
+另外需要注意其中 `currentTime` 的单位是毫秒，且应为整数。`audio.currentTime` 单位为秒，所以要乘以 `1000`。
+
+## 播放与暂停
+
+`pause()` 和 `resume()` 控制歌词组件内部的演出状态，包括逐字动画与辉光、间奏点动画。音频开始播放时调用 `resume()`，音频暂停、结束或被外部中断时调用 `pause()`。
+
+例如，若使用 `` 播放音频，可以使用其事件驱动：
+
+```ts
+const onPlay = () => {
+ player.resume();
+};
+const onPause = () => {
+ player.pause();
+};
+
+audio.addEventListener("play", onPlay);
+audio.addEventListener("pause", onPause);
+```
+
+## 播放进度
+
+### 正常播放
+
+在播放过程中需要更新歌词组件的时间进度。**AMLL 使用的所有时间，单位均为毫秒**。
+
+其中有两个容易混淆的时间：
+
+| 时间类型 | 接收于 | 含义 |
+| ------------ | ------------------------------------------- | -------------------- |
+| 当前播放进度 | `setCurrentTime(time)` / `currentTime` 属性 | 歌曲播放的进度 |
+| 帧间隔 | `update(delta)` | 距离上一帧过去的时间 |
+
+原生方式下，`setCurrentTime` 会更新歌词时间线，`update` 会推进动画。**二者不是同一个值**。
+
+```ts
+let frameId = 0;
+let lastFrameTime = -1;
+
+function startFrameLoop() {
+ const onFrame = (frameTime: number) => {
+ const delta = lastFrameTime === -1 ? 0 : frameTime - lastFrameTime;
+ lastFrameTime = frameTime;
+ if (!audio.paused) {
+ player.setCurrentTime(Math.round(audio.currentTime * 1000));
+ }
+ player.update(delta);
+ frameId = requestAnimationFrame(onFrame);
+ };
+ frameId = requestAnimationFrame(onFrame);
+}
+
+function stopFrameLoop() {
+ cancelAnimationFrame(frameId);
+ frameId = 0;
+ lastFrameTime = -1;
+}
+```
+
+**不应依赖 `` 的 `timeupdate` 事件同步歌词**。这是由于浏览器触发 `timeupdate` 的频率较低且不稳定，通常明显低于动画帧频率。播放中应使用 `requestAnimationFrame` 逐帧同步当前进度。
+
+### 跳转
+
+在正常播放之外，播放进度有可能产生跳变，常见于：
+
+- 拖动进度条
+- 快进快退
+- 点击某一歌词行跳转
+- 循环播放时，进度从结尾跳至开头
+
+播放进度发生跳变时，需要把 `setCurrentTime` 的第二个参数设为 `true`：
+
+```ts
+function onSeeked() {
+ player.setCurrentTime(Math.round(audio.currentTime * 1000), true);
+}
+audio.addEventListener("seeked", onSeeked);
+```
+
+**这个参数表示本次同步是一次 seek。正常播放状态与 seek 状态的布局与动画行为是不同的：**
+
+- 正常播放时，组件会对视图内的每一行单独执行布局与弹簧动画，实现细腻的视觉效果
+- 调整进度时，组件会强制对齐歌词位置，对所有歌词行整体执行布局与弹簧动画效果，减小性能消耗且动画更加利落
+
+如果没有正确标记 seek 状态，可能出现布局异常，例如出现卡顿、歌词行从屏幕一端快速飞到另一端消失等等。你可以在 [issue #429](https://github.com/amll-dev/applemusic-like-lyrics/issues/429) 中看到截图。
+
+### 歌词行点击事件
+
+组件提供了 `line-click` 事件，在某一歌词行被点击时触发，其事件类型为 [`LyricLineMouseEvent`](/reference/core/classlyriclinemouseevent)。
+
+**组件本身不会响应歌词行的点击操作。** 宿主环境需要监听该事件，并作出音频进度跳转等操作。例如：
+
+```ts
+import type { LyricLineMouseEvent } from "@applemusic-like-lyrics/core";
+
+player.addEventListener("line-click", (event) => {
+ const lineEvent = event as LyricLineMouseEvent;
+ audio.currentTime = lineEvent.line.getLine().startTime / 1000;
+ player.setCurrentTime(lineEvent.line.getLine().startTime, true);
+});
+```
+
+值得一提：点击歌词行跳转时也属于 seek。
+
+## 更换歌词
+
+更换歌曲或歌词源时，通过 `setLyricLines` 方法再次设置歌词行对象数组即可。如果加载失败，可以传入空数组清空歌词。
+
+```ts
+player.setLyricLines([]);
+player.update(0);
+```
+
+## React 与 Vue 绑定
+
+React 和 Vue 绑定会创建并销毁底层 Core 组件，也会在未禁用时自动调用 `update`。因此使用绑定时，通常不需要自己调用底层 `update`。
+
+你仍然需要负责这些状态：
+
+| 状态 | React / Vue 传入方式 | 说明 |
+| ------------ | -------------------- | ------------------------------------------- |
+| 歌词数据 | `lyricLines` | 解析后的 `LyricLine[]` |
+| 当前播放进度 | `currentTime` | 播放中用 `requestAnimationFrame` 从音频同步 |
+| 播放状态 | `playing` | 控制歌词组件内部演出暂停或恢复 |
+
+React 绑定额外提供 `isSeeking` 属性，可以在跳转时传入：
+
+```tsx
+
+
diff --git a/amll-local/packages/docs/src/content/docs/guides/lyric/formats.md b/amll-local/packages/docs/src/content/docs/guides/lyric/formats.md
new file mode 100644
index 0000000..f0a18d2
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/lyric/formats.md
@@ -0,0 +1,195 @@
+---
+title: 各歌词格式介绍
+---
+
+本文介绍 [@applemusic-like-lyrics/lyric](https://www.npmjs.com/package/@applemusic-like-lyrics/lyric) 库支持的一些歌词文件格式。
+
+在本文中，「逐字歌词」**泛指时间戳精度高于行级别的歌词**。不同平台、格式实现有所不同，可能对应逐音节或逐词的时间戳。
+
+## TTML
+
+TTML 格式是 AMLL 生态的主要歌词存储与交换格式，支持 AMLL 生态的所有能力，包括翻译音译、背景对唱、逐字音译、注音等等。
+
+有关 TTML 的介绍详见 [TTML](./ttml) 一文。
+
+**本库提供 [`parseTTML`](/reference/lyric/functionparsettml) 和 [`stringifyTTML`](/reference/lyric/functionstringifyttml) 方法用于正反序列化 TTML 歌词。**
+
+## LRC
+
+LRC 是最常见的歌词文件格式，只支持逐行歌词。扩展名为 `.lrc`，是 **l**y**r**i**c**s 的缩写。
+
+我们这里所说的 LRC 是最基本、未作任何扩展的 LRC 格式，有时也称为简单 LRC。LRC 并不是某个机构公开声明定义的，其最初来源已经不可考，目前已经成为业界的某种约定俗成，因此各种变体繁多，很多细节也没有固定。
+
+一般地，LRC 格式中每一行对应着一个歌词行。歌词行的开头有时间戳，表示该行的开始时间。常见的格式有
+
+- `[mm:ss]`
+- `[mm:ss.xx]`
+- `[mm:ss.xxx]`
+
+其中 `mm` 为分钟，`ss.xxx` 为秒，小数点后可能不保留、保留 2 位或保留 3 位。特别地，同一行歌词可以使用多个时间戳，表示在不同时间重复出现。
+
+LRC 格式还支持在开头添加元数据。元数据的格式为 `[tag:content]`。AMLL Editor 支持 LRC 元数据模板，包含了常见字段，在元数据侧边栏的下拉框中可以选择。此处不再列举。
+
+一些实现允许使用 `#` 开头的行作为注释。
+
+这里给出一段 LRC 歌词的示例。
+
+```lrc
+[al:崩坏星穹铁道-不虚此行 On the Journey]
+[ti:不虚此行 On the Journey]
+[ar:魏晨, Nea]
+[length: 2:36]
+
+[00:25.494]We venture through the cosmic sea
+[00:27.541]A thousand light-years, wild and free
+[00:30.805]We dance beneath the galaxy
+[00:32.847]Then will you be with me?
+# ...
+[01:45.949]Catching on, our paths unknown
+[01:50.261]To sink into daylight
+[01:52.851]Break into the moonlight
+[01:56.487]Life goes on, through tides of time
+[02:00.900]Get in the line, to dream alive
+[02:03.580]In our souls, do we know?
+[02:05.896][02:08.473][02:11.262]On the journey
+```
+
+LRC 不支持为歌词添加翻译与音译。一般的处理方法是，如有翻译与音译，通过额外的独立文件提供，时间戳与原文歌词文件相同，对应时间戳对应行的翻译与音译。
+
+[维基百科：LRC (file format)]() 上有更多介绍。
+
+**本库提供 [`parseLrc`](/reference/lyric/functionparselrc) 和 [`stringifyLrc`](/reference/lyric/functionstringifylrc) 方法用于正反序列化 LRC 歌词。**
+
+## LRC A2
+
+LRC A2 首先由 A2 Media Player 提出，故名。其是在 LRC 基础上扩展的结果，通过在文中加注尖括号包裹的时间戳 `` 实现了逐字。时间戳格式与 LRC 类似，可能不保留小数点、或小数点后保留 2 位或 3 位。每个尖括号都表示其**后续**一部分文本片段的开始时间。
+
+LRC A2 的扩展名为 `.lrc` 或 `.alrc`。
+
+这里直接给出示例。
+
+```alrc
+[ti: Somebody to Love]
+[ar: Jefferson Airplane]
+[al: Surrealistic Pillow]
+[length: 2:58]
+
+[00:00.00] <00:00.04> When <00:00.16> the <00:00.82> truth <00:01.29> is <00:01.63> found <00:03.09> to <00:03.37> be <00:05.92> lies
+[00:06.47] <00:07.67> And <00:07.94> all <00:08.36> the <00:08.63> joy <00:10.28> within <00:10.53> you <00:13.09> dies
+[00:13.34] <00:14.32> Don't <00:14.73> you <00:15.14> want <00:15.57> somebody <00:16.09> to <00:16.46> Love
+```
+
+解析时，时间戳前后的空格应当合并。
+
+LRC A2 使用尖括号夹入文中，这里涉及到转义的问题：如果歌词中出现了大于号 `>` 或小于号 `<`，应当如何处置？目前没有找到公开的规范说明，业内没有统一的转义方式。在解析时会尽量按时间戳模式匹配 ``，若歌词中出现 `<` 或 `>` 且不符合时间戳格式，则按普通字符处理。
+
+LRC A2 也不支持为歌词添加翻译与音译。一般的做法是伴随提供 LRC 格式的翻译或音译。
+
+**本库提供 [`parseLrcA2`](/reference/lyric/functionparselrca2) 和 [`stringifyLrcA2`](/reference/lyric/functionstringifylrca2) 方法用于正反序列化 LRC 歌词。**
+
+## 网易云逐字与 QQ 音乐逐字
+
+二者都是音乐平台私有的逐字歌词格式。网易云音乐使用 `.yrc` 作为扩展名，QQ 音乐使用 `.qrc` 作为扩展名。
+
+二者都使用开头的方括号标注行时间戳，格式均为 `[lineStart,lineDur]`。`lineStart` 为行起始时间，以毫秒计的整数；`lineDur` 是行持续时间，也是以毫秒计的整数。二者也均**不支持**类似 LRC 的重复行使用多个时间戳。
+
+在逐字的表现形式上二者有一些不同。
+
+- 网易云的 YRC 采用 `(sylStart,sylDur,0)text` 格式，先时间戳、后文本，时间戳括号内三个数分别是起始时间、持续时间、`0`。所有 YRC 格式歌词都带有这个 `0`，目前尚未发现其具体含义，可能是为未来扩展预留的字段。
+- QQ 音乐的 QRC 采用 `text(sylStart,sylDur)` 格式，先文本、后时间戳。并且没有 YRC 的 `0`。
+
+所有的开始时间均为**绝对时间**，即从音频开始到文本开始所经过的时间。
+
+下面是同一段歌词在两种格式下的示例：
+
+```
+# 网易云音乐 YRC
+[190871,1984](190871,361,0)For (191232,172,0)the (191404,376,0)first (191780,1075,0)time
+[193459,4198](193459,412,0)What's (193871,574,0)past (194445,506,0)is (194951,2706,0)past
+
+# QQ 音乐 QRC
+[190871,1984]For (190871,361)the (191232,172)first (191404,376)time(191780,1075)
+[193459,4198]What's (193459,412)past (193871,574)is (194445,506)past(194951,2706)
+```
+
+QRC 和 YRC **不具有**类似 LRC A2 的合并相邻空格特性。
+
+由于在文中夹注半角括号 `()` 的时间戳，那歌词文本中的圆括号应当如何转义？由于 YRC 和 QRC 都是私有文件格式，没有官方资料可查，于是我们查找这两个平台上的官方歌词：
+
+- 在我们目前处理到的所有 YRC 歌词中，所有的圆括号均为全角 `（）`，无论是中文还是其他语言
+- 在我们目前处理到的所有 QRC 歌词中，圆括号未做转译或替换
+
+因此根据现有样本推测：
+
+- YRC 实际上可能不允许在歌词文本中使用半角圆括号，若有需要应使用全角圆括号。本库也遵守这一原则，在导出为 YRC 时若歌词文本中存在半角圆括号，会自动替换为全角。
+- QRC 在匹配时间戳时会略过非时间戳的圆括号，将其作为歌词文本处理。
+
+YRC、QRC 也不支持为歌词添加翻译与音译。一般的做法是伴随提供 LRC 格式的翻译或音译。
+
+另外，本库在解析 YRC 与 QRC 歌词时，若整行被圆括号括起，则会将该行视为背景行并去除括号。
+
+**本库提供 [`parseYrc`](/reference/lyric/functionparseyrc) 和 [`stringifyYrc`](/reference/lyric/functionstringifyyrc) 方法用于正反序列化 YRC 歌词；提供 [`parseQrc`](/reference/lyric/functionparseqrc) 和 [`stringifyQrc`](/reference/lyric/functionstringifyqrc) 方法用于正反序列化 QRC 歌词。**
+
+特别地，QQ 音乐在分发 QRC 歌词时使用了一种加密格式。此格式为包含了 QRC 文本的 XML，经一种类 DES 算法加密后使用 base64 编码而成。**本库提供 [`decryptQrcHex`](/reference/lyric/functiondecryptqrchex) 函数用于解密这样的 base64 串为 XML 文本，提供 [`encryptQrcHex`](/reference/lyric/functionencryptqrchex) 函数用于将明文 XML 加密为 base64 串。**
+
+## Lyricify 系列格式
+
+[Lyricify](https://lyricify.app) 是一款优秀的逐字歌词展示软件。其定义了 Lyricify Lines、Lyricify Syllable 和 Lyricify 快速导出 三种私有格式。
+
+其中：
+
+- Lyricify Lines 为逐行歌词，扩展名 `.lyl`
+- Lyricify Syllable 为逐字歌词，扩展名 `.lys`，支持设置背景与对唱行
+
+这两种格式 [官方提供了文档说明](https://github.com/WXRIW/Lyricify-App/blob/main/docs/Lyricify%204/Lyrics.md#lyricify-lines-%E6%A0%BC%E5%BC%8F%E8%A7%84%E8%8C%83)。
+
+**本库提供 [`parseLyl`](/reference/lyric/functionparselyl) 和 [`stringifyLyl`](/reference/lyric/functionstringifylyl) 方法用于正反序列化 Lyricify Lines 歌词；提供 [`parseLys`](/reference/lyric/functionparselys) 和 [`stringifyLys`](/reference/lyric/functionstringifylys) 方法用于正反序列化 Lyricify Syllable 歌词。**
+
+Lyricify 快速导出格式扩展名为 `.lqe`（**L**yricify **Q**uick **E**xport 的缩写）。官方没有提供文档说明，但其内容比较易懂。以下说明基于对相关软件实际导出文件的分析，并非官方规范，也可能与未来版本存在差异。
+
+```
+[Lyricify Quick Export]
+[version:1.0]
+
+[lyrics: format@Lyricify Syllable]
+[4]A(365,350)ni(715,307)ro(1022,312)dham (1334,419)a(3203,337)nut(3540,350)pā(3890,306)dam(4196,382)
+[5]Qua(6206,312)e(6518,350)so (6868,370)do(7238,338)mi(7576,373)ne (7949,413)nos (8362,736)ple(9098,306)ne (9404,338)sal(9742,237)va (9979,244)tam(10223,350)
+[4]A(6164,1436)nuc(7600,744)che(8344,724)dam (9068,399)a(9467,293)śā(9760,240)śva(10000,225)tam(10225,893)
+[4]Hi (11851,812)ma(12663,344)ma (13007,369)ja(13376,263)gad (13639,237)i(13876,212)daṃ(14088,800)
+
+
+[translation: format@LRC]
+[00:00.365]不生亦不灭
+[00:06.206]主人啊，求你像这般，赐给我们完全的救恩
+[00:06.164]不常亦不断
+[00:11.851]此世已为我之世
+
+
+[pronunciation: format@LRC, language@romaji]
+[00:00.365]阿难罗昙 阿耨钵昙
+[00:06.164]阿耨遮昙 阿刹缚多
+[00:11.851]天摩诃满 荼揭谛檀
+```
+
+头部定义了文件版本信息。此后内容由几部分构成。`[lyrics: format@Lyricify Syllable]` 后携带 Lyricify Syllable 格式的逐字歌词，此后 `[translation: format@LRC]` 后携带 LRC 格式的翻译歌词、`[pronunciation: format@LRC, language@romaji]` 后携带 LRC 格式的罗马字音译歌词。
+
+需要注意的是，翻译或音译区块只包含存在内容的行。若某一行没有翻译或音译，则该区块中不会出现对应时间戳。
+
+可见 Lyricify 快速导出格式支持逐字时间、背景行、对唱行、翻译、音译。
+
+此外，也可以参考 Lyricify 开发者的项目 [Lyricify Lyrics Helper](https://github.com/WXRIW/Lyricify-Lyrics-Helper)，其中有 Lyricify 系列格式的解析与生成逻辑，并以 MIT 开源。
+
+**本库提供 [`parseLqe`](/reference/lyric/functionparselqe) 和 [`stringifyLqe`](/reference/lyric/functionstringifylqe) 方法用于正反序列化 Lyricify 快速导出。**
+
+## 总结表格
+
+| 格式 | 扩展名 | 逐行时间 | 逐字时间 | 原生翻译音译 | 原生背景对唱 |
+| ----------------- | --------------- | :------: | :------: | :----------: | :----------: |
+| TTML | `.ttml` | ✓ | ✓ | ✓ | ✓ |
+| LRC | `.lrc` | ✓ | ✕ | ✕ | ✕ |
+| LRC A2 扩展 | `.lrc`, `.alrc` | ✓ | ✓ | ✕ | ✕ |
+| 网易云逐字 | `.yrc` | ✓ | ✓ | ✕ | ✕ |
+| QQ 音乐逐字 | `.qrc` | ✓ | ✓ | ✕ | ✕ |
+| Lyricify Lines | `.lyl` | ✓ | ✕ | ✕ | ✕ |
+| Lyricify Syllable | `.lys` | ✓ | ✓ | ✕ | ✓ |
+| Lyricify 快速导出 | `.lqe` | ✓ | ✓ | ✓ | ✓ |
diff --git a/amll-local/packages/docs/src/content/docs/guides/lyric/quickstart.mdx b/amll-local/packages/docs/src/content/docs/guides/lyric/quickstart.mdx
new file mode 100644
index 0000000..1b6f574
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/lyric/quickstart.mdx
@@ -0,0 +1,104 @@
+---
+title: 快速开始
+---
+
+import PackageInstall from "#components/PackageInstall.astro";
+
+AMLL 提供两个 npm 包，用于歌词格式正反序列化：
+
+- [@applemusic-like-lyrics/lyric](https://www.npmjs.com/package/@applemusic-like-lyrics/lyric)
+ 主流各歌词格式的解析与生成库，例如 LRC、YRC、LQE 等，其中 TTML 正反解实际上依赖 @applemusic-like-lyrics/ttml。
+- [@applemusic-like-lyrics/ttml](https://www.npmjs.com/package/@applemusic-like-lyrics/ttml)
+ TTML 逐字歌词格式正反序列化库。提供最详细的信息，包括逐字音译等特色功能。
+
+## Lyric 包
+
+`
+- `... ` 元数据区
+- `` 歌词正文区
+
+命名空间：
+
+- `xmlns="http://www.w3.org/ns/ttml"`
+- `xmlns:ttm="http://www.w3.org/ns/ttml#metadata"`
+- `xmlns:itunes="http://music.apple.com/lyric-ttml-internal"`
+- `xmlns:amll="http://www.example.com/ns/amll"`
+- `xmlns:tts="http://www.w3.org/ns/ttml#styling"`（Ruby 需要）
+
+根属性：
+
+- `xml:lang`：歌词主语言（BCP-47，如 `ja`、`zh-Hans`、`en-US`）
+- `itunes:timing`：`Word`（逐字）或 `Line`（逐行）
+
+## 元数据
+
+TTML 元数据主要放在 `` 中，AMLL 里常见两类：
+
+1. `ttm:*` 元数据（TTML 标准）
+2. `amll:meta` 元数据（AMLL 扩展）
+
+例如：
+
+```xml
+
+ Song Title
+
+
+ Singer A
+
+
+
+```
+
+常见 `amll:meta` 键：
+
+- `musicName`、`artists`、`album`、`isrc`
+- 平台 ID：`ncmMusicId`、`qqMusicId`、`spotifyId`、`appleMusicId`
+- 贡献者：`ttmlAuthorGithub`、`ttmlAuthorGithubLogin`
+
+## 时间与模式
+
+时间一般通过 `begin` / `end` / `dur` 表达，单位支持：
+
+- 时钟格式：`MM:SS.fff`、`HH:MM:SS.fff`，小数点后可保留 1~3 位或不保留
+- 秒值格式：`12.3s`
+
+`itunes:timing="Word"`（逐字）时：
+
+- `` 表示行
+- 行内多个带时间戳的 `` 表示字词
+
+`itunes:timing="Line"`（逐行）时：
+
+- 主要依赖 `整行文本
`
+- 内部 `span` 的逐字时间通常不使用
+
+## 正文结构与扩展角色
+
+正文结构一般为：
+
+```xml
+
+
+
+```
+
+常见属性与约定：
+
+- `itunes:key="L1"`：行唯一 ID（通常 `L1`、`L2`...）
+- `ttm:agent="v1"`：对应 ``
+- `itunes:song-part`：段落信息（如 `Verse`、`Chorus`）
+
+行内辅助信息通过 `ttm:role` 标记：
+
+- `x-translation`：翻译
+- `x-roman`：音译/罗马音
+- `x-bg`：背景人声
+
+示例：
+
+```xml
+
+ コーラス
+ です
+
+
+ (背景)
+ Background
+ haikei
+
+
+```
+
+## Apple Music 风格翻译音译
+
+除了把翻译/音译写在行内，也可以放在 ``：
+
+```xml
+
+
+
+ 第一行翻译
+
+
+
+
+ dai ichi gyou
+
+
+
+```
+
+其中 `for="L1"` 会关联到正文中的 `itunes:key="L1"`。
+
+## Ruby 注音
+
+AMLL 支持 TTML Ruby 结构（`tts:ruby`），适合日语振假名、拼音等：
+
+- `tts:ruby="container"`：整个 Ruby 容器
+- `tts:ruby="base"`：基文本
+- `tts:ruby="textContainer"`：注音容器
+- `tts:ruby="text"`：注音文本（可带时间）
+
+```xml
+
+ 所
+
+ しょ
+
+
+
+ 詮
+
+ せ
+ ん
+
+
+```
+
+## 与本库的实现对齐
+
+本库中的解析/导出实现有如下行为：
+
+- 同时兼容 `itunes:songPart` 与 `itunes:song-part`，导出时优先 `song-part`
+- 可解析并保留 `amll:obscene`、`amll:empty-beat`
+- 背景人声文本可带/不带括号，解析时会做清理
+- 可同时合并行内翻译与 Head Sidecar 翻译（同语言可能出现重复，需业务侧去重）
+- 在无逐字但有行时间戳时，可回退为单词级占位词条，避免信息丢失
diff --git a/amll-local/packages/docs/src/content/docs/guides/overview/eco.md b/amll-local/packages/docs/src/content/docs/guides/overview/eco.md
new file mode 100644
index 0000000..f316a44
--- /dev/null
+++ b/amll-local/packages/docs/src/content/docs/guides/overview/eco.md
@@ -0,0 +1,61 @@
+---
+title: 生态
+---
+
+经过一段时间的发展，AMLL 建立起了一个围绕逐字歌词的开源生态，包含逐字歌词库、编辑器、音乐播放器等。
+
+## 第一方生态
+
+第一方生态是指在 GitHub 上以 [amll-dev](https://github.com/amll-dev/) 组织下的仓库。以下项目的内容与文档均各自独立维护，问题反馈请至各仓库处理。
+
+### AMLL TTML Database
+
+[AMLL TTML Database](https://github.com/amll-dev/amll-ttml-db) 是一个高质量的开放逐字歌词数据库。其中的歌词均由社区贡献并经过审核，以 [CC0-1.0](https://github.com/amll-dev/amll-ttml-db/blob/main/LICENSE) 协议公开。
+
+如果你正在制作音乐播放器，可以将其作为歌词源。你也可以制作逐字歌词并提交到歌词库中。有关提交与使用的相关说明，请转到其 [仓库 wiki](https://github.com/amll-dev/amll-ttml-db/wiki)。
+
+### AMLL TTML Tool
+
+[AMLL TTML Tool](https://github.com/amll-dev/amll-ttml-tool) 是基于 React 编写的逐字歌词编辑器，涵盖歌词内容编辑、打轴等功能。歌词库中大部分逐字歌词均使用此工具制作。
+
+
+
+其部署在 Internal Server Error - MistAperio Gitea
500 Internal Server Error