Голос-бот: расшифровка голосовых сообщений Telegram в текст

Задача

Голосовые сообщения удобны отправителю и неудобны получателю. Их нельзя просмотреть глазами, найти поиском, процитировать или прочитать там, где нельзя включить звук: в метро, на совещании, ночью рядом со спящим ребёнком. Пятиминутное голосовое требует ровно пяти минут внимания, даже если полезного в нём две строки.

Нужен был бот перевода голосовых в текст, которому достаточно переслать сообщение. Без регистрации на сторонних сайтах, без загрузки файла в браузер и с честным поведением: если речи в записи нет, бот должен сказать об этом, а не сочинить текст.

Решение

Golos Bot — собственный Telegram-бот расшифровки голосовых сообщений. Реализовано в версии 2.2.0:

• Любой источник звука. Голосовые (ogg), кружочки (берётся звуковая дорожка), аудиофайлы mp3, m4a, ogg и wav, видео (вырезка из созвона, лекция), документы, когда аудио прислали файлом.
• Три режима. Дословно — каждое слово как сказано, для договорённостей. Прибрано — без «эээ» и повторов, абзацами, на каждый день. Конспект — тезисы и структура.
• Переделать иначе. Режим переключается кнопкой под готовой расшифровкой, пересылать запись заново не нужно.
• Язык ответа. Русский, English или язык оригинала.
• Файлом. Длинный текст отдаётся как .txt, а не режется на куски.
• Кэш. Та же запись в том же режиме возвращается мгновенно, без трат на API.
• Тишина. Если речи нет, бот сообщает об этом, а не выдумывает текст.
• Пул ключей Gemini. Автопереключение при исчерпании квоты и автооткат на запасную модель.
• Лимиты. Число расшифровок в час и максимальная длительность записи; часовой лимит меняется из админки на лету. Список премиум-пользователей без лимита, админы безлимитны всегда.
• Админ-панель. Статистика, аналитика, ключи, пользователи, баны, рассылка, настройки, логи, обслуживание. Новый пользователь — админам приходит карточка с ID и username, один раз.

Как это устроено

Gemini транскрибация аудио одним запросом

Google Gemini — мультимодальная модель, то есть нейросеть, которая понимает звук напрямую, без отдельного этапа «распознать речь, потом обработать текст». Бот отправляет аудио вместе с промптом (инструкцией), в котором указаны режим и язык, и получает готовый текст. Так меньше звеньев и меньше потерь смысла. Глубина рассуждений модели и таймаут ответа задаются настройками.

ffmpeg: проверка и сжатие в моно-MP3

Перед отправкой в модель ffprobe (утилита из набора FFmpeg) читает длительность записи и проверяет, есть ли в ней звук. Если файл больше 20 МБ, FFmpeg пережимает его в моно-MP3 с битрейтом 32 kbps: для распознавания речи этого достаточно, а объём падает в разы. Библиотека pydub намеренно не используется: она не обновлялась с 2021 года и импортирует модуль audioop, удалённый из Python 3.13.

Пул ключей Gemini и квоты

Бесплатная квота Gemini ограничена, поэтому бот держит несколько ключей. Когда ключ упёрся в квоту, он уходит на остывание (по умолчанию 60 минут), а запрос идёт через следующий. Пользователь ничего не замечает, админу приходит уведомление. В админке виден статус каждого ключа и есть кнопка снять остывание принудительно. Если основная модель вернула 404 (переименовали, сняли), бот молча переходит на запасную.

Кэш расшифровок

Результат сохраняется в SQLite вместе с ключом «запись + режим». Повторная отправка той же записи в том же режиме отдаётся из кэша мгновенно. Кэш живёт ограниченный срок (по умолчанию 30 дней), сам аудиофайл удаляется сразу после обработки. В базе также хранятся пользователи и их настройки, журнал расшифровок, использование ключей и настройки, меняемые из админки.

Управление и учёт

Админ-панель открывается командой /admin и работает на кнопках под сообщением. В шапке показана версия бота: по ней видно, что реально раскатано на сервере. При первом появлении нового пользователя всем админам приходит карточка: имя, ID отдельным блоком (копируется тапом), ссылка на username и общее число пользователей в базе. Логика бота покрыта модульными проверками и проверками маршрутизации, в которых Telegram и Gemini заменены имитациями, поэтому сеть для прогона не нужна.

Результат

• Голосовое, кружочек, аудиофайл или видео читаются как текст: его можно найти поиском, процитировать и прочитать без звука.
• Режим меняется после расшифровки без повторной пересылки записи.
• Повторы отдаются из кэша без обращения к API.
• Исчерпание квоты одного ключа не останавливает работу: пул ключей и запасная модель.
• Аудио не хранится, текст расшифровки живёт ограниченный срок.
• Бот работает в Docker с healthcheck и ротацией логов, версия пишется в лог при старте и приходит админам сообщением о запуске.

Технологии: что и зачем

• Python 3.14 и aiogram 3 — асинхронный Telegram-бот на inline-кнопках.
• Google Gemini (google-genai) — расшифровка аудио одним запросом; основная и запасная модели задаются настройками.
• FFmpeg и ffprobe — длительность, проверка наличия звука, сжатие длинных записей.
• SQLite (aiosqlite) — пользователи, журнал, кэш расшифровок, использование ключей, настройки.
• Docker — образ python:3.14-slim, запуск под непривилегированным пользователем, healthcheck, TZ=Europe/Moscow.

Статус

Собственный продукт, в продакшене. Текущая версия 2.2.0 от 20 сентября 2026 года: добавлена подпись «Сделано в DevUnit Lab» со ссылкой на сайт. Версия 2.1.0 (15 августа 2026) зафиксировала переезд в отдельный репозиторий и разбиение однофайлового бота на пакет модулей.

Ограничения: 20 МБ на скачивание через облачный Bot API, работа только в личных сообщениях, очереди при исчерпании всех ключей нет. В планах: кнопка «Скопировать текст», саммари первым сообщением, работа в группах, мониторинг квоты, учёт стоимости, экспорт в .docx и .srt.