A fast, multi-source music bot for Telegram.
Send a Spotify, YouTube, or social-media link — or just type a song name — and TrackFlow finds the best audio, tags it, and delivers it in seconds.
TrackFlow is a self-hostable Telegram bot that turns links and search queries
into high-quality, fully-tagged audio files. It reads metadata from Spotify,
finds the closest matching source on YouTube (the same approach as spotdl),
downloads and transcodes it with yt-dlp + FFmpeg, and caches the result so the
next request for the same track is instant.
It also recognizes music from voice/video clips, downloads audio from YouTube and social-media video links, and ships with a full admin control panel.
Note
Spotify does not serve audio directly. TrackFlow uses Spotify only for metadata (title, artist, album, cover, duration) and sources the audio from YouTube Music. Intended for personal use — respect the copyright laws in your jurisdiction.
- 🔗 Link detection — paste a Spotify track, album, playlist, or artist link and TrackFlow resolves it automatically.
- 🔍 Text search — type a song name; the search engine finds and returns the best match.
▶️ YouTube & video links — extract audio from YouTube, or download videos from popular social platforms.- 🎤 Music recognition — forward a voice note, audio, or video clip and TrackFlow identifies the track (Shazam-powered).
- ❤️ Liked Songs — connect your Spotify account via OAuth and bulk-download your library.
- ⭐ Favorites, history & playlists — personal library management inside the chat.
- ⚡ Instant cache — Telegram
file_idcaching means a previously downloaded track is re-sent in about a second. - 🚀 Parallel downloads — albums and playlists are processed several tracks at a time.
- 🏷 Full metadata — ID3 tags, embedded cover art, and duration on every file.
- 🎚 Quality control — choose 128 / 320 kbps, apply audio effects, and edit metadata.
- 🎯 Recommendations — a "similar songs" engine built on ListenBrainz, Deezer, local audio analysis, and (optionally) Last.fm.
- 🌍 Multi-language — Uzbek, English, and Russian UI.
- 🛡 Admin panel — roles, bans, broadcasts, maintenance mode, live logs, and usage dashboards.
| Source | Capability |
|---|---|
| Spotify | Track / album / playlist / artist links, text search, Liked Songs (OAuth) |
| YouTube / YouTube Music | Audio extraction from links, primary audio source for search |
| Social video platforms | Video download + "Find Music" recognition |
| Local media | Recognize audio/voice/video clips sent to the bot |
| Layer | Technology |
|---|---|
| Language | Python 3.12 (asyncio, uvloop on Linux) |
| Bot framework | aiogram 3 |
| Web / OAuth server | aiohttp |
| Media | yt-dlp + FFmpeg, mutagen |
| Storage | SQLite via aiosqlite |
| Config | pydantic-settings |
| Security | cryptography (Fernet token encryption) |
| Recognition | shazamio |
| Analysis | NumPy (audio feature extraction) |
| Deployment | Docker, Railway |
Prerequisites: Python 3.12+, FFmpeg, and a Telegram bot token from @BotFather.
# 1. Install FFmpeg
# Windows: winget install ffmpeg
# macOS: brew install ffmpeg
# Debian: sudo apt install ffmpeg
# 2. Clone and enter the project
git clone https://github.com/murodovdev/Spotify.git trackflow
cd trackflow
# 3. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 4. Configure environment
cp .env.example .env # Windows: copy .env.example .env
# Edit .env and set BOT_TOKEN (Spotify keys are optional — see below)
# 5. Run
python -m bot.mainThe bot starts polling immediately and launches a local OAuth server on
http://127.0.0.1:8080 (used only for the Spotify "Connect account" flow).
Only BOT_TOKEN is required. Spotify credentials unlock link resolution and
Liked Songs; without them the bot automatically falls back to embed mode
(metadata from public open.spotify.com/embed pages, YouTube-based search).
| Variable | Required | Description |
|---|---|---|
BOT_TOKEN |
✅ | Telegram bot token from @BotFather. |
SPOTIFY_CLIENT_ID |
Spotify app client ID (enables full API + Liked Songs). | |
SPOTIFY_CLIENT_SECRET |
Spotify app client secret. | |
SPOTIFY_REDIRECT_URI |
OAuth callback. Auto-derived if left blank. | |
ADMIN_ID |
Telegram user ID granted owner/admin access. | |
ENCRYPTION_KEY |
Fernet key for encrypting stored tokens. Derived from BOT_TOKEN if blank. |
|
DB_PATH |
SQLite path. Auto: /data/bot.db on Railway, data/bot.db locally. |
|
PORT |
OAuth web server port (default 8080). |
|
MAX_DOWNLOADS |
Max concurrent downloads (default 4). |
|
LASTFM_API_KEY |
Optional — strengthens the recommendation engine. | |
YOUTUBE_COOKIES / _B64 / _FILE |
Optional YouTube cookies to bypass bot checks. See Configuration. |
See docs/CONFIGURATION.md for the full reference, including how to obtain Spotify credentials and export YouTube cookies.
TrackFlow is built to run on Railway with a persistent volume and zero extra infrastructure. A one-page walkthrough — including the critical volume setup that keeps user data across redeploys — is in docs/DEPLOYMENT.md.
# Container build works anywhere Docker runs:
docker build -t trackflow .
docker run --env-file .env -p 8080:8080 -v "$(pwd)/data:/data" trackflow| Command | Description |
|---|---|
/start |
Main menu |
/liked |
Download your Spotify Liked Songs |
/favorites |
Your saved favorites |
/settings |
Quality (128 / 320 kbps) and language |
/help |
Usage help |
/admin |
Admin control panel (authorized users only) |
bot/
├── main.py # Entry point: polling loop + OAuth web server + lifecycle
├── config.py # Environment-based settings (pydantic)
├── i18n.py # Localized strings (UZ / EN / RU)
├── keyboards.py # Inline keyboards
├── security.py # Token encryption helpers
├── handlers/ # Telegram update handlers (links, search, library, video, …)
├── services/ # Core logic
│ ├── spotify.py # Async Spotify Web API client (metadata, OAuth, Liked)
│ ├── search_engine.py # Query → best-match resolution
│ ├── matcher.py # Pick the closest YouTube source for a track
│ ├── downloader.py # yt-dlp → MP3 → ID3 tags + cover art
│ ├── queue.py # Caching, parallel downloads, progress, cancellation
│ ├── recognizer.py # Shazam-based music recognition
│ ├── recommender.py # "Similar songs" engine
│ ├── video_dl.py # Social-media video downloads
│ └── audio_*.py # Effects and analysis
├── db/ # SQLite layer (users, file_id cache, history, tokens)
├── admin/ # Admin control panel (roles, bans, broadcast, dashboard)
└── web/oauth.py # Spotify OAuth callback + /health endpoint
For a deeper tour of the request lifecycle and data flow, see docs/ARCHITECTURE.md.
Contributions are welcome. Please read CONTRIBUTING.md for the development setup, coding style, and pull-request workflow.
Released under the MIT License.