sleep-meditation/docs/TECHNICAL.md

# Sleep Meditation — Technical Documentation

## Scope

This project provides a web app in a container that plays MP3 audio on desktop and mobile, including iPhone lock-screen controls. A separate internal container handles downloading and managing audio tracks.

## Architecture

Two containers share a host volume containing all MP3 files and metadata.

### sleep-meditation (public)
- Runtime: `nginx:1.27-alpine` + Python 3 (managed by supervisord)
- Nginx: serves static files and proxies `/api/` to the local Python API on `localhost:8001`
- Python API: read-only Flask app — lists downloaded tracks only (`GET /api/downloads`)
- App: frontend (`index.html`, `styles.css`, `app.js`)
- MP3 source: mounted host volume at `/usr/share/nginx/html/mp3`
- Externally accessible; no write operations exposed

### sleep-meditation-downloader (internal)
- Runtime: `python:3.12-alpine` + Flask
- UI: management page at `http://<host>:${SLEEP_MEDITATION_DOWNLOADER_PORT}/`
- API: all write operations — download, delete, rename downloads and playlist tracks
- MP3 volume mounted at `/mp3`
- Accessible on `${SLEEP_MEDITATION_DOWNLOADER_PORT}` within the local network (not publicly exposed)
- After downloading, use the refresh button in the sleep app to pick up new downloads

## File overview

```
containers/sleep-meditation/
  Dockerfile
  nginx.conf
  supervisord.conf
  api.py                  ← read-only: GET /api/downloads only
  site/
    index.html
    styles.css
    app.js
    manifest.webmanifest
    service-worker.js
    mp3/playlist.json
containers/sleep-meditation-downloader/
  Dockerfile
  api.py                  ← all write operations + UI file serving
  site/
    index.html
    styles.css
    app.js
stack/
  stack.yml
  sleep-meditation.env
```

## iPhone background playback

- 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.

## UI

Single page — no routing. Contains:

- Playlist selector and audio player with controls
- Downloads list (read-only, populated via `GET /api/downloads`)
- Refresh button (↺) in the header: reloads the full page; useful when the app is saved as a home screen bookmark on iPhone (no browser refresh available)

## 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 playlist track ends:

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

When a downloaded track ends:

- Playback stops. No auto-advance (`singleMode` flag is set when playing a download).

## Track loading behavior

The app loads meditation tracks in this order:

1. `/mp3/playlist.json`
2. Auto-discovery from `/mp3/` directory listing (Nginx `autoindex on`), excluding `/mp3/downloads/`
3. Empty list (no fallback track)

Downloaded tracks are loaded separately via `GET /api/downloads`.

## 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 (`/mp3/...`) or bare filename

When a track title is renamed via the downloader UI, the API writes the updated title back to `playlist.json`. If `playlist.json` does not yet exist in the volume, it is created from the current directory listing.

## Downloaded tracks

- Stored in `/mp3/downloads/` inside the mp3 volume.
- Filenames are URL- and filesystem-safe (letters, digits, spaces, hyphens only).
- Display titles (preserving special characters like `:` and `|`) are stored in `/mp3/downloads/titles.json`.
- Renaming a downloaded track updates `titles.json` only; the filename is not changed.
- Deleting a downloaded track removes the file and its entries from `titles.json` and `skip.json`.

## Skip intro

- A per-track skip offset (seconds) can be set in the downloader UI.
- Stored in `/mp3/downloads/skip.json` as `{ "filename.mp3": seconds }`.
- `GET /api/downloads` returns a `skip` field (default `0`) for each track.
- The sleep app seeks to `skip` seconds after `loadedmetadata` fires when playing a downloaded track.
- Setting skip to `0` removes the entry from `skip.json`.

## API endpoints

### sleep-meditation (public, read-only)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/downloads` | List downloaded tracks |

### sleep-meditation-downloader (internal only)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | Management UI |
| `GET` | `/api/downloads` | List downloaded tracks |
| `GET` | `/api/tracks` | List playlist tracks |
| `POST` | `/api/download` | Start server-side download `{url, title}` |
| `GET` | `/api/download/status/{track_id}` | Poll download status |
| `DELETE` | `/api/downloads/{filename}` | Delete a downloaded track |
| `POST` | `/api/downloads/{filename}/rename` | Rename display title `{title}` |
| `POST` | `/api/downloads/{filename}/skip` | Set skip-intro offset `{seconds}` |
| `POST` | `/api/tracks/rename` | Update playlist track title `{src, title}` |

## Container healthcheck

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