139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# Radio Susan 📻
|
||
|
||
Personal internet radio station. 24/7 automated playback from a music library with smart DJ logic, energy-based scheduling, TTS announcements, and jingles.
|
||
|
||
**Stream:** `https://radio.jihakuz.xyz/stream` (MP3 192kbps)
|
||
|
||
## Stack
|
||
|
||
| Component | Role |
|
||
|-----------|------|
|
||
| **Icecast2** | Streaming server |
|
||
| **Liquidsoap** | Radio automation — reads playlist, inserts jingles, outputs to Icecast |
|
||
| **generate_daily_playlist.py** | Builds a full 24h playlist with baked-in TTS announcements |
|
||
| **generate_site.py** | Generates a static HTML "now playing" site from the playlist |
|
||
| **radio_dj.py** | Fallback per-track DJ when no daily playlist exists |
|
||
| **dj_core.py** | Shared logic: track loading, energy filtering, cooldowns, modes |
|
||
| **analyse_tracks.py** | Essentia audio feature extraction (energy, BPM) |
|
||
| **build_genre_cache.py** | Genre cache from beets DB |
|
||
| **generate_jingles.py** | Generates jingle MP3s from TTS + SFX |
|
||
| **edge-tts** | Microsoft Edge TTS engine for announcements |
|
||
|
||
## How It Works
|
||
|
||
### Daily Pipeline
|
||
|
||
Every midnight, `generate_daily_playlist.py` builds a complete 24-hour playlist:
|
||
|
||
1. **Loads all tracks** from beets DB + genre cache + Essentia audio features
|
||
2. **For each hour**, looks up target energy from an energy curve (ambient at night, high energy in the evening)
|
||
3. **Picks a mode** (weighted random): shuffle 40%, deep cuts 20%, new to library 15%, old favourites 15%, full album 10%
|
||
4. **Selects a track** using contrast maximisation — prefers energy distance from recent picks
|
||
5. **Every 3 tracks**, generates a TTS announcement via edge-tts
|
||
6. **Outputs** `playlist.json` + `playlist.m3u` for Liquidsoap
|
||
|
||
Liquidsoap picks up the new playlist automatically via file watching.
|
||
|
||
### Fallback Chain
|
||
|
||
If the daily playlist is empty or missing:
|
||
1. `radio_dj.py` — same smart DJ logic, picks one track at a time
|
||
2. `all.m3u` — pure random shuffle of the entire library (last resort)
|
||
|
||
### Energy Schedule
|
||
|
||
The DJ schedules by **energy level**, not genre. Whatever genre fits the energy gets played.
|
||
|
||
| Show | Hours | Energy | Vibe |
|
||
|------|-------|--------|------|
|
||
| Night Drift | 00–07 | 1 | Ambient, drone |
|
||
| Morning Calm | 07–09 | 2–3 | Downtempo, chill |
|
||
| Late Morning | 09–12 | 4–5 | Indie, jazz, trip-hop |
|
||
| Lunch Break | 12–14 | 4 | Soul, dub |
|
||
| Afternoon Session | 14–17 | 5–6 | Electronic, funk |
|
||
| Drive Time | 17–19 | 5–6 | Mixed |
|
||
| Evening Heat | 19–22 | 7–8 | Techno, house, DnB |
|
||
| Wind Down | 22–00 | 2–4 | Comedown, ambient |
|
||
|
||
### Smart Modes
|
||
|
||
| Mode | Weight | Strategy |
|
||
|------|--------|----------|
|
||
| shuffle | 40% | Random from energy-matched pool |
|
||
| deep_cuts | 20% | Tracks with 0 plays |
|
||
| new_to_library | 15% | Added in last 14 days |
|
||
| old_favourites | 15% | Highest play count |
|
||
| full_album | 10% | Plays entire album in order |
|
||
|
||
### Cooldowns
|
||
|
||
- **Track:** 7 days
|
||
- **Artist:** 3 hours
|
||
- **Album:** 24 hours
|
||
- **Genre:** no back-to-back same genre
|
||
|
||
### Announcements vs Jingles
|
||
|
||
- **Announcements** are baked into the playlist at generation time — pre-rendered TTS clips inserted into the M3U every 3 tracks.
|
||
- **Jingles** are dynamic in Liquidsoap — randomly rotated from `/jingles/`, roughly 1 per 4 tracks.
|
||
|
||
## Audio Analysis
|
||
|
||
`analyse_tracks.py` uses Essentia to extract per-track features:
|
||
|
||
- **Energy** — normalised via percentile breakpoints to a 1–10 scale
|
||
- **BPM** — via RhythmExtractor2013
|
||
|
||
Results in `audio_features.db` (SQLite). Incremental — only analyses new files.
|
||
|
||
**Known issue:** BPM detection is unreliable for fast genres (hardcore, breakcore, DnB) — often reads half or a third of the real tempo.
|
||
|
||
## Static Website
|
||
|
||
`generate_site.py` builds a single-page dark-themed site:
|
||
|
||
- Now Playing banner (polls track state)
|
||
- Up Next preview
|
||
- Stats bar
|
||
- Collapsible show cards with full tracklists
|
||
- Inline listen button
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
# Copy secrets template
|
||
cp secrets.liq.example secrets.liq
|
||
# Edit with your Icecast password
|
||
nano secrets.liq
|
||
|
||
# Install Python deps
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install edge-tts essentia
|
||
|
||
# Crons (add to crontab)
|
||
0 0 * * * sg mediaserver "python3 generate_daily_playlist.py"
|
||
5 0 * * * sg mediaserver "python3 generate_site.py"
|
||
0 7 * * * python3 build_genre_cache.py
|
||
30 7 * * * venv/bin/python3 analyse_tracks.py
|
||
```
|
||
|
||
## Data Sources
|
||
|
||
| Source | Used for |
|
||
|--------|----------|
|
||
| Beets DB | Track metadata, genres, added date |
|
||
| Navidrome DB | Play counts, starred tracks |
|
||
| audio_features.db | Essentia energy + BPM |
|
||
| genre_cache.json | Genre-to-energy mapping |
|
||
|
||
## SFX Samples
|
||
|
||
The `sfx/` directory contains sound effects used by `generate_jingles.py`:
|
||
|
||
`airhorn` · `cashregister` · `countdown` · `crash` · `demon` · `meow` · `pirate_arr` · `pirate_plank` · `pirate_yaargh` · `reverb_hit` · `scream` · `static` · `sweep` · `synth_horn` · `text_tone`
|
||
|
||
## Resource Usage
|
||
|
||
Minimal. Icecast ~10MB RAM, Liquidsoap ~50–70MB RAM. Playlist generation ~2.5 minutes (mostly TTS). Analysis ~1s/track.
|