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.

docker-compose up -d