[!WARN]
This project was developed entirely with AI coding assistance (Claude Opus 4.6 via Cursor IDE) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.

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
/login	GET/POST	--	Login page
/logout	GET	Session	Clear session
/dashboard	GET	Session	Live playlist dashboard
/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
/admin/announce	POST	Bearer/Session	Announce track to IRC

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

Dashboard

An optional web dashboard for announcing tracks to IRC during live shows. Nick opens the dashboard, sees the current and previous week's playlist, and clicks "Announce" next to a track to push it to the configured IRC channel via connected bot plugins.

Enable by setting these environment variables:

Variable	Default	Description
NTR_WEB_USER	(required)	Dashboard login username
NTR_WEB_PASSWORD	(required)	Dashboard login password
NTR_SECRET_KEY	(required)	Secret key for cookie signing

IRC Commands

Both Sopel and Limnoria plugins expose the same commands:

Command	Description
!1, !2, ... !N	Track by position in the current week's playlist
!song <episode> <position>	Track from a specific episode's playlist
!playlist [episode]	Current week's playlist, or a specific episode
!lastshow <position>	Track from the previous week's show
!status	API health, poller status, and track count
!refresh	Trigger a manual SoundCloud fetch (admin only)

IRC Plugin Setup

Both plugins require the websocket-client package for live announcements:

pip install websocket-client

Sopel

Copy plugins/sopel/ntr_playlist.py into your Sopel plugins directory (typically ~/.sopel/plugins/). Add a [ntr_playlist] section to your Sopel config:

Setting	Default	Description
api_base_url	http://127.0.0.1:8000	NtR API base URL
admin_token	(empty)	Bearer token for admin commands
admin_nicks	(empty)	Comma-separated list of admin nicknames
display_timezone	America/New_York	Timezone for displayed timestamps
ws_url	ws://127.0.0.1:8000/ws/announce	WebSocket endpoint for announcements
announce_channel	#sewerchat	Channel to send announcements to
client_id	sopel	Identifier for this bot in status messages

Limnoria

Copy the plugins/limnoria/NtrPlaylist/ directory into your Limnoria bot's plugins folder. Configure via the Limnoria registry:

Registry Value	Default	Description
apiBaseUrl	http://127.0.0.1:8000	NtR API base URL
adminToken	(empty)	Bearer token for admin commands
adminNicks	(empty)	Space-separated list of admin nicknames
displayTimezone	America/New_York	Timezone for displayed timestamps
wsUrl	ws://127.0.0.1:8000/ws/announce	WebSocket endpoint for announcements
announceChannel	#sewerchat	Channel to send announcements to
clientId	limnoria	Identifier for this bot in status messages

Development

pip install -e ".[dev]"
pytest
ruff check src/ tests/