kami
50 lines
1.8 KiB
Markdown
50 lines
1.8 KiB
Markdown
# muzick
|
|
|
|
A high-performance, distributed music orchestration and recommendation platform.
|
|
|
|
## Overview
|
|
|
|
**muzick** is designed to manage a local music library while providing an "infinite vibe" listening experience. It bridges the gap between a local filesystem and advanced discovery engines through a tiered recommendation architecture.
|
|
|
|
## Tech Stack
|
|
|
|
### **Frontend**
|
|
- **Framework:** React
|
|
- **Routing:** TanStack Router
|
|
- **Data Fetching:** TanStack Query (with Look-ahead Buffering)
|
|
- **State Management:** Zustand (for Session/Vibe state)
|
|
- **Styling:** CSS Variables (Customizable Themes)
|
|
|
|
### **Backend**
|
|
- **Runtime:** Node.js / TypeScript
|
|
- **Framework:** Fastify
|
|
- **Task Queue:** BullMQ (via Redis)
|
|
- **Search:** Typesense
|
|
|
|
### **Infrastructure & Data**
|
|
- **Database:** PostgreSQL (Source of truth for metadata, relationships, and session state)
|
|
- **Cache/Queue:** Redis
|
|
- **Audio Analysis:** Essentia (via Worker processes)
|
|
- **External Metadata:** MusicBrainz, Discogs, LRCLib, Cover Art Archive
|
|
|
|
## Core Concepts
|
|
|
|
- **The Rolling Vibe:** A continuous, evolving stream of music that uses a "Rolling Window" of tracks. It interleaves owned library tracks with high-probability "probation" tracks (external discoveries).
|
|
- **The Dislike Lifecycle:** A multi-stage state machine that protects users from accidental deletions while ensuring the library stays clean.
|
|
- **Tiered Similarity:** Instant metadata-based matches, followed by deep audio-feature similarity.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Docker & Docker Compose
|
|
|
|
### Running Locally
|
|
|
|
Set `MUZICK_VIBE_USER_ID` in `.env` to the UUID of the local Muzick user before
|
|
using Vibe. Durable Vibe session routes intentionally reject client-supplied
|
|
identities, so this is the trusted single-user binding for a self-hosted stack.
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|