Local-first DJ set preparation built around explainable analysis, editable sequencing and portable export.
Portfolio status: Product prototype / pre-release engineering. This repository is not yet product-ready.
APPLAYLIST is a local-first DJ preparation product that turns a selected local music library into an explainable, editable and interoperable DJ set.
flowchart LR
A[Local music library] --> B[Analyze BPM · key · energy]
B --> C[Build explainable set]
C --> D[Edit · lock · reorder]
D --> E[Export approved playlist]
- Repository:
eimyroot/APPLAYLIST - Canonical branch:
feature/bundle-0-bootstrap - Current merged checkpoint: Bundle 46 — MIR Benchmark Harness
- Active architecture slice: Bundle 47 — Desktop Shell Architecture and Security ADR
- Supported Python:
>=3.11,<3.13 - Release status: not yet product-ready
- Default composition authority remains
legacy - Canonical composition remains available behind controlled configuration
- Real local Librosa MIR exists as a benchmark candidate
- Production provider authority remains blocked on licensed benchmark and human review evidence
The repository now contains the library scanner, stable content identity, tagged metadata persistence, a real baseline MIR provider, a fail-closed benchmark harness, composition/export foundations and repository hygiene tooling.
The next implementation target is a secure packaged desktop proof, not additional infrastructure abstraction.
The first release must let a DJ:
- install and open a signed local desktop application,
- select one explicit local audio folder,
- import supported files with stable identity and metadata,
- analyze BPM, key/Camelot, energy and duration using a real local provider,
- inspect confidence, warnings and failures,
- create a deterministic explainable set under explicit musical constraints,
- manually reorder, lock, replace and regenerate tracks,
- export an approved playlist as path-valid UTF-8 M3U8.
- Product Definition v1
- Target Architecture v2
- Desktop Shell ADR
- Desktop Security Contract v1
- MIR Benchmark Specification v1
- License Decision Register v1
- Product Roadmap — Bundles 41–54
React / TypeScript renderer
│ typed Tauri commands and events
▼
Tauri Rust desktop core
│ capabilities, native dialogs, sidecar lifecycle, updates
▼
Authenticated loopback Python sidecar
│ FastAPI transport → application services
▼
Library / analysis / composition / playlist / export
│
├── provider boundary
└── repository boundary
Desktop decision:
- primary: Tauri 2 + React/TypeScript + packaged Python sidecar,
- fallback: Electron + React/TypeScript + packaged Python sidecar only if the Tauri proof fails accepted gates,
- not selected under the current shared-web direction: PySide6/QML.
The React renderer never receives arbitrary shell access, unrestricted filesystem authority, the Python sidecar credential or direct SQLite access.
api/— HTTP schemas/routes and transport validationcore/— domain contracts, configuration, provider registry, benchmark and pure rulesservices/— application orchestration, library, analysis, composition and exportdata/— models, repositories, migrations and persistenceworkers/— typed background-processing foundationfrontend/— future React product UI; starts only in Bundle 48 proofdesktop/— future Tauri core and packaged sidecar supervision; starts only in Bundle 48 proofscripts/— safe operator and verification commandstests/— unit, integration, security and regression evidencedocs/— product, architecture, security, quality, compliance and operations
- Do not run project tests with global Python.
- Use the project virtual environment.
- Do not use Python 3.14 for the product runtime yet.
- Do not commit
.env, virtual environments, databases, caches, benchmark audio or duplicate cloud-sync files. - Optional audio backends must not import on mandatory boot.
- Providers never persist directly.
- Only normalized validated analysis records may be stored.
- Routes and renderer code never own heavy product logic.
- Repositories own persistence.
- Tests and product acceptance gates pass before every checkpoint.
- New abstractions require a named product need.
- Default-provider or authority changes require benchmark and rollback evidence.
- Renderer code never receives generic shell or filesystem APIs.
- Packaged sidecar binds loopback only and uses per-session authentication.
- Desktop update artifacts are signed and private signing keys remain outside the repository.
- Every bundle includes a schema tree and explicit out-of-scope list.
cd /path/to/APPLAYLIST
python3.11 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"
cp .env.example .env
.venv/bin/python -m uvicorn api.main:app --reload --host 127.0.0.1 --port 8000cd /path/to/APPLAYLIST
.venv/bin/python -m compileall -q api core services data workers
.venv/bin/python -m ruff check .
.venv/bin/python -m pytest -qRepository hygiene:
make hygiene-audit
make hygiene-plan
make hygiene-verifyMIR benchmark against an externally stored licensed dataset:
.venv/bin/python scripts/run_mir_benchmark.py \
--manifest /absolute/path/manifest.json \
--dataset-root /absolute/path/dataset \
--output /absolute/path/artifacts/report.json \
--provider librosa \
--source-commit "$(git rev-parse HEAD)"No benchmark audio or restricted annotations belong in the repository.
- Bundle 41 — Product Baseline Realignment ✅
- Bundle 42 — Bounded Library Import ✅
- Bundle 43 — Stable Track Identity and Metadata Boundary ✅
- Bundle 44 — Tagged Metadata and Persistence ✅
- Bundle 45 — Baseline Librosa MIR Provider ✅
- Bundle 46 — MIR Benchmark Harness ✅
- Bundle 47 — Desktop Shell Architecture and Security ADR
- Bundle 48 — Tauri/Python Sidecar Proof
- Bundle 49 — Desktop Library Shell
- Bundle 50 — Analysis Job and Inspector
- Bundle 51 — Transition Intelligence v1
- Bundle 52 — Explainable Set Builder
- Bundle 53 — Manual Playlist Editor
- Bundle 54 — M3U8 End-to-End Release Slice
Until Bundle 54, do not prioritize cloud accounts, streaming integrations, popularity/trend scoring, live mixing, stems, mobile clients, proprietary database reverse engineering, generative AI chat as the primary product surface or additional generalized composition infrastructure.
- Python CI passes on 3.11 and 3.12.
- Frontend/Rust CI is added when Bundle 48 introduces those toolchains.
- Mandatory boot does not require optional audio dependencies.
- Provider output is normalized and validated before storage.
- No fake success or hidden provider fallback.
- Desktop renderer has no generic host authority.
- Packaged artifacts pass layout and clean-machine smoke tests.
- Sidecar lifecycle, authentication and shutdown are proven.
- Signing, notarization, updater and SBOM evidence exist before external release.
- Product-facing slices demonstrate the declared user outcome; a green test count alone is not sufficient.
APPLAYLIST is a commercial proprietary product. Original APPLAYLIST code and product-specific materials are All Rights Reserved unless a specific file explicitly states otherwise.
- Repository visibility: PUBLIC
- Source-code license: Proprietary / All Rights Reserved
- Authorized application builds: End User License Agreement plus applicable commercial/beta terms
- Third-party software: Third-Party Notices and Release Compliance Index
- Brand, logos and visual identity: Trademark and Brand Policy
Third-party dependencies, native libraries, models, datasets, media and other externally owned materials retain their own rights and licenses. The proprietary APPLAYLIST license does not relicense them. A commercial installer remains blocked until the exact shipped dependency set satisfies the distribution gates in the license decision register and third-party notice process.