How theteamalexa/alexamusic works
Project Type & Purpose
• AlexaMusic is a monolithic Python service—a Telegram Bot (and optional Userbot)—for in-chat audio/video playback. It leverages Pyrogram (bot & user sessions), Py-TgCalls for voice‐chat streaming, yt-dlp for media extraction, and MongoDB for state persistence.
High-Level File/Directory Analysis
• “AlexaMusic/”
• core/ – the engine (bot initialization, call management, cookie handling, Git/dir utilities, MongoDB wrappers, userbot auto-join)
• platforms/ – adapter modules for each music source (YouTube, Spotify, SoundCloud, Apple, etc.)
• plugins/ – command handlers organized by role (admins, bot, devs, misc, play, sudo, tools)
• utils/ – shared utilities (database models, decorators, formatters, inline query builders, stream queue, thumbnails, logging)
• Top-level helpers: app.py/.env/config, Dockerfile/docker-compose.yml, heroku/koyeb/render manifests, genstring.py (session generator), requirements.txt
README Insights
• Tech stack: Python 3, Pyrogram, Py-TgCalls, yt-dlp
• External dependencies: Telegram Bot API, MongoDB URI, browser cookies for YouTube
• Deployment targets: Docker, Heroku, Render, Koyeb, Scalingo
• Command-based plugin architecture drives all user interactions
Main Architectural Components
a. Telegram Layer
• Bot Client (Pyrogram)
• Optional Userbot Client (Pyrogram) – auto-join voice chats
b. Core Engine
• Update dispatcher → plugin loader → command router
• Call manager (joins/leaves voice chats)
• Cookie manager for signed-in YouTube access
• Git/dir utilities (self-update, logs, metrics)
c. Platform Adapters
• YouTube, Spotify, SoundCloud, Apple, Resso, Carbon – each implements a standard interface for “search,” “stream,” “download”
d. Media Extraction & Streaming
• yt-dlp (downloads or streams media)
• Py-TgCalls (streams audio/video into Telegram voice chats)
e. Persistence
• MongoDB (chats, user settings, gban, sudo, assistant database, themes, on/off flags, pm-permit)
f. Configuration & Secrets
• .env / config/config.py / sample.env / genstring.py (session generation)
g. Deployment / CI
• Docker / docker-compose
• Heroku, Render, Koyeb, Scalingo manifests
• GitHub Actions (black formatting)
Component Interactions & Data Flows
• User → Telegram Bot API → Bot Client
• Bot Client → Core command dispatcher → Loads appropriate Plugin
• Plugin → Core services (call manager, platform adapter, database)
• Platform Adapter → External music API (or yt-dlp) → Returns media stream/URL
• Call Manager + Py-TgCalls → Inject media stream into Telegram Voice Chat
• Database reads/writes on each stateful operation (queues, settings, bans)
• Logging and metrics captured at each layer
Architectural Patterns & Principles
• Modular Plugin Architecture (separation of commands by concern)
• Adapter Pattern (uniform interface to heterogeneous music sources)
• Layered Design (Telegram layer → business logic → data persistence)
• Dependency Injection via config and environment variables
Final Checklist
• Clear, concise labels on every component
• Layer separation (Deployment, Application, Service, Data)
• Callouts for critical environment variables (API keys, MongoDB URI, session strings)