> ## 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.

# Add songs and playlists to the music radio

> Curate playlists, add song metadata and lyrics, and configure radio playback behavior in lib/music-config.ts to build a personalized music experience.

The `lib/music-config.ts` file defines everything the Birthday Wall radio page plays and displays. You can organize songs into named playlists, attach cover art and background images, embed lyrics that float across the screen, and write personal messages that appear on each song card. You can also tune the radio's global behavior — such as whether lyrics are visible or what the default volume is.

## `Song` fields

Each entry in a playlist's `songs` array must conform to the `Song` interface:

<ParamField path="title" type="string" required>
  The song title displayed on the song card, in the now-playing bar, and in the year-end report.
</ParamField>

<ParamField path="artist" type="string" required>
  The performing artist's name. Shown beneath the title on song cards and used to populate artist stats in the report view.
</ParamField>

<ParamField path="album" type="string">
  The album the track belongs to. Displayed as supplementary metadata on the song detail page.
</ParamField>

<ParamField path="duration" type="string">
  A human-readable duration string such as `"4:12"`. The radio does not enforce this value programmatically — it is purely decorative metadata shown on the card.
</ParamField>

<ParamField path="coverUrl" type="string">
  A fully qualified URL pointing to the album or cover art image. When omitted, the radio uses a default placeholder image.
</ParamField>

<ParamField path="lyrics" type="string">
  Lyric lines separated by `\n`. These lines are rendered as animated floating text in the radio and report views. Keep each line short for the best visual effect.
</ParamField>

<ParamField path="backgroundUrl" type="string">
  A fully qualified URL for the full-bleed background image shown on the song detail and report pages. Unsplash URLs work well here.
</ParamField>

<ParamField path="description" type="string">
  A personal message written to the celebrant. Displayed on the song card inside the radio and on the corresponding section of the report. This is a great place to explain why you chose each song.
</ParamField>

## `Playlist` fields

Songs are grouped into playlists. Each playlist object has:

<ParamField path="id" type="string" required>
  A unique slug used internally to look up the playlist (e.g. `"favorite-songs"`). Use lowercase letters and hyphens only.
</ParamField>

<ParamField path="name" type="string" required>
  The human-readable playlist name shown as the card title in the radio UI.
</ParamField>

<ParamField path="description" type="string">
  A subtitle shown beneath the playlist card. Use it to set context — for example, `"Her favorite songs"`.
</ParamField>

<ParamField path="songs" type="Song[]" required>
  The ordered array of `Song` objects belonging to this playlist. Songs are displayed in the order they appear in the array.
</ParamField>

## Radio preferences (`musicConfig.preferences`)

The `preferences` object stores metadata that surfaces as stats in the year-end report view:

| Field            | Purpose                                                       |
| ---------------- | ------------------------------------------------------------- |
| `favoriteGenre`  | Shown as the celebrant's favorite music genre stat            |
| `mood`           | Shown as the emotional mood stat for the music collection     |
| `favoriteArtist` | Stored as metadata; currently displayed in the report summary |

## Radio settings (`musicConfig.radio`)

<ParamField path="radio.enabled" type="boolean">
  Set to `false` to disable the radio page entirely. Defaults to `true`.
</ParamField>

<ParamField path="radio.autoplay" type="boolean">
  When `true`, the radio attempts to begin playback on page load. Note: this field is not currently wired to actual audio playback — it is reserved for future use.
</ParamField>

<ParamField path="radio.showLyrics" type="boolean">
  Controls whether the floating lyric snippets are rendered over the radio background. Set to `false` to disable the effect.
</ParamField>

<ParamField path="radio.defaultVolume" type="number">
  The initial volume level as an integer from `0` to `100`. Defaults to `70`.
</ParamField>

## Adding a new song

To add a song to an existing playlist, append a new object to that playlist's `songs` array:

```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>
  Lyrics are shown as floating snippets over the radio background. Keep each line under 15 characters for the best visual effect — longer lines may overflow or wrap awkwardly on smaller screens.
</Tip>