Using the Web Interface

UI is subject to change

The screenshots and descriptions in this document are based on the latest version of Koel at the time of writing. As Koel is an ever-evolving project, the actual UI may differ slightly in newer versions.

Koel’s web interface is designed to be as simple and intuitive as possible, drawing inspiration from the best music players out there. Here’s a quick rundown of what you can do with it.

Browsing and Searching for Music

The navigation bar on the left side of the screen is where you can find all the main features of Koel. You can browse your music library by songs…

artists…

albums…

or genres:

You can click on any artist, album, or genre name to see all the songs that belong to it. On the artist and album screens, you can also find other albums and songs by the same artist as well as extra metadata like the artist or album's information when configured.

On any screen with a song list (a "song-list screen") you can:

• Sort the list by clicking on the column headers
• Filter the list by typing in the filter box (marked with )
• Select a song by clicking on it. To select multiple songs, hold down Shift or Ctrl/Cmd while clicking.
• Drag and drop one or more songs to reorder them when applicable
• Drag and drop one or more songs to applicable menu items to the left to perform actions like adding to a playlist, queueing, or marking them as favorite
• Right-click on a song to bring up a context menu with options to play, queue, mark as favorite, add to a playlist, and more

To search globally for songs, artists, and albums, see Instant Search.

Streaming Music

Play a song by double-clicking on it or pressing Enter on either a song list row or a song card. Queue a song (or multiple songs) by right-clicking and choose one of the Queue options, or by dragging and dropping it into the Queue icon in the footer.

You can use the dedicated button (with the icon) to shuffle the current list or the selected songs. To play in order instead of shuffling, hold down Alt/Option while clicking the button.

When a song is playing, you can control playback using the buttons at the bottom of the screen as well as rewind/fast-forward the song by clicking and dragging the progress bar.

From the same area, you also can:

• like/unlike the current song
• switch between repeat modes
• toggle the Queue screen
• show the visualizer
• show the equalizer
• control the volume
• toggle full-screen mode

Right-clicking the footer area brings up context menu for the currently playing song.

Creating and Managing Playlists

Koel supports creating an unlimited number of playlists as well as organizing them into folders. Start by clicking the button next to the "Playlists" header in the navigation bar. You'll be provided with three options:

• "New Playlist…" brings up a dialog to create a standard playlist
• "New Smart Playlist…" brings up a dialog to create a smart playlist
• "New Folder…" brings up a dialog to create a playlist folder

Creating a standard playlist or playlist folder should be straightforward, as you only need to supply a name. Once a playlist or playlist folder is created, you can:

• Drag and drop songs into a standard playlist to add them
• Drag and drop playlists a playlist folder to organize them. You can also drag and drop a playlist out of its folder.

For a smart playlist, you can define the criteria that determine which songs are included in the playlist, and Koel will automatically update the playlist based on those criteria. For example, with the criteria shown in the following screenshot:

Koel will include in the playlist:

• all songs by Pink Floyd, and
• songs by Iron Maiden that have been played more than 99 times by the current user

There are a great variety of criteria to choose from, and you can combine them in any way you like, providing a powerful tool for creating dynamic playlists.

Editing Songs

As an admin (Community edition) or song owner (Koel Plus), you can edit a song's metadata by right-clicking on it and choosing "Edit…". A dialog will appear, allowing you to change the song's title, artist, album, genre, lyrics, and more.

You can also edit multiple songs at once, in which case the changes will be applied to all of them.

Downloading Songs

If ALLOW_DOWNLOAD is set to true (the default value) in your .env file, you can download a song by right-clicking on it and choosing "Download."

You can also download several songs, all songs from an album, all songs by an artist, or a whole playlist as a zip file via the "Download" buttons found on according screens or context menus. This feature requires the zip extension to be installed and enabled on the server.

Resource Intensive

Downloading a large number of songs at once (or a big playlist) can be resource-intensive, may take a long time, or even (silently) fail.

Deleting Songs

As an admin (Community edition) or song owner (Koel Plus), you can delete a song by right-clicking on it and choosing "Delete from Filesystem." You'll be prompted to confirm the deletion, and once confirmed, the song will be removed from the database and the filesystem.

Backup on Delete

By default, Koel keeps a backup of the song before deleting it. You can disable this behavior by setting BACKUP_ON_DELETE to false in your .env file, but be aware that this will make it impossible to recover a song once it's deleted.

Share a Song

You can share a song by right-clicking on it and choosing "Copy Shareable URL." This will copy a URL to the clipboard that can then be shared with anyone with a Koel account.

Keyboard Shortcuts

Koel has a number of keyboard shortcuts to make it easier to navigate and control playback. Note that these shortcuts are only triggered when the focus is not on an input field (including the volume control and the music track) or a textarea.

• h shows the Home screen
• q toggles the Queue screen
• f puts the focus into the search box and triggers the instant search screen
• Enter plays a song. If multiple songs are being selected, Enter adds them to the bottom of the queue, Shift+Enter queues them to top. Adding a Cmd or Ctrl into the combo plays the first selected song right away.
• Space toggles playback
• j plays the next song in queue
• k plays the previous song in queue
• l marks/unmarks the current song as favorite
• r circles through repeat modes (no repeat, repeat all, repeat one)
• → seeks forward 10 seconds
• ← seeks backward 10 seconds
• ↑ increases volume by 10%
• ↓ decreases volume by 10%
• m mutes/unmutes
• Cmd/Ctrl+a selects all songs in the current song-list screen when the list is focused
• Delete removes selected song(s) from the current queue/playlist

With a browser that supports MediaSession — basically, all modern browsers — you can control Koel using hardware media keys without even having Koel or the browser focused.