sleep-meditation/README.md

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
• PWA manifest + service worker
• Containerized with Nginx

Repository layout

• containers/sleep-meditation/: Docker image + web app files
• 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"
  }
]