restructure readme
Hunter
Thursday, November 13th, 2025 at 9:52 PM
2
3 resurrect the lost art of <a href="https://ihavethatonvinyl.com/liner-notes/the-lost-art-of-the-mixtape/">mixtape</a><a href="https://melos.audio/blogs/information/the-lost-art-of-the-mixtape">-making</a> by packaging folders of .mp3s as progressive web apps.
4
-<img src="readme_images/collection.jpeg" width="550">
5 +<p align="center">
6 + <img src="readme_images/collection.jpeg" width="550">
7 +</p>
8
9 ## demo
10 <a href="https://hunterirving.com/vibe_capsule">public domain beats to code to ↗</a>
11
12 ## key features
13 - mixtapes as self-contained apps that work completely offline on Windows, MacOS, Linux, iOS, and Android
-- lock screen media controls (iOS & Android)
-- keyboard media key support (▶️, ⏸️, ⏭️, ⏮️)
14 +- lock screen media controls (iOS & Android) and keyboard media key support (▶️, ⏸️, ⏭️, ⏮️)
15 - highly customizable interface (just add CSS)
16
-<img src="readme_images/playlist.png" width="500">
17 +<p align="center">
18 + <img src="readme_images/playlist.png" width="500">
19 +</p>
20
21 ## own something and be happy
22 modern playlist sharing is ephemeral and platform-locked. shared playlists often require a paid subscription, can be modified after sharing, and decay as licenses expire.
23 > [!WARNING]
24 > <i>This song is no longer available in your country or region.</i>
25
-in the transition from physical mixtapes to cloud-hosted playlists, we lost the ability to give each other digital things. these days, we mostly point to things that we don't control.
26 +in the transition from physical mixtapes to cloud-hosted playlists, we stopped giving each other digital things. these days, we mostly point to things that we don't control.
27
-but digital things can be gifts too, if we preserve the gift-giving structure.
28 +but our custom of gift-giving can be restored, if we restore the structures that enabled it.
29
-this project aims to resurrect what made mixtapes meaningful: permanence, ownership, and intention. when you gift someone a mixapp, you're giving them a digital artifact. something that can persist on their device independent of platforms, algorithms, or corporate whim.
30 +when you give someone a mixapp, you're giving them a digital artifact – something that can persist on their device independent of platforms, contracts, or corporate whim.<br><br>
31
-it's yours, and then it's theirs.
32 +you gave them something.
33 +
34 +now it's theirs.
35 +
36 +hits different, right?<br><br>
37
38 ## quickstart
-1. **add your .mp3 files** to the `/tracks` directory
- - you can do this manually or run `rip.py` to rip tracks from a physical CD
39 +1. **prep your playlist**
40 + - add your .mp3 files to the `/tracks` directory
41 + - you can do this manually or run `rip.py` to rip tracks from a physical CD.
42 + - run `scan.py` to parse `/tracks` and populate `tracks.json`, which defines the songs available to the player. after running `scan.py` once, you can manually edit `tracks.json` to refine your mix.
43 + - optionally, add an `album_art.jpg` to `/tracks` to set the cover art for your mix.
44
-2. **give it a listen**
- - run `scan.py` to parse the contents of `/tracks` and populate `tracks.json`, which defines the songs available to the player. after running `scan.py` once, you can manually edit `tracks.json` to refine your mix.
- - run `host.py` to start a local HTTP server for testing. scan the QR code printed to the terminal to test the app from any device on your local network.
45 +3. **soundcheck**
46 + - run `host.py` to start a local HTTP server for testing. you can scan the QR code printed to the terminal to test the app from any device on your local network.
47
-3. **build the PWA**
- - run `generate_manifests.py` and follow the interactive prompts to specify an app name and the remote server path where your app will be hosted. this creates:
- - `manifest.json` (PWA configuration file)
- - `resource-manifest.json` (defines the files to be cached for offline use)
- - `service-worker.js` (manages offline caching)
- - optionally, add an `album_art.jpg` to `/tracks`. it'll be used as the cover for your mix when playing on supported devices.
48 +4. **manifesting**
49 + - run `generate_manifests.py` and follow the interactive prompts to specify an app name and the remote server path where your app will be hosted.
50 + - this creates the config files that enable offline functionality: `manifest.json`, `resource-manifest.json`, and `service-worker.js`.
51
-4. **deploy your mixapp**
52 +5. **ship it**
53 - upload the entire project directory to any web host with HTTPS support (GitHub Pages, AWS S3, etc.)
54
-5. **install on your device**
- - visit the hosted URL and follow your browser's prompts to "install" or "add app to home screen" (detailed instructions <a href="https://hunterirving.github.io/web_workshop/pwa">here</a>)
- - once installed, the app works completely offline and behaves like a native application<br><br>
55 +6. **share your mixapp**
56 + - send the hosted URL to your recipient and walk them through the installation process:
57 + - **iOS (Safari)**: tap `···` → Share → More → Add to Home Screen → Add
58 + - **Android**:
59 + - **Firefox**: tap `⋮` → Add app to Home screen → Add to home screen
60 + - **Chrome**: tap `⋮` → Add to Home screen → Install
61 + - for detailed PWA installation steps for your browser/OS, <a href="https://hunterirving.github.io/web_workshop/pwa">click here</a>.
62 + - after the initial download, the app works completely offline and behaves like a native application<br><br>
63 <img src="readme_images/lock_screen.jpeg" width="275"><br>
64 (pictured: integration with iOS lockscreen controls)
65
Binary files differ.
