Whisper Transcriber

Prerequisites

Before installing Whisper Transcriber, make sure you have the following:

• Python 3.10 or higher (tested up to 3.12.2) — Download Python
• pip (comes with Python 3.4+)
• ffmpeg installed and available on your system PATH
• A Telegram account to create and interact with your bot
• A CUDA-compatible NVIDIA GPU (optional but strongly recommended for fast transcription — CPU-only mode is supported as a fallback)
• NVIDIA drivers installed if using GPU acceleration
• Git for cloning the repository

---

Get Your API Keys

Telegram Bot Token

1. Open Telegram and search for @BotFather.
2. Start a chat and send the command /newbot.
3. Follow the prompts: provide a display name and a unique username (must end in bot, e.g. MyWhisperBot).
4. BotFather will respond with a token that looks like:

   123456789:ABCDefGhIJKlmNoPQRsTUVwxyZ
   

5. Copy this token — you will use it in the Configuration step.

Note: No OpenAI API key is required. Whisper runs locally on your own hardware using the openai-whisper package.

---

Installation

Option 1: Standard (Non-Docker)

1. Clone the repository:

git clone https://github.com/FlyingFathead/whisper-transcriber-telegram-bot.git
cd whisper-transcriber-telegram-bot

2. Install Python dependencies:

pip install -r requirements.txt

3. Install ffmpeg:

On Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

On Arch Linux:

sudo pacman -S ffmpeg

On macOS (Homebrew):

brew install ffmpeg

On Windows (Chocolatey):

choco install ffmpeg

On Windows (Scoop):

scoop install ffmpeg

---

Option 2: Docker (with GPU support)

1. Install Docker — Get Docker

2. (For GPU acceleration) Install the NVIDIA Container Toolkit on the host machine:

Add the NVIDIA GPG key and repository:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg && \
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

Update the package list:

sudo apt-get update

Check the project README for the remaining Docker setup steps, including building and running the container.

---

Configuration

Set your Telegram bot token using one of the following two methods:

Method A — File: Create the file config/bot_token.txt and paste your token as plain text:

echo "YOUR_TELEGRAM_BOT_TOKEN" > config/bot_token.txt

Method B — Environment variable:

export TELEGRAM_BOT_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"

---

Additional settings are managed in config/config.ini. Key variables and environment options are listed below:

| Variable | Description | Where to get it | |----------|-------------|-----------------| | TELEGRAM_BOT_TOKEN | Authenticates your bot with the Telegram Bot API | @BotFather on Telegram | | Whisper model (in config.ini) | Sets the Whisper model to use — defaults to turbo (Whisper v3). Can also be changed at runtime with /model | No external source; choose from openai/whisper model list | | Supported file formats (in config.ini) | Configures which audio/video upload formats the bot accepts | Set manually in config/config.ini | | cookies.txt path (in config.ini) | Optional path to a cookies file for improved yt-dlp URL availability | Export from your browser using a cookies extension |

---

Running the Bot

Standard mode

python src/main.py

The bot will start, connect to Telegram, and begin listening for messages. On first run, the Whisper model weights will be downloaded automatically (this may take a few minutes depending on your connection).

Docker mode

Check the project README for the specific docker run command, including the flag needed to pass through your NVIDIA GPU to the container.

---

Testing

Once the bot is running, verify it works with this quick smoke test:

1. Open Telegram and search for your bot by the username you set with BotFather.
2. Send the /start command — the bot should respond with a greeting or usage message.
3. Send a short voice message or a supported audio file (e.g., a small .mp3).
4. The bot should reply with a transcription of the audio.
5. Optionally, test URL transcription by sending a YouTube link or any URL supported by yt-dlp.

If the bot responds correctly to all three tests, the installation is working.

---

Troubleshooting

| Problem | Likely cause | Fix | |---------|--------------|-----| | Bot does not respond to any messages | Bot token is missing or incorrect | Double-check config/bot_token.txt or the TELEGRAM_BOT_TOKEN environment variable. Ensure there are no extra spaces or newline characters in the token. | | ffmpeg: command not found error at runtime | ffmpeg is not installed or not on your system PATH | Install ffmpeg using the appropriate command for your OS (see Installation section) and verify with ffmpeg -version. | | Transcription is very slow | No CUDA GPU detected; bot has fallen back to CPU-only mode | Confirm your NVIDIA drivers are installed and that PyTorch can see your GPU by running python -c "import torch; print(torch.cuda.is_available())". Result should be True. | | ModuleNotFoundError on startup | Python dependencies not installed or installed into a different environment | Run pip install -r requirements.txt again inside the correct virtual environment, then retry. | | Large audio files fail to upload via Telegram | Telegram Bot API limits direct file uploads to 20MB | Split the file or use a URL (e.g., a YouTube link) instead of a direct upload. | | Whisper model download fails on first run | Network issue or insufficient disk space | Check your internet connection and ensure you have several GB of free disk space for the model weights. |