Intial Commit

README.md

@@ -0,0 +1,82 @@
+## BasharBotV2 (Local audio Discord bot)
+
+A local-first Discord bot you can talk to. It:
+- **Joins** your voice channel when you type `hey bashar join`
+- **Plays YouTube music** when you say/type `hey bashar play <query>`
+- **Speaks** “Playing <title>” with local TTS (pyttsx3)
+- Built for Windows; runs entirely **locally** (no external APIs)
+
+### 1) Prerequisites (Windows)
+- Python 3.10–3.12
+- FFmpeg in PATH:
+  - PowerShell (Admin):  
+    ```powershell
+    choco install ffmpeg -y
+    ```
+- A Discord bot token created at the Developer Portal
+
+### 2) Setup
+```powershell
+cd "D:\7. Git\BasharBotV2"
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -U pip
+pip install -r requirements.txt
+```
+
+Create a `.env` file in the project root:
+```
+DISCORD_TOKEN=your-bot-token-here
+WHISPER_MODEL_SIZE=small
+```
+
+Note: The bot uses local TTS via `pyttsx3` (Windows SAPI).  
+Local STT (Whisper via `faster-whisper`) scaffolding is included and will be wired to live voice in a follow-up edit.
+
+### 3) Run
+```powershell
+.venv\Scripts\Activate.ps1
+python bot.py
+```
+
+### 4) Use
+In any text channel in your server:
+- `hey bashar join` — the bot joins your current voice channel.
+- `hey bashar play never gonna give you up` — bot speaks “Playing …” and streams the top YouTube result.
+- `hey bashar skip` — skips the current track but keeps the queue.
+- `hey bashar stop` — stops playback and clears the queue.
+- `hey bashar leave` — disconnects from voice.
+
+Speech (local STT via faster-whisper):
+- Send a voice message or audio file attachment that starts with your wake word in speech:
+  - Example voice: “hey bashar play never gonna give you up”
+  - The bot transcribes locally and executes the command.
+- Spoken `skip`/`stop` commands work the same way.
+- The wake word is tolerant (“hey bashar” / “hey bishar” / “hey vishar”, etc.) so mispronunciations still trigger the bot.
+
+Live hotword listening (wake word):
+- Enabled by default. After `hey bashar join`, the bot listens continuously for “hey bashar …”, even while music is playing, and reacts almost immediately (no more 5‑second clips).
+- Say “hey bashar leave” to stop listening and disconnect.
+- Voice receive needs Opus on your machine. On Windows install Opus via `pip install opuslib` (shown below) or drop an `opus.dll` beside `python.exe`. If you still see “Opus library not found”, set `OPUS_LIB=C:\Path\To\opus.dll` in `.env`.
+- Verifying Opus (Windows PowerShell):
+  ```powershell
+  .venv\Scripts\Activate.ps1
+  pip install opuslib
+  ```
+- To disable the listener, set `HOTWORD_ENABLED=false` in `.env`.
+- Optional voice reactions:
+  - Set `GOODBOY_USER_ID` in `.env` (default: `94578724413902848`). When that user speaks a complete English sentence, the bot queues `goodboy.ogg` locally.
+- Logging control via `.env`:
+  - `TRANSCRIPT_LOG_ENABLED=true/false`
+  - `TRANSCRIPT_LOG_PATH=custom/transcript/path.log`
+
+You can queue more tracks by repeating `hey bashar play ...`. The bot handles reconnectable streams.
+
+### 5) Notes
+- All processing is local. YouTube audio is streamed via `yt-dlp` + `ffmpeg`.
+- Library: now using `discord.py` 2.x (voice enabled with `PyNaCl`).
+- If you get an FFmpeg error, confirm it’s in PATH:  
+  `ffmpeg -version`
+
+
+