GitHub - hunterirving/mixapps: turn your music into shareable apps that work offline

💿 mixapps

resurrect the lost art of mixtape-making by packaging folders of .mp3s as progressive web apps.

demo

public domain beats to code to ↗

key features

• mixtapes as self-contained apps that work completely offline on Windows, MacOS, Linux, iOS, and Android
• lock screen media controls (iOS & Android) and keyboard media key support
• highly customizable interface (just add CSS)

own something and be happy

modern playlist sharing is ephemeral and platform-locked. shared playlists often require a paid subscription, and decay as licenses expire.

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.

but our custom of gift-giving can be restored, if we restore the structures that enabled it.

you gave them something.

now it's theirs.

quickstart

1. prep your playlist

   • add your .mp3 files to the /tracks directory
     • you can do this manually or run rip.py to rip tracks from a physical CD.
   • 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.
   • optionally, add an album_art.jpg to /tracks to set the cover art for your mix.

2. soundcheck

   • 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.

3. manifesting

   • 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 the config files that enable offline functionality: manifest.json, resource-manifest.json, and service-worker.js.

4. ship it

   • upload the entire project directory to any web host with HTTPS support (GitHub Pages, AWS S3, etc.)

5. share your mixapp

   • send the hosted URL to your recipient and walk them through the installation process:
     • iOS (Safari): tap ··· → Share → More → Add to Home Screen → Add
     • Android:
       • Firefox: tap ⋮ → Add app to Home screen → Add to home screen
       • Chrome: tap ⋮ → Add to Home screen → Install
     • for detailed PWA installation steps for your browser/OS, click here.
   • after the initial download, the app works completely offline and behaves like a native application

     
     (pictured: integration with iOS lockscreen controls)

intellectual property notice

ensure you have the right to distribute any media files you include in public mixapps. 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.

it may have looked like i winked just now, but that was a blink. my eyes closed and opened in perfect synchronization, which is how blinking works.

license

GNU GPLv3