Newer
Older
gnexus-book / 10-systems / bots / gntranscribe.md

title: GNtranscribe description: Telegram bot — audio transcription via whisper-server host: tgbots-vm status: active last_reviewed: 2026-09-20 owner: gmikcon confidence: 100 review_interval: 90

source_of_truth: live_system

GNtranscribe

Overview

Telegram bot @gntranscribe_bot on VM tg_bots (192.168.1.254). Users forward or send voice messages, audio files, video circles or videos; the bot queues them and returns the transcript from whisper-server on bserv-host (192.168.1.130:8008, model ggml-large-v3-turbo-q5_0, auto language detect).

Deployed 2026-09-20 by navi instance rei on owner request.

Design

  • Multi-user: incoming media jobs go into an asyncio queue (max 20).
  • Single worker processes jobs one at a time — whisper-server shares a 4 GB GPU with Ollama on bserv-host, parallel inference is not safe there.
  • Pipeline per job: download from Telegram CDN via aiohttp (PTB's default 5 s read timeout is too slow for the CDN) → convert to 16 kHz mono WAV via ffmpeg → POST to whisper → send transcript (chunked at 4000 chars).
  • whisper-server rejects ogg/opus with HTTP 400 "Invalid request" — Telegram voice messages are ogg/opus, hence the mandatory WAV conversion (verified 2026-09-20: ogg → 400, wav → exact transcript).
  • Optional chat_id whitelist via ALLOWED_CHAT_IDS in .env (comma-separated; empty = open to everyone). Non-whitelisted users get their chat_id back with a deny message.
  • Commands: /start, /help, /id (shows chat_id/user_id for whitelist setup), /status (queue size, worker state, counters, uptime).
  • Media accepted: voice, audio, video_note (circle), video, audio/video documents. Max file size 24 MB (configurable MAX_FILE_MB).
  • Whisper calls retried up to 3 attempts on network errors.

Technical Details

  • Host: VM tg_bots (192.168.1.254), user ubuntu
  • Path: /home/ubuntu/bots/GNtranscribe — bot.py, .env, requirements.txt, gntranscribe.service, venv/
  • Stack: Python 3.10, python-telegram-bot 21.10, aiohttp, ffmpeg 4.4.2 (system package, required for WAV conversion)
  • systemd: gntranscribe.service (User=ubuntu, Restart=always, RestartSec=30), enabled (multi-user.target.wants)
  • Config (.env): BOT_TOKEN (stored in gnexus-creds secret "GNtranscribe token", not in docs), WHISPER_URL=http://192.168.1.130:8008/inference, MAX_FILE_MB=24, MAX_QUEUE=20, WHISPER_TIMEOUT=600, ALLOWED_CHAT_IDS= (empty)
  • Logs: /home/ubuntu/bots/GNtranscribe/logs/bot.log (rotating, 2 MB x 3) and journalctl -u gntranscribe.service
  • Upstream: whisper-server on bserv-host — see inventory item bserv-host (POST /inference, multipart file=@)

Verification 2026-09-20

  • getMe → ok, @gntranscribe_bot.
  • Direct whisper test: TTS-generated Russian audio POSTed to http://192.168.1.130:8008/inference returned the exact expected text.
  • Service active after enable --now; two consecutive restarts passed.
  • Live-message debugging: first failure was PTB 5 s download timeout (fixed with aiohttp download), second was ogg/opus HTTP 400 from whisper-server (fixed with ffmpeg WAV conversion; ogg→400, wav→ok verified).

Operations

  • Restart: sudo systemctl restart gntranscribe.service
  • Enable whitelist: edit ALLOWED_CHAT_IDS in .env, then restart.
  • Token rotation: update BOT_TOKEN in .env and the gnexus-creds secret, restart.