> For the complete documentation index, see [llms.txt](https://bonsai-docs.gitbook.io/bonsai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bonsai-docs.gitbook.io/bonsai-docs/bonsai-radio/media-setup/song-metadata-and-covers.md).

# Song Metadata and Covers

## Song Metadata and Covers

Bonsai Radio allows you to provide custom information for each song.

Metadata can include:

* Song title
* Artist name
* Cover image

This information can be shown by the radio interface while the song is playing.

### Important: Do Not Edit the Metadata Template

When the media scanner runs, it creates or updates:

```
data/metadata_template.lua
```

This file contains ready-made metadata entries for the tracks found by the scanner.

{% hint style="warning" %}
Do not permanently edit metadata inside `metadata_template.lua`.\
The file may be regenerated when `scan_media.bat` is run, which can overwrite your changes.
{% endhint %}

The correct workflow is:

```
1. Run scan_media.bat
2. Open metadata_template.lua
3. Copy the required track entries
4. Paste them into config.lua
5. Edit the metadata inside config.lua
```

Metadata stored in `config.lua` will not be replaced by the scanner.

### Step 1: Run the Media Scanner

Add your music files to the correct station folders and run:

```
auto_scan_media.bat
```

The scanner will detect the tracks and generate metadata templates for them.

Open:

```
metadata_template.lua
```

You will see entries similar to:

```
['johndoe_loremipsum.mp3'] = {
    title = '',
    artist = '',
    cover = ''
},
```

### Step 2: Copy the Track Template

Copy the complete entry for the track you want to configure.

Example:

```
['johndoe_loremipsum.mp3'] = {
    title = '',
    artist = '',
    cover = ''
},
```

Do not edit the entry directly inside `metadata_template.lua`.

### Step 3: Paste It Into config.lua

Open:

```
config.lua
```

Find the metadata configuration section.

Paste the copied track entry inside the table:

```
Config.Metadata = {
    ['johndoe_loremipsum.mp3'] = {
        title = '',
        artist = '',
        cover = ''
    }
}
```

{% hint style="warning" %}
Make sure the entry is placed inside the correct metadata table in `config.lua`.
{% endhint %}

### Step 4: Enter the Track Information

Edit the copied entry inside `config.lua`.

Example:

```
Config.Metadata = {
    ['johndoe_loremipsum.mp3'] = {
        title = 'Lorem Ipsum',
        artist = 'John Doe',
        cover = ''
    }
}
```

The filename must exactly match the real audio filename.

This includes:

* Uppercase and lowercase letters
* Spaces
* Underscores
* Special characters
* File extension

For an OGG file:

```
Config.Metadata = {
    ['johndoe_loremipsum.ogg'] = {
        title = 'Lorem Ipsum',
        artist = 'John Doe',
        cover = ''
    }
}
```

### Adding Metadata for Multiple Tracks

Copy each required entry from `metadata_template.lua` and place them inside the metadata table in `config.lua`.

Example:

```
Config.Metadata = {
    ['johndoe_loremipsum.ogg'] = {
        title = 'Lorem Ipsum',
        artist = 'John Doe',
        cover = ''
    },

    ['johndoe_loremipsum.mp3'] = {
        title = 'Lorem Ipsum',
        artist = 'John Doe',
        cover = ''
    },

    ['johndoe_loremipsum.mp3'] = {
        title = 'Lorem Ipsum',
        artist = 'John Doe',
        cover = ''
    }
}
```

{% hint style="warning" %}
Each entry must be separated by a comma.
{% endhint %}

### Adding a Cover Image

Place the cover image inside the appropriate Bonsai Radio image folder.

For example:

```
html/images/covers/johndoe_loremipsum.jpg
```

Then enter the relative image path in the track metadata:

```
Config.Metadata = {
    ['johndoe_loremipsum.mp3'] = {
        title = 'Location',
        artist = 'Werenoi',
        cover = 'images/covers/johndoe_loremipsum.jpg'
    }
}
```

Recommended image formats:

* `.jpg`
* `.jpeg`
* `.png`
* `.webp`

### Cover Image Recommendations

For the best result:

* Use square images.
* Use consistent dimensions.
* Compress large image files.
* Use lowercase filenames.
* Avoid spaces and unusual symbols.
* Keep the image inside the Bonsai Radio resource.

Recommended dimensions:

```
512 × 512 pixels
```

Recommended filename:

```
johndoe_loremipsum.jpg
```

### Leaving Metadata Empty

Any metadata value may remain empty.

```
Config.Metadata = {
    ['UnknownSong.mp3'] = {
        title = '',
        artist = '',
        cover = ''
    }
}
```

Bonsai Radio will use its configured fallback behaviour when metadata is unavailable.

{% hint style="info" %}
The scanner does not automatically determine the correct track title, artist or cover image. These values should be entered manually in `config.lua`.
{% endhint %}

### Adding New Music Later

When adding more tracks:

1. Add the audio files to the correct station folder.
2. Run `auto_scan_media.bat`.
3. Open the updated `metadata_template.lua`.
4. Copy only the new track entries.
5. Paste them into the metadata table in `config.lua`.
6. Add the title, artist and cover information.
7. Restart Bonsai Radio.

{% hint style="warning" %}
Do not replace your existing metadata table with the newly generated template.\
Only copy the new entries that are missing from `config.lua`.
{% endhint %}

### Removing a Track

When removing a song:

1. Delete the audio file.
2. Run `scan_media.bat`.
3. Remove the matching metadata entry from `config.lua`.
4. Restart Bonsai Radio.

The scanner removes the audio file from the generated media library, but custom metadata inside `config.lua` should be removed manually.

### Applying Metadata Changes

After changing metadata inside `config.lua`, restart Bonsai Radio:

```
refresh
restart rs_radio
```

Running the scanner again is only necessary when audio files have been:

* Added
* Removed
* Renamed
* Moved

Changing only a title, artist or cover in `config.lua` does not require another media scan.

### Metadata Not Appearing

Check the following:

* The entry is inside `config.lua`, not only `metadata_template.lua`.
* The filename exactly matches the audio file.
* The correct file extension is used.
* The entry is inside the correct metadata table.
* The Lua table syntax is valid.
* Every entry is separated by a comma.
* The cover path points to an existing image.
* Bonsai Radio was restarted after the change.

### Recommended Workflow

```
Add audio files
      ↓
Run auto_scan_media.bat
      ↓
Open metadata_template.lua
      ↓
Copy the required track entries
      ↓
Paste them into config.lua
      ↓
Add titles, artists and covers
      ↓
Restart Bonsai Radio
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bonsai-docs.gitbook.io/bonsai-docs/bonsai-radio/media-setup/song-metadata-and-covers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.