Telegram ASR Bot (Python)

Transcribes Telegram voice notes and audio files using local Faster-Whisper.

Requirements

• Python 3.10+
• ffmpeg installed and available in PATH

Setup

1. Install dependencies:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Create .env (see .env.example):

cp .env.example .env

3. Fill in your TELEGRAM_BOT_TOKEN.

Run

python -m src.main

Docker

Build image:

docker build -t telegram-asr-bot .

Run container (replace token):

docker run --rm \
  -e TELEGRAM_BOT_TOKEN=123456:ABC \
  -e ASR_DEVICE=cpu \
  -v $(pwd)/downloads:/app/downloads \
  -v $(pwd)/tmp:/app/tmp \
  --name telegram-asr-bot \
  telegram-asr-bot

Notes:

• Mounting downloads and tmp keeps files on the host.
• For Apple Silicon GPU accel with Faster-Whisper, use ASR_DEVICE=mps (containerized GPU support varies).

Configuration (env)

• TELEGRAM_BOT_TOKEN (required): Bot token from BotFather
• ASR_MODEL_SIZE (optional): e.g. base, small, medium, large-v3
• ASR_DEVICE (optional): auto | cpu | cuda | mps
• ASR_COMPUTE_TYPE (optional): auto | float16 | int8
• DOWNLOAD_DIR (optional): where Telegram files are saved
• TMP_DIR (optional): where converted wav files are saved

Notes

• Ensure ffmpeg is installed: on macOS via brew install ffmpeg.
• On Apple Silicon, set ASR_DEVICE=mps for Faster-Whisper acceleration.