Beatstream

Beatstream is an app for streaming music from your computer or server to anywhere with a modern Web browser!

Installation

Docker (Quick Start)

Requirements: Docker

docker run -d -p 8080:8080 \
  -v /path/to/your/music:/music \
  -v /path/to/your/data:/data \
  -e DATA_PATH=/data \
  darep/beatstream:latest

Open http://0.0.0.0:8080 on your browser. Log in and wait when indexing ends, refresh page and happy listening!

Note: We suggest the DATA_PATH to make sure your data is persisted, but you can also start the Beatstream docker image without it.

Last.fm

To enable per-user Last.fm connections, create a Last.fm API application and pass its credentials to Beatstream:

docker run -d -p 8080:8080 -v /path/to/your/music:/music \
  -e LASTFM_API_KEY=your-key -e LASTFM_API_SECRET=your-secret \
  darep/beatstream:latest

Each Beatstream user can then connect and disconnect their own Last.fm account from Settings.

Manual Install

Requirements: Go 1.26 or newer. Node.js 20 or newer. TagLib (C bindings) e.g. libtagc

git clone https://github.com/Darep/Beatstream
cd frontend
npm install
npm run build
cd ..
go run .

Open http://0.0.0.0:8080 on your browser. Log in and wait when indexing ends, refresh page and happy listening!

Development

Copy base env vars and modify as you see fit:

cp .env.example .env

Start the Beatstream app:

go run .

Start the frontend development server:

cd frontend
npm install
npm run dev

Docker

Development with docker:

cp .env.example .env
docker compose up

Integration test

The Playwright test builds the production Docker image, starts it with a generated audio fixture, and exercises login, library indexing, streaming, playback controls, search, and logout in headless Chromium. Docker must be running.

cd frontend
npm ci
npm run test:e2e:install
npm run test:e2e

Failed runs keep a screenshot, browser trace, and application logs in frontend/test-results. The same test runs on every push and pull request to master.

Checks

Before committing changes, run:

make format
make check

make check verifies Go formatting, vet, tests, development and production builds, frontend formatting and build, and the Docker Compose image. GitHub Actions runs the same command on every push and pull request to master.

Releasing

Releases follow Semantic Versioning and are published from GitHub Releases.

1. Update CHANGELOG.md: move items from Unreleased into a new versioned section.
2. Go to https://github.com/Darep/Beatstream/releases/new and publish a new release.
3. The GitHub action workflow will publish the new version to Docker Hub.