Matriarx Album Builder — Offline Setup

Offline / Off-Grid Setup

Enable true offline playback for your Matriarx players by hosting your MP3s on Cloudflare R2 or any S3-compatible bucket. This guide shows you how to configure CORS so the player can securely download and store tracks locally.

1. Bucket Setup & CORS Policy

Upload your MP3 files and artwork to your bucket. To enable Off-Grid Mode, apply this exact CORS policy:

CORS Policy (JSON)
[
  {
    "AllowedOrigins": [
      "https://matriarx.com",
      "https://www.matriarx.com",
      "https://yourdomain.com"
    ],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["Range", "Content-Type"],
    "ExposeHeaders": [
      "Accept-Ranges",
      "Content-Length",
      "Content-Range",
      "Content-Type",
      "ETag",
      "Last-Modified"
    ],
    "MaxAgeSeconds": 86400
  }
]
Important: The ExposeHeaders allow the player to check for updates and self-heal automatically.

2. How Off-Grid Mode Works

When enabled, the player downloads tracks to the user’s browser storage for offline playback. It intelligently:

  • Checks for newer versions of your tracks and auto-updates them
  • Self-heals within 24 hours if a track failed to download correctly
  • Resumes playback from where the user left off using browser memory
  • Stays awake even when the phone screen is off (unless aggressive battery saver is enabled)

3. Squarespace vs Private Storage

Squarespace: Works fine for online streaming, but does not support Off-Grid Mode due to CORS limitations.

Cloudflare R2 / S3-Compatible: Required for full offline functionality and automatic track updates.

Troubleshooting Checklist

  • Offline toggle does nothing: Check that your CORS policy exposes ETag, Last-Modified, and Content-Length.
  • Progress bar stuck: Browser is blocking the download — verify CORS and that URLs are direct .mp3 links.
  • Tracks not updating: The player automatically adds cache-busting — no manual action needed.