Live

Klangkurator

Local-first organizer for a DJ music library — crates, real waveforms, track relationships and set planning, with an MCP server an AI agent can search and tag through.

ReactFastAPIPyWebViewMCP

Motivation

I cannot remember every track I have or want in a set, or in which order they should come. Tagging helps with that, and an AI agent can search the library and collect ideas for me. I also wanted one place to write down transition ideas and what worked well. Blocks follow that idea. A block is a run of tracks joined by transitions that work, kept so I can drop it into any set.

Project Overview

Klangkurator is my organizer for a DJ music library, and it runs entirely on my own machine. It keeps crates and tags, analyzes BPM and key for the tracks, and shows real waveforms. Remixes are linked to their originals as track relationships, and a second audio file of the same recording is kept with the existing track instead of becoming a new one. An MCP server sits on top of it, so an AI agent can search the library, tag tracks and build playlists. I built it together with an agent team.

Key Features

  • Crates and tags for a local music library
  • BPM and key analysis for the tracks
  • Real waveforms
  • Track relationships between remixes and originals
  • Sets for planning a DJ set
  • MCP server for AI agents, with no tool that deletes tracks or files

Architecture

React on the frontend, FastAPI on the backend, everything running locally in a desktop window. The library is stored in three human-readable JSON files in the home folder, not in a database. BPM and key are analyzed per track. The MCP server reads and writes through the app's own API, and none of its tools deletes tracks or audio files, so an agent works on the library through a defined surface instead of touching the files.

Challenges Solved

The library has to work with nothing but the local machine: analysis, storage and the agent interface all run against the same local JSON store. A remix is a different track and gets linked to its original, while a second file of the same recording is merged into the track it belongs to. The agent surface reads and writes but deletes nothing. The app was built with an agent squad rather than written line by line by hand.

Explore the Code

Dive into the implementation details and see how this project was built.