Skip to main content

Telegram Bot for downloading MP3 rips of tracks/sets from SoundCloud, Bandcamp, YouTube with tags and artwork.

Project description

Music Downloader Telegram Bot

.. image::
:alt: Telegram Bot

.. image::
:alt: Documentation Status

.. image::
:alt: GitHub License

.. image::
:alt: PyPI Version

.. image::
:alt: PyUp Updates

.. image::
:alt: Travis CI Build Status

.. image::
:alt: Code Climate GPA

.. image::
:alt: Code Climate Issue Count

.. image::
:alt: Code Climate Test Coverage

.. image::
:alt: Codacy Build Status

.. image::
:alt: Scrutinizer Code Quality

.. image::
:alt: Better Code Hub Compliance

.. image::
:alt: Codebeat Quality

Telegram Bot for downloading MP3 rips of tracks/sets from SoundCloud, Bandcamp, YouTube with tags and artwork.

* Free software: MIT license
* Documentation:

.. contents:: :depth: 2

Bot Usage

Send ``/start`` or ``/help`` command to bot or refer directly to the `help message <scdlbot/messages/>`__.

Please report all bugs and issues and suggest your improvements to `issues <>`__.

Supported sites and mainly used packages

- `Telegram Bot API <>`__:
`python-telegram-bot <>`__
- `SoundCloud <>`__:
`scdl <>`__
- `Bandcamp <>`__:
`bandcamp-dl <>`__
- `YouTube <>`__,
`Mixcloud <>`__, everything else from the `list <>`__:
`youtube-dl <>`__




Those should be available in your ``PATH``:

- `Python 3.5+ <>`__
(`pyenv <>`__ recommended)
- `FFmpeg 3.4 <>`__ if not running on Heroku
(fresh builds for `Windows <>`__
and `Linux <>`__ are recommended)
- `Heroku CLI <>`__ is recommended

Install / Update stable from `PyPI <>`__ (recommended)


pip3 install scdlbot

Install / Update unstable from `Git source <>`__


git clone
cd scdlbot
pip3 install --requirement requirements.txt

# Update:
git pull
pip3 install --requirement requirements.txt

# System-wide install link to current sources, recommended:
python3 develop

# System-wide install copy of current sources, not recommended:
python3 install


Download or copy config file sample and set up config environment variables in it:


# PyPI-installed: download sample config:
curl -o .env

# Git source-installed: copy sample config:
cp .env.sample .env

# Use your favourite editor:
nano .env


- ``TG_BOT_TOKEN``: Telegram Bot API Token, `obtain
here <>`__


- ``SC_AUTH_TOKEN``: SoundCloud Auth Token, `obtain
here <>`__
- ``STORE_CHAT_ID``: Chat ID for storing audios of inline mode
- ``USE_WEBHOOK``: use webhook for bot updates: ``1``, use polling
(default): ``0``, `more info <>`__
- ``APP_URL``: app URL like
``https://<appname>``, required for webhook
- ``PORT``: port for webhook to listen to; Heroku sets this automatically
for web dynos
- ``BOTAN_TOKEN``: ` <>`__
`token <>`__
- ``NO_FLOOD_CHAT_IDS``: Comma-separated chat IDs with no replying
and caption spam
- ``BIN_PATH``: Custom directory where ``scdl`` and ``bandcamp-dl``
binaries are available, e.g. ``~/.pyenv/shims/`` if you use pyenv,
default: empty (binaries are availaible in PATH)
- ``DL_DIR``: Parent directory for downloads directories, default: /tmp/scdlbot
- ``DL_TIMEOUT``: Download timeout in seconds, stop downloading if it takes longer than allowed, default: 300
- ``MAX_CONVERT_FILE_SIZE``: Don't try to split and send files over this number of bytes, default: 80000000
- ``SYSLOG_ADDRESS``: Syslog server, for example ````
- ``SYSLOG_DEBUG``: Enable verbose debug logging: 1
- ``HOSTNAME``: Hostname to show up in Syslog messages
- ``GOOGL_API_KEY``: ` URL shortener <>`__
`API key <>`__

Webhooks: These three links should help. In NGINX use TOKEN1 as TG_BOT_TOKEN without ":" symbol, and port in proxy_pass according to PORT environment variable.


Telegram Bot Settings

Send the commands from respective filenames in ``telegram_settings`` dir to `@BotFather <>`__, choose your bot and copy corresponding values in order to use the bot conveniently. Also disable privacy mode if you want to.

Running Locally or at Dedicated Server

Using `Heroku Local <>`__ (preferred)

You will need `Heroku CLI <>`__ installed.


# PyPI-installed: download Procfile:
curl -O

# For long polling:
heroku local worker
# For webhook:
heroku local web

Using just Python


# PyPI or Git source system-wide installs:
export $(cat .env | xargs)
# or just:
env $(cat .env | xargs) scdlbot

# Non-installed Git source repository directory:
export $(cat .env | xargs)
python -m scdlbot
# or just:
env $(cat .env | xargs) python -m scdlbot

Deploying to `Heroku <>`__


Register on Heroku, press the button above and configure variables for deploying.
When app is deployed you **must** set only one dyno working on
"Resources" tab in your app settings depending on `which way of getting
updates <>`__ you have
chosen and set in config variables: ``worker`` for polling or ``web``
for webhook.


You can do the same as the button above but using `Heroku
CLI <>`__, not much of a fun. Assuming you are in
``scdbot`` repository directory:


heroku login
# Create app with Python3 buildpack and set it for upcoming builds:
heroku create --buildpack heroku/python
heroku buildpacks:set heroku/python
# Add FFmpeg buildpack needed for youtube-dl:
heroku buildpacks:add --index 1 --app scdlbot
# Deploy app to Heroku:
git push heroku master
# Set config vars automatically from your .env file
heroku plugins:install heroku-config
heroku config:push
# Or set them one by one:

If you use webhook, start web dyno and stop worker dyno:


heroku ps:scale web=1 worker=0
heroku ps:stop worker

If you use polling, start worker dyno and stop web dyno:


heroku ps:scale worker=1 web=0
heroku ps:stop web

Some useful commands:


# Attach to logs:
heroku logs -t
# Test run ffprobe
heroku run "ffprobe -version"

Deploying to `Dokku <>`__

Use Dokku (your own Heroku) installed on your own server. App is tested and fully
ready for deployment with polling (no webhook yet).


export DOKKU=<your_dokku_server>
scp .env $DOKKU:~
ssh $DOKKU
export DOKKU=<your_dokku_server>
dokku apps:create scdlbot
dokku certs:generate scdlbot scdlbot.$DOKKU
dokku config:set scdlbot $(cat .env | xargs)
git remote add dokku dokku@$DOKKU:scdlbot
git push dokku master
ssh $DOKKU
dokku ps:scale scdlbot worker=1 web=0
dokku ps:restart scdlbot

.. |Deploy| image::

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
scdlbot- (23.9 kB) Copy SHA256 hash SHA256 Wheel py3
scdlbot- (35.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page