starred/koel-koel

Fork 0

mirror of https://github.com/koel/koel.git synced 2026-04-25 08:46:00 +03:00

[GH-ISSUE #2038] Koel does not see song covers #1077

New issue

Closed

opened 2026-02-26 02:35:09 +03:00 by kerem · 7 comments

kerem commented

2026-02-26 02:35:09 +03:00

Owner

Originally created by @mfioretti on GitHub (Jul 30, 2025).
Original GitHub issue: https://github.com/koel/koel/issues/2038

Greetings,

I just set up Koel v7.10.3 Community Edition with docker compose on an Ubuntu 22.04 LTS box, with these setttings to make it see the songs and covers I already had on my hard drive:

volumes:
  db:
    driver: local
  music:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: '/home/koel/music'
  covers:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: '/home/koel/covers'
  search_index:
    driver: local

The files in the covers folders have the same names as the ones in the music folder e.g. song1.mp3 -> song1.jpg, song2.mp3 -> song2.jpg and so on. Not all songs have covers yet, however.

Koel does find and plays the songs, but does not show the covers that exist, just the default icon. I HAVE searched before asking, and found other instances of this problem, but they are all several years old, and judging from the comments they seemed solved. What is happening, and how could I fix it?

Thanks

Originally created by @mfioretti on GitHub (Jul 30, 2025). Original GitHub issue: https://github.com/koel/koel/issues/2038 Greetings, I just set up Koel v7.10.3 Community Edition with docker compose on an Ubuntu 22.04 LTS box, with these setttings to make it see the songs and covers I already had on my hard drive: ``` volumes: db: driver: local music: driver: local driver_opts: type: 'none' o: 'bind' device: '/home/koel/music' covers: driver: local driver_opts: type: 'none' o: 'bind' device: '/home/koel/covers' search_index: driver: local ``` The files in the covers folders have the same names as the ones in the music folder e.g. song1.mp3 -> song1.jpg, song2.mp3 -> song2.jpg and so on. Not all songs have covers yet, however. Koel does find and plays the songs, but does not show the covers that exist, just the default icon. I HAVE searched before asking, and found other instances of this problem, but they are all several years old, and judging from the comments they seemed solved. What is happening, and how could I fix it? Thanks

kerem closed this issue

2026-02-26 02:35:09 +03:00

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@phanan commented on GitHub (Aug 4, 2025):

Koel doesn't have the feature of realizing cover files from the song names like you described — not sure where you read that from. It does, however, recognize files with the standard RegEx pattern of '/(cov|fold)er\.(jpe?g|png)$/i' in the same directory as the songs, but only during scanning.

@phanan commented on GitHub (Aug 4, 2025): Koel doesn't have the feature of realizing cover files from the song names like you described — not sure where you read that from. It does, however, recognize files with the standard RegEx pattern of `'/(cov|fold)er\.(jpe?g|png)$/i'` in the same directory as the songs, but only during scanning.

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@mfioretti commented on GitHub (Aug 4, 2025):

Koel doesn't have the feature of realizing cover files from the song names like you described — not sure where you read that from.

By you the developers, right here on Github at https://github.com/koel/docker . If Koel doesn't find covers that way, then why on Earth the page https://github.com/koel/docker lists music and covers as separate volumes right after "Create the koel container on the same network so they can communicate"?

And why does the Docker Compose file at https://github.com/koel/docker/blob/master/docker-compose.mysql.yml , which is the one I used as template, only changing the paths, have a separate "covers" folder?

Also, even this doesn't work:

It does, however, recognize files with the standard RegEx pattern of '/(cov|fold)er\.(jpe?g|png)$/i' in the same directory as the songs, but only during scanning.

After reading your answer, I copied to the "music" folders two covers I had in "covers", then clicked on Settings and then on Scan /music, and Koel did not find those two covers. I logged into the container, run "php artisan koel:scan" and even then nothing changed, as you can see in the screenshots. What now?

@mfioretti commented on GitHub (Aug 4, 2025): > Koel doesn't have the feature of realizing cover files from the song names like you described — not sure where you read that from. By you the developers, right here on Github at https://github.com/koel/docker . If Koel doesn't find covers that way, then why on Earth the page https://github.com/koel/docker lists music and covers as separate volumes right after "Create the koel container on the same network so they can communicate"? And why does the Docker Compose file at https://github.com/koel/docker/blob/master/docker-compose.mysql.yml , which is the one I used as template, only changing the paths, have a separate "covers" folder? Also, even this doesn't work: > It does, however, recognize files with the standard RegEx pattern of `'/(cov|fold)er\.(jpe?g|png)$/i'` in the same directory as the songs, but only during scanning. After reading your answer, I copied to the "music" folders two covers I had in "covers", then clicked on Settings and then on Scan /music, and Koel did not find those two covers. I logged into the container, run "php artisan koel:scan" and even then nothing changed, as you can see in the screenshots. What now? <img width="566" height="790" alt="Image" src="https://github.com/user-attachments/assets/b228ca7c-5dc0-486d-b8d0-b9c5cc1f1579" /> <img width="384" height="374" alt="Image" src="https://github.com/user-attachments/assets/fa5ebe7a-7812-494f-9e14-3cf4e843fd54" />

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@phanan commented on GitHub (Aug 4, 2025):

Sorry it didn't work exactly the way you expected :) Let me explain:
For Docker, music and covers are two volumes because they are stored in different folders. When scanning, Koel will attempt to extract the cover from the music file and, when found, store it under public/img/covers. Making this folder a volume prevents it from being destroyed.
Now, regarding the pattern, the way it works is: during scanning, Koel attempts to find a cover.jpg or folder.jpg (or png) in the same directory as the music files. Imagine you have a folder like this:

Queen - A Night at the Opera
└── Death on Two Legs.mp3
└── Lazing on a Sunday Afternoon.mp3
└── cover.jpg

When scanning this directory, Koel will fetch the cover.jpg file and copy it into public/img/covers.
Hope this helps!

@phanan commented on GitHub (Aug 4, 2025): Sorry it didn't work exactly the way you expected :) Let me explain: For Docker, `music` and `covers` are two volumes because they are stored in different folders. When scanning, Koel will attempt to extract the cover from the music file and, when found, store it under `public/img/covers`. Making this folder a volume prevents it from being destroyed. Now, regarding the pattern, the way it works is: during scanning, Koel attempts to find a `cover.jpg` or `folder.jpg` (or png) in the same directory as the music files. Imagine you have a folder like this: ``` Queen - A Night at the Opera └── Death on Two Legs.mp3 └── Lazing on a Sunday Afternoon.mp3 └── cover.jpg ``` When scanning this directory, Koel will fetch the cover.jpg file and copy it into `public/img/covers`. Hope this helps!

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@mfioretti commented on GitHub (Aug 4, 2025):

Sorry it didn't work exactly the way you expected :) Let me explain: For Docker, music and covers are two volumes because they are stored in different folders. When scanning, Koel will attempt to extract the cover from the music file and, when found, store it under public/img/covers. Making this folder a volume prevents it from being destroyed.

OK. Please update the github page and the documentation to include this in capital letters, because as it is now it is going to mislead many more people as it happened to me.

This said... it still doesn't work. Right now, that is after I:

copied the two covers I have in the music folder as you explained, and
ran the scan again, and with the -F option too

the public/img/covers folder DOES indeed contain copies of those two covers:

~/html$ find /var/www/html/public/img/covers/ -type f | sort
/var/www/html/public/img/covers/prince of pilsen.jpg
/var/www/html/public/img/covers/vedi-le-fosche-notturne-spoglie.jpg

but, those two songs still get the default Koel icon, not their covers

@mfioretti commented on GitHub (Aug 4, 2025): > Sorry it didn't work exactly the way you expected :) Let me explain: For Docker, `music` and `covers` are two volumes because they are stored in different folders. When scanning, Koel will attempt to extract the cover from the music file and, when found, store it under `public/img/covers`. Making this folder a volume prevents it from being destroyed. OK. Please update the github page and the documentation to include this in capital letters, because as it is now it is going to mislead many more people as it happened to me. This said... it still doesn't work. Right now, that is after I: - copied the two covers I have in the music folder as you explained, and - ran the scan again, and with the -F option too the public/img/covers folder **DOES** indeed contain copies of those two covers: ``` ~/html$ find /var/www/html/public/img/covers/ -type f | sort /var/www/html/public/img/covers/prince of pilsen.jpg /var/www/html/public/img/covers/vedi-le-fosche-notturne-spoglie.jpg ``` but, those two songs still get the default Koel icon, not their covers

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@phanan commented on GitHub (Aug 4, 2025):

OK. Please update the github page and the documentation to include this in capital letters, because as it is now it is going to mislead many more people as it happened to me.

A PR is always welcome ;)

