Skip to main content
Version: 16.x

How to add artwork

You can add your own artwork for folders and playlists so your frontend shows custom thumbnails instead of generic default images.

This guide explains:

  • which image formats are supported
  • how to name artwork files
  • where to place those files
  • what happens when a playlist image is missing

Supported image formats​

The following file types are supported and checked in this order. The first matching image file is used:

  • webp
  • png
  • jpeg
  • jpg
  • bmp
  • gif

You can use any one of these formats for both folder artwork and playlist artwork.

Folder​

To set artwork for a folder, place an image file named folder.ext inside that folder.

Replace .ext with one of the supported extensions.

Examples:

  • folder.webp
  • folder.jpg
  • folder.png

Playlists​

To set artwork for a playlist, use the same base filename as the playlist file.

Example:

  • Playlist file: Jazz.m3u8
  • Artwork file: Jazz.jpg (or Jazz.webp, Jazz.png, and so on)

If a matching playlist artwork file is not found, the folder artwork is used as a fallback.

Example folder structure​

Use this as a reference:

Music/
|-- folder.jpg
|-- Jazz/
|   |-- folder.png
|   |-- Jazz.m3u8
|   |-- Jazz.jpg
|   |-- Smooth.m3u8
|   `-- smooth-track01.mp3
`-- Rock/
    |-- folder.webp
    |-- RockHits.m3u8
    `-- track01.mp3

In this example:

  • Music/folder.jpg is the artwork for the top-level Music folder.
  • Music/Jazz/folder.png is the artwork for the Jazz folder.
  • Music/Jazz/Jazz.jpg is used for the Jazz.m3u8 playlist.
  • Music/Jazz/Smooth.m3u8 has no matching Smooth.* image, so the Jazz folder artwork is used.

Web streams inside a playlist​

The naming rules above work because there is a file to put the image next to. An internet radio station or any other web address listed in a playlist has no such file, so it needs a different way to carry its artwork: a #EXTIMG: line that points at the picture.

Put the line directly above the entry it belongs to, the same way #EXTINF: works. It applies to the next entry only, so each stream gets its own line:

#EXTM3U
#EXTINF:-1,Jazz Radio
#EXTIMG:https://example.com/stations/jazz-radio.png
http://stream.example.com/jazz.mp3

#EXTINF:-1,Rock Radio
#EXTIMG:https://example.com/stations/rock-radio.jpg
http://stream.example.com/rock.mp3

UMS downloads the image once, stores it, and uses it for that stream from then on. It does not fetch it again on every start.

What the line accepts:

  • An absolute address. https://example.com/cover.png works, cover.png and ../art/cover.png do not — a relative path is ignored and the stream keeps the default image.
  • A data: URI, if you would rather keep the picture inside the playlist file than host it somewhere.
  • Only .m3u and .m3u8 playlists. Other playlist formats have no place to put the line.

Capitalization of the directive itself does not matter, #EXTIMG: and #extimg: both work.

Letting UMS write the line for you​

If your control point can set the artwork of an entry, you do not have to edit the playlist by hand. UMS writes the #EXTIMG: line into the playlist file itself, and only after it has successfully loaded the picture — so a broken address leaves the file untouched instead of storing a dead link.

Because the artwork then lives in the playlist file rather than only in the database, it survives a rebuilt database and travels with the file when you copy the playlist elsewhere.