openBeats is a self-hosted, lightweight web application built to stream your personal music library and playlists directly in the browser. It automatically scans your local directories, serves audio tracks, and renders your custom covers. It is fully containerized and designed with privacy and portability in mind.
- Local Directory Scanning: Automatically indexes your music library from your host machine.
- Playlist & Cover Support: Renders custom playlist layouts and loads artwork dynamically via an optimized API.
- Dockerized Architecture: Runs completely isolated in a lightweight production container.
- GitHub Ready & Portable: Uses clean environment variables so anyone can spin it up instantly without hardcoded paths.
- Responsive Web UI: Built with modern web tech to control your beats from any device.
- Frontend & Backend: Next.js (App Router), TypeScript
- Styling: Tailwind CSS
- Containerization: Docker, Docker Compose
- Docker and Docker Compose installed on your system.
- Your personal music library and playlist covers stored on your local drive.
-
Clone the repository:
git clone [https://github.com/ykilian/openBeats.git](https://github.com/ykilian/openBeats.git) cd openBeats -
Configure your Environment:
cp .env.example .env
Open the newly created
.envfile and insert the absolute paths to your local music and cover folders:MUSIC_PATH=path/to/your/music -
Build and Run with Docker:
Spin up the application using Docker Compose:
docker compose up --build
-
Access the App:
Open your preferred web browser and navigate to: http://localhost:3000
Music Grouping (Albums): The server automatically scans your target music directory. Subfolders within your music path are automatically detected and grouped as individual Albums. Organizing your files into folders is currently the way to group your music (true custom playlist support inside the UI is coming soon!).
This project is licensed under the MIT License.