Sleep Meditation

Sleep Meditation is a self-hosted web player for MP3 files, optimized for mobile use.

Goal

A simple website that can play MP3 audio while an iPhone screen is locked, as long as playback is started manually (iOS limitation).

Features

• Playlist through mp3/playlist.json
• Automatic track discovery from /mp3/ when playlist.json is missing
• Standard HTML5 audio player
• Media Session API support (play/pause/next/previous on lock screen)
• Playlist ends at the last track (no automatic loop)
• Back to start button resets to track 1 without autoplay
• Server-side audio download via URL (avoids browser timeout on long files)
• Downloaded tracks stored in /mp3/downloads/, played individually (no auto-advance)
• Track titles editable via Settings page (titles stored separately from filenames)
• Rename and delete downloaded tracks via Settings
• Two-page UI: player + settings (hash routing)
• PWA manifest + service worker
• Containerized with Nginx + Python API (supervisord)

Repository layout

• containers/sleep-meditation/: web player Docker image, Nginx config, Python API, web app
• containers/sleep-meditation-downloader/: downloader image (server-side track downloads)
• stack/docker-compose.yml: Portainer/Compose stack (shared stack convention)
• stack/stack.env: environment variables (documents what Portainer supplies)
• docs/TECHNICAL.md: technical details and iPhone behavior

Deploy (Portainer)

The stack follows the shared stack convention: ENV (dev/prod) and IMAGE_TAG (dev/latest) select the environment, APP_PORT/DOWNLOADER_PORT are the host ports, and the mp3 folder is bind-mounted from /docker/appdata/${ENV}-sleep-meditation/mp3.

1. Deploy stack/docker-compose.yml with the variables from stack/stack.env.
2. Ensure /docker/appdata/<env>-sleep-meditation/mp3 exists on the host and holds the MP3 files (the container reads it at /usr/share/nginx/html/mp3).
3. Optionally add playlist.json in that folder for custom ordering/metadata.
4. Open http://<host>:${APP_PORT} and press Play manually once.

Playlist format

mp3/playlist.json

[
  {
    "title": "Deep Sleep Wave",
    "artist": "Sleep Meditation",
    "src": "/mp3/deep-sleep-wave.mp3"
  }
]

Download a track

Open Settings in the app, enter a direct audio URL and a title, then press Download. The file is downloaded server-side and saved to mp3/downloads/. It appears in the Downloads section on the main page.