# Installation Guide

This guide covers installing Sonora v1.2.8 and setting up your development environment.

# Table of Contents

System Requirements
Installing Sonora
Setting up Lavalink
Environment Configuration
Verification
Troubleshooting

# System Requirements

# Minimum Requirements

Python: 3.11 or higher
Operating System: Linux, macOS, or Windows
Memory: 256MB RAM minimum
Storage: 50MB free space
Network: Stable internet connection

# Recommended Requirements

Python: 3.11+ (latest stable)
Memory: 512MB RAM or more
CPU: Multi-core processor
Storage: 100MB free space

# Installing Sonora

# Using pip (Recommended)

# Install the latest stable version
pip install sonora

# Or install a specific version
pip install sonora==1.2.8

# Install with development dependencies
pip install sonora[dev]

# Using pip with Discord Libraries

Sonora works with multiple Discord libraries:

# For discord.py support
pip install sonora discord.py

# For nextcord support
pip install sonora nextcord

# For py-cord support
pip install sonora py-cord

# From Source (Development)

# Clone the repository
git clone https://github.com/code-xon/sonora.git
cd sonora

# Install in development mode
pip install -e .

# Install with all optional dependencies
pip install -e .[dev,discord,nextcord]

# Virtual Environment (Recommended)

# Create virtual environment
python -m venv sonora_env

# Activate (Linux/macOS)
source sonora_env/bin/activate

# Activate (Windows)
sonora_env\Scripts\activate

# Install Sonora
pip install sonora

# Setting up Lavalink

Sonora requires a Lavalink server for audio processing. Lavalink is a standalone audio sending node based on Lavaplayer.

# Option 1: Docker (Recommended)

# Pull and run Lavalink
docker run -d \
  --name lavalink \
  -p 2333:2333 \
  -v $(pwd)/application.yml:/opt/Lavalink/application.yml \
  fredboat/lavalink:4.0.1

# Option 2: Download JAR

# Download Lavalink JAR
wget https://github.com/fredboat/Lavalink/releases/download/4.0.1/Lavalink.jar

# Create application.yml
# (See configuration below)

# Run Lavalink
java -jar Lavalink.jar

# Lavalink Configuration

Create application.yml in your project directory:

server:
  port: 2333
  address: 0.0.0.0

lavalink:
  server:
    password: "youshallnotpass"
    sources:
      youtube: true
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      http: true
      local: false

  plugins:
    - dependency: "com.github.topisenpai:lavasrc-plugin:4.1.1"
      repository: "https://maven.topi.wtf/releases"

  audio:
    opus:
      quality: 10
    ffmpeg:
      enabled: true

# Testing Lavalink

# Test connection
curl http://localhost:2333/version

# Should return: {"version":"4.0.1"}

# Environment Configuration

# Environment Variables

Create a .env file in your project root:

# Discord Bot Configuration
DISCORD_TOKEN=your_bot_token_here

# Lavalink Configuration
LAVALINK_HOST=localhost
LAVALINK_PORT=2333
LAVALINK_PASSWORD=youshallnotpass

# Optional: Sonora Configuration
SONORA_LOG_LEVEL=INFO
SONORA_DEBUG=false

# Loading Environment Variables

import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Access in your code
discord_token = os.getenv('DISCORD_TOKEN')
lavalink_host = os.getenv('LAVALINK_HOST', 'localhost')
lavalink_port = int(os.getenv('LAVALINK_PORT', 2333))

# Verification

# Test Installation

# test_installation.py
import sonora
from sonora import SonoraClient

print(f"Sonora version: {sonora.__version__}")
print("✅ Sonora imported successfully")

# Test client creation
client = SonoraClient(
    lavalink_nodes=[{
        "host": "localhost",
        "port": 2333,
        "password": "youshallnotpass"
    }]
)
print("✅ SonoraClient created successfully")

# Run the Test

python test_installation.py

# CLI Verification

# Check Sonora CLI
sonoractl --help

# Check environment
sonoractl doctor

# Troubleshooting

# Common Installation Issues

"Python version not supported"

Error: Python 3.11+ required

Upgrade Python to version 3.11 or higher
Check version: python --version

"Module not found"

ModuleNotFoundError: No module named 'sonora'

Ensure Sonora is installed: pip install sonora
Check if virtual environment is activated
Try reinstalling: pip uninstall sonora && pip install sonora

"Permission denied"

PermissionError: [Errno 13] Permission denied

Don't install packages as root/sudo
Use virtual environment instead

# Lavalink Issues

"Connection refused"

ConnectionError: Connection refused

Check if Lavalink is running: docker ps | grep lavalink
Verify port 2333 is not blocked by firewall
Check Lavalink logs for errors

"Authentication failed"

AuthenticationError: Invalid password

Verify password in application.yml matches Sonora configuration
Check for extra spaces or special characters

"No audio sources enabled"

NoSourceError: No sources available

Enable at least one source in application.yml
Restart Lavalink after configuration changes

# Discord Bot Issues

"Invalid token"

LoginError: Invalid token

Get new token from Discord Developer Portal
Ensure token is for a bot application
Check for extra characters in token

"Missing permissions"

PermissionsError: Missing permissions

Grant bot proper permissions in Discord server
Ensure bot has voice channel access
Check bot role hierarchy

# Performance Issues

High CPU usage

Use Python 3.11+ for better performance
Consider using PyPy instead of CPython
Monitor with sonoractl performance

Memory leaks

Update to latest Sonora version
Monitor memory usage with system tools
Restart bot periodically if needed

# Advanced Setup

# Multiple Lavalink Nodes

sonora = SonoraClient(
    lavalink_nodes=[
        {
            "host": "node1.example.com",
            "port": 2333,
            "password": "password1",
            "region": "us-east"
        },
        {
            "host": "node2.example.com",
            "port": 2333,
            "password": "password2",
            "region": "eu-west"
        }
    ],
    node_pooling=True  # Enable load balancing
)

# Custom Lavalink Plugins

# application.yml
lavalink:
  plugins:
    - dependency: "com.github.topisenpai:lavasrc-plugin:4.1.1"
      repository: "https://maven.topi.wtf/releases"
    - dependency: "com.github.topisenpai:lavalyrics-plugin:4.0.1"
      repository: "https://maven.topi.wtf/releases"

# SSL/TLS Configuration

# For HTTPS Lavalink connections
sonora = SonoraClient(
    lavalink_nodes=[{
        "host": "secure-lavalink.example.com",
        "port": 443,
        "password": "password",
        "secure": True  # Enable SSL
    }]
)

# Next Steps

Now that you have Sonora installed and configured:

Read the Getting Started guide
Explore API documentation
Check out examples
Join our Discord server for support

# Support

Documentation: Full API Reference
Issues: GitHub Issues
Community: Discord Server
Email: ramkrishna@code-xon.fun