This said... it still doesn't work.

I still don't think you get it. The file name must be cover.jpg, folder.jpg, cover.png, or folder.png for Koel to recognize it, as this's a standard pattern (where the album cover file is named cover.jpg in the same folder as the music file). When extracting/copying the covers, Koel generates and uses a random file name (ULID), e.g. 01k1txt0ekfp5mkbhxz6yfe6r0.webp, so while I'm not sure where covers/prince of pilsen.jpg comes from, it certainly isn't Koel's work.

@phanan commented on GitHub (Aug 4, 2025): > OK. Please update the github page and the documentation to include this in capital letters, because as it is now it is going to mislead many more people as it happened to me. A PR is always welcome ;) > This said... it still doesn't work. I still don't think you get it. The file name must be `cover.jpg`, `folder.jpg`, `cover.png`, or `folder.png` for Koel to recognize it, as this's a standard pattern (where the album cover file is named `cover.jpg` in the same folder as the music file). When extracting/copying the covers, Koel generates and uses a random file name (ULID), e.g. `01k1txt0ekfp5mkbhxz6yfe6r0.webp`, so while I'm not sure where `covers/prince of pilsen.jpg` comes from, it certainly isn't Koel's work.

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@phanan commented on GitHub (Aug 4, 2025):

This is the original FR btw: https://github.com/koel/koel/issues/380.

