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/by-episode/{episode_number}	GET	--	Look up show by episode number
/shows/{show_id}	GET	--	Specific show by internal ID
/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/