# Extended FAQ

Frequently asked questions and detailed answers.

Sonora is a full-featured, enterprise-grade Python Lavalink client for building high-performance Discord music bots. It provides advanced features like smart autoplay, intelligent queue management, and comprehensive security.

Sonora offers:

• Enterprise features: Security, monitoring, enterprise SDKs
• Advanced AI: Smart autoplay with multiple strategies
• Intelligent queue: Adaptive reordering, skip fatigue detection
• Performance: Lock-free architecture, zero-copy routing
• Security: Plugin sandboxing, encrypted credentials
• Developer experience: Built-in profiling, comprehensive CLI

Yes, Sonora v1.2.8 is a stability patch release with enterprise-grade features suitable for production use.

Problem: Lavalink server fails to start

Solutions:

1. Check Java version: java -version (requires Java 11+)
2. Verify application.yml configuration
3. Check port availability: netstat -tlnp | grep 2333
4. Review logs: tail -f lavalink.log

Problem: Cannot connect to Lavalink

Solutions:

1. Verify Lavalink is running: curl http://localhost:2333/version
2. Check firewall settings
3. Confirm correct host/port in configuration
4. Test network connectivity: telnet localhost 2333

Problem: ModuleNotFoundError when importing Sonora

Solutions:

1. Install correctly: pip install py-sonora
2. Check Python version (3.11+ required)
3. Virtual environment issues: source venv/bin/activate
4. Path issues: python -c "import sys; print(sys.path)"

Problem: play() returns None or raises exception

Causes & Solutions:

1. Invalid query: Check URL format or search terms
2. Lavalink source disabled: Enable sources in application.yml
3. Rate limiting: Wait and retry
4. Network issues: Check Lavalink connectivity

Problem: Poor audio quality or distortion

Solutions:

1. Adjust Lavalink settings:

   lavalink:
     audio:
       opus:
         quality: 10

2. Check source quality
3. Reduce active filters
4. Verify bitrate settings

Problem: Sonora consumes excessive resources

Solutions:

1. Enable performance mode: performance_mode="overdrive"
2. Limit queue size: player.queue.max_size = 1000
3. Reduce filter usage
4. Monitor with sonoractl performance

Problem: Autoplay doesn't suggest tracks

Solutions:

1. Enable autoplay: player.autoplay.enabled = True
2. Check strategy: print(player.autoplay.strategy)
3. Verify history: len(player.queue.history) > 0
4. Test manually: await player.autoplay.fetch_next_track(context)

Problem: Autoplay suggests irrelevant tracks

Solutions:

1. Change strategy: player.autoplay.strategy = "similar_genre"
2. Adjust history size: player.autoplay.max_history = 20
3. Clear history if corrupted
4. Provide better context data

Problem: Playback stops after current track

Solutions:

1. Check loop mode: player.queue.loop_mode
2. Enable autoplay if desired
3. Verify tracks are valid
4. Check for stuck operations

Problem: Queue state inconsistent between bot and users

Solutions:

1. Use proper locking: async with player.queue._lock
2. Avoid concurrent modifications
3. Implement state validation
4. Use snapshots for recovery

Problem: Plugin fails to load or register

Solutions:

1. Check plugin code syntax
2. Verify permissions are requested
3. Review security validation logs
4. Test plugin isolation

Problem: Plugin causes application instability

Solutions:

1. Implement error boundaries in plugins
2. Use timeouts for plugin operations
3. Sandbox plugin execution
4. Monitor plugin resource usage

Question: How are credentials secured?

Answer: Sonora uses AES-encrypted vaults with PBKDF2 key derivation. Master keys are never stored and should be provided securely.

Question: Are plugins safe to run?

Answer: Plugins are sandboxed with code validation, restricted imports, and resource limits. Always review plugin code before installation.

Recommendations:

1. Use connection pooling
2. Enable caching
3. Implement rate limiting
4. Monitor resource usage
5. Scale horizontally

Tips:

1. Limit queue sizes
2. Use object pooling
3. Implement garbage collection
4. Monitor memory patterns
5. Use streaming for large data

Question: How to extend Sonora?

Answer:

1. Use plugins for isolated features
2. Subclass existing classes
3. Implement custom strategies
4. Hook into event system
5. Contribute upstream

Question: How to test modifications?

Answer:

1. Write unit tests with pytest
2. Use fixtures for common setup
3. Mock external dependencies
4. Test edge cases
5. Maintain coverage >90%

# System health
sonoractl doctor

# Performance metrics
sonoractl performance

# Plugin status
sonoractl plugin list

# Queue inspection
sonoractl queue inspect --guild-id 123

import logging
logging.basicConfig(level=logging.DEBUG)

# Enable verbose Lavalink logging
client = SonoraClient(..., log_level="DEBUG")

import cProfile
profiler = cProfile.Profile()
profiler.enable()
# ... code to profile ...
profiler.disable()
profiler.print_stats(sort='cumulative')

Cause: Lavalink connection lost Solution: Check network, restart Lavalink, configure reconnection

Cause: Invalid URL or source disabled Solution: Verify URL, check Lavalink sources, try different source

Cause: Insufficient plugin permissions Solution: Request additional permissions in plugin manifest

Cause: Excessive memory usage Solution: Reduce queue size, limit concurrent operations, monitor usage

• GitHub Issues: Bug reports and feature requests
• Discussions: General questions and community help
• Documentation: Comprehensive guides and API reference

• Enterprise Support: Available for commercial deployments
• Consulting: Custom development and optimization services
• Training: Workshops and onboarding sessions

This FAQ covers the most common questions and issues. For additional help, check the documentation or open a GitHub issue.