`README.md`

61 lines
# mp3-agentabrams

Every MP3 recording ever made on Steve's Mac2, served as a grid + list with sort, density slider, and inline player. Future home: `mp3.agentabrams.com` (DNS hookup pending).

> 358 tracks indexed at first scan · 154 MB total · spans `~/Projects/`, `~/Videos/`, `~/Desktop/`, `~/.claude/skills/`

## Stack

- Express 5 on port **9696** (override with `MP3_PORT`)
- Static frontend at `public/index.html` (no build step)
- `scan-mp3s.js` walks the disk, writes `manifest.json` (gitignored)

## Run

```bash
npm run scan        # rebuild manifest.json
npm start           # http://127.0.0.1:9696
```

In the UI, click "refresh manifest" to re-scan from the browser.

## API

| Route | Verb | Notes |
| --- | --- | --- |
| `/` | GET | static UI |
| `/api/manifest` | GET | full JSON of indexed tracks |
| `/api/refresh` | POST | re-runs scan-mp3s.js |
| `/audio?id=<id>` | GET | streams MP3 by manifest id (range-aware) |
| `/healthz` | GET | 200 if `manifest.count > 0`, else 503 |

Paths never appear in URLs — every track is referenced by stable sha1-prefix id.

## Scan config

Defaults to scanning these roots (`SCAN_ROOTS` env overrides, comma-separated):

```
~/Projects, ~/Videos, ~/Desktop, ~/.claude/skills
```

Excluded substrings (in any path part): `/node_modules/`, `/.git/`, `/.Trash/`, `/Library/Caches/`, `/kamatera-mirror/`, `/.cache/`, `/.next/`, `/dist/`, `/build/`.

`ffprobe` is opt-in (`PROBE_DURATIONS=1` env). It adds ~30-60s to the scan for 358 files; durations show as `—` when off. First scan ran with `PROBE_DURATIONS=0` for speed.

## UI features (per Steve's standing rules)

- **Sort `<select>`**: Newest / Oldest / Title A→Z / Title Z→A / Size ↑↓ / Duration ↑↓ / Source A→Z
- **Density slider** (2–10 columns) — drives `--cols` CSS var on `<main.grid>`
- **View toggle**: grid ↔ list
- **Source filter `<select>`** — auto-populated from unique parent dirs
- **Text filter** — substring match over name + parent + parent2
- **Persisted state**: all controls hydrate from `localStorage` keys under `mp3aa.*` before the first render

## Next steps (gated on Steve)

1. **DNS hookup** — point `mp3.agentabrams.com` at this port via Cloudflare + the same reverse-proxy pattern Steve uses for `videos.agentabrams.com` / `admin.agentabrams.com`.
2. **Duration probe** — run once with `PROBE_DURATIONS=1` after `brew install ffmpeg` (probably already installed).
3. **Auto-refresh watcher** — extend `videos-agentabrams-worker` to also re-scan when new MP3s land in any of the SCAN_ROOTS.
4. **Auth** — if exposed publicly, add the same auth gate as `admin.agentabrams.com` (subagent's pattern).