๐Ÿ’ฟ mixapps

mixapps are like mixtapes or mix CDs, but packaged as Progressive Web Apps that you can install for offline use.

demo

worn grooves โ†—
(public-domain recordings)

key features

own something and be happy

modern playlists are platform-locked, often require a paid subscription, and decay as licenses expire.

these days, we mostly point to things that we don't control.






mixapps are immutable artifacts.

they live on your devices, independent of platforms, contracts, and corporate whim.

once you install one, it's yours.

quickstart

  1. serve it

    • run ./serve.py to start a development server. while the server is running, you can:
      • add new tracks by...
        • adding them to the mix/ directory
        • dragging them into the browser window
        • running ./rip.py to rip tracks from a physical CD
        • running ./buy.py to buy tracks on iTunes
      • reorder tracks by dragging them up or down in the list
      • delete tracks with shift + click
  2. ship it

    • over your own network (recommended):
      • while ./serve.py is running (with HTTPS enabled), use your phone to scan the QR codes it prints to the console. no public host necessary, and nothing ever leaves your network (details).
    • using a public host:
      • when using media you have distribution rights for, you can upload the entire project directory to any static web host with HTTPS support (GitHub Pages, Neocities, AWS S3, etc).
        publishing files you don't have the right to distribute may constitute copyright infringement.
  3. save it

    • once your mixapp is hosted on an HTTPS-enabled server, anyone can install it by opening the URL and following their browser's PWA installation steps:
      • iOS (Safari): tap ยทยทยท โ†’ Share โ†’ View More โ†’ scroll down to reveal and tap Add to Home Screen โ†’ Add
      • Android:
        • Firefox: tap โ‹ฎ โ†’ ยทยทยท More โ†’ Add 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 and cache, mixapps work completely offline and behave like native applications โคต


      (pictured: integration with iOS lockscreen controls)

customization

add custom.css, custom.js, album_art.jpg, and/or icon.png to mix/ to customize your mixapp's appearance and behavior.

your mixapp's name (displayed on your device's home screen) is set by the first of these that applies:

local network installation

PWA installation requires a secure (HTTPS) connection. the easiest way to get one is to upload your files to a public host, but publishing files this way is only appropriate for content you have the right to distribute.

if you'd like to install mixapps without pushing to a public host, you can use serve.py to serve the necessary files over HTTPS on your local network.

how it works

normally, an HTTPS site proves its identity with a certificate signed by a certificate authority (CA) that browsers already trust. a server on your own network has no such signature, so browsers refuse connections by default.

mkcert bridges this gap with two pieces:

on each device you want to install a mixapp to, you add your local CA to that device's list of trusted Certificate Authorities. after that, its browser will automatically accept the certificate presented by your local server, letting you connect and install your mixapp as a PWA.

security

trusting a CA tells a device to trust any HTTPS certificate the CA issues (for any website, not just your mixapp server). in effect, you're asking the installing device to trust your computer to vouch for the whole web.

in practice the risk is small, because an attack needs three things to line up at once: your CA's private key has leaked off your computer, the attacker is on a network where they can intercept the installing device's traffic, and that device still trusts the CA. deny any one and there's nothing to exploit, so a few habits keep you safe:

usage

  1. run ./serve.py. it will offer to install mkcert if needed, then create a local certificate authority (CA) on your computer. if you decline, or your computer isn't connected to a network, it will serve over plain HTTP instead (you can still edit your mix, but other devices won't be able to install it).
  2. first time on a new device: scan the first QR code to download the CA certificate, then install and trust it.

    • iOS:

      1. scanning the QR code prompts you to allow the download. tap Allow.
        iOS prompt: this website is trying to download a configuration profile

      2. install it: open Settings โ†’ General โ†’ VPN & Device Management, tap the downloaded profile, and tap Install.
        iOS profile install screen for the mkcert CA

      3. trust it: open Settings โ†’ General โ†’ About โ†’ Certificate Trust Settings and toggle the CA on.
        iOS Certificate Trust Settings with the mkcert CA toggled on

    • Android: open the downloaded file, or go to Settings โ†’ Security โ†’ Encryption & credentials โ†’ Install a certificate โ†’ CA certificate, and confirm the install. (on Android, installing a user CA is what makes it trusted; there's no separate trust toggle. exact menu names vary by version/manufacturer.)

    a device that already trusts the CA from a previous run can skip this step.

  3. scan the second QR code to open your mixapp over HTTPS, then follow the PWA installation instructions for your device/OS to add it to your homescreen. after the initial installation and cache, mixapps work completely offline. they no longer need the network, server, or certificate.

cleaning up

licenses

this project is licensed under the GNU General Public License v3.0.

the Basteleur font by Keussel (distributed by Velvetyne) is licensed under the SIL Open Font License, version 1.1.