From a2b5b10625126b7e98643af9fe40569c9e004047 Mon Sep 17 00:00:00 2001
From: salmonik <raisersoft@proton.me>
Date: Sat, 18 Apr 2026 00:24:50 +0200
Subject: refactor + preparing bot for public use

Signed-off-by: salmonik <raisersoft@proton.me>
---
 README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 92 insertions(+), 2 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 7a23f7f..92468a7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,93 @@
-not modulable (yet) bot made for shits and giggles for me and my friends
+# Senator Sperma
 
-use python 3.13.12, since py-cord DOES NOT support 3.14 yet
\ No newline at end of file
+A Discord bot with music playback, TTS, web search, and utility commands.
+
+Requires Python 3.13 (py-cord doesn't support 3.14 yet).
+
+## Setup
+
+### 1. Clone & Create Virtual Environment
+
+```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
+
+```bash
+pip install -r requirements.txt
+```
+
+You also need `ffmpeg` and `zbar` library and installed system-wide
+
+### 3. Create .env File
+
+Create a `.env` file in the project root:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```env
+# Required
+TOKEN=your_discord_bot_token
+
+# Optional - Bot Configuration
+STATUS_CHANNEL_ID=123456789012345678  # Channel for startup message
+ASSISTANT_KEYWORD=jarvis  # Keyword to trigger AI assistant
+
+# 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
+
+```bash
+python main.py
+```
+
+## 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
+- `/funkcja` - Math plot
+- `/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)
-- 
cgit v1.2.3