Profile and Preferences

To manage your profile and preferences, click on your avatar in the bottom-right corner of the screen. From here, you can manage a couple aspects of your account:

Profile

To update your profile, you must first authenticate yourself by entering your current password. After that, you can update your name and email, and set a new password. Leaving the New Password field blank will keep your current password intact.

:::tip Pick a strong password Koel enforces a strong password policy. Make sure to pick a password that is at least 10 characters long and contains a mix of letters, numbers, and special characters. Your password will also be checked against a list of leaked passwords for extra security. :::

Custom Avatar

By default, Koel uses Gravatar to fetch your avatar based on your email address. By hovering over the avatar and clicking the <InterfaceIcon :src="uploadIcon" /> icon, you can select an image file from your computer, crop it, and set it as your custom avatar. Remember to click Save for the change to take effect.

To remove your custom avatar and revert to using Gravatar, click the <InterfaceIcon :src="timesIcon" /> icon.

Themes

Koel comes loaded with beautiful, handcrafted themes. You can activate a theme simply by clicking on it. The new theme will be applied immediately.

More themes are to be added in the future, along with the ability to create your own theme.

Preferences

Koel allows you to set a couple of preferences:

Whether playing a song should trigger continuous playback of the entire playlist, album, artist, or genre
Whether to show a notification whenever a new song starts playing
Whether to confirm before closing Koel’s browser tab
Whether to show a translucent, blurred overlay of the current album’s art
Crossfade duration between songs (0–15 seconds, 0 to disable)
Whether to transcode music to a lower bitrate (mobile only, useful if you have a slow connection)
<PlusBadge /> Whether to set your uploaded music as public by default
<PlusBadge /> Whether to include public media (songs, albums, and artists) from other users in your library and search results

These preferences are saved immediately upon change and synced across all of your devices.

Offline Storage

If you have songs cached for offline playback, this section displays your current storage usage with a progress bar showing used vs. available space. You can clear all cached songs at once by clicking the "Clear All" button.

Service Integration Statuses

If your Koel installation is integrated with any external services, such as Last.fm or Spotify, you can see their statuses here along with the ability to connect or disconnect them when applicable.

QR Code Authentication

This tab displays a QR code that you can scan to log in to Koel Player on your phone without having to manually enter your credentials. The code refreshes every ten minutes, but you can also manually refresh it.