From cd8ed8bc5793985df2c1692072a932ceee517b95 Mon Sep 17 00:00:00 2001 From: salmonik Date: Wed, 8 Jul 2026 02:13:35 +0200 Subject: OPEN THE RUST GATES Signed-off-by: salmonik --- README.md | 159 +++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 95 insertions(+), 64 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e9cf127..9b1fea9 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,123 @@ -# Senator Sperma +# Senator Sperma (Rust) -A Discord bot with music playback, TTS, web search, and utility commands. +A Discord bot rebuilt in Rust from the original Python implementation. Music +playback via songbird, AI chat via OpenRouter or anything OpenAI compatible (ollama.cpp and such), TTS, web/file search +scheduled jobs, per-server triggers, QR codes, media conversion, and misc utilities. -Requires Python 3.14. +Built on poise 0.6 + serenity 0.12 + songbird 0.6, with async SQLite (sqlx 0.9) +for persistence. ## Setup -### 1. Clone & Create Virtual Environment +### 1. Clone ```bash git clone https://codeberg.org/salmonik/senator-sperma cd senator-sperma -python -m venv .venv -source .venv/bin/activate # Linux/macOS -# or .venv\Scripts\activate # Windows ``` -### 2. Install Dependencies +### 2. System Dependencies -```bash -pip install -r requirements.txt -``` +The following binaries must be available on `PATH`: + +- `ffmpeg` — audio decoding/encoding for playback, conversion, and compression +- `qalc` (Qalculate) — used by `/math` to evaluate expressions +- `yt-dlp` (optional) — used by `/download` -You also need `ffmpeg` and `zbar` library and installed system-wide +Unlike the Python version, QR encode/decode is handled by the pure-Rust +`qrcode`/`rxing` crates — no `zbar` system library required. -### 3. Create .env File +### 3. Build -Create a `.env` file in the project root: +Requires a recent Rust toolchain (edition 2024). ```bash -cp .env.example .env +cargo build --release ``` -Edit `.env` with your credentials: +### 4. Configure Environment -```env -# Required -TOKEN=your_discord_bot_token +Create a `.env` in the project root +look at `.env.example` on what to put there -# Optional - Bot Configuration -STATUS_CHANNEL_ID=123456789012345678 # Channel for startup message -ASSISTANT_KEYWORD=jarvis # Keyword to trigger AI assistant +On launch, missing variables are reported via tracing (`error!` for required, +`warn!` for optional with defaults). The database and schema migrations are +created automatically on first run. -# Optional - File Server (for music /search commands) -COPYPARTY_URL=http://localhost:8080 -COPYPARTY_PASSWORD=your_password - -# Optional - AI commands -OPENROUTER_API_KEY= -``` - -### 6. Run the Bot +### 5. Run ```bash -python main.py +cargo run --release ``` -## Configuration - -All settings are optional - defaults are provided if not set. - -| Variable | Description | Default | -|---------|-------------|---------| -| `TOKEN` | Discord bot token | (required) | -| `STATUS_CHANNEL_ID` | Channel for startup message | none | -| `ASSISTANT_KEYWORD` | Keyword to trigger AI assistant | `jarvis` | -| `COPYPARTY_URL` | File server base URL | `http://localhost:8080` | -| `COPYPARTY_PASSWORD` | File server password | none | -| `OPENROUTER_API_KEY` | AI API key (for /senator command) | none | - ## Commands -### Music -- `/play` - Play music from file server or an internet audio stream -- `/stop` - Stop playback -- `/join` - Join voice channel -- `/loop` - Loop current track - -### Utility -- `/search` - Search files on server -- `/web` - DuckDuckGo search -- `/download` - Download video/audio -- `/tts` - Text to speech -- `/qr_koduj` / `qr_dekoduj` - QR encode/decode -- `/kompresja` - Compress images -- `/konwersja` - Convert audio/video - -## Dependencies - -- `ffmpeg` - System-wide audio processing -- `py-cord` - Discord library (due to instable nature of discord's voice features, py-cord has to be installed directly from git) +Slash commands are autoregistered globally on startup. Some are registered +under their original Polish verb names to match the UI expected by existing +servers. + +### AI +- `/senator` — chat with the OpenRouter model + +### Music (songbird) +- `/grajcuj` — play from Copyparty search, a direct URL, or an uploaded file +- `/stop` — stop playback and leave voice +- `/join` — join the caller's voice channel + +### TTS +- `/tts` — Google Translate TTS (Polish), sent as a file or played in voice + +### Search & Web +- `/web` — DuckDuckGo HTML scrape (soon to use 4get) +- `/search` — search Copyparty and return a direct download URL +- `/download` — fetch media from any yt-dlp-supported URL + +### Media Tools +- `/compress` (alias `kompresja`) — compress a media attachment to low quality +- `/convert` (alias `konwersja`) — convert media between formats + +### Utilities +- `/upload` — push Discord attachments into Copyparty +- `/say` — repeat the given text as the bot +- `/math` — evaluate an ASCII math expression through `qalc` +- `/qr generowanie` / `/qr dekodowanie` — QR encode / decode + +### Triggers +- `/trigger create` — new trigger group +- `/trigger add` — add keywords/responses to a group +- `/trigger remove` — remove a keyword/response +- `/trigger delete` — delete a group +- `/trigger list` — list a group's keywords and responses +- `/trigger help` — usage info + +### Cron +- `/cron dodaj_audio` — schedule audio playback +- `/cron dodaj_wiadomość` — schedule a periodic message +- `/cron pokaż` — list all cron jobs +- `/cron usuń` — remove a cron job +- `/cron pauza` — pause a job +- `/cron wznów` — resume a job + +### Message Context Menu +- "Wyślij załączniki" (right-click message) — upload attachments to Copyparty +- "kompresja" (right-click message) — compress all attachments + +## Architecture + +The runtime is organised around a shared `Data` struct (poise `user_data`) +that holds the DB pool, HTTP client, Copyparty client, voice manager, the +in-memory trigger cache, autocomplete cache, and per-guild music track handles. + +- `src/main.rs` — boot: tracing, dotenvy, Config, DB pool, framework, cron task +- `src/config.rs` — env-driven `Config` + variable validation +- `src/commands/` — one module per command group +- `src/copyparty/` — Copyparty search/upload client +- `src/openrouter/` — OpenRouter chat client +- `src/database/` — sqlx pool, migrations, query helpers (6 tables) +- `src/voice/` — `VoiceManager`, mp3 → songbird input +- `src/events/` — `handle_ready`, voice-state, message (trigger matching) +- `src/tasks/` — 30s cron scheduler poll loop +- `src/lang.rs` — user-facing Polish strings + +All temporary files go through `crate::config::TEMP_PATH` +(`/tmp/senator_sperma`). -- cgit v1.2.3