# HTXpunk Library Manager

**Local-first music library planner for VirtualDJ and DJs with messy folders.**

Scan many folders → build a safe rename/route plan → identify tracks by sound (optional free AcoustID code) → dry run → apply.  
Your music stays on your PC. **© 2026 HTXpunk LLC**

Version **0.1.0** (marketplace freemium starter)

**GitHub (private source of truth):** https://github.com/djdistraction/htxpunk-library-manager  

**HTXpunk portfolio context:** SFE-Edge / brand hub / GTM live in the sibling private repo  
https://github.com/djdistraction/sfe-edge — see `docs/STRATEGIC_REPLAN_2026-07-22.md` (Library Manager = Engine C after free web launches).  
**Do not merge this product into sfe-edge**; keep separate deploys and history.

---

## Why download this?

- **Multi-folder hierarchical scan** — dozens of roots, nested albums, without freezing the UI  
- **Plan before write** — see current name → proposed name → destination folder  
- **Identify by audio** — free AcoustID access code (guided setup; no jargon wall)  
- **Do No Harm default** — copy into library, keep originals; dry run; undo  
- **VirtualDJ-oriented** layout targets (remixes, karaoke, acapellas, drops, …)

---

## Requirements

- Windows 10/11  
- Python 3.11+ (for the local API)  
- Node.js 20+ (for the UI)  
- Free AcoustID access code for **Identify** (scan/plan works without it)

---

## Quick start (developers / portable)

### 1. Backend

```powershell
cd backend
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

### 2. Frontend

```powershell
cd frontend
npm install
npm run dev
```

Open **http://localhost:3000**

### 3. Public ship path (recommended — single port)

**End users (download zip from htxpunk.net):**

1. Unzip → double-click **`START.bat`**  
2. First run installs a private Python env (needs Python 3.11+)  
3. Browser opens **http://127.0.0.1:8000** (API + UI together)

**Build the zip for the website:**

```powershell
# from repo root
powershell -ExecutionPolicy Bypass -File .\packaging\build-release.ps1
# → dist\HTXpunk-Library-Manager-0.1.0-win64.zip
```

**Developers (Next.js UI on :3000 + API on :8000):**

```powershell
# from repo root
.\packaging\start-library-manager.ps1
```
---

## First-run: song recognition (BYOK)

1. On first launch, a **Song recognition setup** dialog appears.  
2. Choose **I need a free access code** — we open [AcoustID new application](https://acoustid.org/new-application).  
3. Create a free account → create an application named `HTXpunk Library Manager` → copy the code.  
4. Paste into the dialog → **Save**.  
5. Code is stored only in `backend/.env` (never returned by the API again).

You can skip setup and still **Scan / plan**. **Identify** will re-open the wizard if no code is set.

---

## Happy path

1. **Source folders** — Browse or type paths (multi-select OK).  
2. **Scan** — hierarchical plan only (no online lookup). Rows appear as files are found.  
3. **Identify** — selected tracks, one at a time (rate-limited).  
4. Review tabs: **Verified** / **Needs review** / **Duplicates**.  
5. **Dry Run** → **Apply to Library** (default: copy, keep originals).

---

## Library layout (after Apply)

```
{LIBRARY_ROOT}/
├── Music/Original_Versions/
├── Music/Remixes_Mashups/
├── Music/My_Originals/
├── Instrumentals/
├── Acapellas/
├── Karaoke_Videos/
├── Lyric_Videos/
├── Music_Videos/
├── Samples/DJ_Drops/
├── Duplicates/
└── Incoming_Downloads/   (optional watch)
```

---

## Safety

- Binds to `127.0.0.1` only  
- Default apply: **copy keep source**  
- Never overwrite by default (` (2)` suffixes)  
- Undo last batch when history exists  
- Secrets (AcoustID / Discogs) only in `backend/.env`  

---

## Tests

```powershell
cd D:\Projects\dj-library\backend
.\.venv\Scripts\python.exe -m pytest tests -q
```

---

## Freemium (v0.1)

**Free:** scan, plan, identify (your AcoustID code), copy/dry-run/apply, multi-folder queue.  
**Coming later:** AI name review, lyrics prep, virtual folders / vibe playlists, optional pro identify.

---

## Project path

```
D:\Projects\dj-library\
├── backend\
├── frontend\
├── packaging\
└── vdj-plugin\   (advanced VirtualDJ plan executor)
```

---

© 2026 HTXpunk LLC. Local only. Your files are yours.
