tgAudioBot 0.2.1
Telegram bot to get the enhanced audio from web media or sent media.
License: MIT
Requires Python: >=3.6

# tgAudioBot

Telegram bot to get the enhanced audio from web media or sent media.

---

![PyPI](https://img.shields.io/pypi/v/tgAudioBot) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tgAudioBot)
[![GitHub](https://img.shields.io/github/license/infinityofspace/tgAudioBot)](https://github.com/infinityofspace/tgAudioBot/blob/master/License) ![PyPI - Downloads](https://img.shields.io/pypi/dm/tgAudioBot)

---

### Table of Contents

1. [About](#about)
2. [Get-Started](#get-started)
    1. [Prerequires](#prerequires)
    2. [Installation](#installation)
    3. [Setup Bot](#setup-bot)
3. [Audio Filters](#audio-filters)
4. [FAQ](#faq)
5. [Project plan](#project-plan)
6. [Third party notices](#third-party-notices)
7. [Disclaimer](#disclaimer)
8. [License](#license)

---
> Note: The project is still in a very early phase, which means that problems and errors may occur.
> Furthermore, the internal data structures or features are not final and can change significantly from version to version.
> This means that it is not always possible to simply upgrade the version of the bot and keep the old settings and user data.
---

### About

_tgAudioBot_ is a self-hostable telegram bot that allows you to convert web media or sent audio to other audio format and enhance it with various audio filters.
You can find a full list with implemented audio filters in [Audio Filters](#audio-filters) section.

Feature highlights:
- limit download speed
- remove intros/outros from YT Media (based on Sponsorblock)
- remove silence at the beginning or end of audio
- normalize audio loudness
- multi user ready
- clean command to keep focus on audio experience

> Note: Theoretically it would be possible to use the bot in a group, 
> but since the purpose of the bot and the features are designed for a private (1 to 1) chat,
> such use is not recommended. A special support for group use is currently not planned, 
> but this possibility is not excluded for future updates.

### Get-Started

#### Prerequires

_tgAudioBot_ uses ffmpeg to convert audio files to desired file type or apply audio filters.
Therefore ffmpeg must be installed.
For some operating systems a command for installation is listed here:

**Debian Linux:**

```commandline
sudo apt install ffmpeg
```

**Arch Linux:**

```commandline
sudo pacman -S ffmpeg
```

#### Installation

You can install or upgrade _tgAudioBot_ with pip:

```commandline
pip install tgAudioBot --upgrade
```

If you want to install _tgAudioBot_ from source:

```commandline
git clone https://github.com/infinityofspace/tgAudioBot
cd tgAudioBot
python setup.py install
```

#### Setup Bot

Before you can use the bot you have to create a new bot with the official Telegram BotFather bot.
You can find the bot by searching in your Telegram for BotFather or use [this](https://t.me/BotFather) direct link. 
A description of how to use BotFather can be found on the [official Telegram Bot site](https://core.telegram.org/bots#6-botfather).
With BotFather you will receive a Bot API token, which you will need when you first start your new bot.

Now you are ready to start your bot with the command:

```commandline
tgAudioBot
```

Before the first use some settings have to be made:

1. At the first start you will be asked to enter your bot token:
    ```
    INFO: No bot api token found!
    Please enter your bot api token which you got from bot father: <YOUR-BOT-TOKEN>
    ```
2. You will also be asked to add at least one bot admin.
   Admins have more options to change bot settings or actions, such as adding new admins, banning users or restarting the bot.
   Therefore you should only add trusted users as admins.
    ```
    INFO: No admin id found. Do you want to add one or more id manually: [y/N]
    ```
3. This can either be done automatically by sending a "/start" message from the respective telegram account to the bot or manually (skip point 4.):
    ```
    INFO: No admin id found. Do you want to add one or more id manually: [y/N] n
    Your bot can be messages under @<you-bot-username> in any Telegram App.
    Please send a message with the command "/start" to your bot with you admin account.
    You will be asked here for the permit of the respective user.
    ```
4. You will be asked for each user if you want to add them as admin and if you want to add more:
    ```
    Should the user (John, Doe; username: johndoe) with id 12345678 added as admin? [y/N] y
    User with id 12345678 was added to admin list.
    Do you want to add more admins? [y/N] n
    ```

5. Or you can add the Telegram ids of the new admin accounts manually (only if you skipped points 3. and 4.):
    ```
    INFO: No admin id found. Do you want to add one or more id manually: [y/N] y
    Please enter one ore more telegram ids to the admin id list (comma separated): <telegram-id-user-one>, <telegram-id-user-two>
    ```

6. When everything is done, your bot is now ready for use:
    ```
    The bot is now successfully set up and can be used.
    ```

There are several arguments to adjust the bot:
```commandline
usage: tgAudioBot [-h] [-r] [-a] [-f BOT_FOLDER] [-l] [-t] [--worker WORKER]

Telegram bot to get the enhanced audio from from web media or sent media.

optional arguments:
  -h, --help            show this help message and exit
  -r, --reset           Reset the current bot config, all settings and delte the cache.
  -a, --add-admin       Add admins to the bot admin list.
  -f BOT_FOLDER, --bot-folder BOT_FOLDER
                        Directory to store bot data.
  -l, --logging         Enable logging to current bot data folder.
  -t, --token           Change the bot api token.
  --worker WORKER       Number of worker processes that are spawned. Must be at least 1.
```

### Usage

Send or forward the bot a media file (video, video message, audio, voice message) smaller than 20MB and you can then specify the audio file format.
After that the audio will be sent to you in your desired audio format.

Alternatively to a local media file you can also send a link to web media (for example a YouTube link).
The bot will then use this media file instead of a file you send.

The SponsorBlock and the silence removing filters are enabled by default.

You can find a more detailed description of the usage and settings in the wiki under the section [Usage](https://github.com/infinityofspace/tgAudioBot/wiki/Usage).

### Audio Filters

There are multiple filters available:

1. Remove silence at beginning and/or end.
2. Remove parts in audio from Youtube media with SponsorBlock API.
2. Normalize audio loudness.

### FAQ

You can the FAQ in the [wiki](https://github.com/infinityofspace/tgAudioBot/wiki/FAQ).

### Project plan

The project plan with the currently developing and planned features can be found [here](https://github.com/infinityofspace/tgAudioBot/projects/1).

### Third party notices

All modules used by this project are listed below:

| Name | Project | License|
|:---:|:---:|:---:|
| python-telegram-bot | [link](https://github.com/python-telegram-bot/python-telegram-bot) | [LGPLv3](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/LICENSE) |
| youtube-dl | [link](https://github.com/ytdl-org/youtube-dl) | [The Unlicense](https://github.com/ytdl-org/youtube-dl/blob/master/LICENSE) |
| ffmpeg-python | [link](https://github.com/kkroening/ffmpeg-python) | [Apache-2.0](https://github.com/kkroening/ffmpeg-python/blob/master/LICENSE) |
| youtube-title-parse | [link](https://github.com/lttkgp/youtube_title_parse) | [MIT](https://github.com/lttkgp/youtube_title_parse/blob/master/LICENSE) |
| requests | [link](https://github.com/psf/requests) | [Apache-2.0](https://github.com/psf/requests/blob/master/LICENSE) |

Moreover this project uses external APIs:

- This project uses the SponsorBlock API by Ajay Ramachandran licensed under CC BY-NC-SA 4.0. More details can be found at https://sponsor.ajay.app/

### Disclaimer

This project is not intended for downloading copyright media.
It is only for educational purposes and is intended to show how the Telegram Bot API, youtube-dl and advanced audio filters can be combined to obtain improved audio experience of audio.

### License

[MIT](https://github.com/infinityofspace/tgAudioBot/blob/master/License) - Copyright (c) 2020 Marvin Heptner