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