koel Files

Welcome to Koel v9 (code-named Beethoven). This is a massive release with over 140 changes, bringing a completely revamped visual experience, offline support, crossfade playback, an AI-powered assistant, and much more.

What's New

Offline Support

Early offline support has landed. Songs can be cached for offline playback, and the app degrades gracefully when the network is unavailable.

Crossfade Playback

A long-requested feature: crossfade between tracks with a configurable duration, for a seamless listening experience.

Revamped Home Screen

The home screen has been completely redesigned with discovery sections, a card grid layout with row dividers, and a "Something Random" section with a refresh button. Cards now feature cursor-following gradient borders and entity-derived gradient colors for a more vibrant, immersive look.

Visual Overhaul

• Revamped equalizer with an SVG frequency response curve connecting the bands, gradient coloring, and a center reference line
• Album, artist, and other detail screens now display a blurred cover image as the background, giving each screen a unique, immersive feel
• Card-based layout for main content area and footer
• Marquee animations for long titles in the footer, sidebar, and screen headers instead of truncation

Radio Now-Playing

When streaming a radio station, Koel now shows the current playing song by reading ICY metadata from the stream.

Favorites Drag-and-Drop Ordering

You can now reorder your favorite songs via drag-and-drop, giving you full control over the order of your favorites list.

Parallel Scanning

Both library scanning and podcast syncing now run in parallel, significantly speeding up large-library imports and podcast updates.

Smarter Similar Songs

The similar songs algorithm now uses multiple seed songs and is scoped to songs only (excluding podcast episodes), producing better recommendations.

Upload Abort

In-progress uploads can now be aborted.

AI Assistant (Experimental)

Koel now ships with a built-in AI assistant that lets you control your music with natural language. Ask it to play something, manage playlists, toggle favorites — all through a conversational interface. For more information, refer to the documentation.

More Great Features

• Persist song list sort preferences across sessions
• Double-click sidebar playlists to play
• Expand collapsed playlist folders on drag hover
• Create playlist folders inline from playlist forms
• Make collaborative playlist columns toggleable
• Configurable download limit and transcode timeout
• Scroll to the current song in the queue by clicking the footer thumbnail
• Infinite scroll for YouTube video search results

Tooling Overhaul

The frontend toolchain has been modernized significantly:

• Migrated to Vite+ (wrapping Vite 8, Vitest, oxlint, and oxfmt)
• Replaced ESLint with oxlint and added oxfmt as the code formatter
• Replaced axios with ky for HTTP requests
• Replaced Cypress with a comprehensive Vitest test suite
• PHP linting now uses mago
• vue-tsc type checking added to CI
• Upgraded to Saloon v4

Security

• Fixed CVE-2025-7783 (form-data unsafe random boundary)

As usual, a bunch of bug fixes and improvements have also been added under the hood.

Upgrade

[!IMPORTANT] Koel v9 requires PHP 8.3 or higher (previously 8.2).

1. Make a backup of your database
2. Depending on your installation method, either check out the tag by running git pull && git checkout v9.0.0 or downloading and extracting the release archive
3. If building from source, run composer koel:init as your webserver user
4. Enjoy!

New Contributors

• @chrisvoo made their first contribution in https://github.com/koel/koel/pull/2329
• @Sammyjo20 made their first contribution in https://github.com/koel/koel/pull/2334

Full Changelog: https://github.com/koel/koel/compare/v8.3.1...v9.0.0