Musicium

================================================================================
MUSICIUM — DISCORD MUSIC BOT & MINI APP (DISCORD ACTIVITY)
Developed by: Musicium Team
Language: English
Version: 3.2
================================================================================

1. CONCEPT & PURPOSE
--------------------------------------------------------------------------------
Musicium is a next-generation, cross-platform Discord music bot and interactive
Discord Activity (Mini App) designed for modern Discord communities.

Unlike legacy text-only bots where users are restricted to typing chat commands,
Musicium bridges the raw power of a Python server bot with a full-featured visual
web interface. Voice channel participants can launch a collaborative session
directly inside their Discord client (via the Discord Embedded App SDK) or via
any web browser. Listeners enjoy a shared realtime queue, interactive seeking
timeline, and live-synchronized album artwork.

2. ARCHITECTURE & TECH STACK
--------------------------------------------------------------------------------
Backend & Core Engine:
• Python 3.10+ / discord.py: Gateway v10 event handling, PyNaCl voice encryption,
and native Slash Commands.
• aiohttp Web Server: High-performance asynchronous HTTP/WebSocket server
hosting the Mini App and handling real-time API requests.
• WebSocket Realtime Sync: Instant bidirectional synchronization of playback
state (timeline, current track, queue, pause/resume, volume) across all
connected users without page reloads.
• FFmpeg Audio Pipeline: Dynamic audio normalization, ultra-fast seeking (-ss),
and adaptive buffering to withstand network jitter.

Frontend (Mini App & Activity):
• Vanilla JavaScript (ES6+): Lightweight, framework-free client ensuring
lightning-fast load times even on mobile devices.
• Discord Embedded App SDK 1.1.0: Deep native integration inside Discord
voice activities and collaborative sessions.
• Design System (Glassmorphism): Sleek dark theme, subtle ambient background
glow, responsive layout, animated spinning vinyl record plate, and dynamic
equalizer visualizer.

3. SUPPORTED MUSIC PLATFORMS
--------------------------------------------------------------------------------
Musicium integrates a unified multi-provider search and streaming engine:
1. YouTube Music / YouTube: Comprehensive global music catalog, official
releases, music videos, and remixes with automated stream bypass.
2. SoundCloud: Millions of independent songs, community mixes, DJ sets,
and exclusive tracks.
3. Yandex.Music: Official API integration offering high-bitrate audio
streams and extensive international and Russian music libraries.
4. Direct Streams & Web Radio: Support for live web radio stations and
direct audio stream URLs.

4. PLAYER FEATURES & WEB UI
--------------------------------------------------------------------------------
• Compact Vinyl Record Plate: Stylized animated vinyl disc with dynamic sheen
reflection and center album cover, spinning during active playback.
• Interactive Timeline Seeking: Clickable progress bar enabling users to
jump instantly to any minute or second of a song.
• Dynamic Equalizer Bars: Visual representation of active audio playback.
• Loop Modes:
- Normal — Sequential queue playback;
- Track Loop — Repeatedly play the current song;
- Queue Loop — Loop through the entire playlist continuously.
• Shuffle Mode: Randomize the upcoming queue in a single click.
• Volume Controls: Smooth volume slider with percentage readout and quick
mute/unmute toggling.

5. QUEUE MANAGEMENT & SOCIAL INTERACTION
--------------------------------------------------------------------------------
• Per-Guild Isolation: Every Discord server operates an independent player
instance, queue, and playback configuration.
• Queue Management: Instant in-app search and addition, requester avatar and
use