# Project pack: Koel @ fac6f8d

Facts about **Koel** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Koel is a personal music streaming server and web app. Point it at a folder of MP3, FLAC and other audio files and you get a library with albums, artists, playlists, a visualiser and mobile-friendly playback. It can also play podcasts and radio stations.

## Version and source
- Repository: https://github.com/koel/koel
- Pinned commit: `fac6f8d4a8ffff01597efc4613c1de315cd1564a`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/koel/koel/archive/fac6f8d4a8ffff01597efc4613c1de315cd1564a.zip
- Official docs: https://docs.koel.dev
- Live demo: https://demo.koel.dev/. Shared demo. Don't enter real data.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/koel/koel bespoke-koel
  cd bespoke-koel
  git checkout --detach fac6f8d4a8ffff01597efc4613c1de315cd1564a
  # Prepare development requirements and local configuration first.
  composer install
  pnpm install
  cp .env.example .env
  php artisan koel:init
  pnpm dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the Docker guide at https://docs.koel.dev/guide/getting-started, which provides a compose file with the official image.
  ```

- Needs: Docker, or PHP 8.2+, Composer, Node 22 and a database for development
- Develop: `pnpm dev`
- Test: `php artisan test`
- Check/lint: `pnpm lint`
- Stack: php, typescript (Laravel, Vue, Vite, Tailwind). Difficulty for a non-developer with an AI: **moderate**. A Laravel back end with a Vue single-page front end. Themes and settings are easy; features follow the standard Laravel structure.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **media-and-users** [settings]: Where your music is and who can listen. → `Settings → Media path, Users`
- **themes** [extend]: Colours, fonts and player layout. → `resources/assets and Settings → Themes`
- **integrations** [extend]: Scrobbling and artist artwork. → `Settings → Last.fm, Spotify, YouTube`
- **api** [extend]: Control playback and read the library from scripts. → `api-docs/`
- **vue-ui** [code]: Screens and the player. → `resources/assets/js`
- **laravel-app** [code]: Models, jobs and endpoints. → `app/`

## Must keep working
- Laravel migrations. Add new ones; never edit old ones.
- Song scanning, since mistakes could drop library entries.
- Permission checks for private playlists and admin settings.

## Staying updatable
Prefer themes, settings and the API. Add code in new classes and components, following the repo's AGENTS.md.

## Data, costs and safety
- Personal data: **yes**. Stored in: A database for the library plus covers on disk; your music files stay in your own folder. Back up the database. Your music files are only read.
- Service: Last.fm and Spotify (optional) (optional, free): Artist images and scrobbling.
- Service: Object storage (S3-compatible, optional) (optional, pay-per-use): Keep music in the cloud.
- Setting `APP_KEY` (**secret**: the person enters it themselves, never in chat): Laravel encryption key. Never paste it into an AI chat.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `MEDIA_PATH`: The folder inside the container where your music lives.
- Respect copyright. Use it for music you own.
- Use HTTPS and strong passwords if it is reachable from the internet.

---

# Customising Koel

Koel is Laravel plus Vue. The repo has an AGENTS.md describing its conventions, which is helpful for AI tools.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Vue front end | resources/assets/js/ |
| Models, services and jobs | app/ |
| Routes | routes/ |
| Database migrations | database/migrations/ |
| API documentation | api-docs/ |
| Developer docs | docs/ |

## Use the gentlest change first

1. **Settings (no code):** media path, users, integrations and themes.
2. **Extend:** the API.
3. **Code:** Vue components and Laravel classes.

## Recipes

- **New smart-playlist rule:** add the rule in the smart playlist service and its editor control in the front end.
- **New theme:** add CSS variables for the theme and register it in the theme settings.

## Running and checking your changes

- `php artisan test` and `pnpm lint`.
- Scan a small test folder and play a track.

## Pitfalls

- Keep a backup of the database before running migrations.
- Run `php artisan koel:sync` to rescan after changing the media folder.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/koel/fac6f8d/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/koel/fac6f8d/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/koel/fac6f8d/r2/SKILL.md)