add readme.md
Hunter
Friday, November 7th, 2025 at 11:26 PM
1 +# 💿 vibe capsule
2 +
3 +turn a folder of .mp3 files into a progressive web app, resurrecting 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>.
4 +
5 +<img src="readme_images/collection.jpeg" width="600">
6 +
7 +## live demo
8 +<a href="https://hunterirving.com/vibe_capsule">public domain beats to code to ↗</a>
9 +
10 +## key features
11 +- playlists as self-contained apps that work completely offline on Windows, MacOS, Linux, iOS, and Android
12 +- lock screen media controls (iOS & Android)
13 +- keyboard media key support (▶️, ⏸️, ⏭️, ⏮️)
14 +- highly customizable interface (just add CSS)
15 +
16 +<img src="readme_images/playlist.png" width="450">
17 +
18 +## own something and be happy
19 +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.
20 +> [!WARNING]
21 +> This song is no longer available in your country or region.
22 +
23 +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.
24 +
25 +but digital things can be gifts too, if we preserve the gift-giving structure.
26 +
27 +this project aims to resurrect what made mixtapes meaningful: permanence, ownership, and intention. when you gift someone a vibe capsule, you're giving them a digital artifact. something that can persist on their device independent of platforms, algorithms, or corporate whim.
28 +
29 +it's **yours** and then it's **theirs**.
30 +
31 +## quickstart
32 +1. **add your .mp3 files** to the `/tracks` directory
33 + - you can do this manually or run `rip.py` to rip tracks from a physical CD
34 +2. **give it a listen**
35 + - `scan.py` reads the contents of `/tracks` to populate `tracks.json`, which defines the songs that will be available to the player. after running `scan.py` once, you can manually edit `tracks.json` to refine your mix.
36 + - `host.py` starts a local HTTP server for testing. scan the QR code printed to the terminal to access your playlist from any device on your local network.
37 +3. **build the PWA**
38 + - in `generate_manifests.py`, update the following variables:
39 + ```python
40 + BASE_PATH = "/worn_grooves/" # deployment path on your server
41 + APP_NAME = "worn grooves" # a name for your mixtape
42 + ```
43 + - run `generate_manifests.py` to create:
44 + - `manifest.json` (PWA installation requirement)
45 + - `resource-manifest.json` (defines the files to be cached for offline use)
46 + - `service-worker.js` (manages the static file cache)
47 + - optionally, add an `album_art.jpg` to `/resources`. it'll be used as the cover for your mix when playing on supported devices.
48 +4. **deploy your playlist** as a Progressive Web App
49 + - upload the entire project directory to any web host with HTTPS support (GitHub Pages, AWS S3, etc.)
50 + - visit your 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>)
51 + - once installed, the app works completely offline and runs like a native application
52 +
53 +## requirements
54 +- python 3.x
55 +- modern web browser with PWA support
56 +- web server for deployment with HTTPS support (GitHub Pages, AWS S3, etc.)
57 +
58 +## intellectual property notice
59 +ensure you have the right to distribute any media files you include in public vibe capsules. personal archival backups are for your own use. sharing them with others, even as a gift, is not covered by fair use or backup exceptions.
60 +
61 +it may have looked like i winked just now, but i assure you, i did not. that was a blink. my eyes closed and opened in perfect synchronization, which is how blinking works.
62 +
63 +## license
64 +GNU GPLv3
Binary files differ.
Binary files differ.
