> ## Documentation Index
> Fetch the complete documentation index at: https://help.helloazhenweb.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 为音乐电台添加歌曲与歌单

> 在 lib/music-config.ts 中整理歌单、添加歌曲元数据与歌词、配置电台播放行为，打造一份个性化的音乐体验。

`lib/music-config.ts` 文件定义了 Birthday Wall 电台页面要播放和展示的所有内容。你可以把歌曲组织进命名好的歌单、附加封面图和背景图、嵌入会在屏幕上漂浮的歌词，以及为每首歌写下出现在歌曲卡片上的个人留言。你还可以调整电台的全局行为 — 比如是否显示歌词、默认音量是多少。

## `Song` 字段

每个歌单 `songs` 数组中的条目都必须符合 `Song` 接口：

<ParamField path="title" type="string" required>
  显示在歌曲卡片、正在播放条以及年终报告中的歌曲标题。
</ParamField>

<ParamField path="artist" type="string" required>
  演唱者姓名。显示在歌曲卡片上的标题下方，并被用来填充报告中的艺人统计。
</ParamField>

<ParamField path="album" type="string">
  歌曲所属的专辑。作为补充元数据显示在歌曲详情页中。
</ParamField>

<ParamField path="duration" type="string">
  一个人类可读的时长字符串，如 `"4:12"`。电台不会以编程方式校验这个值 — 它只是显示在卡片上的装饰性元数据。
</ParamField>

<ParamField path="coverUrl" type="string">
  指向专辑或封面图的完整 URL。省略时，电台会使用默认的占位图。
</ParamField>

<ParamField path="lyrics" type="string">
  以 `\n` 分隔的歌词行。这些歌词会在电台和报告页中以漂浮文字的形式呈现。每行尽量短，视觉效果最佳。
</ParamField>

<ParamField path="backgroundUrl" type="string">
  在歌曲详情页和报告页中显示的全屏背景图的完整 URL。Unsplash 的 URL 在这里效果不错。
</ParamField>

<ParamField path="description" type="string">
  写给寿星的一段个人留言。显示在电台中的歌曲卡片上和报告对应歌曲的段落中。这里是解释你为什么挑选这首歌的好地方。
</ParamField>

## `Playlist` 字段

歌曲会被组织进歌单。每个歌单对象包含：

<ParamField path="id" type="string" required>
  在内部用来查找歌单的唯一 slug（如 `"favorite-songs"`）。只使用小写字母和连字符。
</ParamField>

<ParamField path="name" type="string" required>
  在电台 UI 中作为卡片标题显示的人类可读歌单名。
</ParamField>

<ParamField path="description" type="string">
  显示在歌单卡片下方的副标题。可以用来交代背景 — 例如 `"Her favorite songs"`。
</ParamField>

<ParamField path="songs" type="Song[]" required>
  属于此歌单的 `Song` 对象数组（有序）。歌曲按数组中的顺序显示。
</ParamField>

## 电台偏好 (`musicConfig.preferences`)

`preferences` 对象保存的元数据会作为统计数据在年终报告中展示：

| 字段               | 用途                 |
| ---------------- | ------------------ |
| `favoriteGenre`  | 作为寿星的最爱音乐风格统计显示    |
| `mood`           | 作为音乐合集的情绪统计显示      |
| `favoriteArtist` | 作为元数据存储；目前显示在报告概要中 |

## 电台设置 (`musicConfig.radio`)

<ParamField path="radio.enabled" type="boolean">
  设为 `false` 可完全禁用电台页面。默认为 `true`。
</ParamField>

<ParamField path="radio.autoplay" type="boolean">
  设为 `true` 时，电台会在页面加载时尝试自动开始播放。注意：该字段目前未接入真正的音频播放，保留供未来使用。
</ParamField>

<ParamField path="radio.showLyrics" type="boolean">
  控制是否在电台背景上渲染漂浮歌词片段。设为 `false` 可关闭该效果。
</ParamField>

<ParamField path="radio.defaultVolume" type="number">
  初始音量，取值为 `0` 到 `100` 的整数。默认为 `70`。
</ParamField>

## 添加一首新歌

要向现有歌单添加歌曲，向该歌单的 `songs` 数组追加一个新对象：

```typescript theme={null}
export const musicConfig = {
  preferences: {
    favoriteGenre: "Pop",
    mood: "Uplifting",
    favoriteArtist: "Taylor Swift",
  },

  playlists: [
    {
      id: "favorite-songs",
      name: "Alex's Playlist",
      description: "Songs picked just for you",
      songs: [
        // existing songs ...
        {
          title: "Love Story",
          artist: "Taylor Swift",
          album: "Fearless",
          duration: "3:55",
          coverUrl: "https://example.com/covers/love-story.jpg",
          backgroundUrl: "https://images.unsplash.com/photo-1516802273409-68526ea71b98?q=80&w=2000",
          lyrics: "You were Romeo\nI was a scarlet letter\nAnd my daddy said stay away\nfrom Juliet",
          description: "This one always reminds me of you — happy birthday, Alex!",
        },
      ],
    },
  ],

  radio: {
    enabled: true,
    autoplay: false,
    showLyrics: true,
    defaultVolume: 70,
  },
};
```

<Tip>
  歌词会作为漂浮片段显示在电台背景上。为获得最佳视觉效果，每行最好不超过 15 个字符 — 过长的行可能会在小屏幕上溢出或换行错乱。
</Tip>