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/: Docker image, Nginx config, Python API, web app
• stack/stack.yml: Portainer/Compose stack
• stack/sleep-meditation.env: environment variables
• docs/TECHNICAL.md: technical details and iPhone behavior

Deploy (Portainer)

1. Deploy stack/stack.yml with variables from stack/sleep-meditation.env.
2. Ensure ${SLEEP_MEDITATION_MP3_PATH} points to a host folder containing MP3 files.
3. Optionally add ${SLEEP_MEDITATION_MP3_PATH}/playlist.json for custom ordering/metadata.
4. Open http://<host>:<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.