mymusics

# MyMusics

Retro-styled web player that picks random tracks from [`data/metadata.tsv`](data/metadata.tsv) and streams MP3s from the Internet Archive item [**The Myspace Dragon Hoard (2008–2010)**](https://archive.org/details/myspace_dragon_hoard_2010). URLs follow the same pattern as the official IA “Hobbit” player (ZIP member paths).

The API uses a **SQLite index** (`data/tracks.db`) built from the TSV for fast random selection, search, and lookup by id — without loading hundreds of thousands of rows into RAM.

## Requirements

- Node.js 20+
- `data/metadata.tsv` (Dragon Hoard export). No local MP3 mirror is required.
- After clone/deploy: run **`npm run index-metadata`** once (or on each TSV update) to create `data/tracks.db`.

## Configuration

1. Copy `.env.example` to `.env` and adjust:

   - `METADATA_TSV` — path to `metadata.tsv` (default: `data/metadata.tsv`).
   - `TRACKS_DB` — SQLite index (default: `data/tracks.db`).
   - **Ports** — [`config/ports.ts`](config/ports.ts): `PORT_INDEX` (0–3) or explicit `PORT` / `VITE_DEV_PORT`. Defaults: API `38471`, Vite `38472`.
   - `IA_ITEM_ID` (optional) — Internet Archive item id (default `myspace_dragon_hoard_2010`).
   - `SERVE_STATIC` — serve SPA from `dist/` on the API port when built.
   - `CORS_ORIGINS` — comma-separated API CORS origins (production defaults to the public site).
   - `PUBLIC_SITE_URL` / `VITE_PUBLIC_SITE_URL` — canonical URL for share links, oEmbed, embed snippet.
   - `VITE_EMBED_PARENT_ORIGIN` — restrict embed `postMessage` target (optional).

2. Install dependencies:

   ```bash
   npm install
   ```

3. Build the track index (required before first API start):

   ```bash
   npm run index-metadata
   ```

   Use `npm run index-metadata -- --if-stale` to skip when the DB is newer than the TSV (used by `npm run build`). Use `--force` to rebuild always.

## Development

Fast dev with a small TSV sample (optional):

```bash
npm run sample-metadata
# set METADATA_TSV=data/metadata.sample.tsv in .env, then:
npm run index-metadata -- --force
```

Start API + Vite:

```bash
npm run dev
```

Open the URL Vite prints (default `http://localhost:38472`).

## Production (static build + API)

```bash
npm run build
SERVE_STATIC=true npm run start
```

`npm run build` runs `index-metadata --if-stale`, compiles the server, and builds the SPA.

**PM2** (after `npm run build`):

```bash
npm run pm2:prod
pm2 save
```

Set `METADATA_TSV` / `TRACKS_DB` in `ecosystem.config.cjs` → `env_production` on the VPS. Re-run **`npm run index-metadata`** when `metadata.tsv` changes.

### Docker

```bash
docker compose build
docker compose up
```

Ensure `data/metadata.tsv` is present under `./data` (volume). The image runs `index-metadata --if-stale` during build when the TSV is copied in.

### VPS: “No tracks available” / `trackCount: 0`

1. Ensure **`data/metadata.tsv`** exists and run **`npm run index-metadata`**.
2. Check **`GET /api/health`**: `tracksReady: true`, `tracksDbExists: true`, `trackCount` > 0, `ftsReady: true`, and `hint` if something failed.
3. Restart PM2 after env changes: `pm2 restart mymusics --update-env`.

### Reverse proxy (e.g. `mymusics.murad.gg`)

Point HTTPS at the Node port (default `38471`). Example **nginx**:

```nginx
server {
  server_name mymusics.murad.gg;
  location / {
    proxy_pass http://127.0.0.1:38471;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
```

**Embed on third-party sites:** HTML responses use `Content-Security-Policy: frame-ancestors *`. Ensure the proxy does not add `X-Frame-Options: DENY`.

## Embed (`/embed`) — priority

Iframe URL: `https://mymusics.murad.gg/embed` with optional query params:

| Param | Default | Effect |
|-------|---------|--------|
| `autoplay` | `1` | `0` disables auto-advance and skips random load on mount |
| `theme` | `default` | `compact` — smaller layout |
| `start` | — | Track id — loads `GET /api/track/:id` |
| `brand` | `1` | `0` hides footer logo |
| `muted` | `0` | `1` starts **audio** muted |
| `preset` | `default` | Color preset: `light`, `dark`, `midnight`, `minimal` |
| `accent` | — | Accent hex (with/without `#`) |
| `bg` | — | Page background hex |
| `panel` | — | Panel/card background hex |
| `text` | — | Primary text hex |
| `fgMuted` | — | Secondary text hex (not audio mute) |
| `radius` | preset | Border radius 0–24 (px) |
| `font` | `sans` | `system`, `sans`, or `serif` |

Full customization guide (presets, CSS tokens, postMessage theme): **[docs/EMBED-CUSTOMIZATION.md](docs/EMBED-CUSTOMIZATION.md)**.

**postMessage** (iframe → parent), payload `{ source: "mymusics", type, ... }`:

- `mymusics:ready` — `{ trackCount }`
- `mymusics:track` — `{ id, title, artist, streamUrl }`
- `mymusics:state` — `{ state: "playing" \| "paused" \| "buffering" \| "error" }`
- `mymusics:error` — `{ code, message }`
- `mymusics:theme-applied` — `{ tokens }` after a theme change

Parent → iframe: `{ source: "mymusics-host", type: "mymusics:command", command: "play" \| "pause" \| "next" }`.

Parent → iframe (theme): `{ source: "mymusics-host", type: "mymusics:theme", theme: { preset, accent, ... } }`.

**oEmbed:** `GET /api/oembed?url=https://mymusics.murad.gg/embed`

The Home and About pages include a snippet generator with preset, accent, and live preview.

## API

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/health` | Diagnostics (`tracksDb`, `ftsReady`, `blockedCount`, …) |
| GET | `/api/track/random` | Random track + `streamUrl` |
| GET | `/api/track/up-next?exclude=` | Next track (prefers different id) |
| GET | `/api/track/:id` | Track by id |
| GET | `/api/track/search?q=&limit=` | Search by title/artist (FTS) |
| POST | `/api/reload` | Reload DB / paths from env |
| POST | `/api/events` | Client metrics (`stream_error`, `time_to_play`) |
| GET | `/api/oembed?url=` | oEmbed JSON for `/embed` |

## Share links

- `https://mymusics.murad.gg/?track=TRACK_ID`
- `https://mymusics.murad.gg/t/TRACK_ID` (redirects to `/?track=`)

## Maintenance

Weekly cron (optional) — sample Archive URLs and block failures:

```bash
npm run verify-tracks
```

Env: `VERIFY_SAMPLE_SIZE` (default `50`).

## Troubleshooting

### HTTP 503 on `/api/track/random`

The pool is empty. Run `npm run index-metadata` and verify `/api/health`.

### Console: TensorFlow / `content.js` messages

These come from **browser extensions**, not MyMusics.

## Playback notes

- Audio streams from `https://archive.org/download/...`. First play can be slow (ZIP member extraction).
- Archive **503** errors are retried automatically a few times; use **Next** if needed.
- Volume is remembered in `localStorage`. Shortcuts on Home: Space, N, M.

## Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Vite + API |
| `npm run index-metadata` | Build `data/tracks.db` from TSV |
| `npm run index-metadata:force` | Force rebuild index |
| `npm run sample-metadata` | Write `data/metadata.sample.tsv` (500 lines) |
| `npm run verify-tracks` | HEAD sample URLs → `blocked_ids` |
| `npm run build` | Index (if stale) + server + SPA |
| `npm run start` | Production Node server |
| `npm run test` | Vitest (metadata + track store) |
| `npm run pm2:prod` | Build + PM2 |

## Logo

`public/mymusics.png` is the MyMusics logo asset.