@phanan commented on GitHub (Aug 4, 2025): This is the original FR btw: https://github.com/koel/koel/issues/380.

kerem commented

2026-02-26 02:35:10 +03:00

Author

Owner

@mfioretti commented on GitHub (Aug 4, 2025):

The file name must be cover.jpg, folder.jpg, cover.png, or folder.png for Koel to recognize it, as this's a standard pattern (where the album cover file is named cover.jpg in the same folder as the music file).

Indeed, I am confused. I had never imagined something like this, because I was giving for granted that a streaming server could give each song its own cover.

That is, if I have three single songs, not albums, inside /music, each by a different author or band, therefore each with its different cover, that is if I have six files:

song1.mp3, cover1.jpg
song2.mp3 and cover2.png
song3.mp3 and cover3.jpg

is it possible to make Koel show those three single songs, each with its own cover, and how? Put every song in its own directory, each with its own or what else?

Thanks

@mfioretti commented on GitHub (Aug 4, 2025): > The file name must be `cover.jpg`, `folder.jpg`, `cover.png`, or `folder.png` for Koel to recognize it, as this's a standard pattern (where the album cover file is named `cover.jpg` in the same folder as the music file). Indeed, I am confused. I had never imagined something like this, because I was giving for granted that a streaming server could give each song its own cover. That is, if I have three single songs, not albums, inside /music, each by a different author or band, therefore each with its different cover, that is if I have six files: song1.mp3, cover1.jpg song2.mp3 and cover2.png song3.mp3 and cover3.jpg is it possible to make Koel show those three single songs, each with its own cover, and how? Put every song in its own directory, each with its own or what else? Thanks

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/koel-koel#1077

No description provided.

Rows
Columns