# 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

```bash
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:

```bash
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`](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 |

Bot plugins (Sopel and Limnoria) connect to the API's WebSocket endpoint
to receive announcements. See plugin READMEs for configuration.

## Development

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