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-22 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).

Incident 2026-09-22 — "Timed out" is Telegram API, not whisper

User reported the bot replying "не удалось расшифровать, сервис транскрибации недоступен". Diagnosis (navi rei):

  • Two voice jobs failed at 10:03:50 and 10:03:55 UTC: job failed chat=221397150: Timed out after only 7.2 s / 5.5 s.
  • Not a whisper outage. whisper-server was reachable the whole time (GET / → HTTP 200 from both navi host and tgbots-vm; POST /inference with invalid body → HTTP 400 in 0.009 s). No whisper attempt N/3 failed retry warnings in the log (whisper retries log them), and the whisper timeout is 600 s — a 5–7 s failure cannot be a whisper timeout.
  • Root cause: python-telegram-bot's TimedOut exception from a Telegram Bot API call (PTB default read timeout 5 s) — most likely send_chat_action/send_message around the job. The generic except Exception in process_job sent the misleading "сервис транскрибации недоступен" message for ANY job exception, including Telegram API timeouts.
  • Service self-recovered; no restart needed; later jobs succeeded.

Known failure mode (triage rule):

  • job failed ... Timed out in ~5–10 s with NO whisper attempt warnings → Telegram Bot API timeout, transcription service is fine.
  • Hang up to 600 s with whisper attempt N/3 failed warnings → actual whisper-server problem (check bserv-host GPU/Ollama load).

Fix applied 2026-09-22 (navi rei, owner-approved)

Patch to bot.py (backup: bot.py.bak-20260922, original 16413 B):

  1. from telegram.error import TimedOut added to imports.
  2. Application.builder() now sets all PTB timeouts to 30 s: read_timeout, write_timeout, connect_timeout, pool_timeout, get_updates_read_timeout, get_updates_write_timeout, get_updates_connect_timeout, get_updates_pool_timeout (PTB default was 5 s — the source of the false "service unavailable").
  3. process_job catches telegram.error.TimedOut separately BEFORE the generic except Exception: logs Telegram API timed out ... transcription service is fine, user asked to retry and sends the user "⏳ Telegram не ответил вовремя — сервис транскрибации в порядке. Перешли сообщение ещё раз." instead of the misleading "сервис транскрибации недоступен".

Verification: py_compile OK; systemctl restart gntranscribe.service → active (running), worker started, GNtranscribe started as @gntranscribe_bot, Application started (10:34:34 UTC, PID 257995). Rollback: cp bot.py.bak-20260922 bot.py && sudo systemctl restart gntranscribe.service.

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.