Sleep Meditation — Technical Documentation

Scope

This project provides a static web app in a container that plays MP3 audio on desktop and mobile, including iPhone lock-screen controls.

Architecture

Service: sleep-meditation
Runtime: nginx:alpine
App: static frontend (index.html, styles.css, app.js)
MP3 source: mounted host volume at /usr/share/nginx/html/mp3

iPhone background playback

Important on iOS:

Autoplay without user interaction is blocked.
The user must start playback manually at least once.
After playback starts, audio usually continues when the screen is locked.
Media Session API enables lock-screen controls for play/pause/track skip.

Player controls

Previous: go to previous track (clamped at first track)
Play/Pause: toggle playback
Next: go to next track (clamped at last track)
Back to start: select first track, reset position to 0:00, no autoplay

When a track ends:

If there is a next track, it starts automatically.
If the last track ends, playback stops (no loop).

File overview

containers/sleep-meditation/
  Dockerfile
  nginx.conf
  site/
    index.html
    styles.css
    app.js
    manifest.webmanifest
    service-worker.js
    mp3/playlist.json
stack/
  stack.yml
  sleep-meditation.env

Track loading behavior

The app loads tracks in this order:

/mp3/playlist.json
Auto-discovery from /mp3/ directory listing (Nginx autoindex on)
Built-in fallback track (/mp3/example.mp3)

Playlist contract

File: /mp3/playlist.json

[
  {
    "title": "Track name",
    "artist": "Artist",
    "src": "/mp3/track.mp3"
  }
]

Rules:

title optional (derived from filename if omitted)
artist optional
src required; absolute path within web root (/mp3/...) or relative filename

Container healthcheck

Endpoint: GET /
Expected: HTTP 200
Configured in Dockerfile with wget

1.9 KiB Raw Blame History