# koel

> The official documentation for Koel, the music streaming solution that works

## Table of Contents

### Introduction

- [What Is Koel?](/guide/what-is-koel.md): An overview of Koel, a modern, open-source personal music streaming service built with Laravel and Vue.js.
- [Getting Started](/guide/getting-started.md): Requirements, installation methods (pre-compiled, source, Docker, Railway), configuration, running with FrankenPHP (binary + systemd), upgrading, and downgrading Koel.
- [Standalone Binary](/guide/standalone-binary.md): Install Koel from the single-archive standalone distribution (FrankenPHP + Caddy + PHP + Koel app), customize the database, and run as a systemd service.
- [Running with FrankenPHP](/guide/running-with-frankenphp.md): Install FrankenPHP, configure Koel's Caddyfile, run artisan commands via php-cli, set up a systemd service on Ubuntu, and serve behind a reverse proxy.

### Usage

- [Music Discovery](/usage/music-discovery.md): How Koel discovers media files via scanning, uploading, filesystem watching, and AWS Lambda integration.
- [Streaming Music](/usage/streaming.md): Streaming methods (PHP, x-accel-redirect, x-sendfile), transcoding with FFmpeg, cloud storage streaming, and crossfade.
- [Using the Web Interface](/usage/web-interface.md): Guide to browsing, searching, playing, editing, downloading, and sharing music through Koel's web interface.
- [Creating and Managing Playlists](/usage/playlists.md): Creating standard and smart playlists, organizing with nested folders, and managing collaborative playlists in Koel.
- [Instant Search](/usage/search.md): Full-text instant search powered by Laravel Scout with support for TNTSearch, Algolia, and Meilisearch.
- [Themes](/usage/themes.md): Built-in theme selection and custom theme support in Koel Plus.
- [Artist, Album, and Playlist Arts](/usage/artist-album-playlist-arts.md): How Koel fetches and displays artwork from Spotify, Last.fm, and MusicBrainz, with support for custom uploads.
- [Podcasts](/usage/podcasts.md): Subscribing to podcasts via RSS, playback behavior, resume position tracking, and automatic syncing.
- [Radio](/usage/radio.md): Adding and streaming internet radio stations in Koel with ICY metadata support.
- [Offline Playback](/usage/offline-playback.md): Caching songs for offline playback using Service Workers, managing offline storage, and limitations.
- [User Management](/usage/user-management.md): User roles (admin, user, manager, guest), creating and inviting users, and managing permissions in Koel.
- [Profile and Preferences](/usage/profile-preferences.md): Managing your profile, avatar, theme selection, playback preferences, and service integration settings.
- [Two-Factor Authentication](/usage/two-factor-authentication.md): Set up two-factor authentication on your Koel account to add a one-time code to every login.
- [Remote Controller](/usage/remote-controller.md): Using Koel's Pusher-based remote controller to control a desktop instance from your phone.
- [Subsonic Clients](/usage/subsonic.md): Connecting Subsonic-compatible apps to your Koel library with your personal API key.
- [Embedding](/usage/embedding.md): Embedding tracks, playlists, albums, and artists via iframe with layout and theme options.

### Koel Plus

- [What Is Koel Plus?](/plus/what-is-koel-plus.md): Overview of Koel Plus premium features including multi-library, collaboration, cloud storage, SSO, white labeling, and AI assistant.
- [Purchase & Activation](/plus/purchase-activation.md): Koel Plus pricing, purchasing, license activation via web or CLI, and deactivation steps.
- [Cloud Storage Support](/plus/cloud-storage-support.md): Setting up SFTP, Amazon S3, DigitalOcean Spaces, Cloudflare R2, Dropbox, and WebDAV (NextCloud, Owncloud) as Koel storage drivers.
- [Collaboration](/plus/collaboration.md): Song visibility, sharing, collaborative playlists, and multi-user library management in Koel Plus.
- [Single Sign-On](/plus/sso.md): Configure Google or generic OpenID Connect SSO for Koel Plus, including environment variables and user management.
- [Proxy Authentication](/plus/proxy-auth.md): Configuring reverse proxy authentication via headers and IP allow-lists for Koel Plus.
- [Media Browser](/plus/media-browser.md): Browsing your music library at the file and folder level using Koel Plus's media browser.
- [White Labeling](/plus/white-labeling.md): Customizing the app name, logo, and default cover image in Koel Plus.
- [Custom Themes](/plus/custom-themes.md): Creating custom themes with colors, background images, and fonts in Koel Plus.
- [AI Assistant](/plus/ai-assistant.md): Using the AI assistant to control music playback, manage playlists, and explore your library with natural language.
- [Ticketmaster](/plus/ticketmaster.md): Integrating Ticketmaster for live event listings on artist pages, including API key setup and country detection.

### Other

- [CLI Commands](/cli-commands.md): Reference for all Koel artisan CLI commands including scanning, syncing, pruning, search indexing, and storage setup.
- [Environment Variables](/environment-variables.md): Comprehensive reference of all Koel .env variables for storage, scanning, streaming, integrations, SSO, and more.
- [Local Development](/development.md): Setting up a local Koel development environment, running the dev server, testing, linting, and contributing.
- [Markdown Extension Examples](/markdown-examples.md): VitePress markdown extension examples including syntax highlighting and custom containers.
- [Mobile Apps](/mobile-apps.md): The official Koel Player Flutter app for Android and iOS as a companion to the web interface.
- [Service Integrations](/service-integrations.md): Setting up MusicBrainz, Last.fm, ListenBrainz, Spotify, and YouTube integrations for metadata, artwork, and scrobbling.
- [Troubleshooting](/troubleshooting.md): Common Koel issues and solutions, debugging steps, log locations, and how to get help.