Free Music Finder

wagenhoffer.dev's Free Music Finder for Creative Commons music discovery on Bandcamp.

Based on the original handeyeco/cc-bc dataset project.

Run locally

1. Install Node.js 18+.
2. Start the app:

npm start

3. Open http://localhost:4173.

No Vite, no React build step. It is a plain static app (index.html, app.js, styles.css) served by server.js.

Asset versioning

npm start and npm run dev automatically run:

npm run generate:license-counts
npm run version-assets

generate:license-counts rebuilds public/license-counts.json from public/urls.json so homepage license counts stay in sync with the dataset.

This stamps hash-based ?v= query params into index.html for styles.css and app.js so CDN/browser caches refresh immediately when assets change.

If you deploy by copying files directly (for example with rsync to /var/www/...), run npm run generate:license-counts and npm run version-assets before syncing.

Dataset sync workflow

Local favorites are managed in:

• config/favorites.bc_ids.json

To sync from upstream while preserving your favorites overlay:

npm run sync:urls
npm run check:urls

sync:urls downloads upstream urls.json, reapplies your favorites by bc_id, writes public/urls.json, and regenerates public/license-counts.json.

check:urls validates:

• no duplicate url_id values
• all overlay bc_id values exist in public/urls.json
• only overlay bc_id values are marked as favorites

To verify whether public/urls.json would change without writing files:

npm run sync:urls:check

Deploy to live

To sync this repo to /var/www/music.wagenhoffer.dev:

npm run deploy:live

Dry run (prints commands only):

npm run deploy:live:dry

Custom target path:

bash scripts/deploy-live.sh --target /var/www/your-site

The deploy script:

• runs npm run generate:license-counts
• runs npm run version-assets (unless --skip-version-assets is passed)
• syncs index.html, app.js, styles.css, and public/
• prints urls.json row/favorite counts after deploy