cottongin/NtR-soudcloud-fetcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add IRC commands/plugin setup to README, update WebSocket docs

Browse Source 
README was missing IRC command reference, plugin installation/config
guidance, and referenced nonexistent plugin READMEs. The WebSocket
docs in api.md were stale — subscribe message now documents role and
client_id fields, status message now includes the clients array.

Made-with: Cursor
This commit is contained in:
cottongin
2026-03-12 08:26:16 -04:00
parent 911dd3d5dd
commit 0f99e7914b
2 changed files with 82 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
README.md
View File

@@ -78,8 +78,57 @@ Enable by setting these environment variables:
| `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.
## 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:
```bash
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

33
docs/api.md
View File

@@ -412,23 +412,52 @@ WebSocket endpoint for receiving announce broadcasts. Used by IRC bot plugins.
After connecting, send a subscribe message:
```json
{"type": "subscribe", "token": "<NTR_ADMIN_TOKEN>"}
{
"type": "subscribe",
"token": "<NTR_ADMIN_TOKEN>",
"role": "bot",
"client_id": "limnoria"
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | yes | Must be `"subscribe"` |
| `token` | string | yes | `NTR_ADMIN_TOKEN` value |
| `role` | string | no | Client role, defaults to `"bot"` |
| `client_id` | string | no | Identifier for this client (e.g. `"sopel"`, `"limnoria"`) |
Invalid token closes the connection with code `4001`.
**Messages from server**
Announce broadcast:
```json
{"type": "announce", "message": "Now Playing: Song #1: Title by Artist - URL"}
```
Status update (sent on subscriber connect/disconnect):
```json
{"type": "status", "subscribers": 2}
{
"type": "status",
"subscribers": 2,
"clients": [
{
"client_id": "limnoria",
"remote_addr": "1.2.3.4",
"connected_at": "2026-03-12T02:00:00+00:00"
}
]
}
```
| Field | Type | Description |
|-------|------|-------------|
| `subscribers` | integer | Number of connected bot clients |
| `clients` | array | List of connected bot clients with their `client_id`, `remote_addr`, and `connected_at` timestamp |
---
## Dashboard Configuration