How ashokshau/tgmusicbot works
Project Type and Purpose
• This is a backend service (a Telegram Voice Chat music bot) built in Python.
• It connects to Telegram (bot API and voice chat API), streams music from third-party platforms (YouTube, Spotify, JioSaavn, etc.), applies caching and filtering, and persists state in MongoDB.
• It lives in a Docker container or can run directly on a VM/Heroku/tmux.
File Structure Insights
• Top-level files: Dockerfile, Procfile, setup scripts, CI workflows, sample.env for configuration.
• TgMusic package:
• __main__.py: entrypoint that launches the bot.
• logger.py: logging configuration.
• core/ directory: business-logic services (API wrappers, HTTPX client, downloader, cacher, config loader, database access, cookie manager, tgcalls integration, audio filters, thumbnail generator, utility helpers).
• modules/ directory: Telegram command handlers organized per feature (play, skip, queue, loop, volume, broadcast, admin, etc.). A utils subfolder holds shared helpers.
• cookies/ directory: management of cookie-based authentication for services.
• pyproject.toml & uv.lock: dependency definitions.
Key Components
• Telegram Layer
• Telegram Bot API (PyTDbot or Pyrogram) for incoming commands.
• Telegram Voice Chat API (PyTgCalls) for streaming audio.
• Command Handling Layer
• modules/ handlers parse updates and emit events or call core services.
• Core Services Layer
• Downloader service: fetches audio from YouTube, Spotify, JioSaavn via HTTPX or cookies.
• Cacher: stores downloaded content or metadata (in MongoDB or file cache).
• Filter/Processor: normalizes audio (volume adjust, format conversion via ffmpeg).
• Database: MongoDB for queue state, user settings, logs.
• Config Manager: reads environment variables (.env → _config).
• API Wrappers: modular wrappers under core/_jiosaavn, _spotify_dl_helper, _youtube, _httpx.
• Cookie Manager: fetches and saves cookies for sites.
• Telegram Integration: PyTgCalls for voice streaming, button generators, thumbnail maker.
• External Systems
• Third-party streaming platforms: YouTube, Spotify, JioSaavn etc.
• MongoDB Atlas or self-hosted MongoDB.
• Optional external API gateway (FallenApiBot) for anti-ban.
• Deployment & Infrastructure
• Docker container built via Dockerfile.
• Continuous Integration (GitHub Workflows).
• Heroku (Procfile/app.json) or standalone VM with tmux.
• Logging to Telegram group or console.
Relationships and Interactions
• Incoming Telegram Updates → Command Handler modules → invoke Core Services.
• Core Services → Downloader/API Wrappers → Third-party Platforms.
• Downloaded audio → Filter/Processor → PyTgCalls → streamed to Telegram Voice Chat.
• State changes (queue updates, user requests) → persisted in MongoDB via core/_database.
• Cacher checks cache first; on cache miss, triggers download.
• Config Manager supplies API keys, tokens, connection strings.
• Logger broadcasts runtime logs to a Telegram logger group or stdout.
• Docker container exposes no ports (communicates outbound to Telegram).
Architectural Patterns and Principles
• Modular Monolith: logical separation into “command modules” and “core services” within one process.
• Layered Architecture: Presentation (Telegram API), Application (modules), Domain (core), Infrastructure (MongoDB, Docker).
• Plugin-like modules: new commands added by dropping files in modules/.
• Event-driven command loop: Telegram update → dispatch to module → event triggers service calls.
• Single responsibility per core file (downloader, cacher, API wrapper).
Essential Details
• Environment configuration feeding into the Config Manager.
• CI/CD pipeline triggering Docker builds and deployments.