TelyDL is a Telegram bot that allows whitelisted users to download music from Tidal and Spotify ( through monochrome and YouTube ( as fallback: MP3 ) directly to the server running it.
The bot handles audio extraction, metadata management, and provides a convenient interface for managing downloaded files.
Send one or multiple links to the bot and it will download it to your server.
- Validate the URL
- Download the audio with embedded metadata
- Save the file in the appropriate directory
- Notify you when complete
- Multi-platform support: supported links: Tidal / Spotify / Youtube
- Simple Whitelist Auth: authentication is required for every action, unauthorized access is denied and reported to the admin user.
- Multiple download sources: HiRes Download through monochrome API / LowRes through
yt-dlp - no API token required: uses monochrome as source
- Metadata handling: Automatic metadata embedding
- Disk space management: Monitors disk space and prevents downloads when storage is low
- URL validation: Filters URLs based on duration and other criteria ( omits tracks longer than 10min, not configurable yet )
- Libraray syncing: sync the libraray to another server with rsync
- Flat download directory: download all files into one directory
- soundcloud support
- video downloads from multimedia: download mp4s from all sources accepted by
yt-dlp( thats a lot ) - torrent integration: provide magnet links ( browse )
- configurable download structure:
base/$ARTIST/$ALBUM/,base/$ARTIST, etc. - metadata configuration:
base/$ARTIST/$ALBUM/,base/$ARTIST, etc.
have one? suggest as Issue or submit PR
- Python 3.8+
uvor other package manageryt-dlpfor YouTube downloadsffmpegoptional for audio extraction when the falback yt-dlp handler is usedmutagenfor metadata tagging- Telegram bot token ( easily acquirable through telegram )
- Clone the repository:
git clone https://github.com/nlsg/telydl.git
cd telydl- acquire token from botfather
TELYDL_BOT_TOKEN: Telegram bot token
- Run the bot:
uv run main.py- install the bot as systemd service ( optional )
TELYDL_BOT_TOKEN=your_telegram_bot_token
TELYDL_WHITELIST=12345,67890 # Comma-separated list of authorized user IDs
# To find out the ID, simple make a request and review the logs for unquthorized accessTELYDL_BOT_TOKEN: Telegram bot tokenTELYDL_BASE_DIRECTORY: Directory where downloads will be storedTELYDL_WHITELIST: Comma-separated list of authorized user IDsTELYDL_ADMIN: where unauthorized access is reported ( falls back to first whitelisted user if unset )TELYDL_RSYNC: Rsync command for backup/sync operationsTELYDL_MIN_DURATION: minimum track length ( default 2min )TELYDL_MAX_DURATION: maximum track_length ( default 10min )TELYDL_MIN_FREE_DISK_SPACE: downloads are omited, if less disk space is available ( default 10Gb )TELYDL_CHECK_DISK_FREQUENCY: check disk space every x download ( default 10 )
- NO COMMAND - parse for urls and download
/help- Show help information/list- List all downloaded files, might break once the lib is to large ( #TODO )/get <pattern>- Download a specific file to your telegram client/remove <pattern>- Remove a file from storage/get_log- Get application logs/rsync- Run sync command
python -m pytest tests/Im happy to see your pull request and will likely approve it :)
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the GPLv3 License.
Big Thanks to the monochrome project, the project would not be able to provide high res downloads without it
Suggestions for mirrored APIs are always welcome - just issue or make a PR
Also thanks to youtube-dl / yt-dlp, very awesome tool I love and use for years.