Как сделать Telegram-бота, который переводит голосовые в текст, на Python

Голосовой Telegram-бот состоит из понятной цепочки: получить файл, расшифровать аудио и вернуть текст в тот же чат. Мы используем python-telegram-bot и локальный faster-whisper. Модель работает на вашем компьютере, токен хранится в переменной окружения, а тяжёлая расшифровка уходит в отдельный поток, чтобы бот не зависал на каждом сообщении.

Пользователь видит одно действие: отправил голосовое и через несколько секунд получил текст. Внутри бот проходит несколько границ. Telegram присылает update с метаданными, отдельный запрос getFile выдаёт путь, библиотека скачивает OGG во временный каталог, а speech-to-text модель превращает звук в сегменты. Наконец Python склеивает сегменты и отвечает.

Как голосовое проходит через Telegram и Python

При старте приложение один раз создаёт WhisperModel small для CPU с int8. Это занимает память, зато модель не загружается для каждого сообщения. Application слушает обновления Telegram. Когда приходит voice, обработчик проверяет размер, скачивает файл во временный каталог и вызывает обычную функцию transcribe_sync через asyncio.to_thread.

У проекта есть один главный маршрут: получить входные данные, проверить их, выполнить действие и показать результат. Если каждый этап можно проверить отдельно, ошибка перестаёт быть загадкой.

От входных данных до видимого результата. Файл скачивается отдельно от update и удаляется после ответа

Пишем обработчик и локальную расшифровку

Создайте проект и установите зависимости: uv init voice-bot, затем uv add python-telegram-bot faster-whisper. В актуальном faster-whisper PyAV декодирует аудио, поэтому отдельный системный FFmpeg для этого примера не требуется. Создайте бота через BotFather, задайте переменную BOT_TOKEN и запустите uv run python bot.py. На Windows PowerShell переменная для текущего окна задаётся как $env:BOT_TOKEN="...".

import asyncio
import os
import tempfile
from pathlib import Path

from faster_whisper import WhisperModel
from telegram import Update
from telegram.ext import Application, ContextTypes, MessageHandler, filters

model = WhisperModel("small", device="cpu", compute_type="int8")


def transcribe_sync(path: Path) -> str:
    segments, _ = model.transcribe(str(path), language="ru", vad_filter=True)
    return " ".join(segment.text.strip() for segment in segments).strip()


async def voice_to_text(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    message = update.effective_message
    voice = message.voice
    if voice.file_size and voice.file_size > 20 * 1024 * 1024:
        await message.reply_text("Файл больше 20 МБ, пришлите запись короче.")
        return

    status = await message.reply_text("Скачиваю и расшифровываю...")
    try:
        with tempfile.TemporaryDirectory() as folder:
            audio_path = Path(folder) / "voice.ogg"
            telegram_file = await voice.get_file()
            await telegram_file.download_to_drive(audio_path)
            text = await asyncio.to_thread(transcribe_sync, audio_path)
        await status.edit_text(text[:4000] or "Не удалось услышать речь.")
    except Exception:
        await status.edit_text("Не получилось обработать запись. Попробуйте ещё раз.")


token = os.environ["BOT_TOKEN"]
app = Application.builder().token(token).build()
app.add_handler(MessageHandler(filters.VOICE, voice_to_text))
app.run_polling(allowed_updates=Update.ALL_TYPES)

Функция transcribe_sync намеренно остаётся синхронной, а граница с async проходит в asyncio.to_thread. Так тяжёлая работа не блокирует цикл Telegram-бота, но код распознавания остаётся простым и тестируемым обычным вызовом.

Что отличает устойчивый проект от случайного успеха. CPU-задача не должна останавливать приём новых сообщений

Почему модель нельзя запускать прямо в async-цикле

Bot API не передаёт весь звук внутри update. Объект Voice содержит file_id, длительность и иногда размер. get_file получает File с временным file_path, после чего download_to_drive сохраняет данные. faster-whisper принимает путь и возвращает segments как ленивый генератор.

Размер модели влияет на скорость, память и качество. tiny или base быстрее, small обычно даёт более устойчивую русскую речь, а крупные модели требуют больше ресурсов. Не обещайте мгновенный ответ: измерьте время на своём компьютере и ограничьте длительность входа.

Проверяем тишину, длинный файл и ошибку сети

Сначала отправьте короткую фразу без шума и сверьте текст. Затем пришлите две секунды тишины, голосовое на другом языке и запись рядом с музыкой. Для каждого случая бот должен дать понятный результат, а не зависнуть. Добавьте проверку duration и отклоняйте файлы длиннее выбранного лимита.

Хороший голосовой бот заметно показывает состояние, ограничивает нагрузку и не оставляет аудио после обработки. Только после этого есть смысл добавлять резюме, тайм-коды или сохранение заметок.

Четыре проверки перед следующим шагом. Приватность и ограничения проверяются вместе с качеством

Делаем бота удобнее и безопаснее

Развить проект можно тремя безопасными способами. Первый: возвращать язык и длительность вместе с текстом. Второй: разбивать длинную расшифровку на сообщения по предложениям. Третий: по явной команде сохранять заметку пользователя в его собственном хранилище. Не добавляйте автоматическую пересылку и публикацию текста без подтверждения.

Как изучить тему в Кодике

В Кодике сначала соберите обычного эхо-бота, затем функцию, которая принимает путь и возвращает строку. Когда обе части работают отдельно, соедините их через временный файл и to_thread. Такой маршрут отделяет Telegram, файловую систему и модель друг от друга.

В тренажёре Кодика перепишите transcribe_sync и проверку лимита отдельно от Telegram. Затем восстановите обработчик по шагам: статус, скачивание, поток, ответ. Если вы можете назвать, какая строка отвечает за каждый этап, проект перестаёт быть непрозрачной связкой библиотек.

Что получится в итоге

Бот показывает статус, скачивает OGG во временный каталог, расшифровывает его локально и возвращает готовый текст без сохранения аудио.