m3u-webplayer

Turns a folder of MP3s and an M3U playlist into a self-contained web player, then uploads it to S3-compatible storage.

What it does

1. Reads playlist/*.m3u and the MP3 files it references
2. Enriches each track with ID3 tags and album art (embedded or fetched from iTunes)
3. Generates playlist/index.html — a fully self-contained web player (no external JS dependencies at runtime)
4. Generates playlist/qr.png — a QR code pointing to the public player URL, also embedded in the player UI
5. Uploads everything to S3, skipping files that haven't changed (ETag/MD5 comparison)
6. Prints the public URL

Setup

Directory layout

playlist/
  your-mixtape.m3u
  01 - Artist - Title.mp3
  02 - Artist - Title.mp3
  ...
config.yaml

config.yaml

output:
  name: ""          # leave empty to auto-generate a random 8-letter name
  s3:
    endpoint: https://s3.example.com
    region: us-east-1
    bucket: my-bucket
    public: https://my-bucket.example.com/
    access_key: ""  # or use environment variables (see below)
    secret_key: ""

name is saved back to config.yaml on first run so the same URL is reused on subsequent runs.

Credentials

S3 credentials can be provided via environment variables instead of (or to override) config.yaml:

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

If neither config nor environment provides credentials, the S3 upload is skipped and only the local playlist/index.html is generated.

Usage

go run .

Or build once and run:

go build -o m3u-webplayer .
./m3u-webplayer

Example output

Using deployment name: mrzocrze

Reading tags and cover art for 21 tracks…

Generated playlist/index.html — 21 tracks, 1:15:49

Uploading to https://s3.example.com/my-bucket/mrzocrze/…
  = 01 - Artist - Title.mp3                           (unchanged)
  ↑ index.html                                        0.0 MB
  ↑ qr.png                                            0.0 MB

Player URL: https://my-bucket.example.com/mrzocrze/

Player features

• Dark/light theme toggle
• Track list with cover art thumbnails, artist, album, duration
• Keyboard shortcuts: Space play/pause, J/↓ next, K/↑ previous, S shuffle, R repeat
• Shuffle and repeat modes
• QR code in the sidebar for easy sharing to mobile

Requirements

• Go 1.21+
• An S3-compatible object store (AWS S3, MinIO, Garage, etc.) with public read access on the bucket