From ffbe601cee02023e84e70832d92811ca51fccd9f Mon Sep 17 00:00:00 2001
From: Ole-Morten Duesund <olemd@glemt.net>
Date: Tue, 17 Mar 2026 17:12:43 +0100
Subject: [PATCH] Update README for 3-file structure and probe tool

Reflect the split into index.html/style.css/app.js, document the
probe-songs.py workflow and songs.json auto-loading, remove outdated
instructions about editing SONGS array in index.html.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 70 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 42 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 2403265..3124d5b 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Part of [donothireus.com](https://donothireus.com).
 
 ## Quick start
 
-The entire player is a single HTML file with no build step.
+No build step, no package manager. Just serve the `public/` directory:
 
 ```bash
 cd public/
@@ -16,15 +16,20 @@ python3 -m http.server 8080
 # open http://localhost:8080
 ```
 
-Or with any other static file server (caddy, nginx, etc).
+Or with any other static file server (Caddy, nginx, etc).
 
 ## Project structure
 
 ```
 public/
-├── index.html          # The complete player (React + Tone.js via CDN)
+├── index.html          # HTML shell, CDN script tags, meta/OG tags
+├── style.css           # Animations, hover/focus states, range styling
+├── app.js              # All React components and logic (JSX via Babel)
 └── audio/              # Drop MP3 files here for real music
+    ├── songs.json      # Generated by tools/probe-songs.py (gitignored)
     └── .gitkeep
+tools/
+└── probe-songs.py      # Probe audio files → songs.json
 ```
 
 ## Deploying to donothireus.com
@@ -63,28 +68,40 @@ CC-licensed tracks.
 
 1. Download CC-BY licensed MP3s (see sources below)
 2. Put them in `public/audio/`
-3. Edit the `SONGS` array in `index.html`, adding a `url` property:
+3. Run the probe tool to generate `songs.json`:
 
-```javascript
-// Before (procedural):
-{ title: "Bureaucratic Sunrise", artist: "The Paywalls",
-  duration: 90, bpm: 120,
-  gen: (s,t) => { ... },
-  wave: "triangle", color: "#e74c3c" },
-
-// After (real audio):
-{ title: "Sneaky Snitch", artist: "Kevin MacLeod",
-  duration: 120,
-  url: "/audio/sneaky-snitch.mp3",
-  color: "#e74c3c" },
+```bash
+./tools/probe-songs.py -d public/audio
+# Writes public/audio/songs.json automatically
 ```
 
-When a song has a `url` property, the player uses HTML5 Audio
-instead of Tone.js. You can mix and match — some songs procedural,
-some real MP3s.
+The app fetches `audio/songs.json` on startup. If it exists and
+contains tracks, they replace the procedural builtins. If not,
+the synth songs are used as a fallback.
 
-Set `duration` to the actual track length in seconds. The color
-is used for the progress bar and visualizer.
+The generated JSON looks like:
+
+```json
+[
+  {
+    "title": "Sneaky Snitch",
+    "artist": "Kevin MacLeod",
+    "duration": 120,
+    "url": "/audio/sneaky-snitch.mp3",
+    "color": "#e74c3c"
+  }
+]
+```
+
+Title and artist are extracted from ID3 tags when available,
+falling back to the filename. Duration comes from ffprobe.
+
+You can also probe specific files or write to a custom path:
+
+```bash
+./tools/probe-songs.py public/audio/track1.mp3 public/audio/track2.mp3
+./tools/probe-songs.py -o public/audio/songs.json *.mp3
+```
 
 ### Where to get CC-BY music
 
@@ -117,14 +134,11 @@ All of these are free to use with attribution (CC-BY or CC0):
 cd public/audio/
 wget -O sneaky-snitch.mp3 "https://incompetech.com/music/royalty-free/mp3-royaltyfree/Sneaky%20Snitch.mp3"
 
-# Get the duration in seconds (needs ffprobe)
-ffprobe -v quiet -show_entries format=duration -of csv=p=0 sneaky-snitch.mp3
-# output: 120.123456  (use 120)
+# Generate songs.json from all audio in the directory
+cd ../..
+./tools/probe-songs.py -d public/audio
 ```
 
-Then update the SONGS array in index.html with the title, artist,
-duration, url, and color.
-
 ### Attribution
 
 If using CC-BY music, add attribution. The fine print at the
@@ -145,7 +159,7 @@ credits section. Kevin MacLeod's required format:
 
 The starting wallet is randomized between $0.50 and $10.00
 each page load. The +$10 button lets people keep exploring
-all the paywalls.
+all the paywalls (with a $0.50 processing fee, naturally).
 
 ## License