initial

README.md

@@ -0,0 +1,166 @@
+# Discord Jukebox Bot
+
+A Discord bot written in Go that plays random music from a Subsonic-compatible server. The bot acts as a jukebox, streaming randomly selected songs directly to a Discord voice channel using real-time audio encoding.
+
+## Features
+
+- Connect to any Subsonic-compatible server (Subsonic, Navidrome, Airsonic, etc.)
+- Play random music in a Discord voice channel with real-time audio streaming
+- Automatic audio format conversion for Discord compatibility
+- Simple slash commands for controlling the jukebox
+- Configurable through environment variables
+
+## Requirements
+
+- Go 1.24 or later
+- A Discord bot token
+- A Subsonic-compatible server
+
+## Installation
+
+### From Source
+
+1. Clone the repository:
+   ```
+   git clone https://github.com/yourusername/discord-jukebox-bot.git
+   cd discord-jukebox-bot
+   ```
+
+2. Build the application:
+   ```
+   go build -o jukebox-bot ./cmd/bot
+   ```
+
+3. Set up environment variables (see Configuration section)
+
+4. Create a `.env` file in the project root (or set environment variables)
+
+5. Run the bot:
+   ```
+   ./jukebox-bot        # Normal mode
+   ./jukebox-bot -debug # Debug mode with verbose logging
+   ```
+
+## Discord Bot Setup
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Create a new application
+3. Navigate to the "Bot" tab and click "Add Bot"
+4. Under the "Privileged Gateway Intents" section, enable:
+   - Server Members Intent
+   - Message Content Intent
+   - Voice States
+5. Copy the bot token (this will be used in your environment variables)
+6. Go to the "OAuth2" -> "URL Generator" tab
+7. Select the following scopes:
+   - `bot`
+   - `applications.commands`
+8. Select the following bot permissions:
+   - Connect
+   - Speak
+   - Send Messages
+   - Use Slash Commands
+9. Copy the generated URL and open it in your browser to add the bot to your server
+
+## Configuration
+
+Configure the bot using environment variables with the `JUKEBOX_` prefix. You can set them in two ways:
+
+1. **Using a `.env` file** (recommended):
+   - Create a `.env` file in the project root directory (same location as the executable)
+   - Use the provided `.env.example` as a template
+   - The bot will automatically load variables from this file when it starts
+
+2. **Setting system environment variables**:
+   - Set the variables in your shell or operating system
+
+### Required Environment Variables
+
+- `JUKEBOX_DISCORD_TOKEN`: Your Discord bot token
+- `JUKEBOX_DISCORD_GUILD_ID`: The ID of your Discord server
+- `JUKEBOX_SUBSONIC_SERVER`: URL of your Subsonic server (e.g., `https://demo.subsonic.org`)
+- `JUKEBOX_SUBSONIC_USERNAME`: Your Subsonic username
+- `JUKEBOX_SUBSONIC_PASSWORD`: Your Subsonic password
+
+### Optional Environment Variables
+
+- `JUKEBOX_DISCORD_CHANNEL_ID`: Specific voice channel ID (bot will join user's channel if not specified)
+- `JUKEBOX_SUBSONIC_VERSION`: Subsonic API version (default: `1.16.1`)
+- `JUKEBOX_AUDIO_VOLUME`: Volume level from 0.0 to 1.0 for audio playback (default: `0.5`)
+- `JUKEBOX_TIMEOUT_SEC`: HTTP request timeout in seconds (default: `30`)
+
+### Sample .env File
+
+```
+# Required settings
+JUKEBOX_DISCORD_TOKEN=your_discord_bot_token_here
+JUKEBOX_DISCORD_GUILD_ID=your_discord_guild_id_here
+JUKEBOX_SUBSONIC_SERVER=https://your-subsonic-server.com
+JUKEBOX_SUBSONIC_USERNAME=your_subsonic_username
+JUKEBOX_SUBSONIC_PASSWORD=your_subsonic_password
+
+# Optional settings
+# JUKEBOX_DISCORD_CHANNEL_ID=specific_voice_channel_id
+# JUKEBOX_SUBSONIC_VERSION=1.16.1
+# JUKEBOX_AUDIO_VOLUME=0.5
+# JUKEBOX_TIMEOUT_SEC=30
+```
+
+## Troubleshooting
+
+If you encounter issues with the bot:
+
+1. First, run the bot in debug mode to get more detailed logs:
+   ```
+   ./jukebox-bot -debug
+   ```
+
+2. Check the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide for common problems and solutions.
+
+3. If you're having audio issues, the detailed logs in debug mode will show:
+   - If songs are being fetched correctly from your Subsonic server
+   - The exact URL being used to stream audio
+   - Audio encoding and streaming progress
+
+## Usage
+
+### Debug Mode
+
+If you're experiencing issues with the bot or want to see more detailed logs:
+
+```
+# Run with debug mode enabled
+./jukebox-bot -debug
+
+# Using make
+make run-debug
+```
+
+Debug mode provides:
+- Detailed logging of Subsonic API requests and responses
+- Audio encoding and streaming progress information
+- Configuration validation and detailed error messages
+
+### Commands
+
+The bot provides the following slash commands:
+
+- `/jukebox play` - Starts playing random music from your Subsonic library
+- `/jukebox stop` - Stops playing music and leaves the voice channel
+- `/jukebox skip` - Skips the current song and plays the next one
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Developer Resources
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Documentation of the project architecture
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Solutions to common problems
+
+## Acknowledgements
+
+- [discordgo](https://github.com/bwmarrin/discordgo) - Go package for Discord API
+- [The Subsonic API](http://www.subsonic.org/pages/api.jsp) - The API this bot uses to fetch music
+- [jonas747/dca](https://github.com/jonas747/dca) - Audio encoding for Discord
+- [layeh/gopus](https://github.com/layeh/gopus) - Opus codec binding for Go