76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# Architecture
|
|
|
|
## Design (DDD layering)
|
|
|
|
```
|
|
cmd/ thin entrypoints: env parsing, wiring, loops. No logic.
|
|
internal/app/ application services: LoadLibrary, Transcode, Ship.
|
|
internal/infra/ infrastructure adapters: m3u writer, icecast SOURCE client,
|
|
MQTT 3.1.1 client, ffmpeg/scp process runners.
|
|
internal/domain/ pure core: Track, UnixTime, FilterPlayable, BuildPlaylist.
|
|
```
|
|
|
|
Dependency rule: `cmd → app → infra → domain`. The domain imports nothing
|
|
project-internal and performs no I/O — playlist policy is 100% unit-testable.
|
|
|
|
## Key decisions
|
|
|
|
1. **Generator and stream are decoupled by files, not by a queue.**
|
|
The shipper drops `playlist.m3u8` + mp3s + `titles.json` into the VPS
|
|
web root; the streamer re-reads them each lap. Consequences:
|
|
- generator machine can sleep; the stream keeps playing shipped music
|
|
- no broker/queue dependency; scp is the sync primitive
|
|
- playlist is the single source of truth for what's on air
|
|
|
|
2. **Continuous live stream, not playlist-file playback.**
|
|
Old stereos handle one URL (`/ai-radio.mp3`) far better than m3u
|
|
playlists (gaps, no re-fetch). The m3u8 still ships as a fallback
|
|
artifact and as the streamer's work list.
|
|
|
|
3. **Titles reach the stereo two ways:**
|
|
- **ID3 tags** baked into each mp3 at transcode time (ID3v2.3 + ID3v1
|
|
fallback) — what the stereo display actually reads from the stream
|
|
- **`titles.json` sidecar** → MQTT now-playing — for dashboards/logging,
|
|
because parsing ID3 from a live stream is painful
|
|
|
|
4. **Zero third-party Go deps.** MQTT 3.1.1 and the icecast SOURCE protocol
|
|
are small enough to hand-roll (see `internal/infra/mqtt.go`,
|
|
`icecast.go`); both are wire-tested against `tests/fakes.py`. ffmpeg and
|
|
scp are the only external binaries.
|
|
|
|
5. **Playlist policy lives in the domain.**
|
|
`BuildPlaylist(tracks, size, bias, seed)`: newest-biased weighted random
|
|
(weight = 1/(rank+bias)), disliked tracks filtered, deterministic under
|
|
seed. Changing musical behavior never touches I/O code.
|
|
|
|
6. **Failure posture: the stream never dies.**
|
|
- MQTT publish failure → log and continue
|
|
- icecast drop → reconnect loop (10s backoff)
|
|
- bad file in playlist → skip
|
|
- empty library → wait, don't crash
|
|
- playlist titles are sanitized: newlines flattened and `#EXT` stripped
|
|
so a song title can't forge a playlist entry (tested)
|
|
|
|
## Data flow contract
|
|
|
|
Shipper → VPS web root (`web/ai-radio/`):
|
|
- `<track-id>.mp3` — 128k 44.1kHz stereo, ID3v2.3+ID3v1, title=DisplayTitle
|
|
- `playlist.m3u8` — #EXTM3U, order = on-air order, relative filenames
|
|
- `titles.json` — `{"<track-id>": "<display title>"}`
|
|
|
|
Streamer → MQTT (QoS 0, topic `airstudio/nowplaying`):
|
|
```json
|
|
{"station":"AI Radio","title":"Neon Rain","artist":"AI Radio",
|
|
"track":"Neon Rain","file":"<id>.mp3",
|
|
"stream_url":"https://…/ai-radio.mp3","ts":1790798159}
|
|
```
|
|
|
|
## Known trade-offs
|
|
|
|
- Streamer opens a fresh MQTT connection per track (fire-and-forget, simple).
|
|
Fine at one publish per ~2 min.
|
|
- scp re-uploads whole files; no delta sync. At 128k a 3-min song ≈ 2.8 MB —
|
|
negligible.
|
|
- The streamer assumes all mp3s share 44.1kHz stereo (enforced at transcode).
|
|
Mixing in foreign files can glitch the stream boundary.
|