86 lines
1.9 KiB
Markdown
86 lines
1.9 KiB
Markdown
# 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:
|
|
|
|
1. `/mp3/playlist.json`
|
|
2. Auto-discovery from `/mp3/` directory listing (Nginx `autoindex on`)
|
|
3. Built-in fallback track (`/mp3/example.mp3`)
|
|
|
|
## Playlist contract
|
|
|
|
File: `/mp3/playlist.json`
|
|
|
|
```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`
|