Quick start

From a fresh clone to playing your own media. On macOS or Linux this is one sitting; on Windows, follow Install on Windows instead — same ground, with the Windows-only traps called out at each step.

1. Check the requirements

PHP 8.4+, Node 22+, Composer, and FFmpeg on the PATH. Requirements has the details and install commands per platform.

2. Install the server

git clone https://github.com/tripsittr/SoundChex.git
cd SoundChex

composer install
npm install

cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan storage:link

npm run build
php artisan serve

storage:link is easy to skip and fails silently. Without it, every avatar and artist image returns 404 with nothing explaining why. If images are missing later, this is the first thing to check.

3. Create the owner account

Open http://localhost:8000 and register. The first account becomes the owner automatically — no setup wizard, no license key.

4. Point it at your media

Admin → Library settings → watch folders, then run a scan: 

php artisan library:scan

Start with a small folder — a dozen files, not the whole collection. A small scan proves paths resolve and playback works before you commit hours to a full one. Nothing is ever moved out of your watch folders until it has been catalogued and identified, and originals are never deleted.

5. Keep the background workers running

php artisan queue:work        # enrichment, transcoding, downloads
php artisan schedule:work     # scanning, backups, pruning

Without the queue worker, metadata never fills in and downloads never start. Background workers covers running these at login on each OS.

6. Add metadata keys (optional)

Sources that need an API key — TMDB, AcoustID, Spotify, OpenSubtitles — are entered under Admin → Metadata sources. The rest work without one. A source with no key skips itself and says so in the log rather than silently returning nothing. See Metadata & integrations.

7. Put it on your devices

  • Mac — install the macOS app.
  • iPhone — the iOS app, or open the library in Safari and use Add to Home Screen.
  • Anything else — any browser gets the full experience at http://<server-ip>:8000/app.

To reach the server from outside your network, see Remote access.