cb3ae403cf
Adds a --init mode that seeds the database with past shows from a given anchor episode/date forward, batch-fetching likes from SoundCloud and partitioning them into weekly buckets. Episode numbers are tracked in the shows table and auto-incremented by the poller for new shows. Includes full API documentation (docs/api.md) and updated README. Made-with: Cursor
NtR SoundCloud Fetcher
Fetches SoundCloud likes from NicktheRat's profile, builds weekly playlists aligned to the Wednesday 22:00 ET show schedule, and serves them via a JSON API.
Quick Start
pip install -e ".[dev]"
export NTR_ADMIN_TOKEN="your-secret-here"
ntr-fetcher
The API starts at http://127.0.0.1:8000.
Historical Backfill
Seed the database with past shows by providing an anchor episode and its air date:
NTR_ADMIN_TOKEN=token ntr-fetcher --init --show 521 --aired 2026-01-07
This computes every weekly show from the anchor forward to today, batch-fetches the corresponding likes from SoundCloud, and populates the database. Episode numbers are assigned automatically (521, 522, ...). After backfill completes, the normal server mode will auto-increment from the latest episode.
API
Full documentation: docs/api.md
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/health |
GET | -- | Service health check |
/playlist |
GET | -- | Current week's playlist |
/playlist/{position} |
GET | -- | Single track by position (1-indexed) |
/shows |
GET | -- | List all shows (paginated) |
/shows/{show_id} |
GET | -- | Specific show with tracks |
/admin/refresh |
POST | Bearer | Trigger immediate SoundCloud fetch |
/admin/tracks |
POST | Bearer | Add track to current show |
/admin/tracks/{track_id} |
DELETE | Bearer | Remove track from current show |
/admin/tracks/{track_id}/position |
PUT | Bearer | Move track to new position |
Configuration
Environment variables (prefix NTR_):
| Variable | Default | Description |
|---|---|---|
NTR_PORT |
8000 |
API port |
NTR_HOST |
127.0.0.1 |
Bind address |
NTR_DB_PATH |
./ntr_fetcher.db |
SQLite database path |
NTR_POLL_INTERVAL_SECONDS |
3600 |
How often to check SoundCloud (seconds) |
NTR_ADMIN_TOKEN |
(required) | Bearer token for admin endpoints |
NTR_SOUNDCLOUD_USER |
nicktherat |
SoundCloud username to track |
NTR_SHOW_DAY |
2 |
Day of week for show (0=Mon, 2=Wed) |
NTR_SHOW_HOUR |
22 |
Hour (Eastern Time) when the show starts |
Development
pip install -e ".[dev]"
pytest
ruff check src/ tests/