歌词场面实战

歌词场面（lyrics-style）不写 JavaScript，用 JSON 描述「槽位怎么摆」。本页以 cinema 影院台为例。JSON 概览 → JSON 内容。

成品长什么样

大封面模糊背景 + 底部歌词区
宿主 迷你播放条隐藏，场面自己提供 prev / play / next
词行可带逐词高亮、译文（取决于 slot options）

官方示例：examples/lyrics-cinema-scene/。

node .\bin\echo-workshop-sdk.mjs example lyrics-cinema-scene .\cinema
cd .\cinema
npm run dev

新建与 preset

node .\bin\echo-workshop-sdk.mjs init .\my-lyrics --recipe cinema-lyrics
# 或其它 preset：editorial | compact | cover
npm run set -- --background cover-blur
npm run set -- --style cinema

preset	适合
`editorial`	封面 + 歌词网格（默认）
`compact`	一行封面标题，省空间
`cinema`	大屏影院感，常藏迷你条
`cover`	大封面柱

已有项目换外形：scaffold . --preset cinema（保留 id / 标题）。

场景树怎么读

content/lyrics-style.json 里 scene.root 是一棵 group / slot 树：

{
  "scene": {
    "background": "cover-blur",
    "hostChrome": { "miniPlayer": "hidden" },
    "root": {
      "type": "group",
      "style": { "display": "flex", "flexDirection": "column", "padding": "48px" },
      "children": [
        { "type": "slot", "slot": "title", "style": { "fontSize": "32px" } },
        { "type": "slot", "slot": "lyrics", "options": { "wordHighlightEnabled": true } },
        {
          "type": "group",
          "children": [
            { "type": "slot", "slot": "previous-track" },
            { "type": "slot", "slot": "play-toggle" },
            { "type": "slot", "slot": "next-track" }
          ]
        }
      ]
    }
  }
}

概念	说明
`group`	布局容器，用白名单 CSS（flex、gap、padding 等）
`slot`	引用宿主提供的 UI 块，不能自创控件类型
`hostChrome.miniPlayer: hidden`	藏宿主迷你条 → 必须自带 `play-toggle`
`responsive.compact`	窄屏覆盖样式

常用 slot 速查

cover · title · artist · album · lyrics · current-line · previous-line · next-line · translation · progress · seek-bar · time-current · time-duration · spectrum · play-toggle · previous-track · next-track · volume-slider · shuffle-toggle · repeat-cycle · like-toggle · status · track-tech

详细规则：

node .\bin\echo-workshop-sdk.mjs guide lyrics

设置项（settings）

同文件里的 settings 控制宿主歌词行为，例如：

{
  "settings": {
    "lyricsPageStyle": "cinemaStage",
    "lyricsWordHighlightEnabled": true,
    "lyricsMusicReactiveVisualsEnabled": true,
    "lyricsFontSizePx": 48,
    "lyricsBackgroundMode": "cover"
  }
}

改字号、背景模式等用 set 或手改 JSON，然后 check。

用 `add` 加槽位

宿主允许时，不必手改整棵树：

npm run add -- --slot spectrum
npm run next

next 会列出当前 kind 还能加哪些 slot。

调试与预览

npm run check — 校验 slot 名、隐藏迷你条时是否有 play-toggle
npm run dev — 打开 fixture 预览（不是真歌频谱，但布局准）
发布后在 ECHO 歌词页切换到你的场面

	lyrics-style（本页）	歌词插件（lyrics-source）
格式	JSON 场面	`plugin.js` provider
作用	排版与样式	提供歌词候选文本
教程	本页	插件教程 · 进阶

两者可以同时存在：一个负责找词，一个负责怎么显示。

发布前检查

藏了 miniPlayer → 有 play-toggle（及需要的 transport）
slot 名全在白名单内
npm run quality 无 blocker
预览图与描述说明适合什么听歌场景