telegram spotify downloader bot: @SpotSeekBot

This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.

Users are responsible for their actions and potential legal consequences. We do not support unauthorized downloading of copyrighted material and take no responsibility for user actions. Artists can send their copyright claims to the developer.

Send bot a link from spotify and it'll download it for you.

• It can be a track link like this: https://open.spotify.com/track/734dz1YaFITwawPpM25fSt
• Or an album like this: https://open.spotify.com/album/0Lg1uZvI312TPqxNWShFXL
• Or a playlist like this: https://open.spotify.com/playlist/37i9dQZF1DWX4UlFW6EJPs

• general pre-install updates in ubuntu:

$ sudo apt update
$ sudo apt upgrade
$ sudo apt-get update
$ sudo apt-get upgrade

• clone the repo
• proxychains4:
  • warp: I got it as a side feature by installing MHSanaei 3x-ui. You might be able to install it via fscarmen warp too.
  • install it via sudo apt-get install proxychains4
  • set warp proxy in /etc/proxychains4.conf
• copy .env.example to .env in the repo root and fill in secrets (see .env.example for key names). variables.py loads that file at import time; existing process environment is not overridden.
• set required variables in variables.py file:
  • promote_channel_username - set to a channel that bot promotes and is its admin (begining with @)
  • warp_mode - set to False if you don't have warp socks proxy
• install pip:

apt install python3-pip

• install necessary python modules (or read the requrements modules and install them one by one):

pip install -r requirements.txt

• ffmpeg:
  • install it via apt install ffmpeg
  • if didn't work correctly you can check another more complicated installation here: https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu
• make scripts that run the bot executable:
• music.db:
  • create it from scratch via create_database() or use the saved one from before
  • weekly Git LFS snapshot: backup_db_to_github.sh (set DB_BACKUP_REPO in .env to a local clone of your private backup repo; uses sqlite .backup, not cp)

chmod +x restart_spotseek.sh restart_spotseek_queue_handler.sh backup_db_to_github.sh

add this text to crontab (change with the path you've cloned repository):

# spotseek
## run main scripts on reboot
@reboot /path/to/spot-seek-bot/restart_spotseek.sh
@reboot /path/to/spot-seek-bot/restart_spotseek_queue_handler.sh
## temp solution to reset every hour to free up memory
0 * * * * /path/to/spot-seek-bot/restart_spotseek.sh
## weekly sqlite backup to private github (Sunday 03:00 UTC)
0 3 * * 0 /path/to/spot-seek-bot/backup_db_to_github.sh

• reboot once to affect

• When you send a spotify link to the bot it searches through its database and if it's the first time it sees this link it will download it with spotdl but if it has done it before it saves time by using previously downloaded files from database.
• I've set 30 seconds waiting time for 2 requests in a row from 1 user so it won't be spammed
• I've set log channel and database channel for the bot. It stores every downloaded song in database channel and use it as a storage and prints logs from everything to log channel (errors, user messags, ...)
• We use spotify api to get tracks from a valid link so you should sign up in https://developer.spotify.com/ and get your own token.
• All mp3 files are downloaded with high 320k quality.

• Note: starting template of each csv should be headers and one empty new line after them

date and time added | spotify track id | telegram audio id

unique user id | last use date and time

• support searching name of song by user
• support inline mode
• option to enable or disable warp mode for everything (spotipy, spotdl, ...)
• fix caption so it will be shown for repetitive tracks
• some musics metadata is not shown
• bot should send available tracks to users while new one is being downloaded with spotdl to use best of time.
• higher priority for first time users
• only 1 single user can use the bot and it can't multitask
• use a library like telethon for big mp3 files more than 50MB
• searching in database algorithm isn't fast and efficient
• Download playlists with more thatn 100 songs
• find a clean way to give access to database to next bot maintainers
• merge database of all spotify downloaders together
• showing message to user when link from other services like deezer is sent.
• find a way to shorten database (audio IDs are very long)
• if all track_ids that a user wants already exists bypass normall routine and send all of them to him
• test portalocker funcion from db_csv_append separately
• handle blocked by user link
• manage too threads bug
• regex should handle both http and https
• make restart_spotseek.sh work without reboot too
• restarting queue handler doesn't stop previous spotdl download so there might be an excessive mp3 file that might lead to creating wrong track
• add gif tutorial for bot in the start
• check out zotify capabilities
• lyrics
• send picture and info of link
• private playlist answer
• more features for premium users
• read track data without api key in similar way to https://spotify.detta.dev/

YT-DLP: probabely the ip is banned by youtube. change it to another.

Sandbox research (2026-08-20) and production wiring: docs/yt-dlp-proxychains-research.md.

This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.

Users are responsible for their actions and potential legal consequences. We do not support unauthorized downloading of copyrighted material and take no responsibility for user actions. Artists can send their copyright claims to the developer.

• BuyMeACoffee (🇺🇸 $)
• Coffeete (🇮🇷 ريال)

• Patreon (🇺🇸 $)
• HamiBash (🇮🇷 ريال)